Package com.luciad.format.jpeg2000

Class TLcdJPEG2000ModelDecoder

java.lang.Object
com.luciad.format.jpeg2000.TLcdJPEG2000ModelDecoder
All Implemented Interfaces:
ILcdModelDecoder
@LcdService(service=ILcdModelDecoder.class, priority=20000) public class TLcdJPEG2000ModelDecoder extends Object implements ILcdModelDecoder
This model decoder decodes georeferenced JPEG2000 files.

Input files

File Required Entry point Description
*.jp2
*.j2k		 x x JPEG2000 file containing the raster data and possibly specifying a model reference and raster bounds using embedded GeoTIFF tags (geoJP2) or via embedded GML (GMLJP2 versions 1.0, 2.0 & 2.1).
*.tab

TAB file specifying a model reference and raster bounds
*.jpw

JPW file specifying raster bounds
*.j2w

J2W file specifying raster bounds

If none of the files specify a model reference, 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.

If none of the files specify raster bounds, it is retrieved from the bounds property of this decoder.

You can find all details about reference decoding on decodeRasterReference(TLcdJPEG2000ModelDescriptor).

Supported file transfer protocols

As random access to the data is required, this decoder only reads from files. So it can for example not read from an InputStream, from a http connection or from an image file inside a jar file.

Model structure

  • This model decoder creates a model per JPEG2000 file.
  • All models returned by this model decoder implement ILcd2DBoundsIndexedModel.

Model descriptor

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

Model reference

  • This decoder retrieves the model references embedded in the JPEG2000 file. Both geoJP2 (embedded GeoTIFF tags) and GMLJP2 (embedded GML) are supported.
  • It is possible to specify a default reference for files from which the reference information is mssing.
  • A custom reference decoder can also be installed.

Model elements

  • Each decoded model contains one object: an ALcdImage (and ILcdMultilevelRaster) instance.

Useful settings

  • The property defaultValue allows the specify the default value that is assigned to decoded rasters.

Customization

  • The decodeRasterReference(com.luciad.format.jpeg2000.TLcdJPEG2000ModelDescriptor) method can be overridden to customize the decoding of the georeferencing information of the raster. This is for example necessary if this information is embedded as application-specific XML.

    • Sample code

    
 ILcdModelDecoder decoder =
   new TLcdJPEG2000ModelDecoder();

 ILcdModel model = decoder.decode("raster.jp2");

    Performance tips

    • The decoded rasters load their data lazily. The encoding parameters of the JPEG2000 file may affect the run-time performance.

    Thread safety

    • The decoding of models is thread-safe, as long as no properties are changed during the decoding.
    • The decoded models are thread-safe for read access.

    Supported versions and specifications

    Known limitations

    • Some rare EPSG model references are not supported.
    • If present, the geoJP2 transformation matrix may only contain translation, rotation and scale (for example no shear). Other transformations can be approximated by encoding tie points instead. Note that the decoding may fail when using tie points if the residual error is above the threshold.
    • This decoder uses the Kakadu JPEG2000 native library for actual decoding. The native library can allocate significant amount of memory. On 32 bit platforms, when several JPEG2000 files are opened and accessed in parallel, the required memory may exceed the limit of virtual memory space (2 GBytes on Windows, 3 GBytes on Linux), which may crash the application. To prevent that from happening, the Java code limits the number of JPEG2000 streams opened in parallel to 10. In practice this means that if more than 10 JPEG2000 files are open at the same time the performance of the decoder will decrease visibly, because the native library will have to switch between the files, each time cleaning its internal caches.

      The number of native decoders allowed to work in parallel can be controlled by setting the jpeg2000.pool.size system property (for example: java -Djpeg2000.pool.size=2 MyApplication).

    • Via the ALcdImage API it is possible to decode monochrome, RGB and multi band images. Each band of the image may contain <= 16 bits, which will not be scaled. Further, it is assumed that all data is unsigned.
    • Due to the limitations of the legacy ILcdRaster API some image components may be converted to lower precision. You can obtain the precision in the image from the model descriptor and the precision in the ILcdRaster from its ILcdRaster.getColorModel() color model. The raster component is either 8 or 16 bits and the total number of bits per raster pixel is at most 32bits. Image components is obtained by scaling the image components. For example, an RGB JPEG2000 image with 11 bits per component will be converted to an RGB raster with 8 bits per component where each component is scaled by (2^11 - 1) / (2^8 - 1).
    • Only GMLJP2 versions 1.0, 2.0 and 2.1 are supported and only the reference will be parsed from the embedded GML, other elements will be ignored.

    Requirements

    • The native JPEG2000 library has to be installed in order to be able to use this decoder.
    Since:
    6.0

    • Field Details

    • Constructor Details

      • TLcdJPEG2000ModelDecoder

        public TLcdJPEG2000ModelDecoder()
        Creates a new TLcdJPEG2000ModelDecoder, with a globally shared buffer for caching pixel data.
        See Also:

      • TLcdJPEG2000ModelDecoder

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

      • TLcdJPEG2000ModelDecoder

        public TLcdJPEG2000ModelDecoder(ILcdBuffer aBuffer, ILcdModelReferenceDecoder aModelReferenceDecoder)
        Creates a new TLcdJPEG2000ModelDecoder with the given buffer and model reference decoder.
        Parameters:
        aBuffer - the buffer in which pixel data can be decoded and cached.
        aModelReferenceDecoder - the model reference decoder.

      • TLcdJPEG2000ModelDecoder

        public TLcdJPEG2000ModelDecoder(ILcdBuffer aBuffer, ILcdModelReferenceDecoder aModelReferenceDecoder, int aDefaultValue)
        Creates a new TLcdJPEG2000ModelDecoder with the given buffer, model reference decoder, and default value.
        Parameters:
        aBuffer - the buffer in which pixel data can be decoded and cached.
        aModelReferenceDecoder - the model reference decoder.
        aDefaultValue - the default pixel value.

      • TLcdJPEG2000ModelDecoder

        public TLcdJPEG2000ModelDecoder(ILcdBuffer aBuffer, ILcdModelReference aDefaultModelReference)
        Creates a new TLcdJPEG2000ModelDecoder with the given buffer and default model reference.
        Parameters:
        aBuffer - the buffer in which pixel data can be decoded and cached.
        aDefaultModelReference - the default model reference.

      • TLcdJPEG2000ModelDecoder

        public TLcdJPEG2000ModelDecoder(ILcdBuffer aBuffer, ILcdModelReference aDefaultModelReference, int aDefaultValue)
        Creates a new TLcdJPEG2000ModelDecoder with the given buffer, default model reference, and default value.
        Parameters:
        aBuffer - the buffer in which pixel data can be decoded and cached.
        aDefaultModelReference - the default model reference.
        aDefaultValue - the default pixel value.

      • TLcdJPEG2000ModelDecoder

        public TLcdJPEG2000ModelDecoder(ILcdBuffer aBuffer, ILcdModelReferenceDecoder aModelReferenceDecoder, ILcdModelReference aDefaultModelReference, int aDefaultValue)
        Creates a new TLcdJPEG2000ModelDecoder with the given properties.
        Parameters:
        aBuffer - the buffer in which pixel data can be decoded and cached.
        aModelReferenceDecoder - the model reference decoder.
        aDefaultModelReference - the default model reference.
        aDefaultValue - the default pixel value.

    • Method Details

      • setModelReferenceDecoder

        public void setModelReferenceDecoder(ILcdModelReferenceDecoder aModelReferenceDecoder)
        Sets the model reference decoder that will be used for decoded models whose image files don't specify model references.
        Parameters:
        aModelReferenceDecoder - the model reference decoder.

      • getModelReferenceDecoder

        public ILcdModelReferenceDecoder getModelReferenceDecoder()
        Returns the model reference decoder that is used for decoded models whose image files don't specify model references. 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 that will be assigned to decoded models whose image files don't specify model references.
        Parameters:
        aDefaultModelReference - the default model reference.

      • getDefaultModelReference

        public ILcdModelReference getDefaultModelReference()
        Returns the default model reference that is assigned to decoded models whose image files don't specify model references.

      • setBounds

        public void setBounds(ILcdBounds aBounds)
        Sets the default model bounds that will be assigned to rasters of the decoded models whose image files don't specify bounds.
        Parameters:
        aBounds - the default model bounds.

      • getBounds

        public ILcdBounds getBounds()
        Sets the default model bounds that is assigned to rasters of the decoded models whose image files don't specify bounds.

      • setMinimumTiePointCount

        public void setMinimumTiePointCount(int aMinimumTiePointCount)
        Sets the minimum number of tie points required for positioning image files that provide tie points instead of scaling information or transformation matrices. The default is 4.

        A value of 3 can be used, if the assumption is made that 3 tie points always define an affine transformation (which is not strictly guaranteed by the GeoTIFF specifications).

        A value of 2 can be used, if the assumption is made that 2 tie points always define an affine transformation without rotation.

        Parameters:
        aMinimumTiePointCount - the minimum number of tie points.
        See Also:

      • getMinimumTiePointCount

        public int getMinimumTiePointCount()
        Returns the minimum number of tie points required for positioning image files that provide tie points.

      • setAllowOrthographicReferencing

        public void setAllowOrthographicReferencing(boolean aAllowOrthographicReferencing)
        Specifies whether images that are positioned in geodetic references using tie points may be put in approximating orthographic grid references that are centered around the images. The default is true.

      • isAllowOrthographicReferencing

        public boolean isAllowOrthographicReferencing()
        Returns whether images that are positioned in geodetic references using tie points may be put in approximating orthographic grid references that are centered around the images.

      • setMaximumResidualTiePointError

        public void setMaximumResidualTiePointError(double aMaximumResidualTiePointError)
        Sets the maximum acceptable average residual error for tie points, when positioning image files that provide tie points instead of scaling information or transformation matrices.

        A raster is always positioned by means of an affine transformation in its coordinate system. For tie points that define an affine transformation, the residual error should therefore be 0. For tie points that define more complex, non-linear warping of the image, it will be larger than 0.

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

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

      • getMaximumResidualTiePointError

        public double getMaximumResidualTiePointError()
        Returns the maximum acceptable average residual error for tie 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 minimumTiePointCount, 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.

      • setDefaultValue

        public void setDefaultValue(int aDefaultValue)
        Sets the default pixel value that will be assigned to the rasters of the decoded models.
        Parameters:
        aDefaultValue - the default pixel value.
        See Also:

      • getDefaultValue

        public int getDefaultValue()
        Returns the default pixel value that is assigned to the rasters of the decoded models.

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

      • canDecodeSource

        public boolean canDecodeSource(String aSourceName)
        Checks whether TLcdJPEG2000ModelDecoder can decode the given data. The extension of the file name should be "jp2" or "j2k".
        Specified by:
        canDecodeSource in interface ILcdModelDecoder
        Parameters:
        aSourceName - the name of the file that is to be decoded.
        Returns:
        true if TLcdJPEG2000ModelDecoder 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:

      • decodeRasterReference

        protected ILcdRasterReference decodeRasterReference(TLcdJPEG2000ModelDescriptor aModelDescriptor) throws IOException
        Decodes the raster reference based on the metadata.

        The default implementation does a best effort using:

        1. the UUID metadata if it is present (aka geoJP2)
        2. the default model reference decoder (default supports .ref, .prj and .epsg files)
        3. the default model reference and/or bounds

        You typically override this method to if the raster reference is encoded in a custom way such as an XML metadata box.

        Parameters:
        aModelDescriptor - the model descriptor
        Returns:
        the raster reference
        Throws:
        IOException - if the raster reference could not be decoded