com.luciad.format.nitf

Defense StandardsClass 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

• EPSG references (<filename>.epsg): see TLcdEPSGModelReferenceDecoder for more info.
• WKT references (<filename>.prj): see TLcdWKTModelReferenceDecoder for more info.
• Luciad encoded model references (<filename>.ref): see TLcdModelReferenceDecoder for more info.

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.

• setAllowOrthographicReferencing(boolean)
• setMaximumResidualTiePointError(double)
• setRasterReferencer(com.luciad.format.raster.reference.ILcdRasterReferencer)

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).

• setDefaultBounds(com.luciad.shape.ILcdBounds)

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

• This model decoder creates a model per raster data set.
• All models returned by this model decoder implement ILcd2DBoundsIndexedModel.
• If the separateGraphics property is set to true, models that contain vector graphic segments also implement ILcdModelTreeNode. The vector data are then returned in model tree nodes, one per graphic segment. The model tree nodes also implement ILcd2DBoundsIndexedModel.

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 Summary

Constructors

Constructor and Description
TLcdNITFModelDecoder() Creates a new TLcdNITFModelDecoder, with a globally shared buffer for caching tiles.
TLcdNITFModelDecoder(ILcdBuffer aBuffer) Creates a new TLcdNITFModelDecoder.
TLcdNITFModelDecoder(ILcdBuffer aBuffer, ILcdModelReferenceDecoder aModelReferenceDecoder) Creates a new TLcdNITFModelDecoder.
TLcdNITFModelDecoder(ILcdBuffer aBuffer, ILcdModelReferenceDecoder aModelReferenceDecoder, ILcdModelReference aDefaultModelReference, ILcdBounds aDefaultBounds) Creates a new TLcdNITFModelDecoder.
TLcdNITFModelDecoder(ILcdBuffer aBuffer, ILcdModelReference aDefaultModelReference, ILcdBounds aDefaultBounds) Creates a new TLcdNITFModelDecoder.

Method Summary

Modifier and Type	Method and Description
boolean	canDecodeSource(String aSourceName) Checks whether this decoder can decode the given data.
ILcdModel	decode(String aSourceName) Creates a new model from the given data source.
protected ILcdBounds	decodeImageBounds(String aCoordinateSystem, String aGeographicLocation, int aDisplayLevel, int aAttachmentLevel, int aImageWidth, int aImageHeight, ILcdModelReference aModelReference) Decodes image bounds based on the given information.
protected ILcdModelReference	decodeModelReference(String aCoordinateSystem, String aGeographicLocation, ILcdModelReference aDefaultModelReference) Decodes a model reference based on the given information.
ILcdBounds	getDefaultBounds() Returns the default bounds for decoded rasters, in case an input NITF file doesn't provide any.
String	getDefaultExtension()
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.
String	getDisplayName() Returns a short, displayable name for the format that is decoded by this ILcdModelDecoder.
ILcdInputStreamFactory	getInputStreamFactory() Returns the input stream factory that is used for creating input streams given source names.
double	getMaximumResidualTiePointError() Returns the maximum acceptable residual error for the four corner points.
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.
ILcdRasterReferencer	getRasterReferencer() Returns the raster referencer that is used when positioning image files based on tie points.
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.
boolean	isDecodeMultilevelRasters() Returns whether the decoder may return multilevel rasters (when possible) instead of single-level rasters.
boolean	isIgnoreGraphics() Returns whether CGM vector graphics segments are ignored.
boolean	isSeparateGraphics() Returns whether CGM vector graphics segments are separated into individual submodels.
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.
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).
void	setDefaultBounds(ILcdBounds aDefaultBounds) Sets the default bounds for decoded rasters, in case an input NITF file doesn't provide any.
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.
void	setIgnoreGraphics(boolean aIgnoreGraphics) Specifies whether to ignore CGM vector graphics segments.
void	setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory) Sets the input stream factory that will be used for creating input streams given source names.
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.
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.
void	setRasterReferencer(ILcdRasterReferencer aRasterReferencer) Sets the raster referencer that will be used when positioning image files based on tie points.
void	setSeparateGraphics(boolean aSeparateGraphics) Specifies whether to separate CGM vector graphics segments into individual submodels.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.luciad.model.ILcdModelDecoder

canDecodeSource, decodeModelMetadata, decodeModelMetadata, decodeSource, discoverDataSources

Constructor Detail

TLcdNITFModelDecoder

public TLcdNITFModelDecoder()

Creates a new TLcdNITFModelDecoder, with a globally shared buffer for caching tiles.

See Also:

TLcdSharedBuffer.getBufferInstance()

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 Detail

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:

setModelReferenceDecoder(com.luciad.model.ILcdModelReferenceDecoder)

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:

setAllowOrthographicReferencing(boolean)

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.

isSeparateGraphics

public boolean isSeparateGraphics()

Returns whether CGM vector graphics segments are separated into individual submodels.

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:

ILcdModelDecoder.decode(String), ILcdModelDecoder.decodeModelMetadata(String)

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);
      }
   }
 

InterruptedIOException - When the thread on which this method is called is interrupted: it is recommended to stop the decoding and throw an InterruptedIOException. This same exception can also be used if the decoder shows UI to the user, and the user cancels the decoding through the UI.

See Also:

ILcdModelDecoder.canDecodeSource(String)

decodeModelReference

protected ILcdModelReference decodeModelReference(String aCoordinateSystem,
                                                  String aGeographicLocation,
                                                  ILcdModelReference aDefaultModelReference)
                                           throws IOException

Decodes a model reference based on the given information.

Parameters:

aCoordinateSystem - the NITF Image Coordinate Representation (ICORDS).

aGeographicLocation - the NITF Image Geographic Location (IGEOLO).

aDefaultModelReference - the default model reference, if set, which can be returned in case the NITF parameters don't specify a valid model reference.

Returns:

the decoded model reference.

Throws:

IOException

decodeImageBounds

protected ILcdBounds decodeImageBounds(String aCoordinateSystem,
                                       String aGeographicLocation,
                                       int aDisplayLevel,
                                       int aAttachmentLevel,
                                       int aImageWidth,
                                       int aImageHeight,
                                       ILcdModelReference aModelReference)
                                throws IOException

Decodes image bounds based on the given information.

Parameters:

aCoordinateSystem - the NITF Image Coordinate Representation (ICORDS).

aGeographicLocation - the NITF Image Geographic Location (IGEOLO).

aDisplayLevel - the NITF display level of the image segment.

aAttachmentLevel - the NITF attachment level of the image segment.

aImageWidth - the image width, expressed in pixels.

aImageHeight - the image height, expressed in pixels.

aModelReference - the previously decoded model reference.

Returns:

the image bounds, expressed in model coordinates.

Throws:

IOException