From 5947a15fb7779528387e8dd7f851352ef5a52b6a Mon Sep 17 00:00:00 2001 From: Louis-Arnaud Date: Wed, 2 Sep 2026 16:48:26 +0200 Subject: [PATCH] imagick: document the image types The IMGTYPE_* constants had empty descriptions and Imagick::setImageType only repeated its own name, leaving readers to guess what an image type is and what the MATTE variants mean. Each constant now states the conversion SetImageType() performs, and the group notes that MATTE is the ImageMagick 6 name for the alpha channel, with the ALPHA spellings available as of ImageMagick 7. setType() is distinguished from setImageType(). --- reference/imagick/constants.xml | 74 +++++++++++- reference/imagick/imagick/getimagetype.xml | 124 ++++++++++----------- reference/imagick/imagick/setimagetype.xml | 39 ++++--- reference/imagick/imagick/settype.xml | 31 +++--- 4 files changed, 175 insertions(+), 93 deletions(-) diff --git a/reference/imagick/constants.xml b/reference/imagick/constants.xml index 11d2b432f076..48182b05b714 100644 --- a/reference/imagick/constants.xml +++ b/reference/imagick/constants.xml @@ -1025,7 +1025,25 @@ <constant>IMGTYPE_<replaceable>*</replaceable></constant> constants - + + An image type combines a color model with the presence or absence of an + alpha channel. + Passing one of these constants to + Imagick::setImageType converts the image to that + type. + Imagick::getImageType reports the type of an image, + but only ever returns a type that describes actual pixel data, never + imagick::IMGTYPE_UNDEFINED or + imagick::IMGTYPE_OPTIMIZE. + + + The constants whose name ends in MATTE are the variants + that carry an alpha channel; the others have none. + In ImageMagick 6 the alpha channel was known as the matte channel, and when + Imagick is built against ImageMagick 7 each of these constants also exists + under an IMGTYPE_*ALPHA name + with the same value. + imagick::IMGTYPE_UNDEFINED @@ -1033,6 +1051,9 @@ + The image type is not known. + Imagick::setImageType converts nothing for this + value, but still records it on the image. @@ -1043,6 +1064,10 @@ + Two colors only. + The image is converted to grayscale, its contrast is stretched, and every + pixel becomes either black or white depending on whether it is lighter or + darker than mid-gray; any alpha channel is discarded. @@ -1053,6 +1078,9 @@ + Shades of gray. + The image is converted to the grayscale colorspace, and any alpha channel + is discarded. @@ -1063,6 +1091,10 @@ + Shades of gray with an alpha channel. + The same as imagick::IMGTYPE_GRAYSCALE, except that + the alpha channel is kept, and if the image has none, an opaque one is + added. @@ -1073,6 +1105,10 @@ + Indexed color. + The image is converted to sRGB and, if it is not already indexed or has + more than 256 colors, it is quantized to 256 colors; any alpha channel is + discarded. @@ -1083,6 +1119,12 @@ + Indexed color with an alpha channel. + The image is converted to sRGB, the alpha channel is kept, and if the + image has none, an opaque one is added. + Unlike imagick::IMGTYPE_PALETTE, the colors are + quantized even when the image is already indexed, and the alpha channel + is included in the quantization. @@ -1093,6 +1135,8 @@ + Direct color: one red, green, and blue value per pixel, with no palette. + The image is converted to sRGB, and any alpha channel is discarded. @@ -1103,6 +1147,10 @@ + Direct color with an alpha channel. + The same as imagick::IMGTYPE_TRUECOLOR, except that + the alpha channel is kept, and if the image has none, an opaque one is + added. @@ -1113,6 +1161,9 @@ + One channel per printing ink, with no palette. + The image is converted to the CMYK colorspace, and any alpha channel is + discarded. @@ -1123,6 +1174,25 @@ + One channel per printing ink, with no palette, plus an alpha channel. + The same as imagick::IMGTYPE_COLORSEPARATION, except + that the alpha channel is kept, and if the image has none, an opaque one + is added. + + + + + + imagick::IMGTYPE_PALETTEBILEVELMATTE + (int) + + + + Indexed color with a fully transparent or fully opaque alpha channel. + The image is converted to sRGB, an opaque alpha channel is added if it + has none, that channel alone is reduced to two values, and the colors + are then quantized. + This is the type of a PNG using binary transparency. @@ -1133,6 +1203,8 @@ + Imagick::setImageType converts nothing for this + value, but still records it on the image. diff --git a/reference/imagick/imagick/getimagetype.xml b/reference/imagick/imagick/getimagetype.xml index bcf42f3e1a77..43cc14a80ff8 100644 --- a/reference/imagick/imagick/getimagetype.xml +++ b/reference/imagick/imagick/getimagetype.xml @@ -3,7 +3,7 @@ Imagick::getImageType - Gets the potential image type + Gets the image type @@ -12,9 +12,12 @@ public intImagick::getImageType - - Gets the potential image type. - + + Returns the type of the image, derived from its colorspace, its storage + class and whether it carries an alpha channel. The pixels themselves are + not examined, so the value reflects how the image is currently held rather + than the smallest type it could be reduced to. + @@ -24,66 +27,59 @@ &reftitle.returnvalues; - - Returns the potential image type. - - - - imagick::IMGTYPE_UNDEFINED - - - - - imagick::IMGTYPE_BILEVEL - - - - - imagick::IMGTYPE_GRAYSCALE - - - - - imagick::IMGTYPE_GRAYSCALEMATTE - - - - - imagick::IMGTYPE_PALETTE - - - - - imagick::IMGTYPE_PALETTEMATTE - - - - - imagick::IMGTYPE_TRUECOLOR - - - - - imagick::IMGTYPE_TRUECOLORMATTE - - - - - imagick::IMGTYPE_COLORSEPARATION - - - - - imagick::IMGTYPE_COLORSEPARATIONMATTE - - - - - imagick::IMGTYPE_OPTIMIZE - - - - + + Returns one of the following + imagick::IMGTYPE_* + constants. imagick::IMGTYPE_UNDEFINED and + imagick::IMGTYPE_OPTIMIZE are never returned. + + + + + imagick::IMGTYPE_BILEVEL + + + + + imagick::IMGTYPE_GRAYSCALE + + + + + imagick::IMGTYPE_GRAYSCALEMATTE + + + + + imagick::IMGTYPE_PALETTE + + + + + imagick::IMGTYPE_PALETTEMATTE + + + + + imagick::IMGTYPE_TRUECOLOR + + + + + imagick::IMGTYPE_TRUECOLORMATTE + + + + + imagick::IMGTYPE_COLORSEPARATION + + + + + imagick::IMGTYPE_COLORSEPARATIONMATTE + + + diff --git a/reference/imagick/imagick/setimagetype.xml b/reference/imagick/imagick/setimagetype.xml index da7b99722110..5f6b586017c7 100644 --- a/reference/imagick/imagick/setimagetype.xml +++ b/reference/imagick/imagick/setimagetype.xml @@ -12,24 +12,35 @@ public boolImagick::setImageType intimage_type - - Sets the image type. - + + Converts the image to the given type, which combines a color model with the + presence or absence of an alpha channel. + Depending on the type, this may change the colorspace, quantize the colors, + or change whether the image has an alpha channel. + + + Imagick::setImageType modifies the image itself. + To set the type that subsequent images are written with instead, use + Imagick::setType. + &reftitle.parameters; - - - - image_type - - - - - - - + + + image_type + + + One of the + imagick::IMGTYPE_* + constants. imagick::IMGTYPE_UNDEFINED and + imagick::IMGTYPE_OPTIMIZE convert nothing, but are + still recorded on the image. + + + + diff --git a/reference/imagick/imagick/settype.xml b/reference/imagick/imagick/settype.xml index 96037abeff25..9ae3e92d0870 100644 --- a/reference/imagick/imagick/settype.xml +++ b/reference/imagick/imagick/settype.xml @@ -12,24 +12,27 @@ public boolImagick::setType intimage_type - - Sets the image type attribute. - + + Sets the image type applied to images written subsequently. + To convert the current image instead, use + Imagick::setImageType. + &reftitle.parameters; - - - - image_type - - - - - - - + + + image_type + + + One of the + imagick::IMGTYPE_* + constants. + + + +