sergiotarxz/libvips
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

fix "how it works" in docs

Browse Source 
I tried loads of ways to fix the rendering of this page, but swapping
the sections headings is the only one that works :(
This commit is contained in:
John Cupitt 2019-07-07 17:18:48 +01:00
parent 37ef7ad231
commit bad58598f6
2 changed files with 210 additions and 210 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
doc/How-it-works.md
View File

@ -15,7 +15,7 @@ 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
**Images**
VIPS images have three dimensions: width, height and bands. Bands usually
(though not always) represent colour. These three dimensions can be any
@ -23,7 +23,7 @@ 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
**Regions**
An image can be very large, much larger than the available memory, so you
can't just access pixels with a pointer \*.
@ -65,7 +65,7 @@ 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
**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.
@ -92,7 +92,7 @@ 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
**Operations**
VIPS operations read input images and write output images, performing some
transformation on the pixels. When an operation writes to an image the
@ -109,7 +109,7 @@ 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
**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
@ -121,7 +121,7 @@ SSE3 on most x86 processors.
Run-time vector code generation typically speeds operations up by a factor
of three or four.
# Joining operations together
**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 /
@ -154,7 +154,7 @@ 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
**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
@ -182,7 +182,7 @@ 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
**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
@ -221,7 +221,7 @@ 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
**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
@ -236,7 +236,7 @@ the cache size by memory use or by files opened.
"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
**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
@ -254,7 +254,7 @@ languages](https://libvips.github.io/libvips/) on many platforms. Most of
these bindings use the introspection system to generate the binding at
run-time.
# Snip
**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

68
doc/How-it-works.xml
View File

@ -13,14 +13,15 @@
<para>
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.
</para>
<section xml:id="images">
<title>Images</title>
<para>
<emphasis role="strong">Images</emphasis>
</para>
<para>
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.
</para>
</section>
<section xml:id="regions">
<title>Regions</title>
<para>
<emphasis role="strong">Regions</emphasis>
</para>
<para>
An image can be very large, much larger than the available memory, so you can’t just access pixels with a pointer *.
</para>
@ -59,9 +60,9 @@ g_object_unref( region );
<para>
(* there is an image access mode where you can just use a pointer, but it’s rarely used)
</para>
</section>
<section xml:id="partial-images">
<title>Partial images</title>
<para>
<emphasis role="strong">Partial images</emphasis>
</para>
<para>
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.
</para>
@ -84,27 +85,27 @@ g_object_unref( region );
<para>
(* in fact VIPS keeps a cache of calculated pixel buffers and will return a pointer to a previously-calculated buffer if it can)
</para>
</section>
<section xml:id="operations">
<title>Operations</title>
<para>
<emphasis role="strong">Operations</emphasis>
</para>
<para>
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.
</para>
<para>
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.
</para>
</section>
<section xml:id="run-time-code-generation">
<title>Run-time code generation</title>
<para>
<emphasis role="strong">Run-time code generation</emphasis>
</para>
<para>
VIPS uses <link xlink:href="http://code.entropywave.com/orc/">Orc</link>, 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 <quote>compiled</quote> to the vector instruction set for your CPU, for example SSE3 on most x86 processors.
</para>
<para>
Run-time vector code generation typically speeds operations up by a factor of three or four.
</para>
</section>
<section xml:id="joining-operations-together">
<title>Joining operations together</title>
<para>
<emphasis role="strong">Joining operations together</emphasis>
</para>
<para>
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.
</para>
@ -131,11 +132,11 @@ g_object_unref( region );
<para>
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.
</para>
</section>
<section xml:id="data-sources">
<title>Data sources</title>
<para>
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. Another section in these docs explains <link xlink:href="How-it-opens-files.html">how libvips opens a file</link>. One of the sources uses the <link xlink:href="http://www.imagemagick.org">ImageMagick</link> (or optionally <link xlink:href="http://www.graphicsmagick.org">GraphicsMagick</link>) library, so VIPS can read any image format that these libraries can read.
<emphasis role="strong">Data sources</emphasis>
</para>
<para>
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. Another section in these docs explains <link xlink:href="How-it-opens-files.md.html">how libvips opens a file</link>. One of the sources uses the <link xlink:href="http://www.imagemagick.org">ImageMagick</link> (or optionally <link xlink:href="http://www.graphicsmagick.org">GraphicsMagick</link> library, so VIPS can read any image format that these libraries can read.
</para>
<para>
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.
@ -143,9 +144,9 @@ g_object_unref( region );
<para>
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.
</para>
</section>
<section xml:id="data-sinks">
<title>Data sinks</title>
<para>
<emphasis role="strong">Data sinks</emphasis>
</para>
<para>
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.
</para>
@ -181,9 +182,9 @@ g_object_unref( region );
<para>
(** tiles can be any shape and size, VIPS has a tile hint system that operations use to tell sinks what tile geometry they prefer)
</para>
</section>
<section xml:id="operation-cache">
<title>Operation cache</title>
<para>
<emphasis role="strong">Operation cache</emphasis>
</para>
<para>
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.
</para>
@ -193,9 +194,9 @@ g_object_unref( region );
<para>
(* Some vips operations DO have side effects, for example, <literal>vips_draw_circle()</literal> will draw a circle on an image. These operations emit an <quote>invalidate</quote> signal on the image they are called on and this signal makes all downstream operations and caches drop their contents.)
</para>
</section>
<section xml:id="operation-database-and-apis">
<title>Operation database and APIs</title>
<para>
<emphasis role="strong">Operation database and APIs</emphasis>
</para>
<para>
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.
</para>
@ -205,9 +206,9 @@ g_object_unref( region );
<para>
There are bindings for <link xlink:href="https://libvips.github.io/libvips/">many other languages</link> on many platforms. Most of these bindings use the introspection system to generate the binding at run-time.
</para>
</section>
<section xml:id="snip">
<title>Snip</title>
<para>
<emphasis role="strong">Snip</emphasis>
</para>
<para>
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.
</para>
@ -271,7 +272,6 @@ Math_arithmetic_item = class
<para>
Now the user can select an object and click <literal>Math / Abs</literal> to find the absolute value of that object.
</para>
</section>
</refentry>