lvconvert(3)

LIBRARY ROUTINE
lvconvert - Convert a Khoros image from one data storage type to another

LIBRARY CALL
#include "vinclude.h"
int
lvconvert(image,k,nflg,sflg,norm_factor,scale_factor,bflg)
struct xvimage *image;
int  k,nflg,sflg,bflg;
float norm_factor,scale_factor;

INPUT

image
    pointer to xvimage structure to be processed

k   VIFF data storage type to convert input image into

sflg
    if non-zero then perform scaling using the scale_factor

nflg
    if non-zero then perform normalization to norm_factor

norm_factor
    value to normalize output image data to

scale_factor
    value to scale image data by

bflg
    logic switch to request each band be processed independently

OUTPUT

image
    receives the output image after processing

Return Value
    1 on success, 0 on failure.

MODIFICATIONS
Scott Wilson and Tom Sauer 11/23/88
    Added cmap type checking and support for color models other
    than VFF_CM_GREY. Tom Sauer -- Tue Dec 27 15:15:26 MST 1988
    Updated lvcset_sizes to handle generic color models Scott Wilson -- updated to XV III 18-Mar-89 Mark Young and Tait Cyrus 11/9/89
    lvconvert was not converting BIT images correctly by not
    incrementing past the padding at the end of each scanline. Scott Wilson -- 8-Feb-90
    Fixed bug that caused BIT to * to ignore scale and
    normalization factors. Scott Wilson -- 6-Jun-90
    Fixed missing free() calls Scott Wilson -- 15-Aug-90
    Renamed lvconvert as lvcvt, for use as a toolbox routine for
    the new lvconvert, which is new code that can do multiband
    processing with each band being normalized or scaled independently.
    If the band processing is chosen to be global, then it just falls
    through to the old lvconvert code. Scott Wilson -- 8-Oct-90
    Modified the normalization procedure so that if the max is zero
    then you get back a zero image. Before, you would get an error
    message and no image. This really screws up editimage. Jeremy Worley Tue Feb 12 14:32:01 MST 1991
    Added support for double and double complex data types. Jeremy Worley Fri Feb 15 16:24:36 MST 1991
    complex to complex case indexing bug fixed. It was indexing (i,2*i+1)
    when it should have been indexing (i,i+1) Jeremy Worley Sun Feb 23 11:50:03 MST 1992
    fixed scale_factor usage so that is is set to 1.0 is sflg is 0.
    also fixed messages that indicate invalid source or destination
    data types.

DESCRIPTION
lvconvert performs data storage type conversions from any VIFF type to any other, with the exception of the transform types. Scaling or (mutually exclusive) normalization can be performed if requested. The scaling and normalization options are important for controlling the loss of precision when converting from a higher data type to a lower data type.

Output data storage type BYTE is a special case. If scaling is requested, then the input image is scaled, and then clipped to the range [0..255] before output. If normalization is requested, the data is offset adjusted and scaled to map onto the range [0..255] before output.

Normalization for other output types simply scales the data so that the most positive data value is equal to the normalization target. No offset adjustment is performed. If the most positive value in the image is zero then a zero valued image of the desired data type will be produced.

When converting from type BIT to type BYTE, the output values will be 0 or 255 depending on whether the bit corresponding to the input pixel is 0 or 1. For conversions from BIT to any type other than BYTE, the output value receives either 0 or 1 depending on the input bit value. This was done so that an BYTE image would be displayable immediately after conversion from type BIT.

The nflg and sflg are used to indicate whether or not the image should be scaled or normalized. If the image is to be scaled or normalized, the norm_factor and scale_factor give the appropriate values.

Note that img1 is used for both the input xvimage structure and the resulting output xvimage structure. This is done to save space, but you must be careful not to overwrite important data.

Use of the bflg option is important when trying to normalize a multiband or vector image. If bflg is false then the largest value of any vector component in the image is used to compute the normalization multiplier. If bflg is true then a different normalization multiplier is used for each band, as dictated by the data in that band.

SEE ALSO
vconvert(1), intro(3), vipl(3), verror(3), vutils(3) lvscale(1), lvnormal(1)

RESTRICTIONS
There needs to be a way to specify the conversion from a COMPLEX type to a non-COMPLEX type to be either the real part or the magnitude (the current version does the real part only).

AUTHOR
Scott Wilson

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