Method

VipsImagejpegsave

Declaration [src]

int
vips_jpegsave (
  VipsImage* in,
  const char* filename,
  ...
)

Description [src]

Optional arguments:

  • Q: %gint, quality factor
  • profile: %gchararray, filename of ICC profile to attach
  • optimize_coding: %gboolean, compute optimal Huffman coding tables
  • interlace: %gboolean, write an interlaced (progressive) jpeg
  • strip: %gboolean, remove all metadata from image
  • subsample_mode: VipsForeignSubsample, chroma subsampling mode
  • trellis_quant: %gboolean, apply trellis quantisation to each 8x8 block
  • overshoot_deringing: %gboolean, overshoot samples with extreme values
  • optimize_scans: %gboolean, split DCT coefficients into separate scans
  • quant_table: %gint, quantization table index
  • restart_interval: %gint, restart interval in mcu

Write a VIPS image to a file as JPEG.

Use Q to set the JPEG compression factor. Default 75.

Use profile to give the name of a profile to be embedded in the JPEG. This does not affect the pixels which are written, just the way they are tagged. See vips_profile_load() for details on profile naming.

If no profile is specified and the VIPS header contains an ICC profile named #VIPS_META_ICC_NAME, the profile from the VIPS header will be attached.

If optimize_coding is set, the Huffman tables are optimized. This is sllightly slower and produces slightly smaller files.

If interlace is set, the jpeg files will be interlaced (progressive jpeg, in jpg parlance). These files may be better for display over a slow network conection, but need much more memory to encode and decode.

If strip is set, no EXIF data, IPTC data, ICC profile or XMP metadata is written into the output file.

Chroma subsampling is normally automatically disabled for Q >= 90. You can force the subsampling mode with subsample_mode.

If trellis_quant is set and the version of libjpeg supports it (e.g. mozjpeg >= 3.0), apply trellis quantisation to each 8x8 block. Reduces file size but increases compression time.

If overshoot_deringing is set and the version of libjpeg supports it (e.g. mozjpeg >= 3.0), apply overshooting to samples with extreme values for example 0 and 255 for 8-bit. Overshooting may reduce ringing artifacts from compression, in particular in areas where black text appears on a white background.

If optimize_scans is set and the version of libjpeg supports it (e.g. mozjpeg >= 3.0), split the spectrum of DCT coefficients into separate scans. Reduces file size but increases compression time.

If quant_table is set and the version of libjpeg supports it (e.g. mozjpeg >= 3.0) it selects the quantization table to use:

  • 0 — Tables from JPEG Annex K (vips and libjpeg default)
  • 1 — Flat table
  • 2 — Table tuned for MSSIM on Kodak image set
  • 3 — Table from ImageMagick by N. Robidoux (current mozjpeg default)
  • 4 — Table tuned for PSNR-HVS-M on Kodak image set
  • 5 — Table from Relevance of Human Vision to JPEG-DCT Compression (1992)
  • 6 — Table from DCTune Perceptual Optimization of Compressed Dental X-Rays (1997)
  • 7 — Table from A Visual Detection Model for DCT Coefficient Quantization (1993)
  • 8 — Table from An Improved Detection Model for DCT Coefficient Quantization (1993)

Quantization table 0 is the default in vips and libjpeg(-turbo), but it tends to favor detail over color accuracy, producting colored patches and stripes as well as heavy banding in flat areas at high compression ratios. Quantization table 2 is a good candidate to try if the default quantization table produces banding or color shifts and is well suited for hires images. Quantization table 3 is the default in mozjpeg and has been tuned to produce good results at the default quality setting; banding at high compression. Quantization table 4 is the most accurate at the cost of compression ratio. Tables 5-7 are based on older research papers, but generally achieve worse compression ratios and/or quality than 2 or 4.

For maximum compression with mozjpeg, a useful set of options is strip, optimize-coding, interlace, optimize-scans, trellis-quant, quant_table=3.

By default, the output stream won’t have restart markers. If a non-zero restart_interval is specified, a restart marker will be added after each specified number of MCU blocks. This makes the stream more recoverable if there are transmission errors, but also allows for some decoders to read part of the JPEG without decoding the whole stream.

The image is automatically converted to RGB, Monochrome or CMYK before saving.

EXIF data is constructed from #VIPS_META_EXIF_NAME, then modified with any other related tags on the image before being written to the file. #VIPS_META_RESOLUTION_UNIT is used to set the EXIF resolution unit. #VIPS_META_ORIENTATION is used to set the EXIF orientation tag.

IPTC as #VIPS_META_IPTC_NAME and XMP as #VIPS_META_XMP_NAME are coded and attached.

See also: vips_jpegsave_buffer(), vips_image_write_to_file().

This method is not directly available to language bindings.

Parameters

filename const char*
 

File to write to.

 The data is owned by the caller of the function.
 The value is a NUL terminated UTF-8 string.
...
 

NULL-terminated list of optional named arguments.

Return value

Returns: int
 

0 on success, -1 on error.