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
*
* Look at the exif tags and rotate the image to make it upright. The
* orientation tag is removed from @out to prevent accidental double rotation.
* Look at the image metadata and rotate the image to make it upright. The
* #VIPS_META_ORIENTATION tag is removed from @out to prevent accidental
* double rotation.
*
* 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
*/

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
* reading these produces a warning, but no fatal error.
*
* Setting @autorotate to %TRUE will make the loader interpret the EXIF
* Orientation field and automatically rotate the image appropriately during
* load. After rotation, the Orientation tag will be removed to prevent
* accidental double-rotation.
* Setting @autorotate to %TRUE will make the loader interpret the
* orientation tag and automatically rotate the image appropriately during
* load.
*
* Using @autorotate can be much slower than doing the rotate later
* in processing. See vips_autorot().
* If @autorotate is %FALSE, the metadata field #VIPS_META_ORIENTATION is set
* 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:
*
@ -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
* 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.
*
* EXIF metadata is attached as @VIPS_META_EXIF_NAME ("exif-data"), IPCT as
* @VIPS_META_IPCT_NAME ("ipct-data"), and XMP as VIPS_META_XMP_NAME
* ("xmp-data").
* EXIF metadata is attached as #VIPS_META_EXIF_NAME, IPCT as
* #VIPS_META_IPCT_NAME, and XMP as #VIPS_META_XMP_NAME.
*
* The int metadata item "jpeg-multiscan" is set to the result 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
* "jpeg-thumbnail-data". See vips_image_get_blob().
*
* This function only reads the image header and does not decompress any pixel
* data. Decompression only occurs when pixels are accessed.
*
* See also: vips_jpegload_buffer(), vips_image_new_from_file().
* See also: vips_jpegload_buffer(), vips_image_new_from_file(), vips_autorot().
*
* 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
* * @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
* 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".
*
* 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.
*
* 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
* 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
* 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().
*
* 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:
*
* * @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
*
* 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.
*
* Setting @autorotate to %TRUE will make the loader interpret the
* Orientation field and automatically rotate the image appropriately during
* load. After rotation, the Orientation tag will be removed to prevent
* accidental double-rotation.
* orientation tag and automatically rotate the image appropriately during
* load.
*
* Using @autorotate can be much slower than doing the rotate later
* in processing. See vips_autorot().
* If @autorotate is %FALSE, the metadata field #VIPS_META_ORIENTATION is set
* 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
* read and attached to the image.
* Any ICC profile is read and attached to the VIPS image as
* #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.
*/
@ -350,6 +357,8 @@ vips_tiffload( const char *filename, VipsImage **out, ... )
* Optional arguments:
*
* * @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
* 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
* * @yres: %gdouble vertical resolution in pixels/mm
* * @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.
*
@ -326,7 +327,7 @@ vips_foreign_save_tiff_init( VipsForeignSaveTiff *tiff )
* fax4, lzw, none and deflate are supported. The default is no compression.
* JPEG compression is a good lossy compressor for photographs, packbits is
* 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.
*
@ -346,7 +347,7 @@ vips_foreign_save_tiff_init( VipsForeignSaveTiff *tiff )
* "don't attach a profile".
*
* 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.
*
* 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.
* The default
* resolution unit is taken from the header field "resolution-unit"
* (#VIPS_META_RESOLUTION_UNIT in C). If this field is not set, then
* resolution unit is taken from the header field
* #VIPS_META_RESOLUTION_UNIT. If this field is not set, then
* VIPS defaults to cm.
*
* 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
* 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
* the tiff image.
* Set @properties to write all vips metadata to the IMAGEDESCRIPTION tag as
* 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().
*

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
* 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"