VipsFormat

typedef struct _VipsFormat VipsFormat;

Actually, we never make VipsFormat objects, we just use virtual methods on the class object. It is defined as:

1
2
3
4
5
6
7
8
9
10
11

typedef struct _VipsFormatClass {
  VipsObjectClass parent_class;

  gboolean (*is_a)( const char *filename );
  int (*header)( const char *filename, IMAGE *out );
  int (*load)( const char *filename, IMAGE *out );
  int (*save)( IMAGE *in, const char *filename );
  VipsFormatFlags (*get_flags)( const char *filename );
  int priority;
  const char **suffs;
} VipsFormatClass;

Add a new format to VIPS by subclassing VipsFormat. Subclasses need to implement at least load() or save().

These members are:

You should also define nickname and description in VipsObject.

At the command-line, use:

1

vips --list classes | grep Format

To see a list of all the supported formats.

For example, the TIFF format is defined like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

typedef VipsFormat VipsFormatTiff;
typedef VipsFormatClass VipsFormatTiffClass;

static void
vips_format_tiff_class_init( VipsFormatTiffClass *class )
{
    VipsObjectClass *object_class = (VipsObjectClass *) class;
    VipsFormatClass *format_class = (VipsFormatClass *) class;

    object_class->nickname = "tiff";
    object_class->description = _( "TIFF" );

    format_class->is_a = istiff;
    format_class->header = tiff2vips_header;
    format_class->load = im_tiff2vips;
    format_class->save = im_vips2tiff;
    format_class->get_flags = tiff_flags;
    format_class->suffs = tiff_suffs;
}

static void
vips_format_tiff_init( VipsFormatTiff *object )
{
}

G_DEFINE_TYPE( VipsFormatTiff, vips_format_tiff, VIPS_TYPE_FORMAT );

Then call vips_format_tiff_get_type() somewhere in your init code to link the format into VIPS (though of course the tiff format is linked in for you already).

VipsFormatClass

typedef struct {
	VipsObjectClass parent_class;

	/* Is a file in this format.
	 */
	gboolean (*is_a)( const char * );

	/* Read just the header into the VipsImage.
	 */
	int (*header)( const char *, VipsImage * );

	/* Load the whole image.
	 */
	int (*load)( const char *, VipsImage * );

	/* Write the VipsImage to the file in this format.
	 */
	int (*save)( VipsImage *, const char * );

	/* Get the flags for this file in this format.
	 */
	VipsFormatFlags (*get_flags)( const char * );

	/* Loop over formats in this order, default 0. We need this because
	 * some formats can be read by several loaders (eg. tiff can be read
	 * by the libMagick loader as well as by the tiff loader), and we want
	 * to make sure the better loader comes first.
	 */
	int priority;

	/* Null-terminated list of allowed suffixes, eg. ".tif", ".tiff".
	 */
	const char **suffs;
} VipsFormatClass;

enum VipsFormatFlags

typedef enum {
	VIPS_FORMAT_NONE = 0,		/* No flags set */
	VIPS_FORMAT_PARTIAL = 1, /* Lazy read OK (eg. tiled tiff) */
	VIPS_FORMAT_BIGENDIAN = 2 /* Most-significant byte first */
} VipsFormatFlags;

Some hints about the image loader.

VIPS_FORMAT_PARTIAL means that the image can be read directly from the file without needing to be unpacked to a temporary image first.

VIPS_FORMAT_BIGENDIAN means that image pixels are most-significant byte first. Depending on the native byte order of the host machine, you may need to swap bytes. See im_copy_swap().

im_analyze2vips ()

int                 im_analyze2vips                     (const char *filename,
                                                         VipsImage *out);

Load an Analyze 6.0 file. If filename is "fred.img", this will look for an image header called "fred.hdr" and pixel data in "fred.img". You can also load "fred" or "fred.hdr".

Images are loaded lazilly and byte-swapped, if necessary. The Analyze metadata is read and attached.

See also: VipsFormat, im_meta_get(), im_grid().

im_bufjpeg2vips ()

int                 im_bufjpeg2vips                     (void *buf,
                                                         size_t len,
                                                         VipsImage *out,
                                                         gboolean header_only);

Read a JPEG-formatted memory block into a VIPS image. It can read most 8-bit JPEG images, including CMYK and YCbCr.

This function is handy for processing JPEG image thumbnails.

See also: VipsFormat, im_jpeg2vips().

im_csv2vips ()

int                 im_csv2vips                         (const char *filename,
                                                         VipsImage *out);

Load a CSV (comma-separated values) file. The output image is always 1 band (monochrome), IM_BANDFMT_DOUBLE. The reader is deliberately rather fussy: it will fail if there are any short lines, or if the file is too short. It will ignore lines that are too long.

Read options can be embedded in the filename. The options can be given in any order and are:

For example:

1

im_csv2vips( "fred.csv:skip:58,sep:\,,line:3", out );

Will read three lines starting at line 59, with comma as the only allowed separator. Note that the ',' has to be escaped with a backslash.

See also: VipsFormat, im_vips2csv(), im_read_dmask(), im_ppm2vips().

im_exr2vips ()

int                 im_exr2vips                         (const char *filename,
                                                         VipsImage *out);

Read a OpenEXR file into a VIPS image.

The reader can handle scanline and tiled OpenEXR images. It can't handle OpenEXR colour management, image attributes, many pixel formats, anything other than RGBA.

This reader uses the rather limited OpenEXR C API. It should really be redone in C++.

See also: VipsFormat.

im_fits2vips ()

int                 im_fits2vips                        (const char *filename,
                                                         VipsImage *out);

Read a FITS image file into a VIPS image.

See also: im_vips2fits(), VipsFormat.

im_jpeg2vips ()

int                 im_jpeg2vips                        (const char *filename,
                                                         VipsImage *out);

Read a JPEG file into a VIPS image. It can read most 8-bit JPEG images, including CMYK and YCbCr.

You can embed options in the filename. They have the form:

1

filename.jpg:<span class="emphasis"><em>shrink-factor</em></span>,<span class="emphasis"><em>fail</em></span>

Example:

1
2

im_jpeg2vips( "fred.jpg:8" out );
im_jpeg2vips( "fred.jpg:,fail" out );

The first example will shrink by a factor of 8 during load. The second will fail with an error if there are any problems loading the file.

Any embedded ICC profiles are ignored: you always just get the RGB from the file. Instead, the embedded profile will be attached to the image as metadata. You need to use something like im_icc_import() to get CIE values from the file. Any EXIF data is also attached as VIPS metadata.

The int metadata item "jpeg-multiscan" is set to the result of jpeg_has_multiple_scans(). Interlaced jpeg images need a large amount of memory to load, so this field gives callers a chance to handle these images differently.

The EXIF thumbnail, if present, is attached to the image as "jpeg-thumbnail-data". See im_meta_get_blob().

See also: VipsFormat, im_vips2jpeg().

im_magick2vips ()

int                 im_magick2vips                      (const char *filename,
                                                         VipsImage *out);

Read in an image using libMagick, the ImageMagick library. This library can read more than 80 file formats, including SVG, BMP, EPS, DICOM and many others. The reader can handle any ImageMagick image, including the float and double formats. It will work with any quantum size, including HDR. Any metadata attached to the libMagick image is copied on to the VIPS image.

The reader should also work with most versions of GraphicsMagick.

See also: VipsFormat.

im_mat2vips ()

int                 im_mat2vips                         (const char *filename,
                                                         VipsImage *out);

Read a Matlab save file into a VIPS image.

This operation searches the save file for the first array variable with between 1 and 3 dimensions and loads it as an image. It will not handle complex images. It does not handle sparse matrices.

See also: VipsFormat.

im_png2vips ()

int                 im_png2vips                         (const char *filename,
                                                         VipsImage *out);

Read a PNG file into a VIPS image. It can read all png images, including 8- and 16-bit images, 1 and 3 channel, with and without an alpha channel.

There is no support for embedded ICC profiles.

See also: VipsFormat, im_vips2png().

im_ppm2vips ()

int                 im_ppm2vips                         (const char *filename,
                                                         VipsImage *out);

Read a PPM/PBM/PGM/PFM file into a VIPS image. It can read 1, 8, 16 and 32 bit images, colour or monochrome, stored in binary or in ASCII. One bit images become 8 bit VIPS images, with 0 and 255 for 0 and 1.

PFM images have the scale factor attached as "pfm-scale".

See also: VipsFormat, im_vips2ppm(), im_meta_get_double()

im_rad2vips ()

int                 im_rad2vips                         (const char *filename,
                                                         VipsImage *out);

Read a Radiance (HDR) file into a VIPS image.

Radiance files are read as IM_CODING_RAD. They have one byte for each of red, green and blue, and one byte of shared exponent. Some operations (like im_extract_area()) can work directly with images in this format, but mmany (all the arithmetic operations, for example) will not. unpack IM_CODING_RAD images to 3 band float with im_rad2float() if you want to do arithmetic on them.

This operation ignores some header fields, like VIEW and DATE. It will not rotate/flip as the FORMAT string asks.

Sections of this reader from Greg Ward and Radiance with kind permission.

See also: VipsFormat, im_rad2float(), im_vips2rad().

im_raw2vips ()

int                 im_raw2vips                         (const char *filename,
                                                         VipsImage *out,
                                                         int width,
                                                         int height,
                                                         int bpp,
                                                         int offset);

This operation mmaps the file, setting out so that access to that image will read from the file.

Use functions like im_copy_morph() to set the pixel type, byte ordering and so on.

See also: VipsFormat, im_vips2raw().

im_tiff2vips ()

int                 im_tiff2vips                        (const char *filename,
                                                         VipsImage *out);

Read a TIFF file into a VIPS image. It is a full baseline TIFF 6 reader, with extensions for tiled images, multipage images, LAB colour space, pyramidal images and JPEG compression. including CMYK and YCbCr.

You can embed a page number in the filename. For example:

1

im_tiff2vips( "fred.tif:23", out );

Will read page 23. By default, the operation reads the first page.

Any ICC profile is read out and attached to the VIPS image.

See also: VipsFormat, im_vips2tiff().

im_tile_cache ()

int                 im_tile_cache                       (VipsImage *in,
                                                         VipsImage *out,
                                                         int tile_width,
                                                         int tile_height,
                                                         int max_tiles);

This operation behaves rather like im_copy() between images in and out, except that it keeps a cache of computed pixels. This cache is made of up to max_tiles tiles (a value of -1 for means any number of tiles), and each tile is of size tile_width by tile_height pixels. Each cache tile is made with a single call to im_prepare().

This is a lower-level operation than im_cache() since it does no subdivision. It is suitable for caching the output of operations like im_exr2vips() on tiled images.

See also: im_cache().

im_vips2bufjpeg ()

int                 im_vips2bufjpeg                     (VipsImage *in,
                                                         VipsImage *out,
                                                         int qfac,
                                                         char **obuf,
                                                         int *olen);

As im_vips2jpeg(), but save as a memory buffer. The memory is allocated local to out (that is, when out is closed the memory will be released, pass NULL to release yourself).

The address of the buffer is returned in obuf, the length of the buffer in olen. olen should really be a size_t rather than an int :-(

See also: VipsFormat, im_vips2jpeg().

im_vips2bufpng ()

int                 im_vips2bufpng                      (VipsImage *in,
                                                         VipsImage *out,
                                                         int compression,
                                                         int interlace,
                                                         char **obuf,
                                                         size_t *olen);

As im_vips2png(), but save as a memory buffer. The memory is allocated local to out (that is, when out is closed the memory will be released, pass NULL to release yourself).

The address of the buffer is returned in obuf, the length of the buffer in olen.

See also: VipsFormat, im_vips2png().

im_vips2csv ()

int                 im_vips2csv                         (VipsImage *in,
                                                         const char *filename);

Save a CSV (comma-separated values) file. The image is written one line of text per scanline. Complex numbers are written as "(real,imaginary)" and will need extra parsing I guess. The image must have a single band.

Write options can be embedded in the filename. The options can be given in any order and are:

For example:

1

im_csv2vips( in, "fred.csv:sep:\t" );

Will write to fred.csv, separating numbers with tab characters.

See also: VipsFormat, im_csv2vips(), im_write_dmask(), im_vips2ppm().

im_vips2fits ()

int                 im_vips2fits                        (VipsImage *in,
                                                         const char *filename);

Write in to filename in FITS format.

See also: im_fits2vips(), VipsFormat.

im_vips2jpeg ()

int                 im_vips2jpeg                        (VipsImage *in,
                                                         const char *filename);

Write a VIPS image to a file as JPEG.

You can embed options in the filename. They have the form:

1

filename.jpg:<span class="emphasis"><em>compression</em></span>,<span class="emphasis"><em>profile</em></span>

If no profile is specified in the save string and the VIPS header contains an ICC profile named IM_META_ICC_NAME ("icc-profile-data"), the profile from the VIPS header will be attached.

The image is automatically converted to RGB, Monochrome or CMYK before saving. Any metadata attached to the image is saved as EXIF, if possible.

Example:

1

im_vips2jpeg( in, "fred.jpg:99,none" );

Will write "fred.jpg" at high-quality with no ICC profile.

See also: VipsFormat, im_jpeg2vips().

im_vips2mimejpeg ()

int                 im_vips2mimejpeg                    (VipsImage *in,
                                                         int qfac);

As im_vips2jpeg(), but save as a mime jpeg on stdout.

See also: VipsFormat, im_vips2jpeg().

im_vips2png ()

int                 im_vips2png                         (VipsImage *in,
                                                         const char *filename);

Write a VIPS image to a file as PNG.

You can embed options in the filename. They have the form:

1

filename.png:<span class="emphasis"><em>compression</em></span>,<span class="emphasis"><em>interlace</em></span>

There is no support for attaching ICC profiles to PNG images.

The image is automatically converted to RGB, RGBA, Monochrome or Mono + alpha before saving. Images with more than one byte per band element are saved as 16-bit PNG, others are saved as 8-bit PNG.

Example:

1

im_vips2png( in, "fred.png:0,1" );

Will write "fred.png" with no compression and with ADAM7 interlacing.

See also: VipsFormat, im_png2vips().

im_vips2ppm ()

int                 im_vips2ppm                         (VipsImage *in,
                                                         const char *filename);

Write a VIPS image to a file as PPM. It can write 8, 16 or 32 bit unsigned integer images, float images, colour or monochrome, stored as binary or ASCII. Integer images of more than 8 bits can only be stored in ASCII.

When writing float (PFM) images the scale factor is set from the "pfm-scale" metadata.

The storage format is indicated by a filename extension, for example:

1

im_vips2ppm( im, "fred.ppm:ascii" )

will write to "fred.ppm" in ascii format. The default is binary.

See also: VipsFormat, im_ppm2vips(), im_meta_set_double().

im_vips2rad ()

int                 im_vips2rad                         (VipsImage *in,
                                                         const char *filename);

Write a VIPS image in Radiance (HDR) format.

This operation needs an IM_CODING_RAD image, or a three-band float image.

Sections of this reader from Greg Ward and Radiance with kind permission.

See also: VipsFormat, im_float2rad(), im_rad2vips().

im_vips2raw ()

int                 im_vips2raw                         (VipsImage *in,
                                                         int fd);

Writes the pixels in in to the file descriptor. It's handy for writing writers for other formats.

See also: VipsFormat, im_raw2vips().

im_vips2tiff ()

int                 im_vips2tiff                        (VipsImage *in,
                                                         const char *filename);

Write a VIPS image to a file as TIFF.

You can embed options in the filename. They have the form:

1

filename.tif:<span class="emphasis"><em>compression</em></span>,<span class="emphasis"><em>layout</em></span>,<span class="emphasis"><em>multi-res</em></span>,<span class="emphasis"><em>format</em></span>,<span class="emphasis"><em>resolution</em></span>,<span class="emphasis"><em>icc</em></span>, <span class="emphasis"><em>bigtiff</em></span>

Example:

1

im_vips2jpeg( in, "fred.tif:jpeg,tile,pyramid" );

Will write "fred.tif" as a tiled jpeg-compressed pyramid.

1

im_vips2jpeg( in, "fred.tif:packbits,tile,,onebit" );

Writes a tiled one bit TIFF image (provided fred.v is a one band 8 bit image) compressed with packbits.

See also: VipsFormat, im_tiff2vips().

vips_format_for_file ()

VipsFormatClass *   vips_format_for_file                (const char *filename);

Searches for a format you could use to load a file.

See also: vips_format_read(), vips_format_for_name().

vips_format_for_name ()

VipsFormatClass *   vips_format_for_name                (const char *filename);

Searches for a format you could use to save a file.

See also: vips_format_write(), vips_format_for_file().

vips_format_get_flags ()

VipsFormatFlags     vips_format_get_flags               (VipsFormatClass *format,
                                                         const char *filename);

Get a set of flags for this file.

vips_format_map ()

void *              vips_format_map                     (VipsSListMap2Fn fn,
                                                         void *a,
                                                         void *b);

Apply a function to every VipsFormatClass that VIPS knows about. Formats are presented to the function in priority order.

Like all VIPS map functions, if fn returns NULL, iteration continues. If it returns non-NULL, iteration terminates and that value is returned. The map function returns NULL if all calls return NULL.

See also: im_slist_map().

vips_format_read ()

int                 vips_format_read                    (const char *filename,
                                                         VipsImage *out);

Searches for a format for this file, then loads the file into out.

See also: vips_format_write().

vips_format_write ()

int                 vips_format_write                   (VipsImage *in,
                                                         const char *filename);

Searches for a format for this name, then saves im to it.

See also: vips_format_read().