[next] [prev] [prev-tail] [tail] [up]

### 1.2 The VIPS file format

VIPS has its own very simple file format. It is used inside VIPS to hold images during computation. You can save images in VIPS format if you want, but the VIPS format is not widely used and you may have problems reading your images into other packages.

If you intend to keep an image, it’s much better to save it as TIFF, JPEG, PNG or PBM/PGM/PPM. VIPS can transparently read and write all these formats.

#### 1.2.1 VIPS file header

All VIPS image files start with a 64-byte header giving basic information about the image dimensions, see Table 1.1. This is followed by the image data. This is usually just the pixel values in native format (ie. the byte order used by the machine that wrote the file) laid out left-to-right and top-to-bottom. After the image data comes a block of optional XML which holds extra image metadata, such as ICC profiles and image history. You can use the command-line program header to extract the XML from an image and edvips to replace it, see the man pages.

The Type field, the Xres/Yres fields, and the Xoffset/Yoffset fields are advisory. VIPS maintains their value (if you convert an image to CIE L*a*b* colour space with im_XYZ2Lab(), for example, VIPS will set Type to be IM_TYPE_LAB), but never uses these values itself in determining the action of an image processing function. These fields are to help the user, and to help application programs built on VIPS which are trying to present image data to the user in a meaningful way.

The BandFmt, Coding and Type fields can take the values shown in tables 1.2, 1.3 and 1.4. The C++ and Python names for these values are slightly different, for historical reasons.

Bytes | Represent | VIPS name
0–3 | VIPS magic number (in hex, 08 f2 f6 b6) |
4–7 | Number of pels per horizontal line (integer) | Xsize
8–11 | Number of horizontal lines (integer) | Ysize
12–15 | Number of bands (integer) | Bands
16–19 | Unused (legacy) | Bbits
20–23 | Band format (eg. IM_BANDFMT_USHORT) | BandFmt
24–27 | Coding type (eg. IM_CODING_NONE) | Coding
28–31 | Type (eg. IM_TYPE_LAB) | Type
32–35 | Horizontal resolution (float, pixels mm-1) | Xres
36–39 | Vertical resolution (float, pixels mm-1) | Yres
40–43 | Unused (legacy) | Length
44–45 | Unused (legacy) | Compression
46–47 | Unused (legacy) | Level
48–51 | Horizontal offset of origin | Xoffset
52–55 | Vertical offset of origin | Yoffset
56–63 | For future expansion (all zeros for now) |
Table 1.1: | VIPS header

BandFmt | C++ and Python name | Value | Meaning
IM_BANDFMT_NOTSET | FMTNOTSET | -1 |
IM_BANDFMT_UCHAR | FMTUCHAR | 0 | Unsigned 8-bit int
IM_BANDFMT_CHAR | FMTCHAR | 1 | Signed 8-bit int
IM_BANDFMT_USHORT | FMTUSHORT | 2 | Unsigned 16-bit int
IM_BANDFMT_SHORT | FMTSHORT | 3 | Signed 16-bit int
IM_BANDFMT_UINT | FMTUINT | 4 | Unsigned 32-bit int
IM_BANDFMT_INT | FMTINT | 5 | Signed 32-bit int
IM_BANDFMT_FLOAT | FMTFLOAT | 6 | 32-bit IEEE float
IM_BANDFMT_COMPLEX | FMTCOMPLEX | 7 | Complex (2 floats)
IM_BANDFMT_DOUBLE | FMTDOUBLE | 8 | 64-bit IEEE double
IM_BANDFMT_DPCOMPLEX | FMTDPCOMPLEX | 9 | Complex (2 doubles)
Table 1.2: | Possible values for BandFmt

Coding | C++ and Python name | Value | Meaning
IM_CODING_NONE | NOCODING | 0 | VIPS computation format
IM_CODING_LABQ | LABQ | 2 | LABQ storage format
Table 1.3: | Possible values for Coding

Type | C++ and Python name | Value | Meaning
IM_TYPE_MULTIBAND | MULTIBAND | 0 | Some multiband image
IM_TYPE_B_W | B_W | 1 | Some single band image
IM_TYPE_HISTOGRAM | HISTOGRAM | 10 | Histogram or LUT
IM_TYPE_FOURIER | FOURIER | 24 | Image in Fourier space
IM_TYPE_XYZ | XYZ | 12 | CIE XYZ colour space
IM_TYPE_LAB | LAB | 13 | CIE L*a*b* colour space
IM_TYPE_CMYK | CMYK | 15 | im_icc_export()
IM_TYPE_LABQ | LABQ | 16 | 32-bit CIE L*a*b*
IM_TYPE_RGB | RGB | 17 | Some RGB
IM_TYPE_UCS | UCS | 18 | UCS(1:1) colour space
IM_TYPE_LCH | LCH | 19 | CIE LCh colour space
IM_TYPE_LABS | LABS | 21 | 48-bit CIE L*a*b*
IM_TYPE_sRGB | sRGB | 22 | sRGB colour space
IM_TYPE_YXY | YXY | 23 | CIE Yxy colour space
IM_TYPE_RGB16 | RGB16 | 25 | 16-bit RGB
IM_TYPE_GREY16 | GREY16 | 26 | 16-bit monochrome
Table 1.4: | Possible values for Type

#### 1.2.2 Computation formats

This type of image has Coding set to IM_CODING_NONE. The header is then followed by a large array of pixels, laid out left-to-right, top-to-bottom. Each pixel contains the specified number of bands. Each band has the specified band format, which may be an 8-, 16- or 32-bit integer (either signed or unsigned), a single or double precision IEEE floating point number, or a pair of single or double precision floats forming a complex number.

All values are stored in the host-machine’s native number representation (that is, either most-significant first, as in SPARC and 680x0 machines, or least-significant first, for Intel and DEC machines). The VIPS library will automatically byte-swap for you if necessary, but this can be slow.

#### 1.2.3 Storage formats

All storage formats have other values for the Coding field. This release supports only IM_CODING_LABQ format.

IM_CODING_LABQ stores L*, a* and b* for each pixel, 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.

This format is a little awkward to process. Some VIPS functions can work directly on IM_CODING_LABQ images (im_extract(), for example), but most will require you to unpack the image to one of the computation formats (for example with im_LabQ2Lab()) first.

[next] [prev] [prev-tail] [front] [up]