15. Associated File Formats

It is intended that nearly all associated binary data files have the same format provided by the label service utility routines. Each record of an associated file has the following format:

 Length    Type      Key       Char Data  Data (B,I*2,I*4,R*4,R*8)
-------------------------------------------------------
|         |        |         |           |            |
| 13 Char | 3 Char | 16 Char | x Bytes   | y Bytes    |
|         |        |         |           |            |
-------------------------------------------------------
Length:
Number of bytes in the record, excluding the length, data type, and key fields.

The definition of the Length field depends on whether or not the Char data field exists. If the Char data field exists, the length is divided into two integer numbers separated bya "/". The first integer specifies the length of the Char data field, and the second integer specifies the length of the Data field. If the Char data field does not exist, the length consists of one integer number specifying the length of the Data field.

Type:
Data type of the record (B,I2,I4,R4,R8).

Key:
User-entered identifying key for the record. The 16 characters include the null value.

Char Data:
Variable length character data.

Data:
Variable length data record.

15.1 Data Descriptor Record (DDR) File

The DDR file contains descriptive image information. There is one DDR file per image. This file is in label services format. The DDR file structure contains the following label service records for each image:

First record 

     
  long nl; /* number of lines in image  */
  long ns; /* number of samples in image  */
  long nbands;  /* number of bands in image  */
  long dtype;  /* data type of samples:  */
               /*  =1: unsigned char  */
               /*  =2: short  /*
               /*  =3: long  /*
               /*  =4: float  /*
  long master_line;  /* line relative to master image  */
  long master_sample;/* sample relative to master image  */
  long valid[8];   /* valid flags:  */
                   /*  =0: INVALID
                   /*  =1: VALID
                   /*  =2: UNKNOWN
                   /*  valid[0] => projection code  */
                   /*  valid[1] => zone code  */
                   /*  valid[2] => datum code  */
                   /*  valid[3] => proj_coef  */
                   /*  valid[4] => ground units  */
                   /*  valid[5] => ground distance  */
                   /*  valid[6] => corner coordinates  */
                   /*  valid[7] => line/sample increments  */
  long proj_code;  /* GCTP projection code  */
  long zone_code;  /* UTM or State Plane zone  */
  long datum_code; /* GCTP datum code  */
  long spare;      /* spare integer value for future use  */
  char system[12]  /* computer system data is on */
  char proj_units[12];  /* Projection units (GCTP units+other) */
  char last_used_date[12];  /* last modified date  */
        /*  NOTE: All ddr dates are stored as:  */
        /*  "dd-mmm-yy".  For example, a date  */      
        /*  of December 31, 1986 is stored as:  */
        /*  "31-dec-86" with month in lower  */
        /*  case.  */  
  char last_used_time[11];  /* last modified time  */
        /*  NOTE: All ddr times are stored  */
        /*  using a twenty-four hour clock.  */
        /*  Seconds are separated by a colon.  */
        /*  Example: 1:05:55 pm is stored as  */
        /*  1305:55  */
        /*  Note that this field is not zero
        /*  terminated in the file. */
Second record 
  double proj_coef[15]; /* GCTP projection parameters  */
                        /* refer to GCTP documentation for  */
                        /* field definitions  */
  double upleft[2];  /* Corner coordinates entered  */
  double loleft[2];  /* in latitude/longitude or  */
  double upright[2]; /* northing/easting order  */
  double loright[2]; /* projection coordinates (y,x)  */
  double pdist_y;    /* projection distance/pixel (y)  */
  double pdist_x;    /* projection distance/pixel (x)  */
  double line_inc;   /* line increment for sampling  */
  double sample_inc; /* sample increment for sampling  */
        /* NOTE: The line/sample increments are  */
        /* the values applied to the original */
        /* image to obtain this image.  If re-  */
        /* or sub-sampling was not applied,  */
        /* value contained in these fields is  */
        /* 1.0   */
Third + records (One record for each band) 
 
  double minval;   /* minimum intensity value  */
  double maxval;   /* maximum intensity value  */

        /*  Band DDR string data  */
  char bandno[4];  /* band number  */
  char valid[2];   /* validity flag for min/max  */
                   /*  =0: INVALID  */
                   /*  =1: VALID  */
                   /*  =2: BOUNDED  */
  char source[32];      /* source of data  */
  char instrument[32];  /* type of sensor  */
  char direction[64];   /* direction of the capture process  */
  char date[10];  /* capture date (See date format above)  */
  char time[8];   /* capture time (See time format above)  */
                  /*  Note that this field is not zero
                  /*  terminated in the file. */
The format for the DDR file follows:

First record

 Length    Type      Key       Char Data   Integer Data
-------------------------------------------------------
|         |        |         |           |            |
| 13 Char | 3 Char | 16 Char | 47 Bytes  | 72 Bytes   |
|         |        |         |           |            |
-------------------------------------------------------
Second record

 Length    Type      Key       Double Data   
------------------------------------------
|         |        |         |           |
| 13 Char | 3 Char | 16 Char | 216 Bytes |
|         |        |         |           |
------------------------------------------
Third record +, one record for each band

 Length    Type      Key       Char Data   Double Data
-------------------------------------------------------
|         |        |         |           |            |
| 13 Char | 3 Char | 16 Char | 151 Bytes | 16 Bytes   |
|         |        |         |           |            |
-------------------------------------------------------
Length:
Number of bytes in the record, excluding the length, data type, and key fields.

Type:
Data type of the record. (I4 or R8)

Key:
Identifying key for the record.

Data:
In the first record, the first 48 bytes are character data, the next 72 are integer data. In the second record, there are 216 bytes of double precision data. The third record type is repeated for each band and contains 151 bytes of character data and 16 bytes of double precision data.

15.2 Display and Lookup Table File (DLTF) Format

This file contains lookup table data. The DLTF stores parameters necessary to redisplay an image in the same state in which it was last viewed. A user may save an image at any step in processing and thus always be able to return to that point without having to execute the modules necessary to recreate the image. The DLTF format follows:

First record

 Length    Type      Key       Window    Zoom     Shift     Description
-----------------------------------------------------------------------
|         |        |         |         |         |         |          |
| 13 Char | 3 Char | 16 Char | 28 Char | 32 Char | 32 Char | 81 Char  |
|         |        |         |         |         |         |          |
-----------------------------------------------------------------------

 #Bands    Bands
----------------------------
|        |                 |
| 4 Char | #bands * 4 Char |
|        |                 |
----------------------------
Second record (one for each band):

 Length  Type   Key     Slope   Offset  Startpt Entpt  LUT data 
-------------------------------------------------------------------
|       |      |       |       |       |                          |
|13 Char|3 Char|16 Char|28 Char|12 Char|2 * Type + #entries *Type |
|       |      |       |       |       |                          |
-------------------------------------------------------------------
Length:
Number of bytes in the record, excluding the length, data type, and key fields.

The length is divided into two integer numbers separated by a "/". The first integer specifies the length of the character portion of the record, and the second integer specifies the length of the noncharacter portion of the record.

Type:
Data type of the record (B or I2).

Key:
User-entered key for the record (i.e., entry name) (**).

For the first record type, this key is limited to twelve characters for two reasons. First, LAS/XID can only handle twelve characters and second, this allows space to append LUT numbers for the 2nd through the Nth record. The DLTF support routines append an @ character to the end of this name before the record is written to the DLTF. This convention keeps the name unique.

For the second record type, the key is the key from the first record type with the LUT number appended. The LUT number is a sequential number based on the total number of bands in the entry. Thus if a total of three bands are saved in the entry, the LUT numbers would be 1, 2, and 3.

Window:
Four character strings containing the image file window. (sl,ss,nl,ns) (**).

Zoom:
Four character strings containing zoom factors. The first two contain the XY zoom values of the image, and the second two contain the XY zoom values of the graphics planes (**).

Shift:
Four character strings containing shift factors. The first two contain the XY shift values of the image, and the second two contain the XY shift values of the graphics planes (**).

Description:
Character string containing a user-specified description of the entry (**).

#Bands:
A character string containing the number of bands of LUT data in the record (up to MAXBND) (**).

Bands:
An array of character fields containing the band numbers of the image file (**).

Slope:
A character string containing the slope value to be applied to the LUT data for nonbyte images. The value is stored with the following character format: [-]m.nnnnnnE[+/-]xx (**).

Offset:
A character string containing the offset value to be applied to the LUT data for nonbyte images (**).

Startpt, Endpt, LUT data:
The look-up table data and range points for a single band of the image. The first two fields consist of the starting and ending point of the LUT. They are the values of the input image that correspond to the first and last entry in the LUT data, respectively. These values are followed by the LUT data.

** The length given for each character field allows for a null character at the end of the string (e.g., each element in the window field is seven characters; however, the actual value may only contain six characters).

15.3 Projection Definition File Format

The projection definition file format contains all information relative to a call to proj and projon. The file is in labeled table format. It may contain as many records as needed to define various projections in a project. This file is generated by the projprm module.

Example:

 
;
"PROJFILE","Projection parameter file";
"PROJKEY","C","Uniquely identify the defined projection",1,8
"PROJTYPE","I4","Projection type code",1,1
"PROJZONE","I4","Projection zone code",1,1
"PROJUNITS","I4","Units code",1,1
"PROJSPH","I4","Speroid code",1,1
"PROJPARMS","R8","Projection parameters",1,15;
"geo",0,62,4,0,0.00000000000000000000E+00,0.00000000000000000000E+00
0.00000000000000000000E+00,0.00000000000000000000E+00,
0.00000000000000000000E+00

15.4 Geometric Mapping Grid Files

The geometric mapping grid file contains a geometric mapping grid, information needed to fill the output space image's DDR, and miscellaneous mapping grid parameters and statistics. The format follows:

First record:

 Length    Type      Key       Model    Units    Proj_valid Fiterr_valid
-----------------------------------------------------------------------
|         |        |         |         |         |         |          |
| 13 Char | 3 Char | 16 Char | 15 Char | 12 Char | 4 Bytes | 4 Bytes  |
|         |        |         |         |         |         |          |
-----------------------------------------------------------------------

Griderr_valid Ncoeff   Code      Zone     Datum     Nrows      Ncols 
--------------------------------------------------------------------------
|           |         |         |         |         |         |          |
| 4 Bytes   | 4 Bytes | 4 Bytes | 4 Bytes | 4 Bytes | 4 Bytes | 4 Bytes  |
|           |         |         |         |         |         |          |
--------------------------------------------------------------------------

Lines     Samples     Out_lines          Out_samps
-------------------------------------------------------------
|         |         |                   |                   |
| 4 Bytes | 4 Bytes | (4 * Nrows) Bytes | (4 * Ncols) Bytes |
|         |         |                   |                   |
-------------------------------------------------------------
Second record:

 Length    Type      Key       Corners     Pdist     Projprms 
-----------------------------------------------------------------
|         |        |         |           |          |           |
| 13 Char | 3 Char | 16 Char | 64 Bytes  | 16 Bytes | 120 Bytes |
|         |        |         |           |          |           |
-----------------------------------------------------------------

Coeffs                  Max_grid_error Ave_grid_error RMS_grid_error
------------------------------------------------------------------
|                       |              |              |          |
| (2 * Ncoef * 8) Bytes | 16 Bytes     | 16 Bytes     | 8 Bytes  |
|                       |              |              |          |
------------------------------------------------------------------

Act_fit_err Grid_tol Max_fit_error Ave_fit_error RMS_fit_error
---------------------------------------------------------------
|           |        |             |             |            |
| 256 Bytes | 8 Bytes| 16 Bytes    | 16 Bytes    | 8 Bytes    |
|           |        |             |             |            |
---------------------------------------------------------------

In_lines                      In_Samps 
---------------------------------------------------------
|                           |                           |
| (Nrows * Ncols * 8) Bytes | (Nrows * Ncols * 8) Bytes |
|                           |                           |
---------------------------------------------------------
Length:
Number of bytes in the record, excluding the length, data type, and key fields.

Type:
Data type of the record (I4 or R8).

Key:
Identifying key for the record.

Model
Type of model used to generate the geometric mapping grid. Standard values are "POLYNOMIAL," "SPACECRAFT," and "FINITE ELEMENT." Other values are allowed, if need be.

Units:
Projection units. This value corresponds to the proj_units field in the DDR.

Proj_valid:
Valid field for projection fields.

Fiterr_valid:
Valid field for fit error fields.

Griderr_valid:
Valid field for gridding error fields.

Ncoeff:
Number of polynomial coefficients in X & Y. This field is zero if other than a polynomial model was used to generate the mapping grid.

Code:
Projection code for the output space image's DDR. Values for this field are defined in the "proj.h" include file. It has the same ranges and defaults as the proj_code field in the DDR.

Zone:
Projection zone code for UTM or State Plane projections. It has the same valid ranges and defaults as the zone_code field in the DDR.

Datum:
Projection datum code. It has the same valid range and defaults as the datum_code field in the DDR.

Nrows:
Number of geometric mapping grid rows.

Ncols:
Number of geometric mapping grid columns.

Lines:
Number of lines in the output image.

Samples:
Number of samples in the output image.

Out_lines:
The locations of the horizontal coordinate (line number) on each grid row, going from top to bottom. The output grid cells are of consistent size and are rectangular, perpendicular to the line,sample axis of the output image. Therefore, only intersections need be given.

Out_samps:
The locations of the vertical coordinate (pixel number) on each grid column, going from left to right. Again, only intersections need be given.

Corners:
Projection coordinates of the resulting output image's four corners. This field corresponds to the DDR's upleft, loleft, upright, and loright fields.

Pdist:
Projection distance per pixel in Y and in X. This field corresponds to the pdist_y and pdist_x field in the DDR.

Projprms:
Array of 15 projection coefficients as required by the projection transformation package. Refer to the projection transformation package documentation for a description of each field for a given projection. This field corresponds to the proj_coef field in the DDR.

Coeffs:
Transformation coefficients. The first ncoeff values are the Y transformation coefficients, followed by ncoeff X transformation coefficients.

Max_grid_err:
Maximum horizontal and vertical grid interpolation errors at any of 16 reference points. Gridding routines give an estimate of the overall quality of the gridding process using a 4 x 4 matrix of reference points located at the intersections of four vertical and four horizontal lines in the image region covered by the mapping grid. The lines are located 3/126, 43/126, 83/126, and 123/126 of the distance from one edge of the area to the other.

Ave_grid_err:
Average of the absolute values of the horizontal and vertical grid interpolation errors of the sixteen reference points.

Rms_grid_err:
RMS of the residual errors of the sixteen reference points.

Ave_fit_err:
Average of the absolute values of the horizontal and vertical residual errors of the tie points from the modeling process, if tie points were used and model = "POLYNOMIAL."

Grid_tol:
Tolerance used in reducing grid.

Max_fit_err:
Maximum horizontal and vertical residual errors of the tie points from the modeling process, if tie points were used and model = "POLYNOMIAL."

RMS_fit_err:
RMS of the residual errors from the modeling process, if tie points were used and model = "POLYNOMIAL."

Act_fit_err:
Actual fitting errors for each of the 16 reference points; each pair of values is given in (line, sample) order, going left to right in each row starting with the top row.

In_lines:
A buffer of input image line coordinates, one for each grid intersection. This buffer has a size of nrows * ncols * sizeof (double) bytes.

In_samps:
A buffer of input image sample coordinates, one for each grid intersection. This buffer has a size of nrows * ncols * sizeof (double) bytes.

15.5 Graphics Overlay Files (GOFs)

Graphics overlay files contain information necessary to display graphics data along with their descriptive attributes. These files use the label services format. Therefore, any other LAS applications that operate on label services files also operate on GOFs. Each file may contain any number of records. The information stored for each record type follows:

Each GOF also contains a header record storing the user-specified attribute names for the file. Attribute names are used to describe the attribute information contained in each record. For example, record 1 of a point GOF may contain a value of 4 for the first attribute. The corresponding attribute name (for example, "CLASS") gives the user a basis for interpreting the meaning of the attribute value. Each file may contain a maximum of 35 unique attribute names. These names may be eight characters in length, and each must have a data type definition (character, integer, real). These data types are used for conversion purposes when necessary. Attribute names are defined by the GOF function in the XID application and may be deleted by the delatt application. Attribute values may contain a maximum of 12 characters and must be compatible with the type defined for the attribute. Attribute values are defined when a GOF record is created or modified using the XID application. Each type of graphics data (point, line, poly, and annot) is stored in a separate file whose filename extension describes the graphics type. For example: MCKINLEY;GOF_POLY is a graphics overlay file containing polygon data; MCKINLEY;GOF_POINT contains point data; MCKINLEY;GOF_LINE contains line data; and MCKINLEY;GOF_ANNOT contains annotation data. Graphics overlay files may optionally be associated with images. The filename is again used to determine this. Using this example, if MCKINLEY is an existing image file, the graphics overlay file MCKINLEY;GOF_POLY is associated with the image. If however, MCKINLEY is not an existing image file, then the GOF is not associated with any particular image.

All coordinate pairs stored in the GOF are sample and line (X,Y) file coordinates within a defined image space.

Finally, the XID application may be used to add records to a GOF or to modify existing GOF records. The interface to GOFs is image I/O independent because it makes use of the label services file format. For this reason, they may be used outside of the LAS image processing package. The format for each type of GOF is expanded upon in the following subsections.

The GOF union and its underlying structures are defined in the "gof.h" include file (see the Include Files section).

Point File (GOF_POINT)

Header Record:

Length   Type   Key     # Recs  Attribute Names  Attrib Data Types Att Mask 
----------------------------------------------------------------------------
|       |      |       |       |                |                 |        | 
|13 Char|3 Char|16 Char|16 Char|35 9-Char fields|35 4-Char fields |35 Bytes|
|       |      |       |       |                |                 |        |
----------------------------------------------------------------------------
Point Data Records:

Length   Type   Label   Attributes 1-35           X       Y 
---------------------------------------------------------------
|       |      |       |                      |       |       |
|13 Char|3 Char|16 Char|35 13-Character fields| Float | Float |
|       |      |       |                      |       |       |
---------------------------------------------------------------
Length:
Number of bytes in the record, excluding the length, data type and key fields.

The length is divided into two integer numbers separated by a "/". The first integer specifies the length of the character portion of the record, and the second integer specifies the length of the noncharacter portion of the record.

Type:
Data type of the record (B,I2,I4,R4,R8).

Key:
The label services key for the header record.

This key is a predefined key specifically for the header record (**).

# Recs:
Number of records in the file (not including the header record).

Attribute Names:
A user-specified name for each attribute defined (**).

Attribute Data Types:
The data type of each defined attribute (**).

Att Mask:
This field contains 1 (one) byte for each attribute. The number contained in this field is the number of characters in the attribute name. A zero in this field indicates the attribute has not been defined.

Label:
A user-defined key to access the point record (**).

Attribute:
1 to 35 user-defined attribute values to be associated with the point (**).

X:
The X (sample) file coordinate location of the point (stored as a 4-byte floating point number).

Y:
The Y (line) file coordinate location of the point (stored as a 4-byte floating point number).

**
The length given for each character field allows for a null character at the end of the string. (For example, label has a length of 16; however, the user may only enter 15 characters.)

Line File (GOF_LINE)

Header Record:

Length   Type   Key     # Recs  Attribute Names  Attrib Data Types Att Mask
----------------------------------------------------------------------------
|       |      |       |       |                |                 |        |
|13 Char|3 Char|16 Char|16 Char|35 9-Char fields|35 4-Char fields |35 Bytes|
|       |      |       |       |                |                 |        |
----------------------------------------------------------------------------
Line Data Records:

Length   Type   Label   Attributes 1-35        # Pts    Future
---------------------------------------------------------------
|       |      |       |                      |       |       |
|13 Char|3 Char|16 Char|35 13-Character fields| Float | Float |
|       |      |       |                      |       |       |
---------------------------------------------------------------
        X, Y Pairs (X1,Y1 ... Xn,Yn)
------------------------------------------
|       |       |        |       |       | 
| Float | Float | . . .  | Float | Float |
|       |       |        |       |       |
------------------------------------------
Length:
Number of bytes in the record, excluding the length, data type, and key fields. The length is divided into two integer numbers separated by a "/". The first integer specifies the length of the character portion of the record, and the second integer specifies the length of the noncharacter portion of the record.

Type:
Data type of the record (B,I2,I4,R4,R8).

Key:
The label services key for the header record. This key is a predefined key specifically for the header record (**).

# Recs:
Number of records in the file (not including the header record).

Attribute Names:
A user-specified name for each attribute defined (**).

Attribute Data Types:
The data type of each defined attribute (**).

Att Mask:
This field contains 1 (one) byte for each attribute. The number contained in this field is the number of characters in the attribute name. A zero in this field indicates the attribute has not been defined.

Label:
A user-defined key to access the line record (**).

Attribute:
1 to 35 user-defined attribute values to be associated with the line (**).

Num Pts:
Number of points in the line. This is also used to calculate where the next line record begins (stored as a 4-byte floating point number).

Future:
Space available for future use.

X,Y Pairs:
X and Y (sample and line) file coordinate locations that define the line (stored as 4-byte floating point numbers).

**
The length given for each character field allows for a null character at the end of the string. (For example, label has a length of 16; however, the user may only enter 15 characters.)

Polygon File (GOF_POLY)

Header Record:

Length   Type   Key     # Recs  Attribute Names  Attrib Data Types Att Mask
----------------------------------------------------------------------------
|       |      |       |       |                |                 |        |
|13 Char|3 Char|16 Char|16 Char|35 9-Char fields|35 4-Char fields |35 Bytes|
|       |      |       |       |                |                 |        |
----------------------------------------------------------------------------
Polygon Data Records:

Length   Type   Label   Attributes 1-35         # Pts  Future 
---------------------------------------------------------------
|       |      |       |                      |       |       |
|13 Char|3 Char|16 Char|35 13-Character fields| Float | Float |
|       |      |       |                      |       |       |
---------------------------------------------------------------
        X, Y Pairs (X1,Y1 ... Xn,Yn)
------------------------------------------
|       |       |        |       |       |
| Float | Float | . . .  | Float | Float |
|       |       |        |       |       |
------------------------------------------
Length:
Number of bytes in the record, excluding the length, data type, and key fields. The length is divided into two integer numbers separated by a "/". The first integer specifies the length of the character portion of the record, and the second integer specifies the length of the noncharacter portion of the record.

Type:
Data type of the record (B,I2,I4,R4,R8).

Key:
The label services key for the header record. This key is a predefined key specifically for the header record (**).

# Recs:
Number of records in the file (not including the header record).

Attribute Names:
A user-specified name for each attribute defined (**).

Attribute Data Types:
The data type of each defined attribute (**).

Att Mask:
This field contains 1 (one) byte for each attribute. The number contained in this field is the number of characters in the attribute name. A zero in this field indicates the attribute has not been defined.

Label:
A user-defined key to access the polygon record (**).

Attribute:
1 to 35 user-defined attribute values to be associated with the polygon (**).

Num Pts:
The number of points in the polygon. This is also used to calculate where the next polygon record begins (stored as a 4-byte floating point number).

Future:
Space available for future use.

Xn,Yn Pairs:
X and Y (sample and line) file coordinate locations that define the vertices of the polygon (stored as 4-byte floating point numbers).

** The length given for each character field allows for a null character at the end of the string. (For example, label has a length of 16; however, the user may only enter 15 characters.)

Annotation File (GOF_ANNOT)

Header Record:

Length   Type   Key     # Recs  Attribute Names  Attrib Data Types Att Mask
----------------------------------------------------------------------------
|       |      |       |       |                |                 |        |
|13 Char|3 Char|16 Char|16 Char|35 9-Char fields|35 4-Char fields |35 Bytes|
|       |      |       |       |                |                 |        |
----------------------------------------------------------------------------
Annotation Data Records:

Length   Type   Label   Attributes 1-35         Annotation 
---------------------------------------------------------------
|       |      |       |                      |               |
|13 Char|3 Char|16 Char|35 13-Character fields| 509 Characters|
|       |      |       |                      |               |
---------------------------------------------------------------
 Size     Angle     X        Y
--------------------------------
|       |       |      |       |
| Float | Float |Float | Float |
|       |       |      |       |
--------------------------------
Length:
Number of bytes in the record, excluding length, data type, and key fields.

The length is divided into two integer numbers separated by a "/". The first integer specifies the length of the character portion of the record, and the second integer specifies the length of the noncharacter portion of the record.

Type:
Data type of the record (B,I2,I4,R4,R8).

Key:
The label services key for the header record. This key is a predefined key specifically for the header record (**).

# Recs:
Number of records in the file (not including the header record).

Attribute Names:
A user-specified name for each attribute defined (**).

Attribute Data Types:
The data type of each defined attribute (**).

Att Mask:
This field contains 1 (one) byte for each attribute. The number contained in this field is the number of characters in the attribute name. A zero in this field indicates the attribute has not been defined.

Label:
A user-defined key to access the annotation record (**).

Attribute:
1 to 35 user-defined attribute values to be associated with the annotation (**).

Annotation:
The user-specified annotation string (**).

Size:
Annotation size (stored as a 4-byte floating point number).

Angle:
Annotation angle (stored as a 4-byte floating point number).

X,Y:
X and Y (sample and line) file coordinate for the annotation location (stored as 4-byte floating point numbers).

**
The length given for each character field allows for a null character at the end of the string. (For example, the annotation string has a length of 509; however, the user may only enter 508 characters.)

15.6 Header Ancillary Annotation Trailer (HAAT) File(s)

Header Ancillary Annotation Trailer (HAAT) files contain all of the information accompanying an image in the same format as it was on tape. The HAAT files are associated files, one file for each type of record. The records are written to a binary, fixed length file. Each function using the HAAT files has to unpack the fields that it needs for processing. The programmer should refer to the tape format documentation for a description of the files or to the dspassoc module. File contents, as well as the number of files, vary with the type of data being used.

The TAE naming convention is as follows: 

     filename;format.record-type
An example from edipsin where filename=test: 

test;edips.ancil - contains EDIPS ancillary records

test;edips.annot - contains EDIPS annotation records

test;edips.headr - contains EDIPS header records

test;edips.trail - contains EDIPS trailer records

15.7 History (HIS) File

There is one history file per image. The file is in label services format. File format for the history file is:

 Length  Type   Key     Date    System User     Module   Parms 
-----------------------------------------------------------------
|       |      |       |       |      |       |       |         |
|13 Char|3 Char|16 Char|17 Char|4 Char|20 Char|20 Char|as needed|
|       |      |       |       |      |       |       |         |
-----------------------------------------------------------------
Length:
Number of bytes in the record, excluding the length, data type, and key fields.

Type:
Data type of the record (B).

Key:
Identifying key for the record (currently this is blank).

Date:
Date and time the application module was executed.

System:
System the module was executed on (VMS, UNIX, etc.).

User:
User login name.

Module:
Application module name (subcommand included).

Parms:
Parameter names and their values.

The TAE global $HISTRY provides the option to create history files that are the concatenation of all histories from the original image to the present file.

15.8 Merged Tie Point Files

The merged tie point files record the approximate coordinates of tie points and specifies options to be used during automatic, precision correlation of each tie point. Each file consists of a single header record, followed by a record for each tie point. The format follows:

First record

 Length   Type    Key     Chip_mode Units   Sea_name    Ref_name 
--------------------------------------------------------------------
|        |       |        |       |        |           |           |
| 13 Char| 3 Char| 16 Char| 9 Char| 12 Char| CMLEN Char| CMLEN Char|
|        |       |        |       |        |           |           |
--------------------------------------------------------------------

Corners   Pdist      Projprms    Proj_valid   Code     Zone      Dataum
--------------------------------------------------------------------------
|        |          |           |           |         |         |        |
|64 Bytes| 16 Bytes | 120 Bytes | 8 Bytes   | 8 bytes | 8 Bytes | 8 Bytes|
|        |          |           |           |         |         |        |
--------------------------------------------------------------------------
Second record

 Length   Type    Key     Pt_id     Ref_chip    Sea_chip 
-----------------------------------------------------------
|        |       |        |        |          |           | 
| 13 Char| 3 Char| 16 Char| 20 Char|CMLEN Char| CMLEN Char|
|        |       |        |        |          |           | 
-----------------------------------------------------------

Geo_coord Nominal   Ref_coord Elevation Zoom_factor Chip_size Offsets
_________________________________________________________________________
|        |         |         |          |          |          |         |
|16 Bytes| 16 Bytes| 16 Bytes| 8 Bytes  | 8 Bytes  | 16 Bytes | 16 Bytes|
|        |         |         |          |          |          |         |
_________________________________________________________________________
Length:
Number of bytes in the record, excluding the length, data type, and key fields.

Type:
Data type of the record (I4 or R8).

Key:
Identifying key for the record.

Chip mode:
Chip mode flag. Values are: 
     "NOCHIPS"  Reference chip images not used 
     "CHIPTEM"  Reference chips used to establish 
                temporal registration
     "CHIPFUL"  Reference chips used to establish 
                geographic registration--extract from 
                full input image
     "CHIPPRE"  Reference chips used to establish 
                geographic registration--search 
                subimages prescaled or rotated.
Units:
Projection units. This value corresponds to the proj_units field in the DDR.

Sea_name:
LAS name of the search image from which points were obtained.

Ref_name:
LAS name of the reference image from which points were obtained. If points were obtained from a source other than an image, this field will be blank.

Corners:
Projection coordinates of the resulting output image's four corners. This field corresponds to the DDR's upleft, loleft, upright, and loright fields.

Pdist:
Projection distance per pixel in Y and in X. This field corresponds to the pdist_y and pdist_x field in the DDR.

Projprms:
Array of 15 projection coefficients as required by the projection transformation package. Refer to the projection transformation package documentation for a description of each field for a given projection. This field corresponds to the proj_coef field in the DDR.

Proj_valid:
Valid field for projection fields.

Code:
Projection code for the output space image's DDR. Values for this field are defined in the "proj.h" include file. It has the same valid ranges and defaults as the proj_code field in the DDR.

Zone:
Projection zone code for UTM or State Plane projections. It has the same valid ranges and defaults as the zone_code field in the DDR.

Datum:
Projection datum code. It has the same valid range and defaults as the datum_code field in the DDR.

Pt_id:
A user-entered field describing each point. It must be unique among points in this file.

Ref_chip:
The LAS image name of the file containing the subimage reference chip. This field is blank if a subimage chip file does not exist for this tie point.

Sea_chip:
The LAS image name of the file containing the prescaled or rotated subimage search chip. This field is blank if a subimage chip file does not exist for this tie point.

Geo_coord:
Geographic coordinates of the tie point. This field may or may not contain data, depending upon the type of registration performed.

Nominal:
Nominal search image location of the tie point in line, sample in the full search image.

Ref_coord:
Image location of the tie point in line, sample in the reference image or subimage. This defines the center of the reference chip to be extracted during the correlation process.

Elevation:
Elevation of the tie point in meters.

Zoom_factor:
The enlargement factor used when selecting the tie point. This gives an indication as to the possible subpixel accuracy of the tie point.

Chip_size:
Desired subimage width and height.

Offsets:
Desired horizontal and vertical search offsets.

15.9 Resampling Weight Table Files

The resampling weight table files contains up to three 33 by N matrices of separable interpolation weights to be used in brightness level resampling. N is the resampling kernel dimension and 33 identifies the 32 subdivisions between pixel values, including both endpoints. The format follows:

 Length   Type    Key      Size1     Size2    Size3 
--------------------------------------------------------
|        |       |        |         |        |         | 
| 13 Char| 3 Char| 16 Char| 8 Bytes | 8 Bytes| 8 Bytes |
|        |       |        |         |        |         |
--------------------------------------------------------

Table1                 Table2                Table3 
------------------------------------------------------------------
|                    |                     |                     |
|(Size1 * 264) Bytes | (Size1 * 264) Bytes | (Size1 * 264) Bytes | 
|                    |                     |                     |
------------------------------------------------------------------
Length:
Number of bytes in the record, excluding the length, data type, and key fields.

Type:
Data type of the record is R8.

Key:
Identifying key for the record.

Size1:
Size of the first table. This table is generally applied in the horizontal direction, but the actual use of this and every table is determined by the routine doing the resampling.

Size2:
Size of the second table. This table is generally applied in the vertical direction. If the second table is not present, this field will contain a zero.

Size3:
Size of the third table. This table is used only with the three- pass option in geom. If the third table is not present, this field will contain a zero.

Table1:
Horizontal resampling table. This is a 33 by Size1 matrix of double precision values. Size1 values for the first of the 33 increments are given, followed by Size1 values for the second of the 33 increments, and so on.

Table2:
Vertical resampling table. This is a 33 by Size2 matrix of double precision values. The format of Table2 is like that of Table1.

Table3:
Third-pass resampling table. This is a 33 by Size3 matrix of double precision values. The format of Table3 is like that of Table1.

15.10 Stats File Format

The file is made up of fixed length records of 512 bytes each. This is a binary file and not a text file. The first record points directly to all the classes. Each class has a record which points to all its sites. The user's data is kept as linked lists of records off the appropriate node. There is also a linked list of deleted records which is pointed to by the first record.

The first 70 bytes of all records are used to hold the same information regardless of the tree level to which the record belongs.

The following is a list of the common fields in the records.

Field name     Function
----------     --------
Data-type      Type of data the record holds. (e.g., "CLASS-LIST",
                  "SITE-LIST","NAME","HIST001","MEAN","POLYGON"
                   "COVARIANCE_MATRIX"
Continuation   If the data record does not fit in our data record space,
  Pointer          put a pointer to the next record here.  If the data 
                   is not continued, then put NULL here.
Next           This indicates the next record at this level.
Shape[9]       This describes the data that is to follow.
The following documentation contains the record formats in more detail. The values which are fixed for each record type have been given.

Image Level Records (level 0)

-----------------------------------------------------------------------
|  First record of the file                                                  |
|                                                                     |
|  Byte #'s      Bytes     Function                                   |
|  --------      -----     --------                                   |
|                                                                     |
|    1 -  26       26      Data-type = "CLASS-LIST"                   |
|   27 -  30        4      Continuation ptr. = NULL                   |
|   31 -  34        4      Next image-level data (ptr)                |
|   35 -  70       36      Shape vector                               |
|   71 -  74        4      Number of classes                          |
|   75 - 474      400      Pointers to classes                        |
|  475 - 478        4      First deleted record (ptr)                 |
|  479 - 512       34      Empty                                      |
|                                                                     |
|  The "first deleted record pointer" points to the first             |
|  record of the deleted record linked list.                          |
|                                                                     |
|                                                                     |
|  Data Record                                                         |
|                                                                     |
|  Byte #'s      Bytes     Function                                   |
|  --------      -----     --------                                   |
|                                                                     |
|   1 -  26        26      Data-type                                  |
|  27 -  30         4      Continuation ptr.                          |
|  31 -  34         4      Next image-level data (ptr)                |
|  35 -  70        36      Shape vector                               |
|  71 - 512       442      Image-level data                           |
|                                                                     |
|  Note:  All stats files must have at least one record               |
|         which is the first record.  Its data type is                |
|         "CLASS-LIST."                                               |
-----------------------------------------------------------------------
Class Level Records (level 1)


-----------------------------------------------------------------------
|  First record for each class                                               |
|                                                                     |
|                                                                     |
|  Byte #'s      Bytes     Function                                   |
|  --------      -----     --------                                   |
|                                                                     |
|    1 -  26       26      Data-type = "SITE-LIST"                    |
|   27 -  30        4      Continuation ptr. = NULL                   |
|   31 -  34        4      Next class-level data (ptr)for this site   |
|   35 -  70       36      Shape vector                               |
|   71 -  74        4      Number of sites for this class             |
|   75 - 474      400      Pointers to sites                          |
|  475 - 512       38      Empty                                      |
|                                                                     |
|                                                                     |
|  Data Record - Level 1 (class level)                                 |
|                                                                     |
|  Byte #'s      Bytes     Function                                   |
|  --------      -----     --------                                   |
|                                                                     |
|   1 - 26         26      Data-type                                  |
|  27 - 30          4      Continuation ptr.                          |
|  31 - 34          4      Next class-level data (ptr) for this class |
|  35 - 70         36      Shape vector                               |
|  71 - 512       442      Class-level data                           |
|                                                                     |
|  Note:  All class must have at least one record which is            |
|         its first.  Its data type is "SITE-LIST."                   |
|                                                                     |
-----------------------------------------------------------------------
Site Level Records (level 2)

-----------------------------------------------------------------------
|  Data Record                                                         |
|                                                                     |
|  Byte #'s      Bytes     Function                                   |
|  --------      -----     --------                                   |
|                                                                     |
|   1 - 26         26      Data-type                                  |
|  27 - 30          4      Continuation ptr.                          |
|  31 - 34          4      Next site-level data (ptr) for this site   |
|  35 - 70         36      Shape vector                               |
|  71 - 512       442      Site-level data                            |
-----------------------------------------------------------------------

15.11 Tie Point Location Files

The tie point location files record the results of automatic or manual correlation for subsequent use in generating geometric mapping grids for the rectification process. Each tie point location file consists of a single header record followed by one record for each tie point. The format follows:

First record

 Length   Type    Key     Ref_mode  Units   Peak_method Corr_type
--------------------------------------------------------------------
|        |       |        |       |        |           |           |
| 13 Char| 3 Char| 16 Char| 9 Char| 12 Char| 25 Char   | 7 Char    |
|        |       |        |       |        |           |           |
--------------------------------------------------------------------

Sea_name       Ref_name
---------------------------
|            |            |
| CMLEN Char | CMLEN Char |
|            |            |
---------------------------

Corners   Pdist      Projprms    Edge_thres   Min_str  Max_dis   
_________________________________________________________________
|        |          |           |           |         |         |
|64 Bytes| 16 Bytes | 120 Bytes | 8 Bytes   | 8 bytes | 8 Bytes |
|        |          |           |           |         |         |
_________________________________________________________________

Proj_valid  Code     Zone      Datum
-----------------------------------------
|         |         |         |         |
| 8 Bytes | 8 Bytes | 8 Bytes | 8 Bytes |
|         |         |         |         |
-----------------------------------------
Second record

 Length   Type    Key     Pt_id     Ref_chip   
-----------------------------------------------
|        |       |        |        |          | 
| 13 Char| 3 Char| 16 Char| 20 Char|CMLEN Char|
|        |       |        |        |          | 
-----------------------------------------------

Geo_coord  Sea_coord   Ref_coord  RMS_error Strength   Displacement
-----------------------------------------------------------------
|          |          |          |          |         |         |
| 16 Bytes | 16 Bytes | 16 Bytes | 16 Bytes | 8 Bytes | 8 Bytes |
|          |          |          |          |         |         |
-----------------------------------------------------------------

 Nominal    Elevation Zoom_factor Ref_size  Offsets   Chip_loc  Sea_size
--------------------------------------------------------------------------
|         |         |         |          |          |          |         |
|16 Bytes | 8 Bytes | 8 Bytes | 16 Bytes | 16 Bytes | 16 Bytes | 16 Bytes|
|         |         |         |          |          |          |         |
--------------------------------------------------------------------------

Chip_coord   Req_size  Location   Active
--------------------------------------------
|          |          |          |         |
| 16 Bytes | 16 Bytes | 16 Bytes | 8 Bytes |
|          |          |          |         |
--------------------------------------------
Length:
Number of bytes in the record, excluding the length, data type, and key fields.

Type:
Data type of the record (I4 or R8).

Key:
Identifying key for the record.

Ref_mode:
Reference mode flag. Valid values are: 

     "IMAGE"    Reference scene is a full image
     "MAP"      Reference area is a map 
     "CHIPTEM"  Reference chips used to establish
                  temporal registration 
     "CHIPFUL"  Reference chips used to establish
                  geographic registration--extract
                  from full input image 
     "CHIPPRE"  Reference chips used to establish
                  geographic registration--search
                  subimages prescaled or rotated.
Units:
Projection units. This value corresponds to the proj_units field in the DDR.

Peak_method:
Correlation peak fitting method. Valid values are:

     "RECIPROCAL"  Elliptic paraboloid fit to
                     reciprocal of correlation values
     "PARABOLOID"  Elliptic paraboloid fit
     "GAUSSIAN"    Elliptic gaussian fit
     "NEAR_INT"    No surface fit.  Tie point assigned
                     the integer coordinate which gave
                     the largest correlation value.
     "NO_CORR"     Auto correlation not performed
Corr_type:
Type of correlation used. Valid types are: 
     "EDGE"   Edge correlation 
     "GREY"   Grey level correlation 
     "PHASE"  Phase correlation 
     "MANUAL" Manually correlated--automatic
                correlation not performed
Sea_name:
LAS name of the search image from which points were obtained.

Ref_name:
LAS name of the reference image from which points were obtained. If points were obtained from a source other than an image, this field may be blank.

Corners:
Projection coordinates of the resulting output image's four corners. This field corresponds to the DDR's upleft, loleft, upright, and loright fields.

Pdist:
Projection distance per pixel in Y and in X. This field corresponds to the pdist_y and pdist_x field in the DDR.

Projprms:
Array of 15 projection coefficients as required by the projection transformation package. Refer to the projection transformation package documentation for a description of each field for a given projection. This field corresponds to the proj_coef field in the DDR.

Edge_thres:
Fraction of pixels to be classified as edges. Refer to the correlation routine for a description of this field.

Min_str:
Minimum acceptable correlation strength.

Max_dis:
Maximum acceptable difference between the nominal tie point location and that given by correlation.

Proj_valid:
Valid field for projection fields.

Code:
Projection code for the output space image's DDR. Values for this field are defined in the "proj.h" include file. It has the same valid ranges and defaults as proj_code field in the DDR.

Zone:
Projection zone code for UTM or State Plane projections. It has the same valid ranges and defaults as the zone_code field in the DDR.

Datum:
Projection datum code. It has the same valid range and defaults as the datum_code field in the DDR.

Pt_id:
A user-entered field describing each point. It must be unique among points in this file.

Ref_chip:
The LAS image name of the file containing the subimage reference chip. This field is blank if a subimage chip file does not exist for this tie point.

Geo_coord:
Geographic coordinates of the tie point. This field may or may not contain data, depending upon the type of registration performed.

Sea_coord:
Refined search image location of the tie point in line, sample in the full search image.

Ref_coord:
Image location of the tie point in line, sample in the reference image or subimage. This defines the center of the reference chip extracted during the correlation process.

Rms_error:
Estimated horizontal and vertical RMS errors. This field is not valid if correlation was not attempted or was not successful.

Strength:
Strength of correlation; set to zero if automatic correlation not attempted. If points were manually selected, the zoom_factor may be used as a rough indication of "correlation" strength--however this is not an analogous indicator and the "units" of measurement are different.

Displacement:
Displacement, measured diagonally, from nominal input image location of tie point to location obtained by correlation; zero if automatic correlation was not attempted.

Nominal:
Nominal search image line and sample coordinates of the tie point; not valid if automatic correlation was not performed.

Elevation:
Elevation of the tie point in meters.

Zoom_factor:
The enlargement factor used when selecting the tie point. This gives an indication as to the possible subpixel accuracy of the tie point.

Ref_size:
Actual width and height of the reference subimage. This reflects adjustments made by the correlation process.

Offsets:
Requested horizontal and vertical search offsets.

Chip_loc:
The line, sample coordinate relative to the full image of the upper-left corner of the input subimage.

Sea_size:
Actual width and height of the input search subimage. This reflects adjustments made by the correlation process.

Chip_coord:
The line, sample coordinates of the tie point relative to the reference chip image. This field is not valid if chips were not used.

Req_size:
Requested width and height of the reference subimage; not valid if automatic correlation was not performed.

Location:
Line and sample coordinates of the upper-left corner of the reference subimage relative to the reference image or reference chip.

Active:
Tie point active flag with accept/reject codes. Valid values are:

     0 --> Accept manually extracted tie point
     1 --> Accept automatically registered tie point
     2 --> Reject; correlation peak too near edge of search area.
     3 --> Reject; subsidiary peak comparable in strength to main peak
     4 --> Reject; strength of peak below minimum specified by user
     5 --> Reject; diagonal displacement from nominal location exceeds 
                    maximum specified by user
     6 --> Correlation not attempted; error in correlation parameters
     7 --> Reject; manually by user
     8 --> Reject; automatically by the modeling process
     9 --> Reject; manually by user during the modeling process
    1X --> Previously rejected tie point reaccepted manually by user.  
                   X indicates original active code of tie point 
                   (0  9) before being reaccepted

15.12 Tie Point Selection Files

Each tie point selection file contains coordinates relative to a single image. Two tie point selection files, one for the search image and one for the reference image or geographic data, must be merged to specify temporal or geographic registration.

Although merging the files requires an extra processing step, the initial generation of two separate data sets permits measurement of map coordinates in a separate step from tie point selection and also facilitates reusing a set of reference image tie points for temporal registration of a series of images.

The tie point selection file consists of a single header record and one tie point selection record for each tie point. The format follows:

First Record

 Length   Type    Key     Mode     Units   Name  
--------------------------------------------------------
|        |       |        |       |        |           |
| 13 Char| 3 Char| 16 Char| 4 Char| 12 Char| CMLEN Char|
|        |       |        |       |        |           |
--------------------------------------------------------

Corners   Pdist      Projprms    Proj_valid   Code     Zone      Datum
__________________________________________________________________________
|        |          |           |          |         |         |         |
|64 Bytes| 16 Bytes | 120 Bytes | 8 Bytes  | 8 bytes | 8 Bytes | 8 Bytes |
|        |          |           |          |         |         |         |
__________________________________________________________________________
Second Record

 Length   Type    Key     Pt_id     Chip_name   
-----------------------------------------------
|        |       |        |        |          | 
| 13 Char| 3 Char| 16 Char| 20 Char|CMLEN Char|
|        |       |        |        |          | 
-----------------------------------------------

Coord      Image_coord Elevation Zoom_factor Chip_size Offsets
------------------------------------------------------------------
|          |          |         |          |          |          |
| 16 Bytes | 16 Bytes | 8 Bytes |  8 Bytes | 16 Bytes | 16 Bytes |
|          |          |         |          |          |          |
------------------------------------------------------------------
Length:
Number of bytes in the record, excluding the length, data type, and key fields.

Type:
Data type of the record (R8).
Key:
Identifying key for the record.

Mode:
Tie point mode. Valid values are: 

     "GEO"  Geographic Coordinates 
     "REF"  Reference Image Coordinates 
     "SEA"  Search Image Coordinates 
     "PRO"  Projection Coordinates 
     "USR"  User Defined Coordinates
Units:
Projection units. This value corresponds to the proj_units field in the DDR.

Name:
LAS name of the image from which points were obtained. If points were obtained from a source other than an image, this field will be blank.

Corners:
Projection coordinates of the resulting output image's four corners. This field corresponds to the DDR's upleft, loleft, upright, and loright fields.

Pdist:
Projection distance per pixel in Y and in X. This field corresponds to the pdist_y and pdist_x field in the DDR.

Projprms:
Array of 15 projection coefficients as required by the projection transformation package. Refer to the projection package documentation for a description of each field for a given projection. This field corresponds to the proj_coef field in the DDR.

Proj_valid:
Valid field for projection fields.

Code:
Projection code for the output space image's DDR. Values for this field are defined in the "proj.h" include file. It has the same valid ranges and defaults as the proj_code field in the DDR.

Zone:
Projection zone code for UTM or State Plane projections. It has the same valid ranges and defaults as the zone_code field in the DDR.

Datum:
Projection datum code. It has the same valid range and defaults as the datum_code field in the DDR.

Pt_id:
A user-entered field describing each point. It must be unique among points in this file. When tie point selection files are merged, this field is used as the key for the merge.

Chip_name:
The LAS image name of the file containing the subimage chip. If the file contains geographic or projection coordinates, this field contains the map identifier of the map used to determine the coordinates. This map id may be cross referenced in the map identifier file.

Coord:
Coordinates of the tie point. These are either geographic coordinates, projection coordinates, or user-defined coordinates. This field is valid when mode is set to "GEO," "PRO," or "USR."

Image_coord:
Image location of the tie point in line/sample in the full image. This field is used when mode is set to "REF" or "SEA," but it may also contain data with other types of registrations.

Elevation:
Elevation of the tie point in meters.

Zoom_factor:
The enlargement factor used when selecting the tie point. This gives an indication as to the possible subpixel accuracy of the tie point.

Chip_size:
Desired subimage width and height. This field is valid only with mode = "REF".

Offsets:
Desired horizontal and vertical search offsets. This field is valid only with mode = "SEA".