sergiotarxz/libvips
sergiotarxz/libvips
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

fix up orientation docs

Browse Source 
document the new orientation system

various tiff/jpeg doc fixups too
This commit is contained in:
John Cupitt 2016-05-28 11:17:17 +01:00
parent 93d0d15f88
commit d51911cda8
6 changed files with 84 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
libvips/conversion/autorot.c
View File

@ -203,12 +203,16 @@ vips_autorot_init( VipsAutorot *autorot )
* *
* * @angle: output #VipsAngle the image was rotated by * * @angle: output #VipsAngle the image was rotated by
* *
* Look at the exif tags and rotate the image to make it upright. The * Look at the image metadata and rotate the image to make it upright. The
* orientation tag is removed from @out to prevent accidental double rotation. * #VIPS_META_ORIENTATION tag is removed from @out to prevent accidental
* double rotation.
* *
* Read @angle to find the amount the image was rotated by. * Read @angle to find the amount the image was rotated by.
* *
* See also: vips_rot(). * vips only supports the four simple rotations, it does not support the
* various mirror modes.
*
* See also: vips_autorot_get_angle(), vips_autorot_remove_angle(), vips_rot().
* *
* Returns: 0 on success, -1 on error * Returns: 0 on success, -1 on error
*/ */

29
libvips/foreign/jpegload.c
View File

@ -369,13 +369,16 @@ vips_foreign_load_jpeg_buffer_init( VipsForeignLoadJpegBuffer *buffer )
* This can be useful for detecting truncated files, for example. Normally * This can be useful for detecting truncated files, for example. Normally
* reading these produces a warning, but no fatal error. * reading these produces a warning, but no fatal error.
* *
* Setting @autorotate to %TRUE will make the loader interpret the EXIF * Setting @autorotate to %TRUE will make the loader interpret the
* Orientation field and automatically rotate the image appropriately during * orientation tag and automatically rotate the image appropriately during
* load. After rotation, the Orientation tag will be removed to prevent * load.
* accidental double-rotation.
* *
* Using @autorotate can be much slower than doing the rotate later * If @autorotate is %FALSE, the metadata field #VIPS_META_ORIENTATION is set
* in processing. See vips_autorot(). * to the value of the orientation tag. Applications may read and interpret
* this field
* as they wish later in processing. See vips_autorot(). Save
* operations will use #VIPS_META_ORIENTATION, if present, to set the
* orientation of output images.
* *
* Example: * Example:
* *
@ -388,12 +391,11 @@ vips_foreign_load_jpeg_buffer_init( VipsForeignLoadJpegBuffer *buffer )
* *
* Any embedded ICC profiles are ignored: you always just get the RGB from * 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 * the file. Instead, the embedded profile will be attached to the image as
* @VIPS_META_ICC_NAME ("icc-profile-data"). You need to use something like * #VIPS_META_ICC_NAME. You need to use something like
* vips_icc_import() to get CIE values from the file. * vips_icc_import() to get CIE values from the file.
* *
* EXIF metadata is attached as @VIPS_META_EXIF_NAME ("exif-data"), IPCT as * EXIF metadata is attached as #VIPS_META_EXIF_NAME, IPCT as
* @VIPS_META_IPCT_NAME ("ipct-data"), and XMP as VIPS_META_XMP_NAME * #VIPS_META_IPCT_NAME, and XMP as #VIPS_META_XMP_NAME.
* ("xmp-data").
* *
* The int metadata item "jpeg-multiscan" is set to the result of * The int metadata item "jpeg-multiscan" is set to the result of
* jpeg_has_multiple_scans(). Interlaced jpeg images need a large amount of * jpeg_has_multiple_scans(). Interlaced jpeg images need a large amount of
@ -403,10 +405,7 @@ vips_foreign_load_jpeg_buffer_init( VipsForeignLoadJpegBuffer *buffer )
* The EXIF thumbnail, if present, is attached to the image as * The EXIF thumbnail, if present, is attached to the image as
* "jpeg-thumbnail-data". See vips_image_get_blob(). * "jpeg-thumbnail-data". See vips_image_get_blob().
* *
* This function only reads the image header and does not decompress any pixel * See also: vips_jpegload_buffer(), vips_image_new_from_file(), vips_autorot().
* data. Decompression only occurs when pixels are accessed.
*
* See also: vips_jpegload_buffer(), vips_image_new_from_file().
* *
* Returns: 0 on success, -1 on error. * Returns: 0 on success, -1 on error.
*/ */
@ -434,6 +433,8 @@ vips_jpegload( const char *filename, VipsImage **out, ... )
* *
* * @shrink: %gint, shrink by this much on load * * @shrink: %gint, shrink by this much on load
* * @fail: %gboolean, fail on warnings * * @fail: %gboolean, fail on warnings
* * @autorotate: %gboolean, use exif Orientation tag to rotate the image
* during load
* *
* Read a JPEG-formatted memory block into a VIPS image. Exactly as * Read a JPEG-formatted memory block into a VIPS image. Exactly as
* vips_jpegload(), but read from a memory buffer. * vips_jpegload(), but read from a memory buffer.

23
libvips/foreign/jpegsave.c
View File

@ -437,19 +437,9 @@ vips_foreign_save_jpeg_mime_init( VipsForeignSaveJpegMime *mime )
* "don't attach a profile". * "don't attach a profile".
* *
* If no profile is specified and the VIPS header * If no profile is specified and the VIPS header
* contains an ICC profile named VIPS_META_ICC_NAME ("icc-profile-data"), the * contains an ICC profile named #VIPS_META_ICC_NAME, the
* profile from the VIPS header will be attached. * profile from the VIPS header will be attached.
* *
* The image is automatically converted to RGB, Monochrome or CMYK before
* saving.
*
* EXIF data is constructed from @VIPS_META_EXIF_NAME ("exif-data"), then
* modified with any other related tags on the image before being written to
* the file.
*
* IPCT as @VIPS_META_IPCT_NAME ("ipct-data") and XMP as VIPS_META_XMP_NAME
* ("xmp-data") are coded and attached.
*
* If @optimize_coding is set, the Huffman tables are optimised. This is * If @optimize_coding is set, the Huffman tables are optimised. This is
* sllightly slower and produces slightly smaller files. * sllightly slower and produces slightly smaller files.
* *
@ -504,6 +494,17 @@ vips_foreign_save_jpeg_mime_init( VipsForeignSaveJpegMime *mime )
* Tables 5-7 are based on older research papers, but generally achieve worse * Tables 5-7 are based on older research papers, but generally achieve worse
* compression ratios and/or quality than 2 or 4. * compression ratios and/or quality than 2 or 4.
* *
* 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.
*
* IPCT as #VIPS_META_IPCT_NAME and XMP as #VIPS_META_XMP_NAME
* are coded and attached.
*
* See also: vips_jpegsave_buffer(), vips_image_write_to_file(). * See also: vips_jpegsave_buffer(), vips_image_write_to_file().
* *
* Returns: 0 on success, -1 on error. * Returns: 0 on success, -1 on error.

27
libvips/foreign/tiffload.c
View File

@ -302,7 +302,7 @@ vips_foreign_load_tiff_buffer_init( VipsForeignLoadTiffBuffer *buffer )
* Optional arguments: * Optional arguments:
* *
* * @page: int, load this page * * @page: int, load this page
* * @autorotate: %gboolean, use Orientation tag to rotate the image * * @autorotate: %gboolean, use orientation tag to rotate the image
* during load * during load
* *
* Read a TIFF file into a VIPS image. It is a full baseline TIFF 6 reader, * Read a TIFF file into a VIPS image. It is a full baseline TIFF 6 reader,
@ -313,17 +313,24 @@ vips_foreign_load_tiff_buffer_init( VipsForeignLoadTiffBuffer *buffer )
* 0) is read. * 0) is read.
* *
* Setting @autorotate to %TRUE will make the loader interpret the * Setting @autorotate to %TRUE will make the loader interpret the
* Orientation field and automatically rotate the image appropriately during * orientation tag and automatically rotate the image appropriately during
* load. After rotation, the Orientation tag will be removed to prevent * load.
* accidental double-rotation.
* *
* Using @autorotate can be much slower than doing the rotate later * If @autorotate is %FALSE, the metadata field #VIPS_META_ORIENTATION is set
* in processing. See vips_autorot(). * to the value of the orientation tag. Applications may read and interpret
* this field
* as they wish later in processing. See vips_autorot(). Save
* operations will use #VIPS_META_ORIENTATION, if present, to set the
* orientation of output images.
* *
* Any ICC profile is read and attached to the VIPS image. Any XMP metadata is * Any ICC profile is read and attached to the VIPS image as
* read and attached to the image. * #VIPS_META_ICC_NAME. Any XMP metadata is read and attached to the image
* as #VIPS_META_XMP_NAME. Any IPCT is attached as #VIPS_META_IPCT_NAME. The
* image description is
* attached as #VIPS_META_IMAGEDESCRIPTION. Data in the photoshop tag is
* attached as #VIPS_META_PHOTOSHOP_NAME.
* *
* See also: vips_image_new_from_file(). * See also: vips_image_new_from_file(), vips_autorot().
* *
* Returns: 0 on success, -1 on error. * Returns: 0 on success, -1 on error.
*/ */
@ -350,6 +357,8 @@ vips_tiffload( const char *filename, VipsImage **out, ... )
* Optional arguments: * Optional arguments:
* *
* * @page: %gint, load this page * * @page: %gint, load this page
* * @autorotate: %gboolean, use orientation tag to rotate the image
* during load
* *
* Read a TIFF-formatted memory block into a VIPS image. Exactly as * Read a TIFF-formatted memory block into a VIPS image. Exactly as
* vips_tiffload(), but read from a memory source. * vips_tiffload(), but read from a memory source.

21
libvips/foreign/tiffsave.c
View File

@ -319,6 +319,7 @@ vips_foreign_save_tiff_init( VipsForeignSaveTiff *tiff )
* * @xres: %gdouble horizontal resolution in pixels/mm * * @xres: %gdouble horizontal resolution in pixels/mm
* * @yres: %gdouble vertical resolution in pixels/mm * * @yres: %gdouble vertical resolution in pixels/mm
* * @bigtiff: set %TRUE to write a BigTiff file * * @bigtiff: set %TRUE to write a BigTiff file
* * @properties: set %TRUE to write an IMAGEDESCRIPTION tag
* *
* Write a VIPS image to a file as TIFF. * Write a VIPS image to a file as TIFF.
* *
@ -326,7 +327,7 @@ vips_foreign_save_tiff_init( VipsForeignSaveTiff *tiff )
* fax4, lzw, none and deflate are supported. The default is no compression. * fax4, lzw, none and deflate are supported. The default is no compression.
* JPEG compression is a good lossy compressor for photographs, packbits is * JPEG compression is a good lossy compressor for photographs, packbits is
* good for 1-bit images, and deflate is the best lossless compression TIFF * good for 1-bit images, and deflate is the best lossless compression TIFF
* can do. LZW has patent problems and is no longer recommended. * can do.
* *
* Use @Q to set the JPEG compression factor. Default 75. * Use @Q to set the JPEG compression factor. Default 75.
* *
@ -346,7 +347,7 @@ vips_foreign_save_tiff_init( VipsForeignSaveTiff *tiff )
* "don't attach a profile". * "don't attach a profile".
* *
* If no profile is specified and the VIPS header * If no profile is specified and the VIPS header
* contains an ICC profile named VIPS_META_ICC_NAME ("icc-profile-data"), the * contains an ICC profile named #VIPS_META_ICC_NAME, the
* profile from the VIPS header will be attached. * profile from the VIPS header will be attached.
* *
* Set @tile to TRUE to write a tiled tiff. By default tiff are written in * Set @tile to TRUE to write a tiled tiff. By default tiff are written in
@ -365,8 +366,8 @@ vips_foreign_save_tiff_init( VipsForeignSaveTiff *tiff )
* *
* Use @resunit to override the default resolution unit. * Use @resunit to override the default resolution unit.
* The default * The default
* resolution unit is taken from the header field "resolution-unit" * resolution unit is taken from the header field
* (#VIPS_META_RESOLUTION_UNIT in C). If this field is not set, then * #VIPS_META_RESOLUTION_UNIT. If this field is not set, then
* VIPS defaults to cm. * VIPS defaults to cm.
* *
* Use @xres and @yres to override the default horizontal and vertical * Use @xres and @yres to override the default horizontal and vertical
@ -377,8 +378,16 @@ vips_foreign_save_tiff_init( VipsForeignSaveTiff *tiff )
* Bigtiff is a variant of the TIFF * Bigtiff is a variant of the TIFF
* format that allows more than 4GB in a file. * format that allows more than 4GB in a file.
* *
* If @in has a field called VIPS_META_XMP_NAME ("xmp-data") it is written to * Set @properties to write all vips metadata to the IMAGEDESCRIPTION tag as
* the tiff image. * xml. If @properties is not set, the value of #VIPS_META_IMAGEDESCRIPTION is
* used instead.
*
* The value of #VIPS_META_XMP_NAME is written to
* the XMP tag. #VIPS_META_ORIENTATION (if set) is used to set the value of
* the orientation
* tag. #VIPS_META_IPCT (if set) is used to set the value of the IPCT tag.
* #VIPS_META_PHOTOSHOP_NAME (if set) is used to set the value of the PHOTOSHOP
* tag.
* *
* See also: vips_tiffload(), vips_image_write_to_file(). * See also: vips_tiffload(), vips_image_write_to_file().
* *

17
libvips/include/vips/header.h
View File

@ -113,6 +113,23 @@ extern "C" {
* *
* The orientation tag for this image. An int from 1 - 8 using the standard * The orientation tag for this image. An int from 1 - 8 using the standard
* exif/tiff meanings. * exif/tiff meanings.
*
* * 1 - The 0th row represents the visual top of the image, and the 0th column
* represents the visual left-hand side.
* * 2 - The 0th row represents the visual top of the image, and the 0th column
* represents the visual right-hand side.
* * 3 - The 0th row represents the visual bottom of the image, and the 0th
* column represents the visual right-hand side.
* * 4 - The 0th row represents the visual bottom of the image, and the 0th
* column represents the visual left-hand side.
* * 5 - The 0th row represents the visual left-hand side of the image, and the
* 0th column represents the visual top.
* * 6 - The 0th row represents the visual right-hand side of the image, and the
* 0th column represents the visual top.
* * 7 - The 0th row represents the visual right-hand side of the image, and the
* 0th column represents the visual bottom.
* * 8 - The 0th row represents the visual left-hand side of the image, and the
* 0th column represents the visual bottom.
*/ */
#define VIPS_META_ORIENTATION "orientation" #define VIPS_META_ORIENTATION "orientation"