com.luciad.format.jpeg2000

LuciadLightspeedClass 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

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

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

• JPEG2000 Standard (Joint Photographic Experts Group)

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