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.
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:
- Points:
- A displayable label specified by the user
- The line and sample location in file coordinates of the point
- The attribute values of the user-defined attributes for the point
- Lines:
- A displayable label specified by the user
- The line and sample locations in file coordinates of the line
segment endpoints making up the line. There is no limit on the
number of points a line may contain.
- The number of points making up the line
- The attribute values of the user-defined attributes for the line
- Polygons:
- A displayable label specified by the user
- The line and sample locations in file coordinates of the vertices
of the polygon. There is no limit on the number of vertices a
polygon may contain.
- The number of vertices making up the polygon
- The attribute values of the user-defined attributes for the polygon
- Annotation:
- The line and sample location in file coordinates of the starting
point of the annotation text
- The pixel height of the annotation text
- The angle at which the annotation text is written
- The attribute values of the user-defined attributes for the
annotation
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".