lelas2viff(3)

LIBRARY ROUTINE
lelas2viff - Converts an ELAS file format to the VIFF image file format.

LIBRARY CALL
#include "vinclude.h"
int lelas2viff(elas_image, elas_fid, viff_image, band_num, x_coord, y_coord, width, height, color_model, subimage)
ELAS *elas_image;
int  elas_fid;
struct  xvimage **viff_image;
int  band_num, x_coord, y_coord, width, height, color_model, subimage;

INPUT

    ELAS *elas_image - pointer to elas image structure

    int elas_fid - file descriptor

    struct xvimage **viff_image - pointer to a pointer of a VIFF image file

    int band_num - band number to process

    int x_coord - starting x location into ELAS image.

    int y_coord - starting y location into ELAS image.

    int width - desired width of VIFF image.

    int height - desired width of VIFF image.

    int color_model - the color space model specified by the user.

    int subimage - flag specifying whether to process entire band or only a specified portion of the band.

OUTPUT

    struct xvimage **viff_image - malloced and copied imagedata for VIFF image

MODIFICATIONS

DESCRIPTION
elas2viff is a routine that converts an ELAS image file format into a VIFF file format. The ELAS image file format describes the image format used by the ELAS Image system.

An ELAS image usually contains more than one channel or band of information, although it can exist as a single band image. This routine performs the conversion from the ELAS image format to the VIFF image format one band at a time. That is, only one band can be converted at a time. Additionally, an option is provided which allows for the conversion of a selected area of the ELAS image. This is accomplished by specifying the starting x and y coordinates along with the desired width and height of the resulting image. If no subimage information is provided, then the entire band is converted to the VIFF format. Another option allows for the selection of the desired color space model of the resulting image.

Record 1 contains all the header information. The remaining records, beginning with record 2 store image data one scanline at a time in (BIL) band-interleaved-by-line format for any number of bands. Each record contains one scan line of one channel, thus each record corresponds to a new scan line for a particular channel.

The Band-Interleaved-By-Line order means that the first scanline of the first band is stored first. It is followed by the first scanline of the second band, third band, fourth band, and so on up to the last band avaliable. This order then repeats for the second scanline, the third scanline and so on.

The format is according to the following scheme:
     Record Number         Data Description
     ------------          ----------------
           1               Header Record
           2               Scan line 1, channel 1
           3               Scan line 1, channel 2
           4               Scan line 1, channel 3
           5               Scan line 2, channel 1
           6               Scan line 2, channel 2
           .                        .
           .                        .
           .                        .

Note that the terminology for band and channel is used interchangably, The term band is typically used in the conventional image processing community, while channel is commonly used in the remote sensing community. Scan line here refers to one row of the image.

The image header for the ELAS image file format is as follows:
 BYTES      TYPE                DESCRIPTION
-------     ----    -------------------------------------------
[1-4]       int     (NBIH) Number of bytes in header.
[5-8]       int     (NBPR) Number of bytes per record.
[9-12]      int     (IL)   Initial line of data file.
[13-16]     int     (LL)   Last line of data file.
[17-20]     int     (IE)   Initial element of each scan line.
[21-24]     int     (LE)   Last element of each scan line.
[25-28]     int     (NC)   Number of channels (bands).
[29-32]     int     (4321) Header record identification.
[33-36]     ASCII   Grid descriptor for Y-axis: NOR, LSNL, etc.
[37-40]     int     Y-Offset: Y-coordinate value for scan line 0.
[41-44]     ASCII   Grid descriptor for X-axis: EAS, LNSE, etc.
[45-48]     int     X-Offset: X-coordinate value for element 0.
[49-52]     float   Y Spot size, or pixel element height.
[53-56]     float   X Spot size, or pixel element width.
[57-72]     float   Transformation matrix (linear) from line and
                     column (IL, LL, IE, LE) coordinates to the
                     coordinates described by the grid descriptors.
                       1., 0., 0., 1. =  identity transformation
                       1., 0., 0., -1. = data in UTM format
[73-84]     ---     Not Used.
[85-88]     int     (Eikonix) Used by modules RFEKDA and VEKS.
[89-92]     int     (LABL) Used by module LABL.
[93-96]     ASCII   (HEAD) Used by module HEAD.
[97-480]    ASCII   Comments - 6 lines at 64 characters each or
                     96 4-character descriptiors for data base use.
[481-992]   int     Color Table (color map)
[993-1024]  ---     Not Used.

The following fields in the VIFF image header are set as follows:

1.  data_storage_type = BYTE (VFF_TYP_1_BYTE)

2.  data_encode_scheme = RAW (VFF_DES_RAW)

3.  map_scheme = NONE (VFF_MS_NONE)

4.  map_enable = OPTIONAL (VFF_MAP_OPTIONAL)

5.  location_type = NONE

6.  num_images = 1

The following arguments define the use of the library routine "lelas2viff":

elas_image
    a pointer to an ELAS image structure.

elas_fid
    an integer specifying the file descriptor of the ELAS image. This is most readily obtained by including a call to "open_elas()" contained in the file elas.c. The routine "open_elas()" opens the specified file and verifies the header and performs byte swapping if necessary using the machine dependencies.

viff_image
    a pointer to a pointer of a VIFF image file. The resulting VIFF image is returned through the use of this pointer.

band_num
    an integer specifying which band number to process.

x_coord
    an integer specifying the starting x location or column into the ELAS image for processing of only a portion of the ELAS image.

y_coord
    an integer specifying the starting y location or row into the ELAS image for processing of only a portion of the ELAS image.

width
    an integer specifying the width (number of columns) of the resulting VIFF image.

height
    an integer specifying the height (number of rows) of the resulting VIFF image.

color_model
    an integer specifying the color space model of the resulting image.

subimage
    an integer representing the optional subimage flag. A value of TRUE indicates that the routine will use the subimage coordinate information indicated in the parameters, x_coord, y_coord, width, and height. A value of FALSE indicates that the routine will ignore the subimage coordinate information and process the entire band of information.

IMPORTANT

The utilities used to read and write the BIG image file are machine dependent. WE ASSUME THAT THE BIG IMAGE WILL ALWAYS BE IN LITENDIAN BYTE FORMAT, since the Terra-Mar Image processing system runs under DOS on a PC. This means that a machine that uses bigendian byt order (i.e. sun, sony, etc) must byte swap some fields in the image header. So, a #if has been placed in the code to allow conversion between litendian byte order and bigendian byte order.

The only file that has machine dependencies is big.c in the file formats library (libfile_formats.a).

1. The not define flag
    This routine can be compiled so that it is not machine dependent by using -DNMD option. NMD stands for not machine dependent. When compiled with this option the bigendian to litendian conversion is not performed.

2. defines for machine dependencies
    The defines for machine dependencies (conversion to and from bigendian) are sun, bigendian, and ieeeorder. So big.c can be compiled with -Dbigendian. Note, when compiling on a sun machine, sun is defined so the conversion code from bigendian to litendian will be be compiled. If it is unwanted see 1. above.

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

RESTRICTIONS
Only one band at a time is converted.

Elas images are assumend to be in NS byte order (little endian).

AUTHOR
Charlie Gage

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