Package com.luciad.format.nitf

Class TLcdNITFModelDecoder

java.lang.Object
com.luciad.format.nitf.TLcdNITFModelDecoder
All Implemented Interfaces:
ILcdInputStreamFactoryCapable, ILcdModelDecoder
@LcdService(service=ILcdModelDecoder.class, priority=20000) public class TLcdNITFModelDecoder extends Object implements ILcdModelDecoder, ILcdInputStreamFactoryCapable
This model decoder decodes rasters in the NITF format (National Imagery Transmission Format, NITF 2.0 and NITF 2.1). This format is identical to the NSIF format (NATO Secondary Imagery Format, NSIF 1.0). It supports uncompressed images, vector-quanitized images, JPEG, and JPEG-2000.

NITF files don't always specify model references. When not specified, the model reference is obtained from an ILcdModelReferenceDecoder. The default reference decoder set on this model decoder is based on all model reference decoders annotated with the LcdService annotation, and can handle

If this fails, the decoder's default model reference is returned. Unless set by the user, the default model reference is null.

Sometimes, NITF files specify a geodetic reference, but their corner points don't form an axis-aligned rectangle. Such files typically contain aerial pictures or satellite imagery. By default, the model decoder will then first try to approximate the perspective view by means of an orthographic grid reference. The user can specify a maximal residual error for the corner points. Generally, if simple referencing techniques fail, the model decoder constructs a grid reference with a projective transformation. Alternatively, a raster referencer can be set to obtain complete control over the way in which raster model reference and bounds are created.

NITF images don't always have bounds in model coordinates. If the bounds are not specified, default bounds can be assigned. By default, these bounds are unset (i.e. null).

The decoder supports the following optional Tagged Record Extensions:

  • BLOCKA, which contains the image corner locations at a higher precision than the one in the standard NITF header.
  • RPC00B, which specifies rational function polynomial coefficients and normalization parameters that define the physical relationship between image coordinates and ground coordinates.
  • SENSRB, providing information about the imaging sensor and its installation (geographical location, position relative to the aircraft, yaw, pitch and roll angles, etc).

Input files

The decoder supports decoding of NITF (*.ntf), NSF (*.nsf) and NSIF (*.nsif) files, as well as any supported CADRG frame file. Extensions for these files are a concatenation of a data series code and a zone code. See TLcdCADRGModelDecoder for more info.

Supported file transfer protocols

  • This model decoder supports all transfer protocols that are supported by the inputStreamFactory of this decoder.

Model structure

Model descriptor

  • All models returned by this model decoder have a TLcdNITFModelDescriptor.
  • The type name of the model descriptor is the display name of this decoder.

Model reference

  • If the NITF file has an RPC00B (Rapid Positioning Capability) tagged record extension, the returned reference is an ILcdGridReference constructed from the RPC parameters (see the RPC00B specifications). The datum of the reference is WGS84.
  • If the NITF file has a SENSRB tagged record extension, the returned reference is an ILcdGridReference constructed from the SENSRB parameters. The datum of the reference is WGS84.
  • If the NITF ICORDS element is set, the returned model reference can be an ILcdGeodeticReference or a TLcdUTMGrid. constructed from the ICORDS element.
  • If none of the above is available, the user-defined model reference decoder and the default model reference are tried (in this order).

Model elements

  • Raster data are decoded as implementation of ALcdImage and (ILcdRaster) elements.
  • Vector data in graphic segments are decoded as ILcdShape elements, as specified by TLcdCGMModelDecoder. By default, the vector data are decoded as elements of the main model. If the separateGraphics property is set to true, they are decoded as elements of model tree nodes of the main model, with one model tree node per graphic segment.

Useful settings

  • If vector data from graphic segments are not required, they can be skipped with the ignoreGraphics property.

Sample code


 ILcdModelDecoder decoder = new TLcdNITFModelDecoder();
 ILcdModel model = decoder.decode("raster.ntf");

Performance tips

  • NITF rasters can be large. Precomputing and storing multiple levels of detail may speed up visualization and some computations. The TLcdGeoTIFFModelEncoder can create compressed and tiled multilevel GeoTIFF files that can replace the original NITF files.

Thread safety

  • The decoding of models is not thread-safe.
  • The decoded models and elements are thread-safe for read access, on the condition that a thread-safe buffer is used.

Supported versions and specifications

  • National Imagery Transmission Format Version 2.1 (NITF, MIL-STD-2500C, 01 May 2006)
  • NATO Secondary Imagery Format (NSIF, STANAG No. 4545, 27 September 1998)
  • Registered Data Values for Raster Product Format (MIL-STD-2411-1, 30 August 1994)
  • Integration of Raster Product Format Files into the National Imagery Transmission Format (MIL-STD-2411-2, 26 August 1994)
  • Vector Quantization Decompression for the National Imagery Transmission Format (MIL-STD-188-199, 27 June 1994)
  • Compressed ARC Digitized Raster Graphics (CADRG, MIL-C-89038, 6 October 1994)
  • Compressed ARC Digitized Raster Graphics (CADRG, MIL-PRF-89038, 6 October 1994)
  • Controlled Image Base (CIB, MIL-C-89041, 15 May 1995)
  • Controlled Image Base (CIB, MIL-PRF-89041, 15 May 1995)
  • Joint Photographic Experts Group (JPEG) Image Compression for the National Imagery Transmission Format (MIL-STD-188-198A, 15 December 1993)
  • The Compendium of Controlled Extensions (CE) for the National Imagery Transmission Format (NITFS), Appendix E, Airborne Support Data Extensions (ASDE, Version 1.1, 16 November 2000)
  • Raster Product Format (MIL-STD-2411, 6 October 1994)

Known limitations

  • The raster path only supports 1 (M/LU) or 3 (RGB) bands (see ELcdNITFBandRepresentation).
  • Signed data is not supported for JPEG2000
  • Non-byte-aligned data is not supported for uncompressed images
  • The current implementation does not support 12-bits grayscale JPEG images.
  • The current implementation ignores data extension segments.

Since:
3.0

  • Constructor Details

    • TLcdNITFModelDecoder

      public TLcdNITFModelDecoder()
      Creates a new TLcdNITFModelDecoder, with a globally shared buffer for caching tiles.
      See Also:

    • TLcdNITFModelDecoder

      public TLcdNITFModelDecoder(ILcdBuffer aBuffer)
      Creates a new TLcdNITFModelDecoder.
      Parameters:
      aBuffer - the shared buffer that decoded models will use.

    • TLcdNITFModelDecoder

      public TLcdNITFModelDecoder(ILcdBuffer aBuffer, ILcdModelReferenceDecoder aModelReferenceDecoder)
      Creates a new TLcdNITFModelDecoder.
      Parameters:
      aBuffer - the shared buffer that decoded models will use.
      aModelReferenceDecoder - the model reference decoder for NITF files that don't specify model references.

    • TLcdNITFModelDecoder

      public TLcdNITFModelDecoder(ILcdBuffer aBuffer, ILcdModelReference aDefaultModelReference, ILcdBounds aDefaultBounds)
      Creates a new TLcdNITFModelDecoder.
      Parameters:
      aBuffer - the shared buffer that decoded models will use.
      aDefaultModelReference - the default model reference for NITF files that don't specify model references.
      aDefaultBounds - the default raster bounds for NITF images that don't have bounds.

    • TLcdNITFModelDecoder

      public TLcdNITFModelDecoder(ILcdBuffer aBuffer, ILcdModelReferenceDecoder aModelReferenceDecoder, ILcdModelReference aDefaultModelReference, ILcdBounds aDefaultBounds)
      Creates a new TLcdNITFModelDecoder.
      Parameters:
      aBuffer - the shared buffer that decoded models will use.
      aModelReferenceDecoder - the model reference decoder for NITF files that don't specify model references.
      aDefaultModelReference - the default model reference for NITF files that don't specify model references.
      aDefaultBounds - the default raster bounds for NITF images that don't have bounds.

  • Method Details

    • setInputStreamFactory

      public void setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory)
      Sets the input stream factory that will be used for creating input streams given source names.
      Specified by:
      setInputStreamFactory in interface ILcdInputStreamFactoryCapable
      Parameters:
      aInputStreamFactory - the input stream factory to be used.

    • getInputStreamFactory

      public ILcdInputStreamFactory getInputStreamFactory()
      Returns the input stream factory that is used for creating input streams given source names.
      Specified by:
      getInputStreamFactory in interface ILcdInputStreamFactoryCapable
      Returns:
      the input stream factory that is used.

    • setModelReferenceDecoder

      public void setModelReferenceDecoder(ILcdModelReferenceDecoder aModelReferenceDecoder)
      Sets the model reference decoder that will be used for creating model references for decoded models, in case an input NITF file doesn't provide one.

    • getModelReferenceDecoder

      public ILcdModelReferenceDecoder getModelReferenceDecoder()
      Returns the model reference decoder that is used for creating model references for decoded models, in case an input NITF file doesn't provide one. The default value supports WKT (*.prj), REF (*.ref), and EPSG (*.epsg).
      Returns:
      the model reference decoder used by this decoder
      See Also:

    • setDefaultModelReference

      public void setDefaultModelReference(ILcdModelReference aDefaultModelReference)
      Sets the default model reference for decoded models, in case an input NITF file and the model reference decoder don't provide one.

    • getDefaultModelReference

      public ILcdModelReference getDefaultModelReference()
      Returns the default model reference for decoded models, in case an input NITF file and the model reference decoder don't provide one.

    • setDefaultBounds

      public void setDefaultBounds(ILcdBounds aDefaultBounds)
      Sets the default bounds for decoded rasters, in case an input NITF file doesn't provide any.

    • getDefaultBounds

      public ILcdBounds getDefaultBounds()
      Returns the default bounds for decoded rasters, in case an input NITF file doesn't provide any.

    • setAllowOrthographicReferencing

      public void setAllowOrthographicReferencing(boolean aAllowOrthographicReferencing)
      Specifies whether images that are rotated in a geodetic reference may be put in an approximating orthographic grid reference that is centered around the image.

    • isAllowOrthographicReferencing

      public boolean isAllowOrthographicReferencing()
      Returns whether images that are rotated in a geodetic reference may be put in an orthographic grid reference that is centered around the image.

    • setMaximumResidualTiePointError

      public void setMaximumResidualTiePointError(double aMaximumResidualTiePointError)
      Sets the maximum acceptable residual error for the four corner points, when positioning image files in an approximating orthographic grid reference.

      The residual error is computed in image coordinates and expressed in pixels. The default is 3.

      Parameters:
      aMaximumResidualTiePointError - the maximum residual error, expressed in pixels.
      See Also:

    • getMaximumResidualTiePointError

      public double getMaximumResidualTiePointError()
      Returns the maximum acceptable residual error for the four corner points.

    • setRasterReferencer

      public void setRasterReferencer(ILcdRasterReferencer aRasterReferencer)
      Sets the raster referencer that will be used when positioning image files based on tie points. If it is set, it replaces the more basic settings allowOrthographicReferencing and maximumResidualTiePointError, which are used by default.
      Parameters:
      aRasterReferencer - the raster referencer, which will create model references and raster bounds based on tie points.

    • getRasterReferencer

      public ILcdRasterReferencer getRasterReferencer()
      Returns the raster referencer that is used when positioning image files based on tie points.

    • setIgnoreGraphics

      public void setIgnoreGraphics(boolean aIgnoreGraphics)
      Specifies whether to ignore CGM vector graphics segments.

    • isIgnoreGraphics

      public boolean isIgnoreGraphics()
      Returns whether CGM vector graphics segments are ignored.

    • setSeparateGraphics

      public void setSeparateGraphics(boolean aSeparateGraphics)
      Specifies whether to separate CGM vector graphics segments into individual submodels. The main model is then a model tree node that contains the raster as its sole element, and the CGM vector graphics in distinct submodels. When this option is enabled the display level between graphic segments and other types of segments is not enforced, which may result in incorrect paint order.

    • isSeparateGraphics

      public boolean isSeparateGraphics()
      Returns whether CGM vector graphics segments are separated into individual submodels. When this option is enabled the display level between graphic segments and other types of segments is not enforced, which may result in incorrect paint order.

    • getDefaultExtension

      public String getDefaultExtension()
      Returns:
      "ntf".

    • getDisplayName

      public String getDisplayName()
      Description copied from interface: ILcdModelDecoder
      Returns a short, displayable name for the format that is decoded by this ILcdModelDecoder.
      Specified by:
      getDisplayName in interface ILcdModelDecoder
      Returns:
      "ntf".

    • isDecodeMultilevelRasters

      public boolean isDecodeMultilevelRasters()
      Returns whether the decoder may return multilevel rasters (when possible) instead of single-level rasters. The default value is false.
      Returns:
      true if the decoder may return multilevel rasters.

    • setDecodeMultilevelRasters

      public void setDecodeMultilevelRasters(boolean aDecodeMultilevelRasters)
      Specifies whether the decoder is allowed to create multilevel rasters if the input data permits (for instance, for rasters with JPEG-2000 compression).
      Parameters:
      aDecodeMultilevelRasters - specifies whether the decoder should create multilevel rasters when possible.

    • canDecodeSource

      public boolean canDecodeSource(String aSourceName)
      Checks whether this decoder can decode the given data. The extension of the file name should be "ntf", "nsf" or "nsif". CADRG frame files are also supported. See TLcdCADRGModelDecoder for more information on which CADRG frame types are supported.
      Specified by:
      canDecodeSource in interface ILcdModelDecoder
      Parameters:
      aSourceName - the name of the file or URL that is to be decoded.
      Returns:
      true if this decoder can decode the data specified by the source name, false otherwise.
      See Also:

    • decode

      public ILcdModel decode(String aSourceName) throws IOException
      Description copied from interface: ILcdModelDecoder
      Creates a new model from the given data source.
      Specified by:
      decode in interface ILcdModelDecoder
      Parameters:
      aSourceName - the data source to be decoded; typically a file name or a URL.
      Returns:
      A model containing the decoded data. While null is allowed, implementors are advised to throw an error instead.
      Throws:
      IOException - for any exceptions caused by IO problems or invalid data. Since decoding invalid data almost always results in RunTimeExceptions (NullPointerException, IndexOutOfBoundsException, IllegalArgumentException, ...) on unexpected places, implementations are advised to catch RuntimeExceptions in their decode() method, and wrap them into an IOException, as illustrated in the code snippet below. 
      
   public ILcdModel decode( String aSourceName ) throws IOException {
      try (InputStream input = fInputStreamFactory.createInputStream(aSourceName)) {
         // Perform decoding ...
      } catch (RuntimeException e) {
         throw new IOException(e);
      }
   }
      See Also:

    • discoverDataSources

      public List<? extends ILcdDataSource> discoverDataSources(String aSourceName) throws IOException

      Retrieves a set of model-specific ILcdDataSource instances.

      By default, this method:

      Concrete model decoders might choose to return a set of ILcdDataSource, for instance, if the path references a collection of data sources.

      An example where this is useful is for container formats, such as NetCDF. A NetCDF file can contain multiple measurement layers. This ILcdModelDecoder.discoverDataSources(String) method allows you to distinguish between them using ILcdDataSources, where each measurement layer can be referenced to and decoded separately using ILcdModelDecoder.decodeSource(ILcdDataSource)

      Provides two data sources for an NITF file. One can be used to decode the NITF file into a georeferenced model, while the other can be used to create a non-georeferenced model. When decoding the data source into a non-georeferenced model, the result is an ILcdModelTreeNode with a sub model for each segment in the NITF file.
      Specified by:
      discoverDataSources in interface ILcdModelDecoder
      Parameters:
      aSourceName - A path to the data source to be decoded; typically a file path or a URL.
      Returns:
      If this model decoder returns true for ILcdModelDecoder.canDecodeSource(String), it will return a list containing at least a single ILcdDataSource.
      Throws:
      IOException - If this model decoder returns false for ILcdModelDecoder.canDecodeSource(String) or if any exceptions caused by IO problems or invalid data occur.

    • canDecodeSource

      public boolean canDecodeSource(ILcdDataSource aDataSource)
      Description copied from interface: ILcdModelDecoder

      Checks whether this model decoder can decode the data source(s), identified by the passed ILcdDataSource.

      For performance reasons, we strongly recommend that this will only be a simple test. For example: check the instance class of aDataSource, or check the file extension if it is a TLcdDataSource.

      The default implementation of this method will check if the given ILcdDataSource is a TLcdDataSource. If not, this method returns false. Otherwise, it delegates the source to the ILcdModelDecoder.canDecodeSource(String) method.

      Specified by:
      canDecodeSource in interface ILcdModelDecoder
      Parameters:
      aDataSource - the ILcdModelSource to be verified.
      Returns:
      true if this decoder can likely decode the data specified by aDataSource, false otherwise.
      See Also:

    • decodeSource

      public ILcdModel decodeSource(ILcdDataSource aDataSource) throws IOException
      Description copied from interface: ILcdModelDecoder

      Creates a new model from the given data source.

      By default, this method:

      Specified by:
      decodeSource in interface ILcdModelDecoder
      Parameters:
      aDataSource - the ILcdDataSource to be decoded.
      Returns:
      a model containing the decoded data. While null is allowed, implementors are advised to throw an error instead.
      Throws:
      IOException - for any exceptions caused by IO problems or invalid data. Since decoding invalid data almost always results in RunTimeExceptions (NullPointerException, IndexOutOfBoundsException, IllegalArgumentException, ...) on unexpected places, implementations are advised to catch RuntimeExceptions in their decode() method, and wrap them into an IOException, as illustrated in the code snippet below. 
      
 public ILcdModel decodeSource(ILcdDataSource aDataSource) throws IOException {
   try {
     // Perform decoding ...
   } catch (RuntimeException e) {
     throw new IOException(e);
   }
 }
      See Also: