.ds f. file_fmats.sec
.NH 1 "FILE_FORMATS LIBRARY"
.XS
\s12\*(SN  FILE_FORMATS LIBRARY\s0
.XE
.sp 2
.NH 2 "INTRODUCTION TO THE FILE_FORMATS LIBRARY"
.XS
      \*(SN  INTRODUCTION
.XE
.sp 2
.PP
The \fIfile_formats\fP library is the Khoros Library that used to be called
the \fIconvert\fP library.  It contains routines 
that perform a variety of different image file conversions.  While most of
the routines in this library are not new to Khoros, they have been made
available in a public Khoros library for the first time as of Khoros 1.0.
The file format conversion routines are provided so that Khoros is
compatible with other software systems.  We continue to use the VIFF file
format internally to Khoros routines;  other file format types are converted
to VIFF file format before being used with Khoros.  The VIFF file format is
described in Chapter 1 of the Khoros Programmer's Manual.  
.PP
The \fIfile_formats\fP library include conversion routines that convert 
various types of image file formats to VIFF, the file format used exclusively
by Khoros routines. Some of the routines found here include conversions to
and from VIFF format from the BIG image file format, the USGS DEM file format,
the DLG format, the FITS file format, the TGA file format, the Portable
Bitmap/Pixmap (PBM) format, Sun Raster image file format, and the GE Signa
raw complex data file.  In addition, utilities to convert to and from the
TIFF file format are included as part of Khoros, but they are NOT located
in this library, as the TIFF software was obtained from the net and is
public domain.  Those interested in the TIFF conversion routines should see
the software found in KHOROS_HOME/public_domain/tiff, or consult the "tiff"
man page.
.PP
When a Khoros file format routine writes out an image file, it writes out
the file in the native byte order specified by that format. For example,
if a user was on a DECstation 3100 using a program that used the 
write_rast() routine, the resulting SUN raster image would be in IEEE or
Bigendian byte order, in spite of the fact that the DECstation 3100 does
not use that type of byte ordering. By the same token, when an image file
is read in by a Khoros file format routine, the image is converted from
its native byte ordering to the current machine type byte ordering. For 
example, if a user was on a DECstation 3100 using a program that used the
read_rast() routine, the SUN raster image being read would be immediately
converted from IEEE or Bigendian byte order to the NS or Litendian byte
ordering. Programmers wishing to contribute additional file format 
conversion routines are expected to follow this convention.
.PP
.sp 2
.NH 2 " LOADING FLOAT DATA" 
.XS 
      \*(SN   LOADING FLOAT DATA
.XE
.sp 2
.NH 3 " load_viff_data()"
.XS
              \*(SN   load_viff_data()
.XE
.PP
Loads float data from a 1-dimensional array (either real or complex)
into the VIFF data format.
.LP
.B 
.sp
load_viff_data(data, bands, location, nrows, ncols, numbands,
               dimension, interleave, start, row_skip, col_skip, complex)
.br
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
Array containing data points
.IP bands:
Array that will contain the data bands.
.IP location:
Array that will contain the location data bands.
.IP "nrows, ncols:"
Total number of points (sets) per band, not including the row & col 
increment factor.
.IP numbands:
Number of bands in the file
.IP dimension:
Number of location bands in the file
.IP interleave:
Whether data is interleaved or not:
.in +5
x1 y1 z1
.br
x2 y2 z2
.br
	.vs.
.br
x1 x2
.br
y1 y2
.br
z1 z2
.br
.in -5
.IP start:
Starting point offset to be read for band
.IP "row_skip, col_skip:"
Number of points to skip along the row and column.  This is done after 
getting each set of points.  The user is expected to use start offset 
if they don't wish to start at the first point of each band.
.IP complex:
TRUE (1) if data is complex, FALSE (0) if real 
.sp
.LP
=====================================================================
.sp 2
.NH 2 " ROUTINES TO HANDLE THE BIG FORMAT" 
.XS 
      \*(SN   ROUTINES TO HANDLE THE BIG FORMAT
.XE
.sp 2
.PP
The BIG image file format describes the image format used by Terra-Mar
MicroImage.  This format is based on record sizes of 512.  Record 1 
contains all the header information.  The remaining records store image
data one scanline at a time in band-interleaved-by-line (BIL) format,
for any number of bands.  Since a scanline has a variable number of pixels
depending on the original data, each scanline is divided
into an appropriate number of records (512 pixels per record).  If the
number of pixels per scanline is not evenly divisible by 512, the last
record for each line will contain the remainder for that line; it will be only
partially full. Note, records are padded to a length of 512.
.PP
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 available. This order
then repeats for the second scanline, the third scanline and
so on. For more detailed information on the BIG file format, see the man page
on \fBbig2viff\fP file conversion routine.
.PP
\fIWe assume that the big image will always be in Litendian byte 
format,\fP since the Terra-Mar Image processing system runs under DOS 
on a PC. This means that a machine that uses Bigendian byte order 
(eg, SUN, Sony, etc) must byte swap some fields in the image header. 
Because of this, the \fIread_big()\fP and \fIwrite_big()\fP routines
allow conversion between Litendian byte order and Bigendian byte order.
.PP
To use the \fIread_big()\fP and \fIwrite_big()\fP routines, you must have
in your code the include statement:
.sp
\f(CW
#include "KHOROS_HOME/include/file_formats/big.h"
\fP
.LP
.sp 2
.NH 3 " read_big()"
.XS
              \*(SN   read_big()
.XE
Reads in an image file in the big format, and stores it in the \fIbig\fP 
structure that is defined in the "KHOROS_HOME/include/file_formats/big.h" file.
.LP
.B 
.sp
struct big *read_big(filename)
.br
char *filename;
.sp 
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP filename: 10
The name of the image file in big format to be read in.
.sp
.LP
=====================================================================
.sp 2
.sp 2
.NH 3 " write_big()"
.XS
              \*(SN   write_big()
.XE
.LP
Writes out an image file in the big format, which is specified by a pointer
to a \fIbig\fP structure that is passed in.  The \fIbig\fP structure is 
defined in the "KHOROS_HOME/include/file_formats/big.h" file.
.LP
.B
.sp
write_big(filename, imageptr)
.br
struct big *imageptr;
.br
char *filename;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP imageptr: 10
A pointer to the \fIbig\fP data structure that defines the image to be
written out.
.IP filename: 10
Name of the image file in big format to be written.
.sp
.LP
=====================================================================
.sp 3
.NH 2 " ROUTINE TO READ THE USGS DEM FORMAT"
.XS
      \*(SN   ROUTINE TO READ THE USGS DEM FORMAT
.XE
.sp
.PP
This function reads an image file that is in the United States
Geological Survey Demographical Elevation Map (USGS DEM) format.  USGS DEM
files contain digital elevation map data; it may appear in 7.5-minute data
(in utm meters) or in 1-degree data (in arc seconds).  This file format 
is used by GIS (Geographical Information System) programs.  There is no
corresponding routine to write out an image in the USGS DEM format, as
the VIFF format simply does not have enough information to make such
a routine applicable. 
.PP
The \fIdemimage\fP structure is defined in the 
"KHOROS_HOME/include/file_formats/dem.h" file.
To use the \fIreaddem()\fP routine, you must have
in your code the include statement:
.sp
\f(CW
#include "KHOROS_HOME/include/file_formats/dem.h"
\fP
.LP
.sp 2
.NH 3 " readdem()"
.XS
              \*(SN   readdem()
.XE
Reads in an image file in the USGS DEM format, and stores it in the 
\fIdemimage\fP structure that is defined in the 
"KHOROS_HOME/include/file_formats/dem.h" file.  Note that a DEM file is not
machine dependent, as these files are in ascii.
.LP
.B 
.sp
struct demimage *readdem(filename)
.br
char *filename;
.sp 
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP filename: 10
The name of the image file in USGS DEM format to be read in.
.sp
.LP
=====================================================================
.sp 3
.NH 2 " ROUTINES TO IMPORT THE DLG FORMAT"
.XS
      \*(SN   ROUTINES TO IMPORT THE DLG FORMAT
.XE
.sp
.PP
These utilities are used in conjunction with image files that are 
in the Digital Line Graph (DLG) format.  They are most often used by 
GIS (Geographical Information System) programs.  While there is a routine
to read the DLG format, there is no corresponding routine to write out 
an image in the DLG format, as the VIFF format simply does not have enough 
information to make such a routine applicable.
Other routines are available to convert UTM coordinates to arc coordinates
arc coordinates to pixel coordinates, and pixel to arc coordinates.
Plotting utilities allow you to plot a line or a point in an image band.
.PP
The \fIdlgimage\fP structure is defined in the
"KHOROS_HOME/include/file_formats/dem.h" file.
To use the \fIreaddlg()\fP routine, you must have
in your code the include statement:
.sp
\f(CW
#include "KHOROS_HOME/include/file_formats/dlg.h"
\fP
.LP
.sp 2
.NH 3 " readdlg()"
.XS
              \*(SN   readdlg()
.XE
.PP
Reads in an image file in the DLG format, and stores it in the \fIdlgimage\fP 
structure that is defined in the "KHOROS_HOME/include/file_formats/dlg.h" file. 
Note that a DLG file is not machine dependent, as these files are in ascii.
.LP
.B 
.sp
struct dlgimage *readdlg(filename)
.br
char *filename;
.sp 
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP filename: 10
The name of the image file in DLG format to be read in.
.sp
.LP
=====================================================================
.sp 2
.NH 3 " utm2arc()"
.XS
              \*(SN   utm2arc()
.XE
.PP
Given the coordinates of the four corners of a square in
both UTM and arc-seconds, this routines converts the UTM
coordinates of a point within the square to arc coordinates.
.LP
.B
.sp
int
utm2arc (utm_west_edge, utm_south_edge, utm_east_edge, utm_north_edge,
arc_west_edge, arc_south_edge, arc_east_edge, arc_north_edge,
x_utm, y_utm, x_arc, y_arc)
.br
double utm_west_edge, utm_south_edge, utm_east_edge, utm_north_edge;
.br
double arc_west_edge, arc_south_edge, arc_east_edge, arc_north_edge;
.br
double x_utm, y_utm;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP utm_west_edge: 16
The utm x coordinate of the west edge
.IP utm_south_edge: 
The utm y coordinate of the south edge
.IP utm_east_edge:
The utm x coordinate of the east edge
.IP utm_north_edge:
The utm y coordinate of the north edge
.IP arc_west_edge:
The longitude in seconds of the west edge
.IP arc_south_edge:
The latitude in seconds of the south edge
.IP arc_east_edge:
The longitude in seconds of the east edge
.IP arc_north_edge:
The latitude in seconds of the north edge
.IP "x_utm, y_utm:"
The UTM (x,y) coordinate to be converted to an arc coordinate
.IP "x_arc, y_arc:"
Return the converted arc (x,y) coordinate
.sp
.LP
=====================================================================
.sp 2
.NH 3 " arc2pixel()"
.XS
              \*(SN   arc2pixel()
.XE
.PP
Given the geographical coordinates of a square region, and
the size of an image to cover the region, this function
tells you which pixel in the image to plot corresponding
to a location within the geographical region defined.
.LP
.B
.sp
int arc2pixel (arc_west_edge, arc_south_edge, arc_east_edge, arc_north_edge,
rows, cols, x_arc, y_arc, x_pixel, y_pixel)
.br
double arc_west_edge, arc_south_edge, arc_east_edge, arc_north_edge;
.br
int rows, cols;
.br
double x_arc, y_arc;
.br
int *x_pixel, *y_pixel;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP arc_west_edge: 16
The longitude in seconds of the west edge
.IP arc_south_edge:
The latitude in seconds of the south edge
.IP arc_east_edge:
The longitude in seconds of the east edge
.IP arc_north_edge:
The latitude in seconds of the north edge
.IP "rows, cols:"
Number of rows and columns in the image covering the desired geographical area
.IP "x_arc, y_arc:"
The arc (x,y) coordinate
.IP "x_pixel, y_pixel:"
Return the (x,y) coord of the pixel corresponding to the input geographical 
location 
.sp
.LP
=====================================================================
.sp 2
.NH 3 " pixel2arc()"
.XS
              \*(SN   pixel2arc()
.XE
.PP
Given the geographical coordinates of a square region and
the size of an image that is to cover that region, this
function returns the geographical coordinates corresponding
to a pixel inside that image.
.LP
.B
.sp
int pixel2arc (arc_west_edge, arc_south_edge, arc_east_edge, arc_north_edge,
rows, cols, x_pixel, y_pixel, x_arc, y_arc)
.br
double arc_west_edge, arc_south_edge, arc_east_edge, arc_north_edge;
.br
int rows, cols;
.br
int x_pixel, y_pixel;
.br
double *x_arc, *y_arc;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP arc_west_edge: 16
The longitude in seconds of the west edge
.IP arc_south_edge:
The longitude in seconds of the south edge
.IP arc_east_edge:
The longitude in seconds of the east edge
.IP arc_north_edge:
The longitude in seconds of the north edge
.IP "rows, cols:"
Number of rows and columns in the image covering the desired geographical area
.IP "x_pixel, y_pixel:"
The (x, y) coord of the pixel to be converted to geographical coords
.IP "x_arc, y_arc:"
Return the converted arc (x, y) coordinate
.sp
.LP
=====================================================================
.sp 2
.NH 3 " dlg_line()"
.XS
              \*(SN   dlg_line()
.XE
.PP
Plots a line in an image band. Returns TRUE (1) on success, FALSE (0) on 
failure.
.LP
.B
.sp
int dlg_line (band, rows, cols, x1, y1, x2, y2)
.br
char *band;
.br
int rows, cols;
.br
int x1, y1, x2, y2;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP band: 11
Pointer to the image band to plot line in
.IP "rows, cols:"
Number of rows and columns in the image band
.IP "x1, y1:"
Starting (x,y) coordinate of the line in the image
.IP "x2, y2:"
Ending (x,y) coordinate of the line in the image
.sp
.LP
=====================================================================
.sp 2
.NH 3 " dlg_point()"
.XS
              \*(SN   dlg_point()
.XE
.PP
Plots a point in an image band. Returns TRUE (1) on success, FALSE (0) on
failure.
.LP
.B
.sp
int dlg_point (band, rows, cols, x, y)
.br
char *band;
.br
int rows, cols;
.br
int x, y;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP band:
Pointer to the image band to plot line in
.IP "rows, cols:"
Number of rows and columns in the image band
.IP "x, y:"
(x,y) coordinate of the point in the image
.sp
.LP
=====================================================================
.sp 2
.NH 3 " cut_locations()"
.XS
              \*(SN   cut_locations()
.XE
.PP
This function is designed to be used to create overlay images.
If you have an image that has been created from a vector file,
such as dlg format, the image will contain some lines and a
lot of blank space between the lines.   The blank space means
that there is no data for the blank areas, and so there is no
point in storing them.  The input to this function is an image
in a structure xvimage.  The image must contain a full set of
explicit locations (i.e. it can't have gone through this
function before) and it must be evenly sampled on a rectangular
grid.  The output will be the same image except that the blank
areas, both image data and locations, will have been removed,
and only those areas containing data are saved.  Note that
the output can no longer be displayed as an image, but requires
a plotting package such as xprism3.
.LP
.sp
.B
int cut_locations (image)
.br
struct xvimage *image;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP image:
Pointer to the VIFF data structure
.sp
.LP
=====================================================================
.sp 2
.NH 3 " get_bit_pixel()"
.XS
              \*(SN   get_bit_pixel()
.XE
.PP
This routine is used to address a pixel in a bit image.
The inputs are the data portion of an xvimage structure,
the band we want to access in the image, and the number
of rows and columns in the image.  Also input are the
x and y coordinates of the bit we want to retrieve
from the image.  The output is an integer, which will
be 0 or 1 depending on the value of the pixel we found.
.LP
.sp
.B
int get_bit_pixel (imagedata, band, rows, cols, x, y, pixel)
.br
unsigned char *imagedata;
.br
int band; 
.br
int rows, cols;
.br
int x, y;
.br
int *pixel;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP imagedata: 11
Pointer to the image data
.IP band:
The band of the image we want to access
.IP "rows, cols:"
The number of rows and columns in the image
.IP "x, y:"
The coordinates of the desired pixel 
.IP pixel:
Returns the integer value of the bit at the given location.
.sp
.LP
=====================================================================
.sp 3
.NH 2 " GENERAL GIS UTILITY ROUTINES"
.XS
      \*(SN   GENERAL GIS UTILITY ROUTINES
.XE
.sp
.PP
These general utility routines for use with GIS programs allow you to read
fixed format data from a file (for instance, DEM or DLG), assign explicit
location data to an image, and move the file pointer to the beginning of the
next line of input.
.sp 2
.NH 3 " assign_locations()"
.XS
              \*(SN   assign_locations()
.XE
.PP
Assigns explicit location data to an image.
.LP
.sp
.B
int assign_locations (img, x_sw, y_sw, x_ne, y_ne)
.br
struct xvimage *img;
.br
double x_sw, y_sw, x_ne, y_ne;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP image:
Pointer to the VIFF data structure
.IP x_sw:
The x coordinate of the left side of the image in the desired reference system.
.IP y_sw:
The y coordinate of the left side of the image in the desired reference system.
.IP x_ne:
The x coordinate of the right side of the image in the desired reference system.
.IP y_ne:
The y coordinate of the top of the image in the desired reference system.
.sp
.LP
=====================================================================
.sp 2
.NH 3 " nextline()"
.XS
              \*(SN   nextline()
.XE
.PP
This utility moves the read head to the beginning of the next line of input.
.sp 
.LP
.sp
.B
void nextline(file)
.br
FILE *file;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP file:
Open stream to the file being read
.sp
.LP
=====================================================================
.sp 2
.NH 3 " readfixed()"
.XS
              \*(SN   readfixed()
.XE
.PP
This function reads fixed format data from an ascii file.
For instance, if you need to read a six character integer
from a file and no delimiting characters are used, you
need this routines.  All this routine does is read the
specified number of characters from your file, and then
do a sscanf from the string to convert to the proper data type.
.LP
.sp
.B
int readfixed (file, number, format, variable)
.br
FILE *file;
.br
int number;
.br
char *format;
.br
char *variable;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP file: 10
Open stream to the ascii data file to be read
.IP number:
Number of bytes to read
.IP format:
C format string for reading the data, eg, "%f"
.IP variable:
A pointer to the variable of the appropriate type to read the data into. The 
type must be consistent with the \fIformat\fP, above.
.sp
.LP
=====================================================================
.sp 2
.NH 3 " ll_to_utm()"
.XS
              \*(SN   ll_to_utm()
.XE
.PP
Converts explicit location data from geographical to universal 
transverse mercator (utm) coordinates.  This routine performs a trigonometric 
conversion between geographical coordinates in latitude and longitude to utm
coordinates.
.LP
.sp
.B
int ll_to_utm (long, lat, sec_flag, zone_flag, easting, northing, zone)
.br
double long, lat;
.br
int sec_flag;
.br
double *easting, *northing;
.br
int *zone;
.R
.sp
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP "long, lat:" 11
The longitude and latitude of the point to be converted to utm
.IP sec_flag:
Set to 1 to specify that the longitude and latitiude are in seconds
.IP zone_flag:
Set to 1 if the user you are providing the utm zone, otherwise it will be 
computed from the longitude
.IP "easting, northing:"
Return the converted utm coordinates
.IP zone:
Returns the utm zone that the easting and northing belong to
.sp
.LP
=====================================================================
.sp 3
.NH 2 " ROUTINES HANDLING THE ELAS FORMAT"
.XS
      \*(SN   ROUTINES HANDLING THE ELAS FORMAT
.XE
.sp
.PP
The Science and Technology Laboratory Application Software is a geobased
information subsystem that has its own file format, called ELAS.  It was
originally designed for analyzing and processing digital imagery data such
as those collected by multispectral scanners or digitized from maps.
The following two routines open and read a read a line out of an ELAS file,
respectively.  Because ELAS files are so large, it is generally not possible
to read the entire file at once; thus the \fIread_elas_line()\fP routine, as
opposed to a \fIread_elas_file()\fP routine.
.PP
The \fIELAS\fP and \fIECOORD\fP structures are defined in the
"KHOROS_HOME/include/file_formats/elas.h" file.
To use the \fIopen_elas()\fP and \fIread_elas_line()\fP routines, you must have
in your code the include statement:
.sp
\f(CW
#include "KHOROS_HOME/include/file_formats/elas.h"
\fP
.LP
.sp 2
.NH 3 " open_elas()"
.XS
              \*(SN   open_elas()
.XE
.LP
Opens an ELAS image file for reading from disk.
.B 
.sp
ELAS *open_elas(filename, fid)
.br
char *filename;
.br
int *fid;
.sp 
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP filename: 10
The name of the image file in ELAS format to be opened.
.IP fid: 10
returns the file descriptor of the open ELAS file.
.sp
.LP
=====================================================================
.sp 2
.sp 2
.NH 3 " read_elas_line()"
.XS
              \*(SN   read_elas_line()
.XE
.LP
Reads a single scan line of a file in ELAS image file format.
ELAS images are read line by line rather than all at once, since they are
typically too large to read all at once.  The coordinates from the ELAS
scan line are returned in the ECOORD structure.
.LP
.sp
.B
.sp
read_elas_line(elas_coord)
.br
ECOORD *elas_coord;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP elas_coord: 10
A pointer to the \fIECOORD\fP data structure in which the coordinates
from the ELAS scan line will be stored.
.sp
.LP
=====================================================================
.sp 3
.NH 2 " ROUTINES HANDLING THE FITS FORMAT"
.XS
      \*(SN   ROUTINES HANDLING THE FITS FORMAT
.XE
.sp
.PP
The FITS image file format describes the standard  astronomical image format. 
This format is based on record sizes of 2880 bytes.  The following routines
support 2D FITS images only.
.PP
To use the \fIread_fits()\fP and \fIwrite_fits()\fP routines, you must have
in your code the include statement:
.sp
\f(CW
#include "KHOROS_HOME/include/file_formats/fits.h"
\fP
.LP
.sp 2
.NH 3 " read_fits()"
.XS
              \*(SN   read_fits()
.XE
Reads in an image file in the FITS format, and stores it in the \fIfits\fP 
structure that is defined in the "KHOROS_HOME/include/file_formats/fits.h" file.
.LP
.B 
.sp
struct fits *read_fits(filename)
.br
char *filename;
.sp 
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP filename: 10
The name of the image file in FITS format to be read in.
.sp
.LP
=====================================================================
.sp 2
.sp 2
.NH 3 " write_fits()"
.XS
              \*(SN   write_fits()
.XE
.LP
Writes out an image file in the FITS format, which is specified by a pointer
to a \fIfits\fP structure that is passed in.  The \fIfits\fP structure is 
defined in the "KHOROS_HOME/include/file_formats/fits.h" file.
.LP
.sp
.B
write_fits(filename, imageptr)
.br
struct fits *imageptr;
.br
char *filename;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP imageptr: 10
A pointer to the \fIfits\fP data structure that defines the image to be
written out.
.IP filename: 10
Name of the image file in FITS format to be written.
.sp
.LP
=====================================================================
.sp 3
.NH 2 " ROUTINES HANDLING THE PBM FORMAT"
.XS
      \*(SN   ROUTINES HANDLING THE PBM FORMAT
.XE
.sp
.PP
The portable bitmap/pixmap (PBM) format was introduced into the public
domain by Jeff Poskanzer in 1989 and since then has become very popular
as an X image file format.  "The portable bitmap format is a lowest
common denominator monochrome file format.  It was originally designed
to make it reasonable to mail bitmaps between different types of machines
using the typical stupid network mailers we have today.  Now it serves as
the common language of a large family of bitmap conversion filters."
.PP
The \fIpbm\fP structure is defined in the 
"KHOROS_HOME/include/file_formats/pbm.h" file.  To use the \fIread_pbm()\fP 
and \fIwrite_pbm()\fP routines, you must have in your code the 
include statement:
.sp
\f(CW
#include "KHOROS_HOME/include/file_formats/pbm.h"
\fP
.LP
.sp 2
.NH 3 " read_pbm()"
.XS
              \*(SN   read_pbm()
.XE
.LP
Reads in an image file in the PBM format, and stores it in the \fIpbm\fP 
structure that is defined in the "KHOROS_HOME/include/file_formats/pbm.h" 
file.
.LP
.B 
.sp
struct big *read_pbm(filename)
.br
char *filename;
.sp 
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP filename: 10
The name of the image file in PBM format to be read in.
.sp
.LP
=====================================================================
.sp 2
.NH 3 " write_pbm()"
.XS
              \*(SN   write_pbm()
.XE
.LP
Writes out an image file in the PBM format, which is specified by a pointer
to a \fIpbm\fP structure that is passed in.  The \fIpbm\fP structure is 
defined in the "KHOROS_HOME/include/file_formats/pbm.h" file.
.LP
.B
.sp
write_pbm(filename, imageptr)
.br
char *filename;
.br
struct pbm *imageptr;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP filename: 10
Name of the image file in PBM format to be written.
.IP imageptr: 10
A pointer to the \fIpbm\fP data structure that defines the image to be
written out.
.sp
.LP
=====================================================================
.sp 3
.NH 2 " ROUTINES HANDLING THE SUN RASTER FORMAT"
.XS
      \*(SN   ROUTINES HANDLING THE SUN RASTER FORMAT
.XE
.sp
.PP
The SUN Raster file format is the file format created and supported by
SUN Microsystems.  A Sun raster image file is composed of three parts: a
header containing 8 integers, a possibly empty set of colormap values, 
and the pixel image, stored a line at a time, in increasing y order.  
The image is laid out in the file as in a memory pixrect.  Each line of the
image is rounded up to the nearest 16 bits.
.PP
To use the \fIread_rast()\fP and \fIwrite_rast()\fP routines, you must have
in your code the include statement:
.sp
\f(CW
#include "KHOROS_HOME/include/file_formats/rast.h"
\fP
.LP
.sp 2
.NH 3 " read_rast()"
.XS
              \*(SN   read_rast()
.XE
Reads in an image file in the SUN raster format, and stores it in the 
\fIrast\fP structure that is defined in the 
"KHOROS_HOME/include/file_formats/rast.h" file.
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. 
.LP
.B 
.sp
struct rast *read_rast(filename)
.br
char *filename;
.sp 
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP filename: 10
The name of the image file in SUN Raster format to be read in.
.sp
.LP
=====================================================================
.sp 2
.NH 3 " write_rast()"
.XS
              \*(SN   write_rast()
.XE
.LP
Writes out an image file in the SUN Raster format, which is specified by a 
pointer to a \fIrast\fP structure that is passed in.  The \fIrast\fP 
structure is defined in the "KHOROS_HOME/include/file_formats/rast.h" file.
The image will be written out in IEEE BYTE ORDER, regardless of the machine 
that is executing the write.
.LP
.sp
.B
.sp
write_rast(filename, imageptr)
.br
struct rast *imageptr;
.br
char *filename;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP imageptr: 10
A pointer to the \fIrast\fP data structure that defines the image to be
written out.
.IP filename: 10
Name of the image file in SUN Raster format to be written.
.sp
.LP
=====================================================================
.sp 3
.NH 2 " ROUTINES HANDLING THE TGA FORMAT"
.XS
      \*(SN   ROUTINES HANDLING THE TGA FORMAT
.XE
.sp
.PP
Truevision defined the TGA file format in 1984 for use with its first
videographics products, since then, it has become popular for the storage
of color images, and has been widely accepted by the graphics industry. 
TGA is the file format  recommended for storing images for the AT&T 
Truevision product family; it allows software products to be compatible 
with AT&T telecommunications and imaging software.  Truevision Inc. 
has currently defined eleven types of data files; for a detailed 
description of the one supported by the following Khoros routines, 
see the man page for \fBtga2viff\fP.
.PP
To use the \fIread_tga()\fP and \fIwrite_tga()\fP routines, you must have
in your code the include statement:
.sp
\f(CW
#include "KHOROS_HOME/include/file_formats/tga.h"
\fP
.LP
.sp 2
.NH 3 " read_tga()"
.XS
              \*(SN   read_tga()
.XE
Reads in an image file in the TGA format, and stores it in the \fItga\fP 
structure that is defined in the "KHOROS_HOME/include/file_formats/tga.h" 
file. 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.
.LP
.B 
.sp
tga *read_tga(fid)
.br
int fid;
.sp 
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP fid: 10
File descriptor of the open file from which to read the TGA image
.IP extraskip:
Number of bytes to skip at the beginning of the file;  ie, there may be an
extra header at the top of the TGA file.
.sp
.LP
=====================================================================
.sp 2
.NH 3 " write_tga()"
.XS
              \*(SN   write_tga()
.XE
.LP
Writes out an image file in the tga format, which is specified by a pointer
to a \fItga\fP structure that is passed in.  The \fItga\fP structure is 
defined in the "KHOROS_HOME/include/file_formats/tga.h" file.
The image will be written out in NS BYTE ORDER, regardless of the machine 
that is executing the write. NS BYTE ORDER is Litendian byte order.
.LP
.sp
.B
.sp
write_tga(fid, imageptr)
.sp
int fid;
.br
tga *imageptr;
.br
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP fid: 10
File descriptor of the open file in tga format to be written.
.IP imageptr: 10
A pointer to the \fItga\fP data structure that defines the image to be
written out.
.sp
.LP
=====================================================================
