PRODUCTS: NITF Escalator Documentation

Stellar Science presents NITF Escalator, an Adobe Photoshop File Format Plug-in that allows you to read NITF 2.0, NITF 2.1 and NSIF 1.0 imagery files directly into Photoshop and other host image processing applications.

Normal Usage
NITF Escalator is a File Format plug-in that conforms to Adobe Photoshop's plug-in API. If you have an application that accepts these types of plug-ins then NITF Escalator will provide you with the ability to directly read in NITF imagery without performing off-line file conversions. Examples of applications that support Adobe's File Format Plug-in API are:

  • Adobe Photoshop CS2/CS3/CS4(x86)
  • Adobe Photoshop Elements 5.0/6.0/7.0

Many other applications support Adobe's File Format Plug-in API. NITF Escalator has not been tested with every such application, but if your application supports Adobe's File Format Plug-in API, you are encouraged to download a free trial version of NITF Escalator to see if it will work with your application. Please let us know what you find.

Routine usage of NITF Escalator is very straightforward. Once the plug-in has been installed into a host application, you need only use the File|Open... capabilities provided by the host. In other words, you will be able to open NITF imagery files just as you would open a JPEG image file. If your host application supports thumbnail display in its Open Dialog, then you will be able to see NITF thumbnails as well. Due to the complexity of the NITF format, however, it is not unusual for the appearance of a NITF thumbnail to differ somewhat from the way the image is initially displayed in your host application. If a NITF file is particularly large or has more than 3 channels, then NITF Escalator may be forced to make guesses as to the appropriate way to scale, crop, and channel map your image for the thumbnail display window. This is normal behavior. Once you have fully opened the image, you may use the capabilities provided by your host application to adjust the display parameters of the image.

Until you have purchased and entered a valid license key for your host application, the first thing you will see after opening a NITF image file is the License Dialog:

This dialog will tell you how many more images you may load before your trial period is finished (Note: The number of trial image loads are fixed on a per-machine basis -- not a per host application basis). Once you have purchased a license key for your host application, you may enter it here and you will never have to see this window again. Your host application's key is displayed here because you will need it in order to purchase a corresponding NITF Escalator license key.

Press OK to clear this window. If you have entered a valid license key or you have trials remaining, your NITF image will begin loading. The first thing NITF Escalator will do is show you the contents of the NITF file and image headers in a tree view:

The primary content of this tree view is the NITF file header and any image headers that are in the file. If you are familiar with the NITF file format specification, then you know that there are other types of headers that can appear in a NITF file (eg. Text Segment Headers and Graphics Segment Headers). Only file headers and image header information will be displayed here. Also note that not all NITF files have images in them. If this is the case, then you will not be able to open that file using NITF Escalator.

Click on the Open button to close this dialog and commence opening your NITF image. In most cases, your image file will begin loading immediately. In some instances, however, NITF Escalator will need to get more information from you before it can load the file.

Multiple Images in one NITF File
The NITF file format specification allows a single NITF file to contain more than one image. If this is the case for a given NITF file, then NITF Escalator will recognize this and ask you which image you would like to load with the following dialog:

When you select an image in the image list on the left, the dialog will tell you the following characteristics about that image:

  • Image Size: The X and Y dimensions of the image.
  • Compression (IC): The compression scheme used to compress the image. NITF Escalator only supports uncompressed images or images that have been compressed with JPEG 2000 compression. If the selected image uses an unsupported compression type, that fact will be indicated here.
  • Image Representation (IREP): The NITF specification allows the following values (see MIL-STD-2500C for more information):

    • MONO - Monochrome image
    • RGB - Red-Green-Blue color image
    • MULTI - Multi-band image
    • NODISPLY - Image not meant for display (though NITF Escalator will display it for you if you wish)
    • NVECTOR - Image contains cartesian coordinates
    • POLAR - Image contains polar coordinates
    • VPH - SAR Video Phase history
    • YCbCr601 - Image is compressed with ITU-R Recommendation BT.601.5 color space
  • Pixel Data Type: The data type contained in the image. Acceptable values are:

    1 Bit Boolean
    8 Bit Unsigned Integer
    8 Bit Signed Integer
    16 Bit Unsigned Integer
    16 Bit Signed Integer
    32 Bit Unsigned Integer
    32 Bit Signed Integer
    Single Precision Real Number
    Double Precision Real Number
    Unknown Pixel Type

If this is not enough information to help you decide which image you would like to load, you can either load each image one by one until you find the one you're looking for. Note that even though you can have multiple NITF image files open at once, you will only be able to have one image open from each NITF file at a time. If you do not wish to use this trial and error approach, you may want to consider examing the image headers to figure out which image you're looking for. Press the Cancel button and then open the file once more. You can then examine the image headers using the tree view.

Intensity Scaling
NITF Images can come in a variety of data types. NITF Escalator can handle nearly all of them, including images that contain the following pixel types:

  • 1 Bit Boolean
  • 8 Bit Unsigned Integer
  • 8 Bit Signed Integer
  • 16 Bit Unsigned Integer
  • 16 Bit Signed Integer
  • 32 Bit Unsigned Integer
  • 32 Bit Signed Integer
  • Single Precision Real Number
  • Double Precision Real Number

Unfortunately, the Adobe Photoshop API is not quite as flexible when it comes to data types. The API only supports 8 Bit Unsigned Integer, 16 Bit Unsigned Integer, and 32 Bit Precision Real Numbers. When NITF Escalator encounters an image that is not one of these types, it will convert the image into an accepted type for you. This may require that the data be intensity scaled so that you will actually be able to see some relevant image detail. The following dialog will allow you to control the details of this transform if you wish:

Each pixel value in the NITF image will be multiplied by the specified Scale, added to the specified Bias and then clamped to the range of New Data Type where New Data Type is one of Photoshop's acceptable pixel types. NITF Escalator will sample the image and determine default values that will normally behave well. If you open an image, however, and it's all black or all white you may need to re-open the image and adjust these values accordingly.

Other Warnings
There are other types of NITF images that deserve special mention and NITF Escalator will point them out when it finds one. For example, you may see a warning box with one of the following messages when loading an image:

  • The selected image contains a Lookup Table (LUT). NITF Escalator does not currently support LUT expansion. The image will display LUT indexes instead of actual colors - NITF images can contain a variety of different LUTs (see MIL-STD-2500C for more information) whereas Photoshop only handles one kind of very simple LUT. Future versions of NITF Escalator may attempt to expand NITF LUTs as a pre-processing step (similar to how it handles odd data types), but the current version does not do this. The image can still be loaded, but it will contain indexes into the LUT rather than real color information.
  • The selected image contains X channels. Photoshop only allows a maximum of 56 channels. NITF Escalator has truncated excess channels so that the image could be loaded - A single NITF image can contain up to 99,999 channels whereas Photoshop will only handle 56 channel images. The current version of NITF Escalator handles this case by slicing off all channels past the 56th one. Future versions of the plug-in may allow you more control over which channels you would like to view.
  • Photoshop seems to have a problem accepting 32 bit Multichannel images. To compensate for this issue, NITF Escalator is converting the image mode to XX. You can avoid this conversion by selecting a different bit depth - Empircally, we have found that Photoshop will not accept 32 bit multichannel images (it fails without offering a good reason). NITF Escalator gets around this limitation by telling Photoshop that the image is either greyscale or Red-Green-Blue (RGB).

Advanced Settings
If you have permissions and the know-how to edit the registry on your computer, there are a few NITF Escalator settings that you may adjust. If you are unsure what the registry is or how to edit it, it's best to skip this section. Modifying your operating system's registry improperly can harm your computer. Future versions of NITF Escalator may offer a more user-friendly way to modify these settings. For now though, they can only be turned on or off by manually editing the registry. Available settings are:

  • No Header Dialog: When you open a NITF file, NITF Escalator initially shows you a dialog that contains much of the file's header information. If you do not wish to see this dialog, then you can turn this behavior off by creating a string value in your registry with the following name: HKEY_CURRENT_USER/Software/Stellar Science/Nitf Escalator/NoHeaderDialog
  • Do Plane Mapping: By default, NITF Escalator will not adjust the order of the image planes (or channels) in a NITF image while it is opening it. The rationale behind this design decision was to avoid confusion. Each image header contains some per channel information -- it could potentially confuse a user if the image's channels showed up in a different order than the order in which they were listed in the image header. Occasionally though, a NITF image will contain information in the IREPBAND field that tells a display application which channels are most appropriately shown as Red, Green or Blue. These channels are not always the first three channels of a multi-channel image. If you create a string value in your registry with the following name, NITF Escalator will read this IREPBAND information when available and use it to create a plane mapping that will tell the host application which channels should be mapped to Red, Green and/or Blue: HKEY_CURRENT_USER/Software/Stellar Science/Nitf Escalator/DoPlaneMapping
  • Thumbnail Level: Many host applications support the display of thumbnails in their respective File|Open... dialogs. Because, many NITF files are very large or very complex, creating thumbnails can also be a very complex process and, more importantly, a very slow one. You can control the speed/quality tradeoff of the NITF Escalator's thumbnails via a registry string with the following name: HKEY_CURRENT_USER/Software/Stellar Science/Nitf Escalator/ThumbnailLevel. Acceptable values for this string are:

    * 0:Do not display thumbnails
    * 1:Display thumbnails but favor speed over quality.
    * 2:Display thumbnails but quality over speed.

    This may be unbearably slow for very large NITF images. Future versions of NITF Escalator may offer more fine-tuned control in this area.
  • No Warning Boxes: The Other Warnings section of this document describes a number of warning boxes that can pop up while loading a NITF image. Create a string value in the registry with the following name to turn these warnings off: HKEY_CURRENT_USER/Software/Stellar Science/Nitf Escalator/NoWarningBoxes