SYNOPSIS

#include <vips/vips.h>

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

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

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

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

float im_col_pythagoras( L1, a1, b1, L2, a2, b2 )
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 )
IMAGE *im;
struct im_col_display *display;

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

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

float im_col_L2Lucs( L )
float L;

float im_col_Lucs2L( Lucs )
float Lucs;

float im_col_C2Cucs( C )
float C;

float im_col_Cucs2C( Cucs )
float Cucs;

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

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

void im_col_make_tables_UCS( void )

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

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.

RETURN VALUE

The functions (usually) return 0 on success and -1 on error.

SEE ALSO

im_XYZ2disp(3), im_dE_fromdisp(3).

COPYRIGHT

National Gallery, 1990-1993.

AUTHOR

D. Saunders - 1988
J.Ph. Laurent - 2/12/1992
J.Cupitt - 21/7/93