lraw2viff(3)

LIBRARY ROUTINE
lraw2viff - Transforms RAW data into the VIFF file format.

LIBRARY CALL
#include "vinclude.h"
int
lraw2viff(filename, image, nrows, ncols, offset, start, row_skip, col_skip,
          numbands, dimension, interleave, data_type, mach_type)
int     nrows, ncols, offset, start, row_skip, col_skip, numbands, dimension,
        interleave, data_type, mach_type;
char    *filename;
struct  xvimage **image;

INPUT

    filename: filename of the INPUT RAW file

image:
    the resulting viff image

nrows:
    number of rows

ncols:
    number of columns

start:
    start offset for each band

row_skip, col_skip:
     number of points to be skipped along the column and rows.

numbands:
    number of bands in the file

dimension:
     number of locations bands default is 0 which implies an implicit image

interleave:
    whether data is interleaved or not

data_type:
    a viff image type that will be used by lvconvert to convert the float file to the proper output type.

mach_type:
    The machine order of the incoming raw data. Valid order types are VFF_DEP_IEEE, VFF_DEP_NSORDER or VFF_DEP_DECORDER.

OUTPUT

    image: holds the result.

MODIFICATIONS
Ghosted by Pascal ADAM 14-JUNE-90

DESCRIPTION
raw2viff is a comprehensive routine that transforms RAW data into a VIFF file format. Since very little can be determined from the input raw file it is left to the user to describe how the file is laid out. This will in turn dictate how the VIFF file will be laid out.

In describing the input raw file the user must consider whether the data is interleaved. How many data (image) bands as well as location bands there are. They must also consider how many rows and columns the image contains as well as header offset, band offset, increment factors, and data type. The best way to explain these issues is to discuss each topic and then to give some examples of different configurations.

interleaved - This field is a boolean that describes if the raw data is interleaved or not. If the data is not interleaved this means that each band of data is specified before the next band of data starts. ie)

x1  x2  x3  x4  x5 ....
y1  y2  y3  y4  y5 ....
z1  z2  z3  z4  z5 ....
w1  w2  w3  w4  w5 ....

Each x point is given, then each y point, then each z point, and finally all w points are specified.

If the data is interleaved that means that each set of points (from each band) is specified before the next set starts. Data points are given as sets (pairs, triplets, etc). ie)

x1  y1  z1  w1
x2  y2  z2  w2
x3  y3  z3  w3
x4  y4  z4  w4
x5  y5  z5  w5

number of rows & columns The user is required to specify the number of rows and the number of columns of the raw data. The rows times the columns indicates the size of the data to be extracted from the raw data file. By specifying the number of rows or columns to be one, this indicates that the data is a 1D image or a single scan line. By specifying the rows and columns greater than one the image is a 2D image or multiple scan lines.

data bands This field describes the image data band. For an implicit image, an image with implied location, this would be the image pixel values. For example, if the raw input file consisted of three bands (triplets) which were Red Green Blue values then each of these would be considered a data band. Each of the fields (Red,Green,Blue) represent a different set of values. The fields do not interrelate to make one value, each can be represented with out the other values being present. Although, this does change the overall meaning of the image.

location bands The location data bands provide the data bands with a direction. The location data can be considered the vector for some data band value. This means that it can use the location data to position the data band values in space. This is useful in describing sparse images, where the user may not want to describe every point within an image, just the ones that have a value. For example, if the raw input file consisted of three bands (triplets) which were X, Y, Z points to be plotted. They would specify that the file contained two location bands and one data band. The X, Y fields would be used for describing the location for the value Z. This configuration is typically used to plot 3D data with xprism3. For a 2D plot we would have one location band, X, and one data band, Y.

NOTE:  raw2viff expects the location data  bands to be before the data
bands.  Thus, if we had an interleaved raw input file with three
location bands and two data bands the file would be in the following
format:
Location1  Location2  Location3  Data1  Data2    (first  point)
Location1  Location2  Location3  Data1  Data2    (second point)
Location1  Location2  Location3  Data1  Data2    (last   point)

header offset The header offset should be used to offset a certain number of bytes from the beginning of the file. Thus, if you wish to skip the first 100 bytes of the file you would specify the header offset as 100.

band offset The band offset should be used to skip a certain number of points from each band of data. Thus, if you wish to skip the first 50 sets of data points then you would specify the band offset to be 50. This provides the user with a flexible way of selecting exactly what part of the file they wish to convert to VIFF format.

Row & Column increment factor The row and column increment factor allows the user to sub-sample the data before converting it to a VIFF file. The default is an increment factor of one for both rows and columns, which will read every point starting from the band offset. If you wish to read every fourth row and column then the increment factor should be set the row and column increment factor to four. If you wish to read every third row and fifth column then you would set the row increment to three and the column increment to five.

data type The data type is used to indicate what type of data the raw file has in it. The raw data file can be any of the following types: byte, short, integer, float, or complex format. The VIFF file that is created will be of the same type. Thus, if the raw data file is of type short then the resulting VIFF will also be of type short.

mach type This integer value allows one to specify the machine type of the raw data. Valid inputs are VFF_DEP_IEEE for IEEE order (big endian), VFF_DEP_NSORDER for NS order (little endian), and VFF_DEP_DECORDER for DEC VAX order. The raw data will be converted from the specified type to the local machine type before creating the VIFF output image.

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

RESTRICTIONS

AUTHOR
Ramiro Jordan, Mike Lang, Mark Young, Tom Sauer

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