12. DDR Implementation Guidelines

12.1 General Assumptions

A null value contains a blank if it is a string or a 0 (zero) if it is a numeric value. If a 0 is a valid value for a particular field, the validity flag should be checked.

Module editddr is also implemented so that the user can add, change, invalidate, or validate any field.
The only fields of the input DDR file to be changed are the last_used_date and last_used_time fields.
For applications which create an output DDR but have no input DDR file (e.g., testgen, tapein, etc.) when there are values that are not known by the application program, the corresponding validity flag is given the value of a TAE global called $DDRVFLG. This flag has either the value of "IN" for INVALID or "UN" for UNKNOWN. Using this global eliminates confusion of the UNKNOWN validity flag by users who do not combine images of unlike origins.
The UNKNOWN validity flag is used when combining an image that has valid projection information with an image that does not have valid projection information. Using the UNKNOWN validity flag for the image that does not have the valid projection information preserves the valid projection information when the output image is created.
EXAMPLE:
```
     A mask image is created using testgen
     and this image is combined using the routine
     concat with an image that has valid projection
     information.  If the testgen image validity flags
     had the value of INVALID, the output image
     validity flags would have the value of INVALID
     and the projection information of the input
     image is lost.  But, if the testgen image
     contained the value of UNKNOWN, the output
     image validity flags would have the value of
     VALID and the projection information of the
     input image would be retained by copying the
     information to the input DDR file.
```
For application modules that have multiple inputs and a single output image, the fields proj_code, zone_code, datum_code, proj_units, proj_coef, upleft, loleft, upright, loright, pdist_y, pdist_x, line_inc, samp_inc and their associated valid fields contain the values as shown by the truth table.

Truth Table
```
Three possible values for validity flags:
   = 0 invalid(I)
   = 1 valid(V)
   = 2 unkonwn(U)
```
Assumptions:
1. The validity flags are checked first, and then (if necessary) actual values are checked in determining output.
2. If any of the input validity flags are invalid, the actual values are not checked. The output value is null and the corresponding flags is invalid.
3. Validity flags for values filled in from tape header records are marked VALID. If a field cannot be filled in from the tape header records, the validity flag of that field will have the value of $DDRVFLG.
4. If data values of the projection fields are not equal, a nonfatal error message is output.
5. One exception to this table is the updating of the corder fields: upleft, loleft, upright, loright. If the corner fields of two or more input images are not within tolerance of each other, a nonfatal error message is output and the validity flag is set to $DDRVFLG. The values of the first image with valid corner fields are copied to the output DDR file if $DDRVFLG is set to UNKNOWN. The values of these four fields are made null if $DDRVFLG is set to INVALID.
```
------------------------------------------------------------
| flag1 | flag2 | equality of data | out value |output flag|
------------------------------------------------------------
|   V   |   V   |    equal         |  copy     |    V      |
|   V   |   V   |  not equal       |  null     |    I      |
|   I   |   I   |     N/A          |  null     |    I      |
|   U   |   U   |    equal         |  copy     |    U      |
|   U   |   U   |  not equal       |  null     |    U      |
|   V   |   I   |     N/A          |  null     |    I      |
|   V   |   U   |     N/A          |copy valid |    V      |
|   I   |   U   |     N/A          |  null     |    I      |
------------------------------------------------------------
```

12.2 Master_line and master_sample fields

Master coordinate fields do not have a validity flag. The values of these fields are copied/recalculated when there is only one input image.
For modules that have multiple inputs, the master_line and master_sample of the output image are made (1,1).
For modules that modify the internal geometry of an image, master_line and master_sample of the output image are made (1,1).
For module perspec, master_line and master_sample of the output image are made (1,1).

12.3 Proj_code, zone_code, datum_code, proj_coef, proj_units and valid fields

When the values for these fields can be retrieved from the header information of the input tape, the tape routine places these values in the correct fields and sets the corresponding validity flags to VALID.
For the module perspec these fields are invalid because the projection that the image was mapped to is lost.

12.4 System field

If this field does not match the system currently doing the processing and the data type of the image is not compatible with the processing system, a fatal error is output. (This check exists because of the possibility of a network file server being used to connect systems with different data formats.)
This parameter is always retrieved, never copied. One exception is editddr, in which the user may change the system field.
The codes used for this field are in two parts. The first part is a general code that shows in which hardware format the data is stored; the second part is a code that shows the specific operating system of the machine. This field is in the following format.

          Machine     Operating
          Hardware    System
          Code        Code
          ---------------------
               ieee-std
                sun-bsd

This field is retrieved from a logical (environment variable) called DATASYS.

12.5 Last_modified date and time fields

This field is updated on the open (beginning of processing) and not the close (end of processing).
For the module tapein this field is updated even when the DDR file is to be copied from the tape.
For the module tapeout this field is updated as the DDR file is copied from the tape.

12.6 Upleft, loleft, upright, loright and valid fields

These fields can be invalid if the input images are windowed, subsampled, or expanded and if any one of the following conditions exist:

-- The projection code is invalid.
-- The input window projection coordinates are not equal (if 
   more than one input image).
-- The projection code is equal to 1 (UTM) and proj_coef[0] is 
   equal to 0 and proj_coef[1] is equal to 0 and zone_code is 
   invalid.
-- The projection code is equal to 2 (State Plane) and the 
   zone_code is invalid.
-- The poj_coef are not equal.

If the input image(s) are not windowed, subsampled, or expanded, these fields are copied or recalculated from the input DDR to the output DDR file.
If projection distance is invalid, the corner fields are made invalid regardless if there is a specified window or not. This occurs because the input windows cannot be compared if ground distance is not valid.
For any projection coordinate system, it is assumed that the area of study has a rectangular coordinate system. If the projection coordinate system is not rectangular and the corners have to be recalculated, the output coordinate values are not guaranteed to be valid even though the validity flag is set to VALID.
For the module tapeout if a window is specified, these fields are recalculated before the DDR file is copied to the tape.
If the pixels of an image are replicated, the line/sample used to calculate the upleft, loleft, upright, and loright corners is (1,1) and not the middle pixel of the block of replicated pixels.
Since these fields are double precision, a TAE global ($PROJTOL) is set and used as the tolerance--the amount that these fields can be off and still be considered equal. The values placed in the output DDR file are those of the first image with valid corner fields. This global, $PROJTOL, is specified in the number of pixels. For example, if this global is set to .5, the corners of two images that are being compared will be within one-half of a pixel of each other.
If these fields of two or more input images are not within tolerance of each other, a nonfatal error message is output and the validity flag is set to the global $DDRVFLG. The values of the first valid input corners are copied to the output DDR when the $DDRVFLG is set to UNKNOWN. The values of these fields are set to null when the global $DDRVFLG is set to INVALID.

12.7 Line_inc., samp_inc, and valid fields

These fields reflect the increment values from the "master" image.

EXAMPLE:

     IN2;IMG is subsampled from IN1;IMG by 3 in each direction and the
     IN3;IMG is subsampled from IN2;IMG by 2 in each direction.
     IN2;IMG has line increment and sample increment of 3; whereas,
     IN3;IMG has line increment and sample increment of 6.

An integer value greater than 1 (one) specifies that the image has been subsampled and a positive fractional value less than 1 specifies that the image has been expanded.
For modules that rotate an image, these fields are invalidated.
For modules that modify the internal geometry of an image, master_line and master_sample of the output image are made (1,1).

12.8 Pdist_y, pdist_x, and valid fields

These values are recalculated when the output image is resampled, subsampled, or expanded. Otherwise, they are copied or invalidated.

12.9 Min, max, and valid fields

For module tapeout if the image is windowed, the minimum and maximum values are flagged invalid. (The min and max can be made valid again when the image is read from the tape.)
These values are calculated when $MINMAX is set to "yes"; otherwise they are made invalid or bounded (if possible). They are not copied from the input DDR file.
The validity flag of these fields can have a value of
```
     VALID
     NOT VALID
     BOUNDED
```
The BOUNDED status is calculated when the functionality of the application makes this possible. If there are advantages for an application to save processing time by using the BOUNDED status, the programmer should implement the logic to do so.

12.10 Source, instrument, direction, date, and time fields

These fields are only updated by the tape ingest routines. All other routines copy or invalidate these fields. The exception to this rule is editddr.
For application modules math, concat, or other modules that combine two or more input images into one band of the output image, these fields are copied if they are the same for all input images; otherwise, they become invalid.
Date and time are the date and time that the data was captured.

There are specific codes used for source, instrument, and direction as shown in the list. This allows for these fields to be compared for each input image. (See the second assumption listed in this section.) The user can still enter other codes for these fields, source, instrument, and direction, but the values may be lost if the other combines images with inconsistent values.

   source		    instrument	        direction
   dem		dem-ascii   ascending
   spot		dem-binary  descending
   landsat-1,	dted
   landsat-2,	dtt
   landsat-3,	mss
   landsat-4,	rbv
   landsat-5	tm
   noaa-6,
   noaa-7,
   noaa-8,
   noaa-9,
   noaa-10,
   noaa-11