.TH IM_XYZ2disp 3 "2 Decemder 1992"
.SH NAME
im_XYZ2disp, im_disp2XYZ, im_Lab2XYZ, im_XYZ2Lab, im_XYZ2Yxy, im_Yxy2XYZ,
im_XYZ2sRGB, im_sRGB2XYZ,
im_Lab2LCh, im_LCh2Lab, im_LCh2UCS, im_UCS2LCh \- convert images between 
various colour spaces
.SH SYNOPSIS
#include <vips/vips.h>

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

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

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

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

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

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

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

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

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

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

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

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

.SH 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).

.SH RETURN VALUE
The functions return 0 on success and -1 on error.
.SH SEE ALSO
im_col_XYZ2rgb(3), im_dE_fromLab(3), im_LabQ2Lab(3), im_Lab2disp(3).
.SH COPYRIGHT
National Gallery and Birkbeck College, 1990 - 1993
.SH AUTHOR
K. Martinez \- 2/12/1992
.br
J. Cupitt \- 21/7/93