| synopsis || arguments || prev || next |
Overload navigation: 1, 2, 3, 4, 5, 6
void init( jp2_colour_space space, int Lrange, int Loff, int Lbits, int Arange, int Aoff, int Abits, int Brange, int Boff, int Bbits, kdu_uint32 illuminant=JP2_CIE_D50, kdu_uint16 temperature=5000)
Java: void Init( int space, int Lrange, int Loff, int Lbits, int Arange, int Aoff, int Abits, int Brange, int Boff, int Bbits, long illuminant, int temperature)
[Declared in "../apps/compressed_io/jp2.h"]
This function may be used to initialize the jp2_colour object with a JP2_CIELab_SPACE or JP2_CIEJab_SPACE colour space description which has non-default parameters.
To understand the role of the various range and offset parameters we will start by describing CIE Lab. The CIE equations for this colour space start by defining a collection of normalized linear primaries, X'=X/X0, Y'=Y/Y0 and Z'=Z/Z0, all in the range 0 to 1, where X0, Y0 and Z0 are the whitepoint tri-stimulus responses for the relevant illuminant. These are subjected to gamma correction, with a gamma value of 3.0 and beta=0.16. Then L, a* and b* coordinates are formed from
To represent these quantities digitally, we define scaled and offset coordinates L', a' and b', each of which has a nominal range from 0 to 1. To represent these quantities as n-bit numbers, we simply multiply by (2^n-1). Specifically, we write
In the above, Lbits, Abits and Bbits are the actual precision, as reported by the jp2_dimensions object, which is associated with each of the 3 colour channels.
The weakness of this representation is obvious, since the offset terms should have been recorded as real-valued ratios, rather than integers whose meaning depends on the bit-depth. The bit-depth is not recorded with colour descriptions, so the meaning of a colour description is not self contained — a most regrettable oversight on the part of JPX!!
Unlike other JP2/JPX design weaknesses which we have been able to hide through the design of appropriate Kakadu interfaces, this one cannot safely be concealed. We force the application to supply both the integer-valued offets and the bit-depths of each component here. The bit-depths will be automatically checked against those identified by the jp2_dimensions object, after untangling the various interconnections between colour channels and code-stream components, and any inconsistency will result in an error being generated (through kdu_error) when the relevant file header is being written.
We turn now to the Jab space. This colour space is based on CIECAM97, which actually describes a colour appearance model rather than a colour space. Jab is an encoding of 3 of the parameters from this colour appearance model, from which any of the other parameters may be recovered if desired. Unfortunately, CIECAM97 may be subject to major revision, so it is not sure how stable any Jab image encoding can be expected to be. A revised CIECAM97 proposal by Mark Fairchild in 2000 describes various choices which could be used for the a and b coordinates. For these reasons, we do not commit ourselves to a more thorough explanation here and we do not implement an colour transforms based on CIEJab.
Must be one of JP2_CIELab_SPACE or JP2_CIEJab_SPACE.
Range of luminance (L or J) coordinate. Default value is 100.
Works together with Lbits to identify an offset for the luminance (L or J) coordinate. Default is 0.
Precision of the sample values used to represent the luminance channel. This value must agree with the actual value returned by the relevant jp2_dimensions object's jp2_dimensions::get_bit_depth function. The need to include a value here is the result of poor design in the JPX file format.
Range of the a* coordinate. Default value is 170 for Lab and 255 for Jab.
Precision of the sample values used to represent the a* channel. This value must agree with the actual value returned by the relevant jp2_dimensions object's jp2_dimensions::get_bit_depth function. The need to include a value here is the result of poor design in the JPX file format.
Range of the b* coordinate. Default value is 200 for Lab and 255 for Jab.
Works together with Bbits to identify an offset for the a* coordinate. Default is 0.75*2^{ Bbits-1} for Lab and 2^{ Bbits-1} for Jab.
Precision of the sample values used to represent the b* channel. This value must agree with the actual value returned by the relevant jp2_dimensions object's jp2_dimensions::get_bit_depth function. The need to include a value here is the result of poor design in the JPX file format.
Identifies the illuminant for the JP2_CIELab_SPACE. This argument is ignored if space= JP2_CIEJab_SPACE. Rather than specifying the illuminant through its chromaticity coordinates, an enumeration is used. The possible values are as follows:
Ignored unless space = JP2_CIELab_SPACE and illuminant = JP2_CIE_DAY. Gives the colour temperature for a CIE standard daylight (these are all defined by three power spectral basis functions and an equation which converts the temperature to weights on these three basis functions), measured in degrees Kelvin.