![]() |
![]() |
![]() |
VIPS Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <vips/vips.h> #define IM_D93_X0 #define IM_D93_Y0 #define IM_D93_Z0 #define IM_D75_X0 #define IM_D75_Y0 #define IM_D75_Z0 #define IM_D65_X0 #define IM_D65_Y0 #define IM_D65_Z0 #define IM_D55_X0 #define IM_D55_Y0 #define IM_D55_Z0 #define IM_D50_X0 #define IM_D50_Y0 #define IM_D50_Z0 #define IM_A_X0 #define IM_A_Y0 #define IM_A_Z0 #define IM_B_X0 #define IM_B_Y0 #define IM_B_Z0 #define IM_C_X0 #define IM_C_Y0 #define IM_C_Z0 #define IM_E_X0 #define IM_E_Y0 #define IM_E_Z0 #define IM_D3250_X0 #define IM_D3250_Y0 #define IM_D3250_Z0 void im_col_ab2Ch (float a
,float b
,float *C
,float *h
); void im_col_Ch2ab (float C
,float h
,float *a
,float *b
); void im_col_XYZ2Lab (float X
,float Y
,float Z
,float *L
,float *a
,float *b
); void im_col_Lab2XYZ (float L
,float a
,float b
,float *X
,float *Y
,float *Z
); float im_col_pythagoras (float L1
,float a1
,float b1
,float L2
,float a2
,float b2
); void im_col_make_tables_UCS (void
); float im_col_L2Lucs (float L
); float im_col_Lucs2L (float Lucs
); float im_col_C2Cucs (float C
); float im_col_Cucs2C (float Cucs
); float im_col_Ch2hucs (float C
,float h
); float im_col_Chucs2h (float C
,float hucs
); double im_col_ab2h (double a
,double b
); float im_col_dECMC (float L1
,float a1
,float b1
,float L2
,float a2
,float b2
); float im_col_dE00 (float L1
,float a1
,float b1
,float L2
,float a2
,float b2
); int im_LCh2Lab (VipsImage *in
,VipsImage *out
); int im_LabQ2XYZ (VipsImage *in
,VipsImage *out
); int im_rad2float (VipsImage *in
,VipsImage *out
); int im_float2rad (VipsImage *in
,VipsImage *out
); int im_LCh2UCS (VipsImage *in
,VipsImage *out
); int im_Lab2LCh (VipsImage *in
,VipsImage *out
); int im_Lab2LabQ (VipsImage *in
,VipsImage *out
); int im_Lab2LabS (VipsImage *in
,VipsImage *out
); int im_Lab2XYZ (VipsImage *in
,VipsImage *out
); int im_Lab2XYZ_temp (VipsImage *in
,VipsImage *out
,double X0
,double Y0
,double Z0
); int im_Lab2UCS (VipsImage *in
,VipsImage *out
); int im_LabQ2Lab (VipsImage *in
,VipsImage *out
); int im_LabQ2LabS (VipsImage *in
,VipsImage *out
); int im_LabS2LabQ (VipsImage *in
,VipsImage *out
); int im_LabS2Lab (VipsImage *in
,VipsImage *out
); int im_UCS2XYZ (VipsImage *in
,VipsImage *out
); int im_UCS2LCh (VipsImage *in
,VipsImage *out
); int im_UCS2Lab (VipsImage *in
,VipsImage *out
); int im_XYZ2Lab (VipsImage *in
,VipsImage *out
); int im_XYZ2Lab_temp (VipsImage *in
,VipsImage *out
,double X0
,double Y0
,double Z0
); int im_XYZ2UCS (VipsImage *in
,VipsImage *out
); int im_sRGB2XYZ (VipsImage *in
,VipsImage *out
); int im_XYZ2sRGB (VipsImage *in
,VipsImage *out
); int im_Yxy2XYZ (VipsImage *in
,VipsImage *out
); int im_XYZ2Yxy (VipsImage *in
,VipsImage *out
); int im_dECMC_fromLab (VipsImage *in1
,VipsImage *in2
,VipsImage *out
); int im_dE00_fromLab (VipsImage *in1
,VipsImage *in2
,VipsImage *out
); int im_dE_fromXYZ (VipsImage *in1
,VipsImage *in2
,VipsImage *out
); int im_dE_fromLab (VipsImage *in1
,VipsImage *in2
,VipsImage *out
); int im_lab_morph (VipsImage *in
,VipsImage *out
,DOUBLEMASK *mask
,double L_offset
,double L_scale
,double a_scale
,double b_scale
); enum VipsIntent; int im_icc_present (void
); int im_icc_transform (VipsImage *in
,VipsImage *out
,const char *input_profile_filename
,const char *output_profile_filename
,VipsIntent intent
); int im_icc_import (VipsImage *in
,VipsImage *out
,const char *input_profile_filename
,VipsIntent intent
); int im_icc_import_embedded (VipsImage *in
,VipsImage *out
,VipsIntent intent
); int im_icc_export_depth (VipsImage *in
,VipsImage *out
,int depth
,const char *output_profile_filename
,VipsIntent intent
); int im_icc_ac2rc (VipsImage *in
,VipsImage *out
,const char *profile_filename
);
These operators let you transform coordinates and images between colour spaces, calculate colour differences, and move to and from device spaces.
Radiance images have four 8-bits bands and store 8 bits of R, G and B and another 8 bits of exponent, common to all channels. They are widely used in the HDR imaging community.
The colour functions can be divided into three main groups. First, functions to transform images between the different colour spaces supported by VIPS: RGB (also referred to as disp), sRGB, XYZ, Yxy, Lab, LabQ, LabS, LCh and UCS). Secondly, there are a set of operations for calculating colour difference metrics. Finally, VIPS wraps LittleCMS and uses it to provide a set of operations for reading and writing images with ICC profiles.
This figure shows how the VIPS colour spaces interconvert:
The colour spaces supported by VIPS are:
LabQ
This is the principal VIPS colorimetric storage format. LabQ images have four 8-bit bands and store 10 bits of L and 11 bits of a and b.
You cannot perform calculations on LabQ
images (they are
tagged with IM_CODING_LABQ
), though a few operations such as
im_extract_area()
will work directly with them.
LabS
This format represents coordinates in CIELAB space as a three-band IM_BANDFMT_SHORT image, scaled to fit the full range of bits. It is the best format for computation, being relatively compact, quick, and accurate. Colour values expressed in this way are hard to visualise.
Lab
Lab colourspace represents CIELAB colour values with a three-band IM_BANDFMT_FLOAT image. This is the simplest format for general work: adding the constant 50 to the L channel, for example, has the expected result.
VIPS uses D65 LAB, but you can use other colour temperatures with a
little effort, see im_XYZ2Lab_temp()
.
XYZ
CIE XYZ colour space represented as a three-band IM_BANDFMT_FLOAT
image.
Yxy
CIE Yxy colour space represented as a three-band IM_BANDFMT_FLOAT
image.
RGB
(also refered to as disp
+) This is a generic 8-bit RGB
image. VIPS has a system for going to and from RGB with a simple
display structure, but it's mostly deprecated. See
disp.
Use im_icc_export()
and friends as a modern replacement.
LCh
Like Lab
, but rectangular ab
coordinates
are replaced with
polar Ch
(Chroma and hue) coordinates.
Hue angles are expressed in degrees.
UCS
A colour space based on the CMC(1:1) colour difference measurement.
This is a highly uniform colour space, much better than CIELAB for
expressing small differences. Conversions to and from
UCS
are extremely slow.
#define IM_D3250_X0 (105.6590)
Areas under curves for black body at 3250K, 2 degree observer.
void im_col_ab2Ch (float a
,float b
,float *C
,float *h
);
Calculate Ch from ab, h in degrees.
|
CIE a* value |
|
CIE b* value |
|
return Chroma |
|
return Hue angle (degrees) |
void im_col_Ch2ab (float C
,float h
,float *a
,float *b
);
Calculate ab from Ch, h in degrees.
|
Chroma |
|
Hue angle (degrees) |
|
return CIE a* value |
|
return CIE b* value |
void im_col_XYZ2Lab (float X
,float Y
,float Z
,float *L
,float *a
,float *b
);
Calculate Lab from XYZ, D65.
See also: im_XYZ2Lab_temp()
.
|
Input CIE XYZ colour |
|
Input CIE XYZ colour |
|
Input CIE XYZ colour |
|
return CIE Lab value |
|
return CIE Lab value |
|
return CIE Lab value |
void im_col_Lab2XYZ (float L
,float a
,float b
,float *X
,float *Y
,float *Z
);
Calculate XYZ from Lab, D65.
See also: im_Lab2XYZ_temp()
.
|
Input CIE Lab value |
|
Input CIE Lab value |
|
Input CIE Lab value |
|
Return CIE XYZ colour |
|
Return CIE XYZ colour |
|
Return CIE XYZ colour |
float im_col_pythagoras (float L1
,float a1
,float b1
,float L2
,float a2
,float b2
);
Pythagorean distance between two points in colour space. Lab/XYZ/UCS etc.
|
Input coordinate 1 |
|
Input coordinate 1 |
|
Input coordinate 1 |
|
Input coordinate 2 |
|
Input coordinate 2 |
|
Input coordinate 2 |
float im_col_Lucs2L (float Lucs
);
Calculate L from Lucs using a table. Call im_col_make_tables_UCS()
at
least once before using this function.
|
L ucs |
Returns : |
L* |
float im_col_Cucs2C (float Cucs
);
Calculate C from Cucs using a table.
Call im_col_make_tables_UCS()
at
least once before using this function.
|
Cucs |
Returns : |
C. |
float im_col_Ch2hucs (float C
,float h
);
Calculate hucs from C and h.
|
Chroma |
|
Hue (degrees) |
Returns : |
hucs. |
float im_col_Chucs2h (float C
,float hucs
);
Calculate h from C and hucs, using a table.
Call im_col_make_tables_UCS()
at
least once before using this function.
|
Chroma |
|
Hue ucs (degrees) |
Returns : |
h. |
float im_col_dECMC (float L1
,float a1
,float b1
,float L2
,float a2
,float b2
);
CMC colour difference from a pair of Lab values.
|
Input coordinate 1 |
|
Input coordinate 1 |
|
Input coordinate 1 |
|
Input coordinate 2 |
|
Input coordinate 2 |
|
Input coordinate 2 |
Returns : |
CMC(1:1) colour difference |
float im_col_dE00 (float L1
,float a1
,float b1
,float L2
,float a2
,float b2
);
CIEDE2000, from:
Luo, Cui, Rigg, "The Development of the CIE 2000 Colour-Difference Formula: CIEDE2000", COLOR research and application, pp 340
|
Input coordinate 1 |
|
Input coordinate 1 |
|
Input coordinate 1 |
|
Input coordinate 2 |
|
Input coordinate 2 |
|
Input coordinate 2 |
Returns : |
CIE dE2000 colour difference. |
int im_LCh2Lab (VipsImage *in
,VipsImage *out
);
Turn LCh to Lab.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_LabQ2XYZ (VipsImage *in
,VipsImage *out
);
Convert an image from LabQ (Coding == IM_CODING_LABQ) to XYZ.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_rad2float (VipsImage *in
,VipsImage *out
);
Unpack a RAD (IM_CODING_RAD) image to a three-band float image.
See also: im_rad2float()
, im_LabQ2LabS()
.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_float2rad (VipsImage *in
,VipsImage *out
);
Convert a three-band float image to Radiance 32-bit packed format.
See also: im_rad2float()
, VipsFormatRad, im_LabQ2Lab()
.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_LCh2UCS (VipsImage *in
,VipsImage *out
);
Turn LCh to UCS.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_Lab2LCh (VipsImage *in
,VipsImage *out
);
Turn Lab to LCh.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_Lab2LabQ (VipsImage *in
,VipsImage *out
);
Convert a Lab three-band float image to LabQ (IM_CODING_LABQ).
See also: im_LabQ2Lab()
.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_Lab2LabS (VipsImage *in
,VipsImage *out
);
Turn Lab to LabS, signed 16-bit int fixed point.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_Lab2XYZ (VipsImage *in
,VipsImage *out
);
Turn D65 Lab to XYZ.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_Lab2XYZ_temp (VipsImage *in
,VipsImage *out
,double X0
,double Y0
,double Z0
);
Turn Lab to XYZ. X0
, y0
, Z0
give the Lab colour temperature.
|
input image |
|
output image |
|
colour temperature |
|
colour temperature |
|
colour temperature |
Returns : |
0 on success, -1 on error. |
int im_Lab2UCS (VipsImage *in
,VipsImage *out
);
Convert an image from Lab to UCS.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_LabQ2Lab (VipsImage *in
,VipsImage *out
);
Unpack a LabQ (IM_CODING_LABQ) image to a three-band float image.
See also: im_LabQ2Lab()
, im_LabQ2LabS()
, im_rad2float()
.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_LabQ2LabS (VipsImage *in
,VipsImage *out
);
Unpack a LabQ (IM_CODING_LABQ) image to a three-band signed short image.
See also: im_LabS2LabQ()
, im_LabQ2Lab()
, im_rad2float()
.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_LabS2LabQ (VipsImage *in
,VipsImage *out
);
Convert a LabS three-band signed short image to LabQ
See also: im_LabQ2LabS()
.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_LabS2Lab (VipsImage *in
,VipsImage *out
);
Convert a LabS three-band signed short image to a three-band float image.
See also: im_Lab2LabS()
.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_UCS2XYZ (VipsImage *in
,VipsImage *out
);
Convert an image from UCS to XYZ.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_UCS2LCh (VipsImage *in
,VipsImage *out
);
Turn UCS to LCh.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_UCS2Lab (VipsImage *in
,VipsImage *out
);
Convert an image from UCS to Lab.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_XYZ2Lab (VipsImage *in
,VipsImage *out
);
Turn XYZ to D65 Lab.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_XYZ2Lab_temp (VipsImage *in
,VipsImage *out
,double X0
,double Y0
,double Z0
);
Turn XYZ to Lab. X0
, y0
, Z0
give the Lab colour temperature.
|
input image |
|
output image |
|
colour temperature |
|
colour temperature |
|
colour temperature |
Returns : |
0 on success, -1 on error. |
int im_sRGB2XYZ (VipsImage *in
,VipsImage *out
);
Convert an image from sRGB to XYZ.
The conversion is supposed to be quick
rather than accurate. Use an ICC profile with im_icc_transform()
for more
precision.
See also: im_icc_transform.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_XYZ2sRGB (VipsImage *in
,VipsImage *out
);
Convert an image from XYZ to sRGB. The conversion is supposed to be quick
rather than accurate. Use an ICC profile with im_icc_transform()
for more
precision.
See also: im_icc_transform.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_Yxy2XYZ (VipsImage *in
,VipsImage *out
);
Turn Yxy to XYZ.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_XYZ2Yxy (VipsImage *in
,VipsImage *out
);
Turn XYZ to Yxy.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_dECMC_fromLab (VipsImage *in1
,VipsImage *in2
,VipsImage *out
);
Calculate dE CMC from two Lab images.
|
first input image |
|
second input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_dE00_fromLab (VipsImage *in1
,VipsImage *in2
,VipsImage *out
);
Calculate CIE dE00 from two Lab images.
|
first input image |
|
second input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_dE_fromXYZ (VipsImage *in1
,VipsImage *in2
,VipsImage *out
);
Calculate CIELAB dE 1976 from a pair of XYZ images.
|
first input image |
|
second input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_dE_fromLab (VipsImage *in1
,VipsImage *in2
,VipsImage *out
);
Calculate CIE dE 1976 from two Lab images.
|
first input image |
|
second input image |
|
output image |
Returns : |
0 on success, -1 on error. |
int im_lab_morph (VipsImage *in
,VipsImage *out
,DOUBLEMASK *mask
,double L_offset
,double L_scale
,double a_scale
,double b_scale
);
Morph an image in CIELAB colour space. Useful for certain types of gamut mapping, or correction of greyscales on some printers.
We perform three adjustments:
cast
Pass in mask
containing CIELAB readings for a neutral greyscale. For
example:
3 | 4 | |
14.23 | 4.8 | -3.95 |
18.74 | 2.76 | -2.62 |
23.46 | 1.4 | -1.95 |
27.53 | 1.76 | -2.01 |
Interpolation from this makes cast corrector. The top and tail are interpolated towards [0, 0, 0] and [100, 0, 0], intermediate values are interpolated along straight lines fitted between the specified points. Rows may be in any order (ie. they need not be sorted on L*).
Each pixel is displaced in a/b by the amount specified for that L in the table.
L*
Pass in scale and offset for L. L' = (L + offset) * scale.
saturation
scale a and b by these amounts, eg. 1.5 increases saturation.
Find the top two by generating and printing a greyscale. Find the bottom by printing a Macbeth and looking at a/b spread
|
input image |
|
output image |
|
cast correction table |
|
L adjustment |
|
L adjustment |
|
a scale |
|
b scale |
Returns : |
0 on success, -1 on error. |
typedef enum { IM_INTENT_PERCEPTUAL = 0, IM_INTENT_RELATIVE_COLORIMETRIC, IM_INTENT_SATURATION, IM_INTENT_ABSOLUTE_COLORIMETRIC } VipsIntent;
The rendering intent. IM_INTENT_ABSOLUTE_COLORIMETRIC is best for scientific work, IM_INTENT_RELATIVE_COLORIMETRIC is usually best for accurate communication with other imaging libraries.
int im_icc_present (void
);
VIPS can optionally be built without the ICC library. Use this function to test for its availability.
Returns : |
non-zero if the ICC library is present. |
int im_icc_transform (VipsImage *in
,VipsImage *out
,const char *input_profile_filename
,const char *output_profile_filename
,VipsIntent intent
);
Transform an image with the ICC library. The input image is moved to profile-connection space with the input profile and then to the output space with the output profile.
Use im_icc_import()
and im_icc_export_depth()
to do either the first or
second half of this operation in isolation.
See also: im_icc_import()
, im_icc_export_depth()
.
|
input image |
|
output image |
|
get the input profile from here |
|
get the output profile from here |
|
transform with this intent |
Returns : |
0 on success, -1 on error. |
int im_icc_import (VipsImage *in
,VipsImage *out
,const char *input_profile_filename
,VipsIntent intent
);
Import an image with the ICC library. The input image in device space is moved to D65 LAB with the input profile.
See also: im_icc_transform()
, im_icc_import_embedded()
.
|
input image |
|
output image |
|
get the input profile from here |
|
transform with this intent |
Returns : |
0 on success, -1 on error. |
int im_icc_import_embedded (VipsImage *in
,VipsImage *out
,VipsIntent intent
);
Import an image with the ICC library. The input image in device space is moved to D65 LAB with the input profile attached to the image under the name IM_META_ICC_NAME.
See also: im_icc_transform()
, im_icc_import()
.
|
input image |
|
output image |
|
transform with this intent |
Returns : |
0 on success, -1 on error. |
int im_icc_export_depth (VipsImage *in
,VipsImage *out
,int depth
,const char *output_profile_filename
,VipsIntent intent
);
Export an image with the ICC library. The input image in
D65 LAB is transformed to device space using the supplied profile.
depth
can be 8 or 16, for 8 or 16-bit image export.
See also: im_icc_transform()
, im_icc_import()
.
|
input image |
|
output image |
|
depth to export at |
|
use this profile |
|
transform with this intent |
Returns : |
0 on success, -1 on error. |
int im_icc_ac2rc (VipsImage *in
,VipsImage *out
,const char *profile_filename
);
Transform an image from absolute to relative colorimetry using the MediaWhitePoint stored in the ICC profile.
See also: im_icc_transform()
, im_icc_import()
.
|
input image |
|
output image |
|
use this profile |
Returns : |
0 on success, -1 on error. |