Package com.luciad.format.cadrg

Class TLcdCADRGModelDecoder

java.lang.Object
com.luciad.format.cadrg.TLcdCADRGModelDecoder
All Implemented Interfaces:
ILcdInputStreamFactoryCapable, ILcdModelDecoder
@LcdService(service=ILcdModelDecoder.class, priority=20000) public class TLcdCADRGModelDecoder extends Object implements ILcdModelDecoder, ILcdInputStreamFactoryCapable
This model decoder decodes rasters in the CADRG format (Compressed ARC Digital Raster Graphics) and in the CIB format (Controlled Image Base).

Input files

File Required Entry point Description
A.TOC
x Table of contents, referring to individual frame files
*.<ds><z> x x Individual frame file.
<ds> refers the the data series code as listed in the data series table below.
<z> refers to the ARC zone number. This is a character in the range [1-9] for the northern hemisphere or [A-HJ] for the southern hemisphere. Please refer to section 3.4 of the ADRG specification (MIL-A-89007) for more details on the ARC system.

Supported Data Series

The decoder supports all data series codes from MIL-STD-2411-1 Change 3 (2010), table 5.1.4 with a fixed scale >= 1m. In summary, the following codes are supported:

A1, A2, A3, A4, AT, C1, C2, C3, C4, C5, C6, C7, C8, C9, CA, CB, CC, CD, CE, CF, CH, CJ, CK, CL, CN, CP, CQ, CR, CS, CT, D1, D2, EG, ES, ET, F1, F2, F3, F4, F5, GN, I1, I2, I3, I4, JA, JG, JN, JO, JR, K1, K2, K3, K7, K8, KB, KE, KM, KR, KS, KU, L1, L2, L3, L4, L5, LF, LN, MH, MI, MJ, OH, ON, OW, P1, P2, P3, P4, P5, P6, P7, P8, P9, PA, PB, PC, PD, PE, PF, PG, PH, PI, PJ, PK, PL, PM, PN, PO, PP, PQ, PR, PS, PT, PU, PV, R1, R2, R3, R4, R5, RC, RL, RR, RV, TC, TF, TL, TN, TP, TQ, TR, TT, UL, V1, V2, V3, V4, VH, VN, VT, WA, WB, WC, WD, WE, WF, WG, WH, WI, WK, XD, XE, XF, XG, XH, XI, XJ, XK, Y9, YA, YB, YC, YD, YE, YF, YI, YJ, YZ, Z8, ZA, ZB, ZC, ZD, ZE, ZF, ZG, ZH, ZI, ZJ, ZK, ZT, ZV, ZZ

The following codes are recognized, but can't be decoded:

CG, CM, CO, HA, I5, IV, M1, M2, MM, OA

We refer to the specification for a more detailed overview of these codes.

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.

Model descriptor

Model reference

  • All models returned by this model decoder have instances of ILcdGeodeticReference as model references.
  • The geodetic datum of this reference is an ellipsoidal datum WGS84.

Model elements

  • Each decoded model contains either TLcdCADRGRaster elements, or ILcdMultilevelRaster elements containing TLcdCADRGRaster instances, depending on the property createMultilevelRasters.
  • In both cases, the TLcdCADRGRaster instances correspond to the CADRG/CIB boundary rectangles. They contain additional information about the rectangles.
  • The TLcdCADRGRaster instances in turn contain TLcdCADRGTile instances that correspond to the individual CADRG/CIB frames. They contain additional information about the frames.

Useful settings

  • By default, the decoder will produce tiles with full ARGB DirectColorModel instances instead of IndexColorModel instances. This avoids problems with clashing color maps from different CADRG tiles (cfr. MIL-C-89038, Section 3.10.3 "Color reduction"). This behavior can be disabled by setting the property expandColorMap to false.
  • The property createMultilevelRasters allows to decode ILcdMultilevelRaster elements instead of simple ILcdRaster elements.

Sample code


 ILcdModelDecoder decoder =
   new TLcdCADRGModelDecoder(TLcdSharedBuffer.getBufferInstance(), true, true);

 ILcdModel model = decoder.decode("A.TOC");

Performance tips

  • Creating multilevel rasters can help avoiding picking the right level of detail when painting them. Rasters that are defined at different levels of detail will not be painted at the same time, which is generally unnecessary for overlapping rasters. Usually this should be combined with expanding color maps since all levels must use the same kind of pixel.

Thread safety

  • The decoding of models is thread-safe, as long as no properties are changed during the decoding.
  • 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

  • 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)
  • Raster Product Format (MIL-STD-2411, 6 October 1994)
  • Integration of Raster Product Format Files into the National Imagery Transmission Format (MIL-STD-2411-2, 26 August 1994)
  • Registered Data Values for Raster Product Format (MIL-STD-2411-1, 30 August 1994)

Known limitations

  • Any legend frames, overview frames, elevation frames, and polar frames in the table of contents are currently ignored.

  • Field Details

  • Constructor Details

    • TLcdCADRGModelDecoder

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

    • TLcdCADRGModelDecoder

      public TLcdCADRGModelDecoder(ILcdBuffer aBuffer)
      Creates a new TLcdCADRGModelDecoder.
      Parameters:
      aBuffer - the buffer in which pixel data can be decoded and cached.

    • TLcdCADRGModelDecoder

      public TLcdCADRGModelDecoder(ILcdBuffer aBuffer, boolean aExpandColorMap)
      Creates a new TLcdCADRGModelDecoder.
      Parameters:
      aBuffer - the buffer in which pixel data can be decoded and cached.
      aExpandColorMap - specifies whether the color maps of decoded tiles should be expanded.

    • TLcdCADRGModelDecoder

      public TLcdCADRGModelDecoder(ILcdBuffer aBuffer, boolean aExpandColorMap, boolean aCreateMultilevelRasters)
      Creates a new TLcdCADRGModelDecoder.
      Parameters:
      aBuffer - the buffer in which pixel data can be decoded and cached.
      aExpandColorMap - specifies whether the color maps of decoded tiles should be expanded.
      aCreateMultilevelRasters - specifies whether the decoder should create multilevel rasters instead of ordinary rasters

  • Method Details

    • setClassTraceOn

      public static void setClassTraceOn(boolean aClassTraceOn)
      Deprecated.
      This method has been deprecated. It is recommended to use the standard Java logging framework directly.
      Enables tracing for all instances of this class. If the argument is true then all log messages are recorded, otherwise only the informative, warning and error messages are recorded.
      Parameters:
      aClassTraceOn - if true then all log messages are recorded, otherwise only the informative, warning and error messages are recorded.

    • setTraceOn

      public void setTraceOn(boolean aTraceOn)
      Deprecated.
      This method has been deprecated. It is recommended to use the standard Java logging framework directly.
      Enables tracing for this class instance. Calling this method with either true or false as argument automatically turns off tracing for all other class instances for which setTraceOn has not been called. If the argument is false then only the informative, warning and error log messages are recorded.
      Parameters:
      aTraceOn - if true then all log messages are recorded for this instance. If false, then only the informative, warning and error log messages are recorded.

    • isTraceOn

      public boolean isTraceOn()
      Deprecated.
      This method has been deprecated. It is recommended to use the standard Java logging framework directly.
      Returns true if tracing is enabled for this class.
      Returns:
      true if tracing is enabled for this class, false otherwise.

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

    • setExpandColorMap

      public void setExpandColorMap(boolean aExpandColorMap)
      Sets whether the color maps of decoded tiles should be expanded.

    • isExpandColorMap

      public boolean isExpandColorMap()
      Returns whether the color maps of decoded tiles are expanded. The default is false.

    • setCreateMultilevelRasters

      public void setCreateMultilevelRasters(boolean aCreateMultilevelRasters)
      Specifies whether decoded models should contain multilevel rasters, one for each CADRG zone, or just regular rasters. The default is false.

      When you enable multi-level data then you should typically also enable expanding of color maps since all levels must have the same pixel type.

      See Also:

    • isCreateMultilevelRasters

      public boolean isCreateMultilevelRasters()
      Returns whether decoded models contain multilevel rasters, one for each CADRG zone, or just regular rasters. The default is false.
      Returns:
      true if multilevel rasters are created, false if regular rasters are created.

    • 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:
      the displayable name of this ILcdModelDecoder.

    • decodeModelMetadata

      public TLcdModelMetadata decodeModelMetadata(String aSourceName) throws IOException
      Decodes metadata for the specified data source.

      If the given data source is a .TOC file, the resulting TLcdModelMetadata will also contain a metadata instance for each of the referenced frame files. These frame files' metadata are stored as data series children and can be retrieved with TLcdModelMetadata.discoverDataSeries(). All information in the metadata is obtained from the .TOC file itself, which means that none of the frame files will be decoded (or even accessed) and a call to TLcdModelMetadata.discoverDataSeries() will not trigger any additional I/O.

      If the given data source is a single frame file, the file is simply decoded and the resulting metadata is extracted from that decoded model with ILcdModel.getModelMetadata().

      Specified by:
      decodeModelMetadata in interface ILcdModelDecoder
      Parameters:
      aSourceName - the data source for which the model metadata will be decoded.
      Returns:
      the model metadata for the data source, never null.
      Throws:
      IOException - if the metadata cannot be decoded for some reason.
      See Also:

    • canDecodeSource

      public boolean canDecodeSource(String aSourceName)
      Checks whether TLcdCADRGModelDecoder can decode the given data. The result is true if the source name has one of the supported extensions.
      Specified by:
      canDecodeSource in interface ILcdModelDecoder
      Parameters:
      aSourceName - the name of the file or URL that is to be decoded.
      Returns:
      true if TLcdCADRGModelDecoder 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: