Skip to content

Commit bc24777

Browse files
jcupittjcupitt
committed
fix small things
1 parent b2b95ca commit bc24777

File tree

5 files changed

+92
-92
lines changed

5 files changed

+92
-92
lines changed

‎doc/How-it-works.md

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,15 @@ improvement by only keeping the pixels currently being processed in RAM
44
and by having an efficient, threaded image IO system. This page explains
55
how these features are implemented.
66

7-
### Images
7+
# Images
88

99
VIPS images have three dimensions: width, height and bands. Bands usually
1010
(though not always) represent colour. These three dimensions can be any
1111
size up to 2 ** 31 elements. Every band element in an image has to have the
1212
same format. A format is an 8-, 16- or 32-bit int, signed or unsigned, 32-
1313
or 64-bit float, and 64- or 128-bit complex.
1414

15-
### Regions
15+
# Regions
1616

1717
An image can be very large, much larger than the available memory, so you
1818
can't just access pixels with a pointer \*.
@@ -54,7 +54,7 @@ for a section of the file to be read in.
5454
(\* there is an image access mode where you can just use a pointer, but
5555
it's rarely used)
5656
57-
### Partial images
57+
# Partial images
5858
5959
A partial image is one where, instead of storing a value for each pixel, VIPS
6060
stores a function which can make any rectangular area of pixels on demand.
@@ -81,7 +81,7 @@ generate / stop sequence works like a thread.
8181
(\* in fact VIPS keeps a cache of calculated pixel buffers and will return
8282
a pointer to a previously-calculated buffer if it can)
8383
84-
### Operations
84+
# Operations
8585
8686
VIPS operations read input images and write output images, performing some
8787
transformation on the pixels. When an operation writes to an image the
@@ -98,7 +98,7 @@ set of mechanisms to copy image areas by just adjusting pointers. Most of
9898
the time no actual copying is necessary and you can perform operations on
9999
large images at low cost.
100100
101-
### Run-time code generation
101+
# Run-time code generation
102102
103103
VIPS uses [Orc](http://code.entropywave.com/orc/), a run-time compiler, to
104104
generate code for some operations. For example, to compute a convolution
@@ -110,7 +110,7 @@ SSE3 on most x86 processors.
110110
Run-time vector code generation typically speeds operations up by a factor
111111
of three or four.
112112
113-
### Joining operations together
113+
# Joining operations together
114114
115115
The region create / prepare / prepare / free calls you use to get pixels
116116
from an image are an exact parallel to the start / generate / generate /
@@ -143,7 +143,7 @@ each thread runs a very cheap copy of just the writeable state of the
143143
entire pipeline, threads can run with few locks. VIPS needs just four lock
144144
operations per output tile, regardless of the pipeline length or complexity.
145145
146-
### Data sources
146+
# Data sources
147147
148148
VIPS has data sources which can supply pixels for processing from a variety
149149
of sources. VIPS can stream images from files in VIPS native format, from
@@ -171,7 +171,7 @@ are demanded by different threads VIPS will move these windows up and down
171171
the file. As a result, VIPS can process images much larger than RAM, even
172172
on 32-bit machines.
173173
174-
### Data sinks
174+
# Data sinks
175175
176176
In a demand-driven system, something has to do the demanding. VIPS has a
177177
variety of data sinks that you can use to pull image data though a pipeline
@@ -210,7 +210,7 @@ ensure that there are at least two tiles for every thread)
210210
(\*\* tiles can be any shape and size, VIPS has a tile hint system that
211211
operations use to tell sinks what tile geometry they prefer)
212212
213-
### Operation cache
213+
# Operation cache
214214
215215
Because VIPS operations are free of side-effects\*, you can cache them. Every
216216
time you call an operation, VIPS searches the cache for a previous call to
@@ -225,7 +225,7 @@ the cache size by memory use or by files opened.
225225
"invalidate" signal on the image they are called on and this signal makes
226226
all downstream operations and caches drop their contents.)
227227
228-
### Operation database and APIs
228+
# Operation database and APIs
229229
230230
VIPS has around 300 image processing operations written in this style. Each
231231
operation is a GObject class. You can use the standard GObject calls to walk
@@ -243,7 +243,7 @@ gobject-introspection. It is written in Python, so as long as you can get
243243
gobject-introspection working, you should be able to use vips. It supports
244244
python2 and python3 and works on Linux, OS X and Windows.
245245
246-
### Snip
246+
# Snip
247247
248248
The VIPS GUI, nip2, has its own scripting language called Snip. Snip is a
249249
lazy, higher-order, purely functional, object oriented language. Almost all

‎doc/Making-image-pyramids.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ operation flags: sequential nocache
5555
You can also call `vips_dzsave()` from any language with a libvips binding, or
5656
by using `.dz` or `.szi` as an output file suffix.
5757

58-
### Writing [DeepZoom](http://en.wikipedia.org/wiki/Deep_Zoom) pyramids
58+
# Writing [DeepZoom](http://en.wikipedia.org/wiki/Deep_Zoom) pyramids
5959

6060
The `--layout` option sets the basic mode of operation. With no
6161
`--layout`, dzsave writes DeepZoom pyramids. For example:
@@ -79,7 +79,7 @@ will write JPEG tiles with the quality factor set to 90. You can set any
7979
format write options you like, see the API docs for `vips_jpegsave()`
8080
for details.
8181

82-
### Writing Zoomify pyramids
82+
# Writing Zoomify pyramids
8383

8484
Use `--layout zoomify` to put dzsave into zoomify mode. For example:
8585

@@ -93,7 +93,7 @@ directories called `TileGroupn`, each containing 256 image tiles.
9393

9494
As with DeepZoom, you can use `--suffix` to set jpeg quality.
9595

96-
### Writing [Google Maps](https://developers.google.com/maps/) pyramids
96+
# Writing [Google Maps](https://developers.google.com/maps/) pyramids
9797

9898
Use `--layout google` to write Google maps-style pyramids. These are
9999
compatible with the [NYU Pathology pyramid
@@ -125,7 +125,7 @@ For example:
125125
$ vips dzsave wtc.tif gmapdir --layout google --background 0 --centre
126126
```
127127

128-
#### Other options
128+
# Other options
129129

130130
You can use `--tile-size` and `--overlap` to control how large the tiles
131131
are and how they overlap (obviously). They default to the correct values
@@ -157,7 +157,7 @@ Use `--properties` to output an XML file called `vips-properties.xml`. This
157157
contains a dump of all the metadata vips has about the image as a set of
158158
name-value pairs. It's handy with openslide image sources.
159159

160-
#### Preprocessing images
160+
# Preprocessing images
161161

162162
You can use `.dz` as a filename suffix, meaning send the image to
163163
`vips_dzsave()`. This means you can write the output of any vips operation to a
@@ -182,7 +182,7 @@ $ vips dzsave CMU-1.mrxs[level=1] x
182182
Will pull out level 1 (the half-resolution level of an MRXS slide) and
183183
make a pyramid from that.
184184

185-
#### Troubleshooting
185+
# Troubleshooting
186186

187187
If you are building vips from source you do need to check the summary at
188188
the end of configure carefully. You must have the `libgsf-1-dev` package

‎doc/Making-image-pyramids.xml

Lines changed: 45 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -131,57 +131,57 @@ $ vips dzsave wtc.tif gmapdir --layout google
131131
<programlisting>
132132
$ vips dzsave wtc.tif gmapdir --layout google --background 0 --centre
133133
</programlisting>
134-
<sect2 id="other-options">
135-
<title>Other options</title>
136-
<para>
137-
You can use <literal>--tile-size</literal> and <literal>--overlap</literal> to control how large the tiles are and how they overlap (obviously). They default to the correct values for the selected layout.
138-
</para>
139-
<para>
140-
You can use <literal>--depth</literal> to control how deep the pyramid should be. Possible values are <literal>onepixel</literal>, <literal>onetile</literal> and <literal>one</literal>. <literal>onepixel</literal> means the image is shrunk until it fits within a single pixel. <literal>onetile</literal> means shrink until it fits with a tile. <literal>one</literal> means only write one pyramid layer (the highest resolution one). It defaults to the correct value for the selected layout. <literal>--depth one</literal> is handy for slicing up a large image into tiles (rather than a pyramid).
141-
</para>
142-
<para>
143-
You can use <literal>--angle</literal> to do a 90, 180 or 270 degree rotate of an image during pyramid write.
144-
</para>
145-
<para>
146-
You can use <literal>--container</literal> to set the container type. Normally dzsave will write a tree of directories, but with <literal>--container zip</literal> you’ll get a zip file instead. Use .zip as the directory suffix to turn on zip format automatically:
147-
</para>
148-
<programlisting>
134+
</refsect3>
135+
<refsect3 id="other-options">
136+
<title>Other options</title>
137+
<para>
138+
You can use <literal>--tile-size</literal> and <literal>--overlap</literal> to control how large the tiles are and how they overlap (obviously). They default to the correct values for the selected layout.
139+
</para>
140+
<para>
141+
You can use <literal>--depth</literal> to control how deep the pyramid should be. Possible values are <literal>onepixel</literal>, <literal>onetile</literal> and <literal>one</literal>. <literal>onepixel</literal> means the image is shrunk until it fits within a single pixel. <literal>onetile</literal> means shrink until it fits with a tile. <literal>one</literal> means only write one pyramid layer (the highest resolution one). It defaults to the correct value for the selected layout. <literal>--depth one</literal> is handy for slicing up a large image into tiles (rather than a pyramid).
142+
</para>
143+
<para>
144+
You can use <literal>--angle</literal> to do a 90, 180 or 270 degree rotate of an image during pyramid write.
145+
</para>
146+
<para>
147+
You can use <literal>--container</literal> to set the container type. Normally dzsave will write a tree of directories, but with <literal>--container zip</literal> you’ll get a zip file instead. Use .zip as the directory suffix to turn on zip format automatically:
148+
</para>
149+
<programlisting>
149150
$ vips dzsave wtc.tif mypyr.zip
150151
</programlisting>
151-
<para>
152-
to write a zipfile containing the tiles. You can use <literal>.szi</literal> as a suffix to enable zip output as well.
153-
</para>
154-
<para>
155-
Use <literal>--properties</literal> to output an XML file called <literal>vips-properties.xml</literal>. This contains a dump of all the metadata vips has about the image as a set of name-value pairs. It’s handy with openslide image sources.
156-
</para>
157-
</sect2>
158-
<sect2 id="preprocessing-images">
159-
<title>Preprocessing images</title>
160-
<para>
161-
You can use <literal>.dz</literal> as a filename suffix, meaning send the image to <literal>vips_dzsave()</literal>. This means you can write the output of any vips operation to a pyramid. For example:
162-
</para>
163-
<programlisting>
152+
<para>
153+
to write a zipfile containing the tiles. You can use <literal>.szi</literal> as a suffix to enable zip output as well.
154+
</para>
155+
<para>
156+
Use <literal>--properties</literal> to output an XML file called <literal>vips-properties.xml</literal>. This contains a dump of all the metadata vips has about the image as a set of name-value pairs. It’s handy with openslide image sources.
157+
</para>
158+
</refsect3>
159+
<refsect3 id="preprocessing-images">
160+
<title>Preprocessing images</title>
161+
<para>
162+
You can use <literal>.dz</literal> as a filename suffix, meaning send the image to <literal>vips_dzsave()</literal>. This means you can write the output of any vips operation to a pyramid. For example:
163+
</para>
164+
<programlisting>
164165
$ vips extract_area huge.svs mypy.dz[layout=google] 100 100 10000 10000
165166
</programlisting>
166-
<para>
167-
The arguments to <literal>extract_area</literal> are image-in, image-out, left, top, width, height. So this command will cut out a 10,000 by 10,000 pixel area from near the top-left-hand corner of an Aperio slide image, then build a pyramid in Google layout using just those pixels.
168-
</para>
169-
<para>
170-
If you are working from OpenSlide images, you can use the shrink-on-load feature of many of those formats. For example:
171-
</para>
172-
<programlisting>
167+
<para>
168+
The arguments to <literal>extract_area</literal> are image-in, image-out, left, top, width, height. So this command will cut out a 10,000 by 10,000 pixel area from near the top-left-hand corner of an Aperio slide image, then build a pyramid in Google layout using just those pixels.
169+
</para>
170+
<para>
171+
If you are working from OpenSlide images, you can use the shrink-on-load feature of many of those formats. For example:
172+
</para>
173+
<programlisting>
173174
$ vips dzsave CMU-1.mrxs[level=1] x
174175
</programlisting>
175-
<para>
176-
Will pull out level 1 (the half-resolution level of an MRXS slide) and make a pyramid from that.
177-
</para>
178-
</sect2>
179-
<sect2 id="troubleshooting">
180-
<title>Troubleshooting</title>
181-
<para>
182-
If you are building vips from source you do need to check the summary at the end of configure carefully. You must have the <literal>libgsf-1-dev</literal> package for <literal>vips_dzsave()</literal> to work.
183-
</para>
184-
</sect2>
176+
<para>
177+
Will pull out level 1 (the half-resolution level of an MRXS slide) and make a pyramid from that.
178+
</para>
179+
</refsect3>
180+
<refsect3 id="troubleshooting">
181+
<title>Troubleshooting</title>
182+
<para>
183+
If you are building vips from source you do need to check the summary at the end of configure carefully. You must have the <literal>libgsf-1-dev</literal> package for <literal>vips_dzsave()</literal> to work.
184+
</para>
185185
</refsect3>
186186

187187

‎doc/Using-vipsthumbnail.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ The thumbnailing functionality is implemeted by
66
`vips_thumbnail_buffer()`, see the docs for details. You can use these
77
functions from any language with a libvips binding.
88

9-
### libvips options
9+
# libvips options
1010

1111
`vipsthumbnail` supports the usual range of vips command-line options. A
1212
few of them are useful:
@@ -23,7 +23,7 @@ useful to see where libvips is looping and how often.
2323
`--vips-info` shows a higher level view of the operations that `vipsthumbnail`
2424
is running. 
2525

26-
### Looping
26+
# Looping
2727

2828
vipsthumbnail can process many images in one operation. For example:
2929

@@ -43,7 +43,7 @@ much load you want to put on your system. For example:
4343
$ parallel vipsthumbnail ::: *.jpg
4444
```
4545

46-
### Thumbnail size
46+
# Thumbnail size
4747

4848
You can set the bounding box of the generated thumbnail with the `--size`
4949
option. For example:
@@ -65,7 +65,7 @@ is.
6565
You can append `<` or `>` to mean only resize if the image is smaller or larger
6666
than the target.
6767

68-
### Cropping
68+
# Cropping
6969

7070
`vipsthumbnail` normally shrinks images to fit within the box set by `--size`.
7171
You can use the `--smartcrop` option to crop to fill the box instead. Excess
@@ -88,7 +88,7 @@ down to 128 pixels across using the `attention` strategy. This one searches
8888
the image for features which might catch a human eye, see `vips_smartcrop()`
8989
for details.
9090

91-
### Linear light
91+
# Linear light
9292

9393
Shrinking images involves combining many pixels into one. Arithmetic
9494
averaging really ought to be in terms of the number of photons, but (for
@@ -108,7 +108,7 @@ done by the image libraries is done at encode time, and done in
108108
terms of CRT voltage, not light. This can make linear light thumbnailing of
109109
large images extremely slow.
110110

111-
### Output directory
111+
# Output directory
112112

113113
You set the thumbnail write parameters with the `-o`
114114
option. This is a pattern which the input filename is pasted into to
@@ -147,7 +147,7 @@ $ vipsthumbnail fred.jpg ../jim.tif -o mythumbs/tn_%s.jpg
147147
Now both input files will have thumbnails written to a subdirectory of
148148
their current directory.
149149

150-
### Output format and options
150+
# Output format and options
151151

152152
You can use `-o`
153153
to specify the thumbnail image format too. For example: 
@@ -224,7 +224,7 @@ $ ls -l x.jpg
224224
-rw-r–r– 1 john john 3600 Nov 12 21:27 x.jpg
225225
```
226226

227-
### Colour management
227+
# Colour management
228228

229229
`vipsthumbnail` will optionally put images through LittleCMS for you. You can
230230
use this to move all thumbnails to the same colour space. All web browsers
@@ -253,7 +253,7 @@ It’ll look identical to a user, but be almost half the size.
253253
You can also specify a fallback input profile to use if the image has no
254254
embedded one, but this is less useful.
255255

256-
### Auto-rotate
256+
# Auto-rotate
257257

258258
Many JPEG files have a hint set in the header giving the image orientation. If
259259
you strip out the metadata, this hint will be lost, and the image will appear
@@ -262,7 +262,7 @@ to be rotated.
262262
If you use the `--rotate` option, `vipsthumbnail` examines the image header and
263263
if there's an orientation tag, applies and removes it.
264264

265-
### Final suggestion
265+
# Final suggestion
266266

267267
Putting all this together, I suggest this as a sensible set of options:
268268

0 commit comments

Comments
 (0)