NITF File

This section describes the overall software design. You can also NitfFile for descriptions of the class member functions.

We want to be able to read an write NITF files.

The NitfFile class structure is shown in Fig. 4.

Fig. 4 NitfFile class structure

Note that only NitfFile, NitfImageSegment, NitfTextSegment and NitfGraphicSegment can have TREs. NitfResSegment and NitfDesSegment can not. However, NitfResSegment and NitfDesSegment can have a “user_subheader” supplied. The particular fields in a user_subheader are determined by the desid or resid type identifier.

TRE Errors

It is not infrequent to run into a file that has a TRE that doesn’t conform to the documentation that we code from. A required field might be left blank for example, or a format might have changed (e.g. MATESA changed from version 0.1 to 1.0 of the SNIP).

Depending on what you are trying to do you may want:

1. The difference to be completely ignored, and the TRE replaced with TreUnknown.

2. The difference reported as a warning, and the TRE replaced with TreUnknown.

3. The difference to be treated as an error and an exception thrown.

To accommodate this range of possibilities. the TRE reading code reports using python warnings module. We introduce a new warning “TreWarning” derived from the standard UserWarning exception.

You can use the standard warnings filterwarnings function to control the behavior. For example, to treat all TreWarnings as an error you can use the code snippet:

warnings.filterwarnings("error", category=pynitf.TreWarning)

To ignore just the MATESA format change, you can use:

warnings.filterwarnings("ignore", "Trouble reading TRE MATESA",
                        category=pynitf.TreWarning)

NitfFile Handles and Hooks

In addition to the NitfSegment, NitfFile contains several handle and hooks, shown in Fig. 5.

Fig. 5 NitfFile class Handles and Hooks

NitfSegmentHookSet

The NitfSegmentHookSet is used to extend the handling of various attributes of a segment. The hooks are pretty general, and can be used for whatever is desired. But the original use case was adding higher level objects to NitfSegments such as RPC and RSM (done in the separate GeoCal library).

The current set of higher level objects are:

Table 1 Higher level objects handled by various NitfSegmentHook

Segment Attribute	Description
rpc	In GeoCal (not pynitf). This is a RPC (Rational Polynomial Coefficient. This is a common technique, and there are numerous references. One reference is Fraser, CS, Dial, G, Grodecki, J “Sensor orientation via RPCs” ISPRS J PHOTOGRAMM 60 (3): 182-194 MAY 2006.
rsm	In GeoCal (not pynitf). This is a RSM (Replacement Sensor Model), see Dolloff, J.T., M.M. Iiyama, and C.R. Taylor, 2008. The Replacement Sensor Model (RSM): Overview, Status, and Performance Summary, ASPRS 2008 Annual Conference, April 28 - May 2, 2008

See Fig. 6.

Fig. 6 NitfSegmentHookSet

We call all the NitfSegmentHook objects at several points in the processing:

• After NitfSegment.__init__ is called for a segment. This might do something like add a new attribute to the newly created segment (e.g., add “rpc”)

• Before writing a NitfSegment to a file. This might translate a higher level object into TREs (e.g., for a RSM object).

• After reading a NitfSegment. This might create a object based on TREs (e.g., RSM based on various RSM Tres). Note this actually gets called after the entire file has been read, so if the objects depend on other later segments they are available (e.g., the orbit DESs for a GLAS/GFM object on a image segment)

• Before calling __str__ on a NitfSegment. This can be used to write out a higher level object (e.g., RPC, RSM).

• Before calling __str__ on a TRE. This can write a replacement text. Should return “True” if the TRE printing has been done by this function, “False” if the normal TRE printing should be done instead.

Note that when printing out a NitfSegment, most of the time we want the higher level objects printed. However, there may be instances where we want the “raw” data (e.g., nitfinfofull reporting raw TRE data). NitfSegmentHookSet will skip calling before_str_hook and before_tre_str_hook if “remove_for_report_raw” is True for the NitfSegmentHook.

NitfSegmentUserSubheaderHandleSet

The NitfSegmentUserSubheaderHandleSet is used to handle reading and writing the user subheaders found in the NitfDesSegment and NitfResSegment. This is a Priority Handle Set for handling each of these segment types. The handle returns the user subheader class type, which is then used by NitfSegment for reading and writing the user subheader. See Fig. 7.

Fig. 7 NitfSegmentUserSubheaderHandleSet

NitfSegmentDataHandleSet

The NitfSegmentDataHandleSet is used to handle reading and writing the data field of each of the NitfSegment types. This is a Priority Handle Set for handling each of these segment types. See Fig. 8.

Fig. 8 NitfSegmentDataHandleSet

NitfFile convenience functions

While the individual lists can be filters/searched using normal python functions, there are a set of things done frequently enough that it is useful to add convenience functions to do them. These are shown in in Fig. 9.

Fig. 9 NitfFile Convenience Functions