.ds f. convert.sec
.NH 1 "CONVERT LIBRARY"
.XS
\s12\*(SN  CONVERT LIBRARY\s0
.XE
.sp 2
.NH 2 "INTRODUCTION TO THE CONVERT LIBRARY"
.XS
      \*(SN  INTRODUCTION
.XE
.sp 2
.PP
The \fIconvert\fP library provides read, write and general data 
manipulation utilities for
different image file formats. The code in the read and write 
routines is machine dependent. These routines are only the
utility routines, see intro(3) for the actual VIFF to ???
library conversions.
.LP
In this file the terms IEEE BYTE ORDER and NS BYTE ORDER.
IEEE BYTE ORDER is big endian ordering, it is used by
any Motorola or sparc based machine. In IEEE BYTE ORDER the
bytes are swapped from what we normally think of. NS BYTE ORDER 
is little endian ordering, it is used by any Intel and some MIPS
based machines. The byte ordering is what we think it should be.
.sp 2
ALL programs that utilize these routines MUST include the statement:
.sp
#include "vinclude.h"
.sp
Each conversion routine has a different include. the list follows:
.IP "For Sun Raster Images:"
#include "convert/rast.h"
.IP "For Terra-Mar Big Images:"
#include "convert/big.h"
.IP "For TGA Images:"
#include "convert/tga.h"
.IP "For DEM Images:"
#include "convert/dem.h"
.sp 3
.NH 2 "ASCII AND RAW CONVERT UTILITIES"
.XS
      \*(SN  ASCII AND RAW CONVERT UTILITIES
.XE
.sp
.LP
For reading and writing ascii and raw files, see the section on the VUTILS 
library in this chapter of the manual. Also, see the man (3) page
for vutils.
.sp 2
.LP
=====================================================================
.sp 3
.NH 2 "VIFF DATA CONVERT UTILITIES"
.XS
      \*(SN  VIFF DATA CONVERT UTILITIES
.XE
.sp 2
.NH 3 " load_viff_data()"
.XS
              \*(SN   load_viff_data()
.XE
.sp
.LP
Loads float data from a 1-dimension array either real or complex 
into the VIFF data format.
.sp 2
.B
.sp
load_viff_data(data, bands, location, nrows, ncols, numbands, dimension,
interleave, start, row_skip, col_skip, complex)
.sp
float *data
.br
float *bands;
.br
float *location;
.br
int nrows;
.br
int ncols;
.br
int numbands;
.br
int dimension;
.br
int interleave;
.br
int start;
.br
int row_skip;
.br
int col_skip;
.br
int complex;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP data: 10
float array containing data points.
.IP bands: 10
array that will contain the VIFF data bands
.IP location: 10
array that will contain the location data bands.
.IP nrows: 10
total number of rows per band, not including the row 
skipping factor.
.IP ncols: 10
total number of columns per band, not including the column 
skipping factor.
.IP numbands: 10
number of bands in the VIFF format 
.IP dimension: 10
number of location bands in the VIFF format
.IP interleave 10:
If set to 1, the data is interleaved, otherwise the
data is not interleaved. Interleaved implies data
is in the form: x1, y1, z1, x2, y1, z2. Noninterleaved
implies data is in the form: x1, x2, y1, y2, z1, z2.
.IP start: 10
Starting point offset to be read for each band.
.IP row_skip: 10
Number of points along the row to skip. This is done after getting each
set of points.  Since the user is expected to use start offset if 
they don't wish to start at the first point of each band.
.IP col_skip: 10
Number of points along the column to skip. This is done after getting each
set of points.  Since the user is expected to use start offset if 
they don't wish to start at the first point of each band.
.IP complex: 10
Type of data, either real or complex. If complex is set to 1, then 
the data is complex, otherwise it is real data.
.sp 2
.LP
=====================================================================
.bp
.NH 2 "SUN RASTER CONVERT UTILITIES"
.XS
      \*(SN  SUN RASTER CONVERT UTILITIES
.XE
.sp 2
.NH 3 " write_rast()"
.XS
              \*(SN   write_rast()
.XE
.sp
.LP
Writes out a Sun Raster image file format. The image will be written
out in IEEE BYTE ORDER, regardless of the machine that is executing
the write.
.sp 2
.B
.sp
int write_rast(filename, image)
.sp
char *filename;
.br
struct rast *image
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP filename: 10
The name of the file to write the image to.
.IP image: 10
a pointer to a Sun rast image structure.
.IP write_rast returns: 10
a 0 upon failure and a 1 upon success.
.sp
.LP
=====================================================================
.sp 2
.NH 3 " read_rast()"
.XS
              \*(SN   read_rast()
.XE
.sp
.LP
Reads in a Sun Raster image. The image will be read in as if it were stored
in IEEE BYTE ORDER (SUN's byte order). If the machine executing the read
is not IEEE BYTE ORDER, the file will be converted to the correct machine 
type. Read_rast will return a pointer to the rast image structure.
.sp 2
.B
.sp
struct rast *read_rast(filename)
.sp
char *filename;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP filename: 10
The name of the file to read.
.IP read_rast returns: 10
a pointer to a Sun rast image structure, If the read fails NULL is returned.
.sp
.LP
=====================================================================
.bp
.NH 2 "TGA CONVERT UTILITIES"
.XS
      \*(SN  TGA CONVERT UTILITIES
.XE
.sp 2
.NH 3 "  write_tga()"
.XS
              \*(SN   write_tga()
.XE
.sp
.LP
Writes out a TGA image file format. The image will be written
out in NS BYTE ORDER, regardless of the machine that is executing
the write. NS BYTE ORDER is little endian byte order. 
.sp 2
.B
.sp
int write_tga(filename, image);
.sp
char *filename;
.br
tga *image;
.R 
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP filename: 10
The name of the file to write the image to.
.IP image: 10
a pointer to a TGA image structure.
.IP write_tga returns: 10
a 0 upon failure and a 1 upon success.
.sp
.LP
=====================================================================
.sp 2
.NH 3 " read_tga()"
.XS
              \*(SN   read_tag()
.XE
.sp
.LP
Reads in a TGA image. The image will be read in as if it were stored
in NS BYTE ORDER. If the machine executing the read
is not NS BYTE ORDER, the file will be converted to the correct machine 
type. 
.sp 2
.B
.sp
tga *read_tga(filename)
.sp
char *filename;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP filename: 10
The name of the file to read.
.IP read_rast returns: 10
a pointer to a TGA image structure. If the read fails NULL is returned.
.sp
.LP
=====================================================================
.bp
.NH 2 "BIG CONVERT UTILITIES"
.XS
      \*(SN  BIG CONVERT UTILITIES
.XE
.sp 2
.NH 3 "  write_big()"
.XS
              \*(SN   write_big()
.XE
.sp
.LP
Writes out a Terra-Mar BIG image. The image will be written
out in NS BYTE ORDER, regardless of the machine that is executing
the write. NS BYTE ORDER is little endian byte order. 
.sp 2
.B
.sp
int write_big(filename, image);
.sp
char *filename;
.br
struct tga *image;
.R 
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP filename: 10
The name of the file to write the image to.
.IP image: 10
a pointer to a BIG image structure.
.IP write_tga returns: 10
a 0 upon failure and a 1 upon success.
.sp
.LP
=====================================================================
.sp 2
.NH 3 " read_big()"
.XS
              \*(SN   read_big()
.XE
.sp
.LP
Reads in a Terra-Mar BIG image. The image will be read in as if it were stored
in NS BYTE ORDER. If the machine executing the read
is not NS BYTE ORDER, the file will be converted to the correct machine 
type. 
.sp 2
.B
.sp
struct big *read_big(filename)
.sp
char *filename;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP filename: 10
The name of the file to read.
.IP read_rast returns: 10
a pointer to a BIG image structure. If the read fails NULL is returned.
.sp
.LP
=====================================================================
.bp
.NH 2 "DEM CONVERT UTILITIES"
.XS
      \*(SN  DEM CONVERT UTILITIES
.XE
.sp 2
.NH 3 " readdem()"
.XS
              \*(SN   readdem()
.XE
.sp
.LP

(Per needs to fill in the description.)

.sp 2
.B
.sp
struct demimage *readdem(filename)
.sp
char *filename;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP filename: 10
The name of the file to read.
.IP readdem returns: 10
a pointer to a readdem image structure. If the read fails NULL is returned.
.sp
.LP
=====================================================================
.bp
.NH 2 "MRI CONVERT UTILITIES"
.XS
      \*(SN  MRI CONVERT UTILITIES
.XE
.sp 2
.NH 3 " read_raw_mag()"
.XS
              \*(SN   read_raw_mag()
.XE
.sp
.LP
Read_raw_mag reads in a raw data file acquired using the magnets at UNM CNID 
Data from the magnets are stored in IEEE BYTE ORDER, so
If the machine executing the read
is not IEEE BYTE ORDER, the file will be converted to the correct machine
byte order.
.sp 2
.B
.sp
char *read_raw_mag(fid, header_offset, type, conv_to_float, num_pts)
.sp
int fid;
.br
int header_offset, type, conv_to_float;
.br
int *num_pts;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP fid: 10
The file identifier to read data from.
.IP header_offset: 10
Offset, in bytes, of data from the beginning of raw file.
.IP type: 10
Data type of raw input file. Valid data types are VFF_TYP_BIT, VFF_TYP_1_BYTE,
VFF_TYP_2_BYTE, VFF_TYP_4_BYTE, VFF_TYP_FLOAT, VFF_TYP_COMPLEX.
.IP conv_to_float: 10
Flag set to 1 if the data is to be converted to float before returning.
.IP num_pts: 10
returns the number of data points read.
.IP read_raw_mag returns: 10
a pointer to a char. If the read fails NULL is returned.
.sp
.LP
=====================================================================
