lvcltrans(3)

LIBRARY ROUTINE
lvcltrans - Tristimulus to tristimulus color space conversions

LIBRARY CALL
#include "vinclude.h"
int
lvcltrans (img, type, type_flg, norm, norm_flg, mflg, trmatrix)
struct xvimage *img,
               *trmatrix;
int     type,
        type_flg,
        norm_flg,
        mflg;
float   norm;

INPUT

img input image of type xvimage

type
    output image colormap type.

type_flg
    if set the conversion is "type" otherwise defalut is RGB.

norm
    normalization/scale factor.

norm_flg
    if set use "norm" else use 255.0.

trmatrix
    specifies a 3x3 user defined conversion matrix.

mflg
    if set use trmatrix, else use "type" as the conversion type.

OUTPUT

img overwrites the input image with new image data and colormap type.

MODIFICATIONS

DESCRIPTION
lvcltrans specifies the linear transformation matricies for conversion between ntscYIQ, cieXYZ, ntscCMY, cieUVW and ntscRGB or genericRGB colorspaces. These transformations were taken from Pratt (Digital Image Processing, 1978). The values in the matricies are based on NTSC RGB standard phosphers, as Pratt describes.

A user specified transformation matrix may also be used (mflg must be set). The transformation matrix must be a 3x3 image of type FLOAT. The resulting color space model will be GENERIC. The input image will still be normalized/scaled. The input image can be any multi-spectral image.

The input image must be of type FLOAT, and of color space model ntscYIQ, cieXYZ, ntscCMY, cieUVW, or ntscRGB or genericRGB. The input image will be normalized by the variable norm. The default is 255.

If converting from ntscYIQ, cieUVW, or cieXYZ to ntscCMY the routine first converts to ntscRGB then converts to ntscCMY because ntscCMY = 1 - ntscRGB.

If converting from ntscCMY to ntscYIQ, cieXYZ, or cieUVW the routine first converts to ntscRGB then converts from ntscRGB to ntscYIQ, cieXYZ or cieUVW using the transformation matrices.

When converting between the different color spaces, care must be taken in regards to the normalization factor. If the image had been scaled by using vscale, then the scale factor used in vscale should be the normalization factor used in this routine. (Read the vcltrans(1) man page for detailed description)

The output values of some of the transformations will be negative, and some values will be greater than 1.

The following transformation matricies are used:

RGBtoYIQ = { { 0.299, 0.587, 0.114},
             { 0.596, -0.274, -0.322},
             { 0.211, -0.523, 0.312} }; RGBtoXYZ = { { 0.607, 0.174, 0.201},
             { 0.299, 0.587, 0.114},
             { 0.000, 0.066, 1.117} }; RGBtoUVW = { { 0.405, 0.116, 0.133},
             { 0.299, 0.587, 0.114},
             { 0.145, 0.827, 0.627} }; YIQtoRGB = { { 1.000, 0.956, 0.621},
             { 1.000, -0.272, -0.647},
             { 1.000, -1.106, 1.703} }; YIQtoXYZ = { { 0.967, 0.318, 0.594},
             { 1.000, 0.000, 0.000},
             { 1.173, -1.238, 1.870} }; YIQtoUVW = { { 0.653, 0.208, 0.403},
             { 1.000, 0.000, 0.000},
             { 1.599, -0.780, 0.623} }; XYZtoRGB = { { 1.910, -0.533, -0.288},
             {-0.985, 2.000, -0.028},
             { 0.058, -0.118, 0.896} }; XYZtoYIQ = { { 0.000, 1.000, 0.000},
             { 1.407, -0.842, -0.451},
             { 0.932, 1.189, 0.233} }; XYZtoUVW = { { 0.667, 0.000, 0.000},
             { 0.000, 1.000, 0.000},
             {-0.500, 1.500, 0.500} }; UVWtoRGB = { { 2.432, 0.332, -0.576},
             {-1.519, 2.083, -0.057},
             { 1.440, -2.823, 1.803} }; UVWtoYIQ = { { 0.000, 1.000, 0.000},
             { 1.403, 0.534, -0.907},
             { 1.757, -1.898, 0.470} }; UVWtoXYZ = { { 1.500, 0.000, 0.000},
             { 0.000, 1.000, 0.000},
             { 1.500, -3.000, 2.000} };

These matricies can be found in the lvcltrans.h include file.

DIAGNOSTICS
The input image "img" is of type xvimage and must contain 3 data bands. If the mflg is set the input image can be any multi-spectral image. If the mflg is not set the input image must be of color space model ntscRGB, genericRGB, ntscYIQ, ntscCMY, cieXYZ or cieUVW. The input image must be of data type FLOAT.

Variable type specifes the output image color space type (conversion). If flag type_flg is set the conversion is "type" otherwise the default conversion is to ntscRGB.

The normalization/scale factor "norm" is used to normalize the image between 0 and 1. If the flag "norm_flg" is set use "norm" as the normalization/scale factor, else use 255.0.

The image "trmatrix" specifies a 3x3 user defined conversion matrix. The image must contain only one data band, have a data storage type of FLOAT, and have map enable set to OPTIONAL. If the mflg is set, use trmatrix as the transformation matrix, else use "type" as the conversion type.

The input image is used as the output image "img", so one must be careful not to overwrite important input image data. lvcltrans returns a 1 upon success and a 0 upon failure.

SEE ALSO
vcltrans(1), intro(3), vipl(3), verror(3), vutils(3)

RESTRICTIONS
The input image must be of one of the color space models listed above. The data type of the input must be VFF_TYP_FLOAT.

AUTHOR
Donna Koechner, Tom Sauer

COPYRIGHT
Copyright 1991, University of New Mexico. All rights reserved.