.TH IM_COL_XYZ2RGB 3 "2 December 1992"
.SH NAME
im_col_Lab2LCh, im_col_LCh2ab, im_col_Lab2XYZ, im_col_XYZ2Lab,
im_col_pythagoras, im_col_display, im_col_XYZ2rgb, im_col_rgb2XYZ,
im_col_L2Lucs, im_col_Lucs2L, im_col_C2Cucs, im_col_Cucs2C, im_col_Ch2hucs,
im_col_Chucs2h, im_col_make_tables_UCS, im_col_dECMC
\- colour space conversion
.SH SYNOPSIS
#include <vips/vips.h>


int im_col_ab2Ch( a, b, C, h )
.br
float a, b, *C, *h;


int im_col_Ch2ab( C, h, a, b )
.br
float C, h, *a, *b;

int im_col_Lab2XYZ( L, a, b, X, Y, Z )
.br
float L, a, b, *X, *Y, *Z;

int im_col_XYZ2Lab( X, Y, Z, L, a, b )
.br
float X, Y, Z, *L, *a, *b;

float im_col_pythagoras( L1, a1, b1, L2, a2, b2 )
.br
float L1, a1, b1, L2, a2, b2;

extern struct im_col_display *im_col_displays[];

struct im_col_tab_disp *im_col_make_tables_RGB( im, display )
.br
IMAGE *im;
.br
struct im_col_display *display;

int im_col_XYZ2rgb( display, table, X, Y, Z, r, g, b, oflow )
.br
struct im_col_display *display;
.br
struct im_col_tab_disp *table;
.br
float X, Y, Z;
.br
int *r, *g, *b;
.br
int *oflow;


int im_col_rgb2XYZ( display, table, r, g, b, X, Y, Z )
.br
struct im_col_display *display;
.br
struct im_col_tab_disp *table;
.br
int r, g, b;
.br
float *X, *Y, *Z;

float im_col_L2Lucs( L )
.br
float L;

float im_col_Lucs2L( Lucs )
.br
float Lucs;

float im_col_C2Cucs( C )
.br
float C;

float im_col_Cucs2C( Cucs )
.br
float Cucs;

float im_col_Ch2hucs( C, h )
.br
float h, C;

float im_col_Chucs2h( C, hucs )
.br
float hucs, C;

void im_col_make_tables_UCS( void )

float im_col_dECMC( L1, a1, b1, L2, a2, b2 )
.br
float L1, a1, b1, L2, a2, b2;

.SH DESCRIPTION
Colour space conversion.
These functions convert colour values between four different formats: XYZ 
(float), Lab (float), UCS (float), and RGB (unsigned char)
displayable. Additionally, functions are provided to move from (a,b)-style
rectangular colour coordinates to (C,h)-style coordinates. h is always
in degrees.

UCS is a colour space derived from the CMC(1:1) equations. There is no easy
analytical conversion from UCS to Lab, so look-up tables are used. These have
to be built with a call to im_col_make_tables_UCS(). Once built, these
tables are shared by all UCS functions. You may call im_col_make_tables_UCS()
many times - tables are only built on the first call.

im_col_pythagoras() returns the pythagoran distance between two points in a
colour space. It can be used for finding CIELAB delta E's. im_col_dECMC()
returns the colour difference between two LAB points in CMC(1:1).

An im_col_display structure characterises a CRT screen (see <vips/colour.h>). 
You can make up your own (if you can find a TV analyser), or use one of the
structures provied by VIPS in the NULL-terminated array im_col_displays[]. See
the source for disp2XYZ(1) for ideas on extracting a display struct from this
list.

im_make_tables_RGB(3) has a display type as argument, and returns a pointer
to the structure im_col_tab_RGB. This latter contains the matrices to go from
XYZ to luminances (and back), and the tables to go from the luminances (in r,
g, b) to the effective signal values to be applied to the monitor input (and
back). The function returns NULL on error. The IMAGE argument is passed on to
im_malloc() to make the space required for the tables. Pass either NULL (if
you need to free the memory yourself) or an IMAGE descriptor (if you want the
memory to be freed automatically when that descriptor is closed).

im_col_XYZ2rgb() takes a display, a look-up table and an XYZ coordinate are
returns three values in the range 0-255. The extra value oflow is set to 0 if
the specified XYZ position aflls within the display gamut, and to 1 if the
point lies outside the gamut. im_col_rgb2XYZ() is the reverse transformation.
.SH RETURN VALUE
The functions (usually) return 0 on success and -1 on error.
.SH SEE\ ALSO
.nf
im_XYZ2disp(3), im_dE_fromdisp(3).
.SH COPYRIGHT
National Gallery, 1990-1993.
.SH AUTHOR
D. Saunders \- 1988
.br
J.Ph. Laurent \- 2/12/1992
.br
J.Cupitt \- 21/7/93