SYNOPSIS

#include <vips/vips.h>

int im_XYZ2disp(in, out, display)
IMAGE *in, *out;
struct im_col_display *display;

int im_disp2XYZ(in, out, display)
IMAGE *in, *out;
struct im_col_display *display;

int im_Lab2XYZ(in, out)
IMAGE *in, *out;

int im_XYZ2Lab(in, out)
IMAGE *in, *out;

int im_XYZ2Yxy(in, out)
IMAGE *in, *out;

int im_Yxy2XYZ(in, out)
IMAGE *in, *out;

int im_XYZ2sRGB(in, out)
IMAGE *in, *out;

int im_sRGB2XYZ(in, out)
IMAGE *in, *out;

int im_Lab2LCh(in, out)
IMAGE *in, *out;

int im_LCh2Lab(in, out)
IMAGE *in, *out;

int im_LCh2UCS(in, out)
IMAGE *in, *out;

int im_UCS2LCh(in, out)
IMAGE *in, *out;

DESCRIPTION

Functions to convert images between the different colour spaces supported by VIPS: RGB, sRGB, XYZ, Yxy, Lab, LCh and UCS. RGB and sRGB are three band uchar files. XYZ, Lab, LCh and UCS are three band float files.

These are the basic conversion routines provided by VIPS. Other conversions, such as im_Lab2disp(3), are built by composing these functions and are provided as a convenience to the programmer.

The VIPS colour spaces inter-convert as follows:

                        +------- sRGB
                        |
  LabQ ----- Lab ----- XYZ ----- RGB
   |          |         |
   |          |         +------- Yxy
   |          |
   |          +------- LCh ----- UCS
   |
   +-------- LabS

The colour spaces are:

LabQ --- This is the principal VIPS colorimetric storage format. See im_LabQ2Lab(3) for an explanation. You cannot perform calculations on LabQ images. They are for storage only.

LabS --- This format represents coordinates in CIE Lab space as 16-bit integers. It is the best format for computation, being relatively compact, quick, and accurate. Colour values expressed in this way are hard to visualise. See the page for im_LabQ2LabS().

Lab --- Coordinates in CIE Lab space are represented as float values in the usual range. This is the easiest format for general work: adding 50 to the L channel, for example, has the expected result.

XYZ --- CIE XYZ colour space.

Yxy --- CIE Yxy colour space.

RGB --- This format is compatible with the RGB colour systems used in other packages. If you want to export your image to a PC, for example, convert your colorimetric image to RGB, then turn it to TIFF with vips2TIFF(1). You need to supply a structure which characterises your display. See the manual page for im_col_XYZ2rgb(3) for hints on these guys.

sRGB --- This is a standard RGB, as defined by:

  http://www.color.org/contrib/sRGB.html

it's handy for carrying colour information through JPEG compressors, for example.

LCh --- Like Lab, but the rectangular ab coordinates are replaced with the 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 Lab for expressing small differences. Conversions to and from UCS are extremely slow.

These conversions set the Type field in the image header to LABQ, LABS, LAB, XYZ, RGB, sRGB, LCH and UCS respectively. The Type field is for user information only --- no function reads the Type field to determine its behaviour. Visualisation programs, such as ip(1), use the Type field to help present the information to the user.

All VIPS colour spaces are based around D65.

VIPS has functions for finding colour difference images. See im_dE_fromLab(3).

RETURN VALUE

The functions return 0 on success and -1 on error.

COPYRIGHT

National Gallery and Birkbeck College, 1990 - 1993

AUTHOR

K. Martinez - 2/12/1992
J. Cupitt - 21/7/93