add howitworks.md
This commit is contained in:
John Cupitt
parent
60e661614f
commit
30829ef003
|
|
@ -1,5 +1,6 @@
|
|||
25/3/17 started 8.5.2
|
||||
- better behaviour for truncated PNG files, thanks Yury
|
||||
- move some docs from the wiki and blog into core libvips docs
|
||||
|
||||
25/3/17 started 8.5.1
|
||||
- init more classes earlier, thanks David
|
||||
|
|
|
|||
|
|
@ -0,0 +1 @@
|
|||
How-it-works.xml
|
||||
|
|
@ -0,0 +1,316 @@
|
|||
Compared to most image processing libraries, VIPS needs little RAM and runs
|
||||
quickly, especially on machines with more than one CPU. VIPS achieves this
|
||||
improvement by only keeping the pixels currently being processed in RAM
|
||||
and by having an efficient, threaded image IO system. This page explains
|
||||
how these features are implemented.
|
||||
|
||||
### Images
|
||||
|
||||
VIPS images have three dimensions: width, height and bands. Bands usually
|
||||
(though not always) represent colour. These three dimensions can be any
|
||||
size up to 2 ** 31 elements. Every band element in an image has to have the
|
||||
same format. A format is an 8-, 16- or 32-bit int, signed or unsigned, 32-
|
||||
or 64-bit float, and 64- or 128-bit complex.
|
||||
|
||||
### Regions
|
||||
|
||||
An image can be very large, much larger than the available memory, so you
|
||||
can't just access pixels with a pointer \*.
|
||||
|
||||
Instead, you read pixels from an image with a region. This is a rectangular
|
||||
sub-area of an image. In C, the API looks like:
|
||||
|
||||
```c
|
||||
VipsImage *image = vips_image_new_from_file( filename, NULL );
|
||||
VipsRegion *region = vips_region_new( image );
|
||||
|
||||
// ask for a 100x100 pixel region at 0x0 (top left)
|
||||
VipsRect r = { left: 0, top: 0, width: 100, height: 100 };
|
||||
if( vips_region_prepare( region, &r ) )
|
||||
vips_error( ... );
|
||||
|
||||
// get a pointer to the pixel at x, y, where x, y must
|
||||
// be within the region
|
||||
|
||||
// as long as you stay within the valid area for the region,
|
||||
// you can address pixels with regular pointer arithmetic
|
||||
|
||||
// compile with -DDEBUG and the macro will check bounds for you
|
||||
|
||||
// add VIPS_REGION_LSKIP() to move down a line
|
||||
VipsPel *pixel = VIPS_REGION_ADDR( region, x, y );
|
||||
|
||||
// you can call vips_region_prepare() many times
|
||||
|
||||
// everything in libvips is a GObject ... when you're done,
|
||||
// just free with
|
||||
g_object_unref( region );
|
||||
```
|
||||
|
||||
The action that `vips_region_prepare()` takes varies with the type of
|
||||
image. If the image is a file on disc, for example, then VIPS will arrange
|
||||
for a section of the file to be read in.
|
||||
|
||||
(\* there is an image access mode where you can just use a pointer, but
|
||||
it's rarely used)
|
||||
|
||||
### Partial images
|
||||
|
||||
A partial image is one where, instead of storing a value for each pixel, VIPS
|
||||
stores a function which can make any rectangular area of pixels on demand.
|
||||
|
||||
If you use `vips_region_prepare()` on a region created on a partial image,
|
||||
VIPS will allocate enough memory to hold the pixels you asked for and use
|
||||
the stored function to calculate values for just those pixels \*.
|
||||
|
||||
The stored function comes in three parts: a start function, a generate
|
||||
function and a stop function. The start function creates a state, the
|
||||
generate function uses the state plus a requested area to calculate pixel
|
||||
values and the stop function frees the state again. Breaking the stored
|
||||
function into three parts is good for SMP scaling: resource allocation and
|
||||
synchronisation mostly happens in start functions, so generate functions
|
||||
can run without having to talk to each other.
|
||||
|
||||
VIPS makes a set of guarantees about parallelism that make this simple to
|
||||
program. Start and stop functions are mutually exclusive and a state is
|
||||
never used by more than one generate. In other words, a start / generate /
|
||||
generate / stop sequence works like a thread.
|
||||
|
||||
|
||||
|
||||
(\* in fact VIPS keeps a cache of calculated pixel buffers and will return
|
||||
a pointer to a previously-calculated buffer if it can)
|
||||
|
||||
### Operations
|
||||
|
||||
VIPS operations read input images and write output images, performing some
|
||||
transformation on the pixels. When an operation writes to an image the
|
||||
action it takes depends upon the image type. For example, if the image is a
|
||||
file on disc then VIPS will start a data sink to stream pixels to the file,
|
||||
or if the image is a partial one then it will just attach start / generate /
|
||||
stop functions.
|
||||
|
||||
Like most threaded image processing systems, all VIPS operations have to
|
||||
be free of side-effects. In other words, operations cannot modify images,
|
||||
they can only create new images. This could result in a lot of copying if
|
||||
an operation is only making a small change to a large image so VIPS has a
|
||||
set of mechanisms to copy image areas by just adjusting pointers. Most of
|
||||
the time no actual copying is necessary and you can perform operations on
|
||||
large images at low cost.
|
||||
|
||||
### Run-time code generation
|
||||
|
||||
VIPS uses [Orc](http://code.entropywave.com/orc/), a run-time compiler, to
|
||||
generate code for some operations. For example, to compute a convolution
|
||||
on an 8-bit image, VIPS will examine the convolution matrix and the source
|
||||
image and generate a tiny program to calculate the convolution. This program
|
||||
is then "compiled" to the vector instruction set for your CPU, for example
|
||||
SSE3 on most x86 processors.
|
||||
|
||||
Run-time vector code generation typically speeds operations up by a factor
|
||||
of three or four.
|
||||
|
||||
### Joining operations together
|
||||
|
||||
The region create / prepare / prepare / free calls you use to get pixels
|
||||
from an image are an exact parallel to the start / generate / generate /
|
||||
stop calls that images use to create pixels. In fact, they are the same:
|
||||
a region on a partial image holds the state created by that image for the
|
||||
generate function that will fill the region with pixels.
|
||||
|
||||
|
||||
|
||||
VIPS joins image processing operations together by linking the output of one
|
||||
operation (the start / generate / stop sequence) to the input of the next
|
||||
(the region it uses to get pixels for processing). This link is a single
|
||||
function call, and very fast. Additionally, because of the the split between
|
||||
allocation and processing, once a pipeline of operations has been set up,
|
||||
VIPS is able to run without allocating and freeing memory.
|
||||
|
||||
This graph (generated by `vipsprofile`, the vips profiler) shows memory use
|
||||
over time for a vips pipeline running on a large image. The bottom trace
|
||||
shows total memory, the upper traces show threads calculating useful results
|
||||
(green), threads blocked on synchronisation (red) and memory allocations
|
||||
(white ticks).
|
||||
|
||||
|
||||
|
||||
Because the intermediate image is just a small region in memory, a pipeline
|
||||
of operations running together needs very little RAM. In fact, intermediates
|
||||
are small enough that they can fit in L2 cache on most machines, so an
|
||||
entire pipeline can run without touching main memory. And finally, because
|
||||
each thread runs a very cheap copy of just the writeable state of the
|
||||
entire pipeline, threads can run with few locks. VIPS needs just four lock
|
||||
operations per output tile, regardless of the pipeline length or complexity.
|
||||
|
||||
### Data sources
|
||||
|
||||
VIPS has data sources which can supply pixels for processing from a variety
|
||||
of sources. VIPS can stream images from files in VIPS native format, from
|
||||
tiled TIFF files, from binary PPM/PGM/PBM/PFM, from Radiance (HDR) files,
|
||||
from FITS images and from tiled OpenEXR images. VIPS will automatically
|
||||
unpack other formats to temporary disc files for you but this can
|
||||
obviously generate a lot of disc traffic. It also has a special
|
||||
sequential mode for streaming operations on non-random-access
|
||||
formats. A post on the libvips blog [explains how libvips opens a
|
||||
file](http://libvips.blogspot.co.uk/2012/06/how-libvips-opens-file.html). One
|
||||
of the sources uses the [ImageMagick](http://www.imagemagick.org) (or
|
||||
optionally [GraphicsMagick](http://www.graphicsmagick.org)) library, so
|
||||
VIPS can read any image format that these libraries can read.
|
||||
|
||||
VIPS images are held on disc as a 64-byte header containing basic image
|
||||
information like width, height, bands and format, then the image data as
|
||||
a single large block of pixels, left-to-right and top-to-bottom, then an
|
||||
XML extension block holding all the image metadata, such as ICC profiles
|
||||
and EXIF blocks.
|
||||
|
||||
When reading from a large VIPS image (or any other format with the same
|
||||
structure on disc, such as binary PPM), VIPS keeps a set of small rolling
|
||||
windows into the file, some small number of scanlines in size. As pixels
|
||||
are demanded by different threads VIPS will move these windows up and down
|
||||
the file. As a result, VIPS can process images much larger than RAM, even
|
||||
on 32-bit machines.
|
||||
|
||||
### Data sinks
|
||||
|
||||
In a demand-driven system, something has to do the demanding. VIPS has a
|
||||
variety of data sinks that you can use to pull image data though a pipeline
|
||||
in various situations. There are sinks that will build a complete image
|
||||
in memory, sinks to draw to a display, sinks to loop over an image (useful
|
||||
for statistical operations, for example) and sinks to stream an image to disc.
|
||||
|
||||
The disc sink looks something like this:
|
||||
|
||||
|
||||
|
||||
The sink keeps two buffers\*, each as wide as the image. It starts threads
|
||||
as rapidly as it can up to the concurrency limit, filling each buffer with
|
||||
tiles\*\* of calculated pixels, each thread calculating one tile at once. A
|
||||
separate background thread watches each buffer and, as soon as the last tile
|
||||
in a buffer finishes, writes that complete set of scanlines to disc using
|
||||
whatever image write library is appropriate. VIPS can write with libjpeg,
|
||||
libtiff, libpng and others. It then wipes the buffer and repositions it
|
||||
further down the image, ready for the next set of tiles to stream in.
|
||||
|
||||
These features in combination mean that, once a pipeline of image processing
|
||||
operations has been built, VIPS can run almost lock-free. This is very
|
||||
important for SMP scaling: you don't want the synchronization overhead to
|
||||
scale with either the number of threads or the complexity of the pipeline
|
||||
of operations being performed. As a result, VIPS scales almost linearly
|
||||
with increasing numbers of threads:
|
||||
|
||||
|
||||
|
||||
Number of CPUs is on the horizontal axis, speedup is on the vertical
|
||||
axis. Taken from the [[Benchmarks]] page.
|
||||
|
||||
(\* there can actually be more than one, it allocate enough buffers to
|
||||
ensure that there are at least two tiles for every thread)
|
||||
|
||||
(\*\* tiles can be any shape and size, VIPS has a tile hint system that
|
||||
operations use to tell sinks what tile geometry they prefer)
|
||||
|
||||
### Operation cache
|
||||
|
||||
Because VIPS operations are free of side-effects\*, you can cache them. Every
|
||||
time you call an operation, VIPS searches the cache for a previous call to
|
||||
the same operation with the same arguments. If it finds a match, you get
|
||||
the previous result again. This can give a huge speedup.
|
||||
|
||||
By default, VIPS caches the last 1,000 operation calls. You can also control
|
||||
the cache size by memory use or by files opened.
|
||||
|
||||
(\* Some vips operations DO have side effects, for example,
|
||||
`vips_draw_circle()` will draw a circle on an image. These operations emit an
|
||||
"invalidate" signal on the image they are called on and this signal makes
|
||||
all downstream operations and caches drop their contents.)
|
||||
|
||||
### Operation database and APIs
|
||||
|
||||
VIPS has around 300 image processing operations written in this style. Each
|
||||
operation is a GObject class. You can use the standard GObject calls to walk
|
||||
the class hierarchy and discover operations, and libvips adds a small amount
|
||||
of extra introspection metadata to handle things like optional arguments.
|
||||
|
||||
The [C API](using-from-c.html) is a set of simple wrappers which create
|
||||
class instances for you. The [C++ API](using-from-cpp.html) is a little
|
||||
fancier and adds things like automatic object lifetime management. The
|
||||
[command-line interface](using-cli.html) uses introspection to run any vips
|
||||
operation in the class hierarchy.
|
||||
|
||||
The [Python API](using-from-python.html) is built on top of
|
||||
gobject-introspection. It is written in Python, so as long as you can get
|
||||
gobject-introspection working, you should be able to use vips. It supports
|
||||
python2 and python3 and works on Linux, OS X and Windows.
|
||||
|
||||
### Snip
|
||||
|
||||
The VIPS GUI, nip2, has its own scripting language called Snip. Snip is a
|
||||
lazy, higher-order, purely functional, object oriented language. Almost all
|
||||
of nip2's menus are implemented in it, and nip2 workspaces are Snip programs.
|
||||
|
||||
VIPS operations listed in the operation database appear as Snip functions. For
|
||||
example, `abs` can be used from Snip as:
|
||||
|
||||
```
|
||||
// absolute value of image b
|
||||
a = vips_call "abs" [b] [];
|
||||
```
|
||||
|
||||
However, `abs` won't work on anything except the primitive vips image type. It
|
||||
can't be used on any class, or list or number. Definitions in `_stdenv.dev`
|
||||
wrap each VIPS operation as a higher level Snip operation. For example:
|
||||
|
||||
```
|
||||
abs x
|
||||
= oo_unary_function abs_op x, is_class x
|
||||
= vips_call "abs" [x] [], is_image x
|
||||
= abs_cmplx x, is_complex x
|
||||
= abs_num x, is_real x
|
||||
= abs_list x, is_real_list x
|
||||
= abs_list (map abs_list x), is_matrix x
|
||||
= error (_ "bad arguments to " ++ "abs")
|
||||
{
|
||||
abs_op = Operator "abs" abs Operator_type.COMPOUND false;
|
||||
|
||||
abs_list l = (sum (map square l)) ** 0.5;
|
||||
|
||||
abs_num n
|
||||
= n, n >= 0
|
||||
= -n;
|
||||
|
||||
abs_cmplx c = ((re c)**2 + (im c)**2) ** 0.5;
|
||||
}
|
||||
```
|
||||
|
||||
This defines the behaviour of `abs` for the base Snip types (number, list,
|
||||
matrix, image and so on), then classes will use that to define operator
|
||||
behaviour on higher-level objects.
|
||||
|
||||
Now you can use:
|
||||
|
||||
```
|
||||
// absolute value of anything
|
||||
a = abs b;
|
||||
```
|
||||
|
||||
and you ought to get sane behaviour for any object, including things like
|
||||
the `Matrix` class.
|
||||
|
||||
You can write Snip classes which present functions to the user as menu
|
||||
items. For example, `Math.def` has this:
|
||||
|
||||
```
|
||||
Math_arithmetic_item = class
|
||||
Menupullright "_Arithmetic" "basic arithmetic for objects" {
|
||||
|
||||
Absolute_value_item = class
|
||||
Menuaction "A_bsolute Value" "absolute value of x" {
|
||||
action x = map_unary abs x;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Now the user can select an object and click `Math / Abs` to find the absolute
|
||||
value of that object.
|
||||
|
||||
|
|
@ -126,13 +126,26 @@ IGNORE_HFILES = $(IGNORE_VIPS_INCLUDE) $(IGNORE_VIPS_C)
|
|||
# Images to copy into HTML directory.
|
||||
# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
|
||||
HTML_IMAGES = \
|
||||
$(top_srcdir)/doc/images/interconvert.png
|
||||
$(top_srcdir)/doc/images/interconvert.png \
|
||||
$(top_srcdir)/doc/images/Combine.png \
|
||||
$(top_srcdir)/doc/images/Memtrace.png \
|
||||
$(top_srcdir)/doc/images/Sequence.png \
|
||||
$(top_srcdir)/doc/images/Sink.png \
|
||||
$(top_srcdir)/doc/images/Vips-smp.png
|
||||
|
||||
# we have some files in markdown ... convert to docbook for gtk-doc
|
||||
# pandoc makes sect1 headers, we want refsect3 for gtk-doc
|
||||
.md.xml:
|
||||
pandoc -s -S --template="$(realpath pandoc-docbook-template.docbook)" --wrap=none -V title="$<" -f markdown -t docbook -o $@ $<
|
||||
sed -e s/sect1/refsect3/g < $@ > x && mv x $@
|
||||
|
||||
# Our markdown source files
|
||||
markdown_content_files = \
|
||||
How-it-works.md
|
||||
|
||||
# converted to xml in this dir by pandoc
|
||||
markdown_content_files_docbook = $(markdown_content_files:.md=.xml)
|
||||
|
||||
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
|
||||
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
|
||||
content_files = \
|
||||
|
|
@ -144,7 +157,7 @@ content_files = \
|
|||
extending.xml \
|
||||
function-list.xml \
|
||||
file-format.xml \
|
||||
whatsnew-8.5.xml \
|
||||
${markdown_content_files_docbook} \
|
||||
binding.xml
|
||||
|
||||
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
|
||||
|
|
@ -159,7 +172,7 @@ expand_content_files = \
|
|||
extending.xml \
|
||||
function-list.xml \
|
||||
file-format.xml \
|
||||
whatsnew-8.5.xml \
|
||||
${markdown_content_files_docbook} \
|
||||
binding.xml
|
||||
|
||||
# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
|
||||
|
|
@ -176,13 +189,14 @@ include gtk-doc.make
|
|||
# Other files to distribute
|
||||
# e.g. EXTRA_DIST += version.xml.in
|
||||
EXTRA_DIST += \
|
||||
${markdown_content_files} \
|
||||
images \
|
||||
gen-function-list.py
|
||||
|
||||
# Files not to distribute
|
||||
# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
|
||||
# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt
|
||||
DISTCLEANFILES = libvips.types
|
||||
DISTCLEANFILES = libvips.types
|
||||
|
||||
# Comment this out if you want 'make check' to test you doc status
|
||||
# and run some sanity checks
|
||||
|
|
|
|||
|
|
@ -1,109 +0,0 @@
|
|||
#!/bin/sh
|
||||
#
|
||||
|
||||
usage() {
|
||||
cat <<EOF
|
||||
gtkdoc-mkhtml version 1.25 - generate documentation in html format
|
||||
|
||||
--verbose Print extra output while processing
|
||||
--path=SEARCH_PATH Extra source directories
|
||||
MODULE Name of the doc module being parsed
|
||||
DRIVER_FILE File containing the toplevel DocBook file.
|
||||
--version Print the version of this program
|
||||
--help Print this help
|
||||
EOF
|
||||
}
|
||||
|
||||
# echo "args $*\n";
|
||||
|
||||
# parse options, ignore unknown options for future extensions
|
||||
|
||||
verbose="0"
|
||||
searchpath=
|
||||
uninstalled=no
|
||||
while true; do
|
||||
case "X$1" in
|
||||
X--version) echo "1.25"; exit 0;;
|
||||
X--help) usage; exit 0;;
|
||||
X--uninstalled) uninstalled=yes; shift;;
|
||||
X--verbose) verbose="1"; shift;;
|
||||
X--path=*) searchpath=`echo "$1" | sed s/.*=//`; shift;;
|
||||
X--*) shift;;
|
||||
X*) break;;
|
||||
esac
|
||||
done
|
||||
|
||||
if test $# -lt 2; then
|
||||
usage 1>&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
module="$1"
|
||||
shift
|
||||
document="$1"
|
||||
shift
|
||||
|
||||
quiet="1"
|
||||
if test $verbose = "1"; then
|
||||
quiet="0"
|
||||
fi
|
||||
|
||||
if test $uninstalled = yes; then
|
||||
# this does not work from buiddir!=srcdir
|
||||
gtkdocdir=`dirname $0`
|
||||
# traditional Bourne shells may not support -e here, use -f
|
||||
if test ! -f $gtkdocdir/gtk-doc.xsl; then
|
||||
# try to src dir (set from makefiles) too
|
||||
if test -f $ABS_TOP_SRCDIR/gtk-doc.xsl; then
|
||||
gtkdocdir=$ABS_TOP_SRCDIR
|
||||
fi
|
||||
fi
|
||||
styledir=$gtkdocdir/style
|
||||
#echo "uninstalled, gtkdocdir=$gtkdocdir, cwd=$PWD"
|
||||
else
|
||||
# the first two are needed to resolve datadir
|
||||
prefix=/usr
|
||||
datarootdir=${prefix}/share
|
||||
gtkdocdir=${datarootdir}/gtk-doc/data
|
||||
styledir=$gtkdocdir
|
||||
fi
|
||||
|
||||
# we could do "$path_option $PWD "
|
||||
# to avoid needing rewriting entities that are copied from the header
|
||||
# into docs under xml
|
||||
if test "X$searchpath" = "X"; then
|
||||
path_arg=
|
||||
else
|
||||
path_arg="--path $searchpath"
|
||||
fi
|
||||
|
||||
# profiling
|
||||
profile_args=""
|
||||
if test "$GTKDOC_PROFILE" != ""; then
|
||||
profile_args="--profile"
|
||||
fi
|
||||
|
||||
#echo /usr/bin/xsltproc $path_arg --nonet --xinclude \
|
||||
# --stringparam gtkdoc.bookname $module \
|
||||
# --stringparam gtkdoc.version "1.25" \
|
||||
# "$@" $gtkdocdir/gtk-doc.xsl "$document"
|
||||
/usr/bin/xsltproc 2>profile.txt $profile_args $path_arg --nonet --xinclude \
|
||||
--stringparam gtkdoc.bookname $module \
|
||||
--stringparam gtkdoc.version "1.25" \
|
||||
--stringparam chunk.quietly $quiet \
|
||||
--stringparam chunker.output.quiet $quiet \
|
||||
"$@" $gtkdocdir/gtk-doc.xsl "$document" || exit $?
|
||||
|
||||
# profiling
|
||||
if test "$GTKDOC_PROFILE" != ""; then
|
||||
cat profile.txt | gprof2dot.py -e 0.01 -n 0.01 | dot -Tpng -o profile.png
|
||||
else
|
||||
rm profile.txt
|
||||
fi
|
||||
|
||||
# copy navigation images and stylesheets to html directory ...
|
||||
cp -f $styledir/*.png $styledir/*.css ./
|
||||
|
||||
|
||||
echo "timestamp" > ../html.stamp
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 56 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 37 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
|
|
@ -39,7 +39,7 @@
|
|||
<xi:include href="xml/function-list.xml"/>
|
||||
<xi:include href="xml/file-format.xml"/>
|
||||
<xi:include href="xml/using-threads.xml"/>
|
||||
<xi:include href="xml/whatsnew-8.5.xml"/>
|
||||
<xi:include href="xml/How-it-works.xml"/>
|
||||
</chapter>
|
||||
|
||||
<chapter>
|
||||
|
|
|
|||
|
|
@ -11,11 +11,11 @@ $endif$
|
|||
<refmeta>
|
||||
<refentrytitle>$title$</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>VIPS Library</refmiscinfo>
|
||||
<refmiscinfo>libvips</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>VIPS</refname>
|
||||
<refname>libvips</refname>
|
||||
<refpurpose>$title$</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
|
|
|
|||
|
|
@ -1,184 +0,0 @@
|
|||
libvips 8.5 should be out by the end of March 2017. This page introduces the
|
||||
main features.
|
||||
|
||||
## New operators
|
||||
|
||||
Almost all of the logic from the `vipsthumbnail` program is now in a pair of
|
||||
new operators, `vips_thumbnail()` and `vips_thumbnail_buffer()`. These are very
|
||||
handy for the various scripting languages with vips bindings: you can now make
|
||||
a high-quality, high-speed thumbnail in PHP (for example) with just:
|
||||
|
||||
```php
|
||||
$filename = ...;
|
||||
$image = Vips\Image::thumbnail($filename, 200, ["height" => 200]);
|
||||
$image.writeToFile("my-thumbnail.jpg");
|
||||
```
|
||||
|
||||
The new thumbnail operator has also picked up some useful features:
|
||||
|
||||
* **Smart crop** A new cropping mode called `attention` searches the image for
|
||||
edges, skin tones and areas of saturated colour, and attempts to position the
|
||||
crop box over the most significant feature. There's a `vips_smartcrop()`
|
||||
operator as well.
|
||||
|
||||
* **Crop constraints** Thanks to tomasc, libvips has crop constraints. You
|
||||
can set it to only thumbnail if the image is larger or smaller than the target
|
||||
(the `<` and `>` modifiers in imagemagick), and to crop to a width or height.
|
||||
|
||||
* **Buffer sources** `vips_thumbnail_buffer()` will thumbnail an image held as
|
||||
a formatted block of data in memory. This is useful for cloud services, where
|
||||
the filesystem is often rather slow.
|
||||
|
||||
CLAHE, or Contrast-Limited Adaptive Histogram Equalisation, is a simple way to
|
||||
make local histogram equalisation more useful.
|
||||
|
||||
Plain local equalization removes
|
||||
all global brightness variation and can make images hard to understand.
|
||||
The `hist_local` operator now has a `max-slope` parameter you can use to limit
|
||||
how much equalisation can alter your image. A value of 3 generally works well.
|
||||
|
||||
## Toilet roll images
|
||||
|
||||
libvips used to let you pick single pages out of multi-page images, such
|
||||
as PDFs, but had little support for processing entire documents.
|
||||
|
||||
libvips 8.5 now has good support for toilet roll images. You can load a
|
||||
multipage image as a very tall, thin strip, process the whole thing, and write
|
||||
back to another multi-page file. The extra feature is an `n` parameter which
|
||||
gives the number of pages to load, or -1 to load all pages.
|
||||
|
||||
For example, (OME-
|
||||
TIFF)[https://www.openmicroscopy.org/site/support/ome-model/ome-tiff]
|
||||
is a standard for microscopy data that stores volumetric images as multi-page
|
||||
TIFFs. They have some (sample
|
||||
data)[https://www.openmicroscopy.org/site/support/ome-model/ome-tiff/data.html]
|
||||
including a 4D image of an embryo.
|
||||
|
||||
Each TIFF contains 10 slices. Normally you just see page 0:
|
||||
|
||||
```
|
||||
$ vipsheader tubhiswt_C0_TP13.ome.tif
|
||||
tubhiswt_C0_TP13.ome.tif: 512x512 uchar, 1 band, b-w, tiffload
|
||||
```
|
||||
|
||||
Use `n=-1` and you see all the pages as a very tall strip:
|
||||
|
||||
```
|
||||
$ vipsheader tubhiswt_C0_TP13.ome.tif[n=-1]
|
||||
tubhiswt_C0_TP13.ome.tif: 512x5120 uchar, 1 band, b-w, tiffload
|
||||
```
|
||||
|
||||
You can work with PDF, TIFF, GIF and all imagemagick-supported formats in
|
||||
this way.
|
||||
|
||||
You can write this tall strip to another file, and it will be broken up into
|
||||
pages:
|
||||
|
||||
```
|
||||
$ vips copy tubhiswt_C0_TP13.ome.tif[n=-1] x.tif
|
||||
$ vipsheader x.tif
|
||||
x.tif: 512x512 uchar, 1 band, b-w, tiffload
|
||||
$ vipsheader x.tif[n=-1]
|
||||
x.tif: 512x5120 uchar, 1 band, b-w, tiffload
|
||||
```
|
||||
|
||||
The extra magic is a `page-height` property that images carry around that says
|
||||
how long each sheet of toilet paper is.
|
||||
|
||||
There are clearly some restrictions with this style of multi-page document
|
||||
handling: all pages must have identical width, height and colour depth; and image
|
||||
processing operators have no idea they are dealing with a multi-page document,
|
||||
so if you do something like `resize`, you'll need to update `page-height`.
|
||||
You'll also need to be careful about edge effects if you're using spatial
|
||||
filters.
|
||||
|
||||
## Computation reordering
|
||||
|
||||
Thanks to the developer of
|
||||
(PhotoFlow)[https://github.com/aferrero2707/PhotoFlow], a non-destructive image
|
||||
editor with a libvips backend, libvips can now reorder computations to reduce
|
||||
recalculation. This can (sometimes) produce a dramatic speedup.
|
||||
|
||||
This has been (discussed on the libvips
|
||||
blog)[http://libvips.blogspot.co.uk/2017/01/automatic-computation-reordering.html],
|
||||
but briefly, the order in which operator arguments are evaluated can have a
|
||||
big effect on runtime due to the way libvips tries to cache and reuse results
|
||||
behind the scenes.
|
||||
|
||||
The blog post has some examples and some graphs.
|
||||
|
||||
## New sequential mode
|
||||
|
||||
libvips sequential mode has been around for a while. This is the thing libvips
|
||||
uses to stream pixels through your computer, from input file to output file,
|
||||
without having to have the whole image in memory all at the same time. When it
|
||||
works, it give a nice performance boost and a large drop in memory use.
|
||||
|
||||
There are some more complex cases where it didn't work. Consider this Python
|
||||
program:
|
||||
|
||||
```python
|
||||
#!/usr/bin/python
|
||||
|
||||
import sys
|
||||
import random
|
||||
|
||||
import gi
|
||||
gi.require_version('Vips', '8.0')
|
||||
from gi.repository import Vips
|
||||
|
||||
composite = Vips.Image.black(10000, 10000)
|
||||
|
||||
for filename in sys.argv[2:]:
|
||||
tile = Vips.Image.new_from_file(filename, access = Vips.Access.SEQUENTIAL)
|
||||
x = random.randint(0, composite.width - tile.width)
|
||||
y = random.randint(0, composite.height - tile.height)
|
||||
composite = composite.insert(tile, x, y)
|
||||
|
||||
composite.write_to_file(sys.argv[1])
|
||||
```
|
||||
|
||||
It makes a large 10,000 x 10,000 pixel image, then inserts all of the images
|
||||
you list at random positions, then writes the result.
|
||||
|
||||
You'd think this could work with sequential mode, but sadly with earlier
|
||||
libvipses it will sometimes fail. The problem is that images can cover each
|
||||
other, so while writing, libvips can discover that it only needs the bottom few
|
||||
pixels of one of the input images. The image loaders used to track the current
|
||||
read position, and if a request came in for some pixels way down the image,
|
||||
they'd assume one of the evaluation threads had run ahead of the rest and
|
||||
needed to be stalled. Once stalled, it was only restarted on a long timeout,
|
||||
causing performance to drop through the floor.
|
||||
|
||||
libvips 8.5 has a new implementation of sequential mode that changes the way
|
||||
threads are kept together as images are processed. Rather than trying to add
|
||||
constraints to load operations, instead it puts the constraints into operations
|
||||
that can cause threads to become spread out, such as vertical shrink.
|
||||
|
||||
As a result of this change, many more things can run in sequential mode, and
|
||||
out of order reads should be impossible.
|
||||
|
||||
## `libxml2` swapped out for `expat`
|
||||
|
||||
libvips has used libxml2 as its XML parser since dinosaurs roamed the Earth.
|
||||
Now libvips is based on gobject, the XML parser selected by glib, expat, makes
|
||||
more sense, since it will already be linked.
|
||||
|
||||
It's nice to be able to remove a required dependency for a change.
|
||||
|
||||
## File format support
|
||||
|
||||
As usual, there are a range of improvements to file format read and write.
|
||||
|
||||
* Thanks to a push from Felix Bünemann, TIFF now supports load and save to and
|
||||
from memory buffers.
|
||||
* `dzsave` can write to memory (as a zip file) as well.
|
||||
* Again, thanks to pushing from Felix, libvips now supports ICC, XMP and IPCT
|
||||
metadata for WebP images.
|
||||
* FITS images support `bzero` and `bscale`.
|
||||
* `tiffload` memory use is now much lower for images with large strips.
|
||||
|
||||
## Other
|
||||
|
||||
Many small bug fixes, improvements to the C++ binding. As usual, the
|
||||
ChangeLog has more detail, if you're interested.
|
||||
Loading…
Reference in New Issue