file_formats(3)

NAME
file_formats - Utilities for image file conversions other than VIFF.

DESCRIPTION
The file_formats 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. Note that these routines are only the utility routines, see intro(3) for the actual VIFF to ??? library conversions.

For an explanation of all the following routines in greater detail, with explanations of all arguments to each routine, see the section on file_formats in the Khoros Programmer's Manual, Chapter 8, Libraries.

ALL programs that utilize these routines MUST include the statement:

#include "vinclude.h"

Each set of conversion routines need different include files. The list follows:

For Sun Raster Images:
    #include "file_formats/rast.h"

For Terra-Mar Big Images:
    #include "file_formats/big.h"

For TGA Images:
    #include "file_formats/tga.h"

For DEM Images:
    #include "file_formats/dem.h"

For DLG Images:
    #include "file_formats/dlg.h"

For FITS Images:
    #include "file_formats/fits.h"

For PBM Images:
    #include "file_formats/pbm.h"

For ELAS Images:
    #include "file_formats/elas.h"

AVAILABLE ROUTINES

load_viff_data()

Loads float data from a 1-dimension array either real or complex into the VIFF data format.

load_viff_data(data, bands, location, nrows, ncols, numbands,
        dimension, interleave, start, row_skip, col_skip, complex)
float *data;
float *bands;
float *location;
int nrows;
int ncols;
int numbands;
int dimension;
int interleave;
int start;
int row_skip;
int col_skip;
int complex;

read_rast()

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.

#include "file_formats/rast.h"
struct rast *read_rast(filename)
char *filename;

write_rast()

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.

#include "file_formats/rast.h"
int write_rast(filename, image)
char *filename;
struct rast *image;

read_tga()

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.

#include "file_formats/tga.h"
tga *read_tga(filename)
char *filename;

write_tga()

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.

#include "file_formats/tga.h"
int write_tga(filename, image);
char *filename;
tga *image;

write_tga()

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.

#include "file_formats/tga.h"
int write_big(filename, image);
char *filename;
struct tga *image;

read_big()

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.

#include "file_formats/tga.h"
struct big *read_big(filename)
char *filename;

write_big()

Writes out an image file in the big format, which is specified by a pointer to a big structure that is passed in. The big structure is defined in the "KHOROS_HOME/include/file_formats/big.h" file.

write_big(filename, imageptr)
struct big *imageptr;
char *filename;

readdem()

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.

#include "file_formats/dem.h"
struct demimage *readdem(filename)
char *filename;

readdlg()

Reads in an image file in the DLG format, and stores it in the dlgimage structure that is defined in the "KHOROS_HOME/include/file_formats/dlg.h" file.

#include "file_formats/dlg.h"
struct dlgimage *readdlg(filename)
char *filename;

utm2arc()

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.

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)
double utm_west_edge, utm_south_edge, utm_east_edge, utm_north_edge;
double arc_west_edge, arc_south_edge, arc_east_edge, arc_north_edge;
double x_utm, y_utm;

arc2pixel()

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.

int arc2pixel (arc_west_edge, arc_south_edge, arc_east_edge, arc_north_edge, rows, cols, x_arc, y_arc, x_pixel, y_pixel)
double arc_west_edge, arc_south_edge, arc_east_edge, arc_north_edge;
int rows, cols;
double x_arc, y_arc;
int *x_pixel, *y_pixel;

pixel2arc()

Given the geographical coordinates of a square region and the size of an image that is to cover that regoin, this function returns the geographical coordinates corresponding to a pixel inside that image.

int pixel2arc (arc_west_edge, arc_south_edge, arc_east_edge, arc_north_edge, rows, cols, x_pixel, y_pixel, x_arc, y_arc)
double arc_west_edge, arc_south_edge, arc_east_edge, arc_north_edge;
int rows, cols;
int x_pixel, y_pixel;
double *x_arc, *y_arc;

dlg_line()

Plots a line in an image band. Returns TRUE (1) on success, FALSE (0) on failure.

int dlg_line (band, rows, cols, x1, y1, x2, y2)
char *band;
int rows, cols;
int x1, y1, x2, y2;

dlg_point()

Plots a point in an image band. Returns TRUE (1) on success, FALSE (0) on failure.

int dlg_point (band, rows, cols, x, y)
char *band;
int rows, cols;
int x, y;

cut_locations()

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.

int cut_locations (image)
struct xvimage *image;

get_bit_pixel()

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 ouput is an integer, which will be 0 or 1 depending on the value of the pixel we found.

int get_bit_pixel (imagedata, band, rows, cols, x, y, pixel)
unsigned char *imagedata;
int band;
int rows, cols;
int x, y;
int *pixel;

assign_locations()

Assigns explicit location data to an image.

int assign_locations (img, x_sw, y_sw, x_ne, y_ne)
struct xvimage *img;
double x_sw, y_sw, x_ne, y_ne;

nextline()

This utility moves the read head to the beginning of the next line of input.

void nextline(file)
FILE *file;

readfixed()

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.

int readfixed (file, number, format, variable)
FILE *file;
int number;
char *format;
char *variable;

ll_to_utm()

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.

int ll_to_utm (long, lat, sec_flag, zone_flag, easting, northing, zone)
double long, lat;
int sec_flag;
double *easting, *northing;
int *zone;

open_elas()

Opens an ELAS image file for reading from disk.

ELAS *open_elas(filename, fid)
char *filename;
int *fid;

read_elas_line()

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.

read_elas_line(elas_coord)
ECOORD *elas_coord;

read_fits()

Reads in an image file in the FITS format, and stores it in the fits structure that is defined in the "KHOROS_HOME/include/file_formats/fits.h" file.

struct fits *read_fits(filename)
char *filename;

write_fits()

Writes out an image file in the FITS format, which is specified by a pointer to a fits structure that is passed in. The fits structure is defined in the "KHOROS_HOME/include/file_formats/fits.h" file.

write_fits(filename, imageptr)
struct fits *imageptr;
char *filename;

read_pbm()

struct big *read_pbm(filename)
char *filename;

write_pbm()
Writes out an image file in the PBM format, which is specified by a pointer to a pbm structure that is passed in. The pbm structure is defined in the "KHOROS_HOME/include/file_formats/pbm.h" file.

write_pbm(filename, imageptr)
char *filename;
struct pbm *imageptr;