asc2viff(1)

PROGRAM
asc2viff - Transforms ASCII data into a VIFF file format.

SYNTAX

asc2viff

-i  input ascii data file

-o  resulting output image (viff file)

-r  number of rows

-c  number of columns

[-fi]
    if yes the ascii input file is supposed to be interleaved; if no (default) it is considered as not interleaved

[-t]
    if no (default), the data are supposed real, if yes, the data should be defined as a complex pair in the ascii file

[-m]
    increment factor for skipping rows

[-n]
    increment factor for skipping columns

[-b]
    specify the number of data bands (image)

[-d]
    specify the number of location bands (dimensions)

[-h]
    number of points to offset from the start of the data file

[-s]
    number of points to offset from the first point of each band

[-V]
    Gives the version for asc2viff

[-U]
    Gives the usage for asc2viff

[-P]
    Prompts for command line options

[-A [file1]]
    Creates the answer file called asc2viff.ans or file1

[-a [file1]]
    Uses asc2viff.ans or file1 as the answer file

DESCRIPTION
asc2viff is a comprehensive routine that transforms ASCII data into a VIFF file format. Since very little can be determined from the input ascii 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 ascii 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 decribes if the ascii 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 ascii data. The rows times the columns indicates the size of the data to be extracted from the ascii 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 ascii 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 interelate to make one value, each can be represented with out the 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 i 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 ascii 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:  asc2viff expects the location data  bands to be before the
       data bands.  Thus,  if we had an interleaved ascii 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 points from the beginning of the file. Thus, if you wish to skip the first 100 data points of the file you would specify the header offset as 100. This does not offset comments. This field allows ascviff to be compatible with raw2viff, where it makes sense to offset a number of bytes to skip a header. Therefore, by using a header offset of 100 you will skip 100 points regardless of whether data is complex. The number of data and location bands also do not affect the number of points skipped. (A 100 is a 100!!).

NOTE: asc2viff skips any comment line that begins with a '#' or a C style comment (begins with /*). The rest of the comment is then discarded until the end of the line is encountered for the '#' or for the C style comment comments are discarded until a */ is encounterd. Thus header offset should not be confused with skipping ascii comments.

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. Therefore, by using a band offset of 50 you will skip 50 sets of points at the beginning of each band. So if you have one complex data band then when skipping 50 complex points you will be skipping 100 data points, since complex has both real and imaginary components.

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 boolean that describes whether the data bands are complex or not. Note that location bands can only be real or float point values, but that the data bands can be either complex or real. If the data bands are complex then the input data type should be set to true. The band data is then expected to be described by two points, the first being the real part the second describing the imaginary part. Note: By setting the data type to complex the output VIFF file will also be complex. Otherwise, the data type is expected to be float and the resulting VIFF file be of type float.

REQUIRED ARGUMENTS

-i  type: infile
    desc: input ascii data file

-o  type: outfile
    desc: resulting output image (viff file)

-r  type: integer
    desc: number of rows

-c  type: integer
    desc: number of columns

OPTIONAL ARGUMENTS

-fi type: boolean
    desc: if yes the ascii input file is supposed to be interleaved; if no (default) it is considered as not interleaved
    default: false

-t  type: boolean
    desc: if no (default), the data are supposed real, if yes, the data should be defined as a complex pair in the ascii file
    default: false

-m  type: integer
    desc: increment factor for skipping rows
    default: 1
    bounds: value >= 0

-n  type: integer
    desc: increment factor for skipping columns
    default: 1
    bounds: value >= 0

-b  type: integer
    desc: specify the number of data bands (image)
    default: 1
    bounds: value > 0

-d  type: integer
    desc: specify the number of location bands (dimensions)
    default: 0
    bounds: value >= 0

-h  type: integer
    desc: number of points to offset from the start of the data file
    default: 0
    bounds: value >= 0

-s  type: integer
    desc: number of points to offset from the first point of each band
    default: 0
    bounds: value >= 0

EXAMPLES

The following example will produce a single band image. The image is an implicit image (no location data) with one band of 64 by 64 float point values.
   % asc2viff -i ascii_file -o image_file -c 64 -r 64 -b 1

The following example will again produce a single band image, but offset 1024 points from the beginning of the file before reading the data.
   % asc2viff -i ascii_file -o image_file -c 64 -r 64 -b 1 -h 1024

The following example will produce a single band image with two location bands. The image is an explicit image (two location bands) with one band of (64 by 64) or 4096 float point values. The data is also interleaved. This is an example that could be used with xprism3 for plotting a three dimensional image. The two location bands would be used as the x and y location information, where as the band data would be used as the z value.

The data is expected to be in the following format (4096 "x y z" pairs):

   % asc2viff -i ascii_file -o image_file -c 64 -r 64 -b 1 -d 2 -l 1
        x1  y1  z1
        x2  y2  z2
        x3  y3  z3
           ....

If the data was not interleaved then it would be in the following format:

   % asc2viff -i ascii_file -o image_file -c 64 -r 64 -b 1 -d 2 -l 0
        x1  x2  x3  ....  x4095  x4096
        y1  y2  y3  ....  y4095  y4096
        z1  z2  z3  ....  z4095  z4096

The following example will produce a single band image with two location bands. The image is an implicit image with three band of (64 by 64) or 4096 float point values. The data is also interleaved. This is an example of how to input the RGB example described in the data band description.

The data is expected to be in the following format (4096 "x y z" pairs):

   % asc2viff -i ascii_file -o image_file -c 64 -r 64 -b 3 -d 0 -l 1
        R1  G1  B1
        R2  G2  B2
        R3  G3  B3
           ....

If the data was not interleaved then it would be in the following format:

   % asc2viff -i ascii_file -o image_file -c 64 -r 64 -b 3 -d 0 -l 0
        R1  R2  R3  ....  R4095  R4096
        G1  G2  G3  ....  G4095  G4096
        B1  B2  B3  ....  B4095  B4096

SEE ALSO
intro(1), verror(3), vgparms(3), vutils(3), lasc2viff(3)

RESTRICTIONS

The default output format will be set to float if the complex flag is false and complex if the complex flag is true. The user will need to use vconvert in order convert the VIFF to a different data type. asc2viff should provide the facility to convert to the proper data type, but the command line becomes to complex since the user would have to specify to normilize, scale, and data type.

The header offset is misleading since asc2viff naturally skips ascii comment line that begin with either '%' '*' '#' or '!'. The header offset allows the user to skip a certain number of points from the beginning of the file, and it also allows us to be consistent with the raw2viff command. Therefore, by using a header offset of 100 you will skip 100 points regardless of whether data is complex. The number of data and location bands also do not affect the number of points skipped. (A 100 is a 100!!).

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