path: root/libcolour.7

.TH LIBCOLOUR 7 libcolour
.SH NAME
libcolour - A C colour space library
.SH DESCRIPTION
.B libcolour
is C library for colour space conversions.
.B libcolour
provides conversion between a large number of colour
spaces, including many different RGB colour spaces.
It also supports encode and non-encoded representations.
libcolour futhermore provides access to custom RGB
colour spaces.
.P
To use libcolour, include the header file
.B <libcolour.h>
and link with
.B -lcolour
.BR -lm .
.SH COLOUR MODELS
.B libcolour
supports a number of colour models. A colour model
is specified with a value of
.nf

	\fBtypedef enum libcolour_model libcolour_model_t;\fP

.fi
The colour models can listed using the macros
.nf

	\fBLIBCOLOUR_LIST_MODELS\fP(\fIMACRO\fP, \fITYPE_AFFIX\fP)

.fi
or
.nf

	\fBLIBCOLOUR_LIST_MODELS_N\fP(\fIMACRO\fP, \fITYPE_AFFIX\fP, ...)

.fi
where
.I MACRO
is the macro that shall be expanded, and
.I TYPE_AFFIX
shall be
.BR f ,
.BR lf ,
or
.BR llf
for
.BR float -typed,
.BR double -typed,
and
.BR long\ double -typed
colour module stuctures, respectively.
.B LIBCOLOUR_LIST_MODELS
expands
.I MACRO
with three parameters:
.B enum libcolour_model
value of the colour model,
.BR typedef -name
of
.B struct
used to store colours of the colour model,
and the name of the member in
.BR union\ libcolour_colour_f ,
.BR union\ libcolour_colour_lf ,
and
.B union libcolour_colour_llf
that is used to store a colour with the colour model.
.B LIBCOLOUR_LIST_MODELS_N
is identical to
.B LIBCOLOUR_LIST_MODELS
except allows the programmer to specify additional
parameters to pass
.I MACRO
when it is expanded.
.P
There there are three
.BR struct s
defined for each colour model, the first member
in each
.B struct
is
.nf

	\fBenum libcolour_model model;\fP

.fi
The three
.BR struct s
for each colour model are for different data types:
.BR float ,
.BR double ,
and
.BR long\ double .
For example, for sRGB, the follow
.BR struct s
are defined:
.nf

	\fBtypedef struct libcolour_srgb_f libcolour_srgb_f_t;\fP
	\fBtypedef struct libcolour_srgb_lf libcolour_srgb_lf_t;\fP
	\fBtypedef struct libcolour_srgb_llf libcolour_srgb_llf_t;\fP

.fi
for
.BR float ,
.BR double ,
and
.BR long\ double ,
respectively. Similarly,
.nf

	\fBtypedef union libcolour_colour_f libcolour_colour_f_t;\fP
	\fBtypedef union libcolour_colour_lf libcolour_colour_lf_t;\fP
	\fBtypedef union libcolour_colour_llf libcolour_colour_llf_t;\fP

.fi
are used for
.BR float ,
.BR double ,
and
.BR long\ double ,
respectively, and all have the member
.nf

	\fBenum libcolour_model model;\fP

.fi
The
.BR struct s
are
.I not
padded to be of the same size.
.P
.B <libcolour.h>
defines
.BR struct s
the following for colour models:
.P
.TP
Generic RGB
See
.BR LIBCOLOUR_RGB (7).
.TP
Standard RGB
See
.BR LIBCOLOUR_SRGB (7).
.TP
CIE xyY
See
.BR LIBCOLOUR_CIEXYY (7).
.TP
CIE 1931 XYZ
See
.BR LIBCOLOUR_CIEXYZ (7).
.TP
CIE L*a*b*
See
.BR LIBCOLOUR_CIELAB (7).
.TP
CIE 1976 (L*, u*, v*)
See
.BR LIBCOLOUR_CIELUV (7).
.TP
CIE LChuv (also known as CIE HLCuv)
See
.BR LIBCOLOUR_CIELCHUV (7).
.TP
YIQ
See
.BR LIBCOLOUR_YIQ (7).
.TP
YDbDr
See
.BR LIBCOLOUR_YDBDR (7).
.TP
YUV
See
.BR LIBCOLOUR_YUV (7).
.TP
YPBPR
See
.BR LIBCOLOUR_YPBPR (7).
.TP
YCgCo (YCoCg)
See
.BR LIBCOLOUR_YCGCO (7).
.TP
CIE 1960 UCS
See
.BR LIBCOLOUR_CIE1960UCS (7).
.TP
CIE 1964 (U*, V*, W*)
See
.BR LIBCOLOUR_CIEUVW (7).
.TP
YES
See
.BR LIBCOLOUR_YES (7).
.SH ILLUMINANTS
.B libcolour
provides a number of initialiser macros for standard
illuminants. The following macros expand to a
.B libcolour_ciexyy_f_t
with the standard 2 degrees observer value in CIE
xyY, each have a supplementary 10 degrees observer
counterpart using suffix
.BR _10DEG_OBS ,
both with the Y value set to 1. Additionally, each
macro, including the
.B _10DEG_OBS
variants, have a variant that uses the
.B _LF
affix that expands to a
.B libcolour_ciexyy_lf_t
and a variant that uses the
.B _LLF
affix that expands to a
.B libcolour_ciexyy_llf_t
in addition to the listed variants that uses
the
.B _F
affix.
.P
.TP
.B LIBCOLOUR_ILLUMINANT_A_F
.nf
CIE Standard Illuminant A.
Incandescent/Tungsten.
2855.54 Kelvin (2848 Kelvin in old definition of 1 Kelvin).
.fi
.TP
.B LIBCOLOUR_ILLUMINANT_B_F
.nf
CIE Standard Illuminant B.
Direct sunlight at noon (obsolete).
4874 Kelvin.
.fi
.TP
.B LIBCOLOUR_ILLUMINANT_C_F
.nf
CIE Standard Illuminant C.
Average/north sky daylight (obsolete).
6774 Kelvin.
.fi
.TP
.B LIBCOLOUR_ILLUMINANT_D50_F
.nf
CIE Standard Illuminant D50.
Horizon Light.
5002.78 Kelvin (5000 Kelvin in old definition of 1 Kelvin).
.fi
.TP
.B LIBCOLOUR_ILLUMINANT_D55_F
.nf
CIE Standard Illuminant D55.
Mid-morning/mid-afternoon daylight.
5503.06 Kelvin (5500 Kelvin in old definition of 1 Kelvin).
.fi
.TP
.B LIBCOLOUR_ILLUMINANT_D65_F
.nf
CIE Standard Illuminant D65.
Noon daylight.
6503.62 Kelvin (6500 Kelvin in old definition of 1 Kelvin).
.fi
.TP
.B LIBCOLOUR_ILLUMINANT_D75_F
.nf
CIE Standard Illuminant D75.
North sky daylight.
7504.17 Kelvin (7500 Kelvin in old definition of 1 Kelvin).
.fi
.TP
.B LIBCOLOUR_ILLUMINANT_E_F
.nf
CIE Standard Illuminant E.
Equal energy.
5454 Kelvin.
.fi
.TP
.B LIBCOLOUR_ILLUMINANT_F1_F
.nf
CIE Standard Illuminant F1.
Daylight fluorescent.
6430 Kelvin.
.fi
.TP
.B LIBCOLOUR_ILLUMINANT_F2_F
.nf
CIE Standard Illuminant F2.
Cool white fluorescent.
4230 Kelvin.
.fi
.TP
.B LIBCOLOUR_ILLUMINANT_F3_F
.nf
CIE Standard Illuminant F3.
White fluorescent.
3450 Kelvin.
.fi
.TP
.B LIBCOLOUR_ILLUMINANT_F4_F
.nf
CIE Standard Illuminant F4.
Warm white fluorescent.
2940 Kelvin.
.fi
.TP
.B LIBCOLOUR_ILLUMINANT_F5_F
.nf
CIE Standard Illuminant F5.
Daylight fluorescent.
6350 Kelvin.
.fi
.TP
.B LIBCOLOUR_ILLUMINANT_F6_F
.nf
CIE Standard Illuminant F6.
Lite white fluorescent.
4150 Kelvin.
.fi
.TP
.B LIBCOLOUR_ILLUMINANT_F7_F
.nf
CIE Standard Illuminant F7.
D65 simulator, daylight simulator.
6500 Kelvin.
.fi
.TP
.B LIBCOLOUR_ILLUMINANT_F8_F
.nf
CIE Standard Illuminant F8.
D50 simulator, Sylvania F40 Design 50.
5000 Kelvin.
.fi
.TP
.B LIBCOLOUR_ILLUMINANT_F9_F
.nf
CIE Standard Illuminant F9.
Cool white deluxe fluorescent.
4150 Kelvin.
.fi
.TP
.B LIBCOLOUR_ILLUMINANT_F10_F
.nf
CIE Standard Illuminant F10.
Philips TL85, Ultralume 50.
5000 Kelvin.
.fi
.TP
.B LIBCOLOUR_ILLUMINANT_F11_F
.nf
CIE Standard Illuminant F11.
Philips TL84, Ultralume 40.
4000 Kelvin.
.fi
.TP
.B LIBCOLOUR_ILLUMINANT_F12_F
.nf
CIE Standard Illuminant F12.
Philips TL83, Ultralume 30.
3000 Kelvin.
.fi
.SH FUNCTIONS
.TP
.BR libcolour_convert (3)
Colour space and colour model conversion.
.TP
.BR libcolour_convert_en_masse (3)
Colour space and colour model conversion
for many colours.
.TP
.BR libcolour_srgb_encode (3)
Apply the sRGB transfer function.
.TP
.BR libcolour_srgb_decode (3)
Unapply the sRGB transfer function.
.TP
.BR libcolour_delta_e (3)
Calculate the delta E*_ab distance.
.TP
.BR libcolour_proper (3)
Sets any member or submember that may
be incorrectly set.
.TP
.BR libcolour_get_rgb_colour_space (3)
Selects RGB colour space.
.TP
.BR libcolour_marshal (3)
Marshal a colour record.
.TP
.BR libcolour_unmarshal (3)
Unmarshal a colour record.
.SH NOTES
All
.B enum
values have a macro with the same name defined
which can be used to test the existance of value.
.SH AUTHORS
Mattias Andrée
.RI < m@maandree.se >