add file format docs
add some docs on the vips file format
This commit is contained in:
John Cupitt
parent
29fa54444e
commit
46d8b93bc3
@ -137,6 +137,7 @@ content_files = \
|
||||
using-cpp.xml \
|
||||
extending.xml \
|
||||
function-list.xml \
|
||||
file-format.xml \
|
||||
binding.xml
|
||||
|
||||
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
|
||||
@ -149,6 +150,7 @@ expand_content_files = \
|
||||
using-cpp.xml \
|
||||
extending.xml \
|
||||
function-list.xml \
|
||||
file-format.xml \
|
||||
binding.xml
|
||||
|
||||
# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
|
||||
|
||||
227
doc/reference/file-format.xml
Normal file
227
doc/reference/file-format.xml
Normal file
@ -0,0 +1,227 @@
|
||||
<?xml version="1.0"?>
|
||||
<!-- vim: set ts=2 sw=2 expandtab: -->
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
||||
]>
|
||||
<refentry id="file-format">
|
||||
<refmeta>
|
||||
<refentrytitle>The VIPS file format</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>VIPS Library</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>File format</refname>
|
||||
<refpurpose>The VIPS file format</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1 id="vips-format">
|
||||
<title>Introduction</title>
|
||||
<para>
|
||||
VIPS has a simple, native file format. It's very fast, there is no image
|
||||
size limit, and it supports
|
||||
arbitrary metadata. Although few other programs can read these images
|
||||
(though recent versions of ImageMagick do support <code>.vips</code>
|
||||
format), it can be useful as an intermediate format for command-line
|
||||
processing. For example:
|
||||
|
||||
<programlisting language="bash">
|
||||
$ vips invert input.tif t.v
|
||||
$ vips gamma t.v output.tif
|
||||
</programlisting>
|
||||
|
||||
is faster than using <code>.tif</code> for the temporary intermediate
|
||||
image. This section documents the VIPS file format.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
VIPS comes with a command-line program called
|
||||
<command>vipsedit</command> which is useful for destructively changing
|
||||
fields in a vips image. The <command>vipsheader</command> program can be
|
||||
used to extract any metadata.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
VIPS files come in three parts. First, there is a 64-byte header,
|
||||
containing an identifying magic number and a set of very basic fields,
|
||||
such as image width in pixels. Next, the image data is stored as a set
|
||||
of band-interleaved scanlines, from the top of the image to the bottom.
|
||||
Finally, after the pixel data comes an optional block of XML containing
|
||||
any extra metadata, such as ICC profiles.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="vips-format-header">
|
||||
<title>The header</title>
|
||||
<para>
|
||||
The fields in the VIPS header are always stored least-significant byte
|
||||
first (Intel ordering). Only the most basic information about the image
|
||||
is in the header: most metadata is stored in the XML extension block
|
||||
after the pixel data.
|
||||
|
||||
<table>
|
||||
<title>The VIPS header</title>
|
||||
<tgroup cols='4' align='left' colsep='1' rowsep='1'>
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Bytes</entry>
|
||||
<entry>Type</entry>
|
||||
<entry>VIPS name</entry>
|
||||
<entry>Meaning</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
|
||||
<row>
|
||||
<entry>0 -- 3</entry>
|
||||
<entry></entry>
|
||||
<entry></entry>
|
||||
<entry>VIPS magic number, 08 f2 f6 b6</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>4 -- 7</entry>
|
||||
<entry>%gint</entry>
|
||||
<entry><code>width</code></entry>
|
||||
<entry>Width of image, in pixels</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>8 -- 11</entry>
|
||||
<entry>%gint</entry>
|
||||
<entry><code>height</code></entry>
|
||||
<entry>Height of image, in pixels</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>12 -- 15</entry>
|
||||
<entry>%gint</entry>
|
||||
<entry><code>bands</code></entry>
|
||||
<entry>Number of image bands</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>16 -- 19</entry>
|
||||
<entry></entry>
|
||||
<entry></entry>
|
||||
<entry>Unused</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>20 -- 23</entry>
|
||||
<entry>#VipsBandFormat</entry>
|
||||
<entry><code>format</code></entry>
|
||||
<entry>Band format</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>24 -- 27</entry>
|
||||
<entry>#VipsCoding</entry>
|
||||
<entry><code>coding</code></entry>
|
||||
<entry>Image coding</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>28 -- 31</entry>
|
||||
<entry>#VipsInterpretation</entry>
|
||||
<entry><code>interpretation</code></entry>
|
||||
<entry>Pixel interpretation</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>32 -- 35</entry>
|
||||
<entry>%gfloat</entry>
|
||||
<entry><code>xres</code></entry>
|
||||
<entry>Horizontal resolution, in pixels per millimetre</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>36 -- 39</entry>
|
||||
<entry>%gfloat</entry>
|
||||
<entry><code>yres</code></entry>
|
||||
<entry>Vertical resolution, in pixels per millimetre</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>40 -- 47</entry>
|
||||
<entry></entry>
|
||||
<entry></entry>
|
||||
<entry>Unused</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>48 -- 51</entry>
|
||||
<entry>%gint</entry>
|
||||
<entry><code>xoffset</code></entry>
|
||||
<entry>Horizontal offset of origin, in pixels</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>52 -- 55</entry>
|
||||
<entry>%gint</entry>
|
||||
<entry><code>yoffset</code></entry>
|
||||
<entry>Vertical offset of origin, in pixels</entry>
|
||||
</row>
|
||||
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="vips-format-data">
|
||||
<title>The image data</title>
|
||||
<para>
|
||||
If <code>coding</code> is set to #VIPS_CODING_NONE, pixels are stored in
|
||||
native C format, that is, the native format of the
|
||||
machine that wrote the data. If you open a big-endian image on a
|
||||
little-endian machine, VIPS will automatically byte-swap for you.
|
||||
VIPS has 10 band formats, see #VipsBandFormat.
|
||||
Image data is stored as a simple list of scanlines, from the top of the
|
||||
image to the bottom. Pixels are band-interleaved, so RGBRGBRGBRGB,
|
||||
for example. There is no padding at the end of scanlines.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If <code>coding</code> is set to #VIPS_CODING_LABQ, each pixel is four
|
||||
bytes, with 10 bits for L* and 11 bits for each of a* and b*. These
|
||||
32 bits are packed into 4 bytes, with the most significant 8 bits of each
|
||||
value in the first 3 bytes, and the left-over bits packed into the final
|
||||
byte as 2:3:3.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If <code>coding</code> is set to #VIPS_CODING_RAD, each pixel is
|
||||
RGB or XYZ float, with 8 bytes of mantissa
|
||||
and then 8 bytes of exponent, shared between the three channels. This
|
||||
coding style is used by the Radiance family of programs (and the HDR
|
||||
format) commonly used for HDR imaging.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Other values of <code>coding</code> can set other coding styles. Use
|
||||
VIPS_IMAGE_SIZEOF_IMAGE() to calculate the size of the image data
|
||||
section.
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="vips-format-metadata">
|
||||
<title>The metadata</title>
|
||||
<para>
|
||||
Following the image data is a chunk of XML holding a simple list of
|
||||
name-value pairs. Binary data is encoded with base64. Use
|
||||
vips_image_set() and friends to set and get image metadata.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You can use <command>vipsheader -f getext x.v</command> to get the
|
||||
XML from a VIPS image, and
|
||||
<command>vipsedit --setext x.v < file.xml</command> to replace the
|
||||
XML.
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
|
||||
</refentry>
|
||||
@ -37,6 +37,7 @@
|
||||
<xi:include href="xml/binding.xml"/>
|
||||
<xi:include href="xml/extending.xml"/>
|
||||
<xi:include href="xml/function-list.xml"/>
|
||||
<xi:include href="xml/file-format.xml"/>
|
||||
</chapter>
|
||||
|
||||
<chapter>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user