TLcdJPIPModelDecoder (LuciadLightspeed API documentation)

java.lang.Object
- com.luciad.format.jpeg2000.TLcdJPIPModelDecoder

All Implemented Interfaces:

ILcdModelDecoder
```
@LcdService(service=ILcdModelDecoder.class,
            priority=20000)
public class TLcdJPIPModelDecoder
extends Object
implements ILcdModelDecoder
```
This model decoder decodes georeferenced JPEG2000 images retrieved through the JPEG2000 Interactive Protocol (JPIP).

Input sources
The model decoder can only recognize a URI that points to a JPEG2000 image (ex. http://host:port/path/to/image.jp2).
Supported transfer protocols
- This model decoder only supports "http" or "jpip".
Model structure
- This model decoder creates a model per JPIP source.
- All models returned by this model decoder implement ILcd2DBoundsIndexedModel.
Model descriptor
- All models returned by this model decoder have a TLcdJPIPModelDescriptor.
- The type name of the model descriptor is the display name of this decoder.
Model reference
If present the raster data contains embedded GeoTIFF tags (geoJP2) then the model reference and raster bounds are decoded from it. If the image does not specify a model reference, it is retrieved with the help of the getModelReferenceDecoder() or as the getDefaultModelReference() of this decoder. If the image does not specify raster bounds, it is retrieved from the getDefaultBounds() property of this decoder.
Model elements
- Each decoded model contains one object: an ALcdImage (and ILcdMultilevelRaster) instance.
Releasing resources
A JPIP model and its elements allocate a number of resources (ex. memory, network connections, ...). These are automatically released when they are garbage collected. However in some cases it is necessary to release these resources immediately. For example if the JPIP server limits the number of sessions per client. The resources can be released by invoking ILcdDisposable.dispose() on all model elements. Note that the caller must ensure that the elements are not used after they are disposed. Typically this means removing all layers that use the model from their view before disposing the elements.
Useful settings
- The property getDefaultValue() allows the specify the default value that is assigned to decoded rasters.
Customization
The ILcdTransport used for communicating with a JPIP server can be customized by using the setTransportFactory(com.luciad.io.transport.ILcdTransportFactory) method.
The decodeRasterReference(com.luciad.format.jpeg2000.TLcdJPIPModelDescriptor) 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 TLcdJPIPModelDecoder();
 ILcdModel model = decoder.decode("http://localhost:8080/image.jp2");

Performance tips

The decoded rasters load their data lazily. The encoding parameters of the JPEG2000 image may affect the run-time performance.
The image cache size affects how much data needs to be retrieved from the server. Typically some of the data retrieved for an image region can be reused in subsequent requests for nearby image regions. A larger cache size increases the chance that data can be read from the cache instead of retrieving it again from the server.

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 images 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 images are open at the same time the performance of the decoder will decrease visibly, because the native library will have to switch between the images, 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.

model descriptor

ILcdRaster

ILcdRaster.getColorModel() color model

(2^11 - 1) / (2^8 - 1)

Requirements

The native JPEG2000 library has to be installed in order to be able to use this decoder.

Since:: 2012.1

Constructor Summary

Constructors
Constructor and Description
`TLcdJPIPModelDecoder()` Creates a new `TLcdJPIPModelDecoder`, with a globally shared buffer for caching pixel data.
`TLcdJPIPModelDecoder(ILcdBuffer aBuffer)` Creates a new `TLcdJPIPModelDecoder` with the given buffer.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`canDecodeSource(String aSourceName)` Checks whether `TLcdJPIPModelDecoder` can decode the given data.
`ILcdModel`	`decode(String aSourceName)` Creates a new model from the given data source.
`protected ILcdRasterReference`	`decodeRasterReference(TLcdJPIPModelDescriptor aModelDescriptor)` Decodes the raster reference based on the metadata.
`ILcdBounds`	`getDefaultBounds()` Sets the default model bounds that is assigned to rasters of the decoded models whose images don't specify bounds.
`ILcdModelReference`	`getDefaultModelReference()` Returns the default model reference that is assigned to decoded models whose images don't specify model references.
`int`	`getDefaultValue()` Returns the default pixel value that is assigned to the rasters of the decoded models.
`String`	`getDisplayName()` Returns a short, displayable name for the format that is decoded by this `ILcdModelDecoder`.
`int`	`getImageCacheSize()` Returns the size (in bytes) of the image cache.
`double`	`getMaximumResidualTiePointError()` Returns the maximum acceptable average residual error for tie points.
`int`	`getMinimumTiePointCount()` Returns the minimum number of tie points required for positioning images that provide tie points.
`ILcdModelReferenceDecoder`	`getModelReferenceDecoder()` Returns the model reference decoder that is used for decoded models whose images don't specify model references.
`ILcdRasterReferencer`	`getRasterReferencer()` Returns the raster referencer that is used when positioning images based on tie points.
`ILcdTransportFactory`	`getTransportFactory()` Returns the transport factory that will construct the `ILcdTransport` used for communicating with a JPIP server.
`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.
`boolean`	`isQueryServerOnCanDecode()` Returns whether the server should be queried in the `canDecodeSource(String)` method.
`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.
`void`	`setDefaultBounds(ILcdBounds aBounds)` Sets the default model bounds that will be assigned to rasters of the decoded models whose images don't specify bounds.
`void`	`setDefaultModelReference(ILcdModelReference aDefaultModelReference)` Sets the default model reference that will be assigned to decoded models whose images don't specify model references.
`void`	`setDefaultValue(int aDefaultValue)` Sets the default pixel value that will be assigned to the rasters of the decoded models.
`void`	`setImageCacheSize(int aCacheSize)` Sets the size (in bytes) of the image cache.
`void`	`setMaximumResidualTiePointError(double aMaximumResidualTiePointError)` Sets the maximum acceptable average residual error for tie points, when positioning images that provide tie points instead of scaling information or transformation matrices.
`void`	`setMinimumTiePointCount(int aMinimumTiePointCount)` Sets the minimum number of tie points required for positioning images that provide tie points instead of scaling information or transformation matrices.
`void`	`setModelReferenceDecoder(ILcdModelReferenceDecoder aModelReferenceDecoder)` Sets the model reference decoder that will be used for decoded models whose images don't specify model references.
`void`	`setQueryServerOnCanDecode(boolean aQueryServerOnCanDecode)` Sets whether the server should be queried in the `canDecodeSource(String)` method.
`void`	`setRasterReferencer(ILcdRasterReferencer aRasterReferencer)` Sets the raster referencer that will be used when positioning images based on tie points.
`void`	`setTransportFactory(ILcdTransportFactory aTransportFactory)` Sets the transport factory that will construct the `ILcdTransport` used for communicating with a JPIP server.

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
  - TLcdJPIPModelDecoder
```
public TLcdJPIPModelDecoder()
```
    Creates a new TLcdJPIPModelDecoder, with a globally shared buffer for caching pixel data.
    
    See Also:
    
    TLcdSharedBuffer.getBufferInstance()
  - TLcdJPIPModelDecoder
```
public TLcdJPIPModelDecoder(ILcdBuffer aBuffer)
```
    Creates a new TLcdJPIPModelDecoder with the given buffer.
    
    Parameters:
    
    aBuffer - the buffer in which pixel data can be decoded and cached.
- Method Detail
  - setModelReferenceDecoder
```
public void setModelReferenceDecoder(ILcdModelReferenceDecoder aModelReferenceDecoder)
```
    Sets the model reference decoder that will be used for decoded models whose images don't specify model references.
    The default value is null.
    
    Parameters:
    
    aModelReferenceDecoder - the model reference decoder.
  - getModelReferenceDecoder
```
public ILcdModelReferenceDecoder getModelReferenceDecoder()
```
    Returns the model reference decoder that is used for decoded models whose images don't specify model references.
    
    Returns:
    
    the model reference decoder
    
    See Also:
    
    setModelReferenceDecoder(com.luciad.model.ILcdModelReferenceDecoder)
  - setDefaultModelReference
```
public void setDefaultModelReference(ILcdModelReference aDefaultModelReference)
```
    Sets the default model reference that will be assigned to decoded models whose images don't specify model references.
    The default value is null.
    
    Parameters:
    
    aDefaultModelReference - the default model reference.
  - getDefaultModelReference
```
public ILcdModelReference getDefaultModelReference()
```
    Returns the default model reference that is assigned to decoded models whose images don't specify model references.
    
    Returns:
    
    the default model reference
    
    See Also:
    
    setDefaultModelReference(com.luciad.model.ILcdModelReference)
  - setDefaultBounds
```
public void setDefaultBounds(ILcdBounds aBounds)
```
    Sets the default model bounds that will be assigned to rasters of the decoded models whose images don't specify bounds.
    The default value is null.
    
    Parameters:
    
    aBounds - the default model bounds.
  - getDefaultBounds
```
public ILcdBounds getDefaultBounds()
```
    Sets the default model bounds that is assigned to rasters of the decoded models whose images don't specify bounds.
    
    Returns:
    
    the bounds
    
    See Also:
    
    setDefaultBounds(com.luciad.shape.ILcdBounds)
  - setMinimumTiePointCount
```
public void setMinimumTiePointCount(int aMinimumTiePointCount)
```
    Sets the minimum number of tie points required for positioning images that provide tie points instead of scaling information or transformation matrices.
    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.
    The default is 3.
    
    Parameters:
    
    aMinimumTiePointCount - the minimum number of tie points.
    
    See Also:
    
    setMaximumResidualTiePointError(double)
  - getMinimumTiePointCount
```
public int getMinimumTiePointCount()
```
    Returns the minimum number of tie points required for positioning images that provide tie points.
    
    Returns:
    
    the minimum number of tie points
    
    See Also:
    
    setMinimumTiePointCount(int)
  - 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.
    
    Returns:
    
    whether orthographic referencing is allowed
    
    See Also:
    
    setAllowOrthographicReferencing(boolean)
  - setMaximumResidualTiePointError
```
public void setMaximumResidualTiePointError(double aMaximumResidualTiePointError)
```
    Sets the maximum acceptable average residual error for tie points, when positioning images 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 10.
    
    Parameters:
    
    aMaximumResidualTiePointError - the maximum residual error, expressed in pixels.
    
    See Also:
    
    setMinimumTiePointCount(int)
  - getMaximumResidualTiePointError
```
public double getMaximumResidualTiePointError()
```
    Returns the maximum acceptable average residual error for tie points.
    
    Returns:
    
    the maximum acceptable average residual error for tie points
    
    See Also:
    
    setMaximumResidualTiePointError(double)
  - setRasterReferencer
```
public void setRasterReferencer(ILcdRasterReferencer aRasterReferencer)
```
    Sets the raster referencer that will be used when positioning images based on tie points. If it is set, it replaces the more basic settings minimumTiePointCount, allowOrthographicReferencing, and maximumResidualTiePointError, which are used by default.
    The initial value is null.
    
    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 images based on tie points.
    
    Returns:
    
    the raster referencer
    
    See Also:
    
    setRasterReferencer(com.luciad.format.raster.reference.ILcdRasterReferencer)
  - setDefaultValue
```
public void setDefaultValue(int aDefaultValue)
```
    Sets the default pixel value that will be assigned to the rasters of the decoded models.
    The initial value is 0.
    
    Parameters:
    
    aDefaultValue - the default pixel value.
    
    See Also:
    
    ILcdRaster.setDefaultValue(int)
  - getDefaultValue
```
public int getDefaultValue()
```
    Returns the default pixel value that is assigned to the rasters of the decoded models.
    
    Returns:
    
    the default value.
    
    See Also:
    
    setDefaultValue(int)
  - getTransportFactory
```
public ILcdTransportFactory getTransportFactory()
```
    Returns the transport factory that will construct the ILcdTransport used for communicating with a JPIP server.
    
    Returns:
    
    the transport
    
    See Also:
    
    setTransportFactory(com.luciad.io.transport.ILcdTransportFactory)
  - setTransportFactory
```
public void setTransportFactory(ILcdTransportFactory aTransportFactory)
```
    Sets the transport factory that will construct the ILcdTransport used for communicating with a JPIP server.
    The default transport factory creates ILcdTransports based on the Apache HttpClient library. This factory uses the proxy configuration from the system-wide proxy selector
    The transports created by the factory should implement ILcdDisposable if they hold any resources (ex. network connections).
    This setter does not affect already decoded models.
    
    Parameters:
    
    aTransportFactory - the transport factory, must not be null
  - getImageCacheSize
```
public int getImageCacheSize()
```
    Returns the size (in bytes) of the image cache.
    
    Returns:
    
    the cache size in bytes
    
    See Also:
    
    setImageCacheSize(int)
  - setImageCacheSize
```
public void setImageCacheSize(int aCacheSize)
```
    Sets the size (in bytes) of the image cache.
    A larger cache size results in lower bandwidth usage (the server does not need to resend data) but a higher memory consumption.
    The default cache size is 64MB.
    This setter does not affect already decoded models.
    The cache size will be clamped to the minimal cache size if it is too small.
    
    Parameters:
    
    aCacheSize - the cache size in bytes
  - isQueryServerOnCanDecode
```
public boolean isQueryServerOnCanDecode()
```
    Returns whether the server should be queried in the canDecodeSource(String) method.
    
    Returns:
    
    true if the server should be queried
    
    See Also:
    
    setQueryServerOnCanDecode(boolean)
  - setQueryServerOnCanDecode
```
public void setQueryServerOnCanDecode(boolean aQueryServerOnCanDecode)
```
    Sets whether the server should be queried in the canDecodeSource(String) method.
    If enabled, the server will be queried in the canDecode method to verify that it is a valid JPIP server, otherwise this method will only verify that the provided source name is a valid URI.
    This is enabled by default.
    
    Parameters:
    
    aQueryServerOnCanDecode - true if the server should be queried
  - 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 TLcdJPIPModelDecoder can decode the given data. The source name should be a URI with one of the supported schemes.
    This method verifies that the specified source name is a valid URI. If isQueryServerOnCanDecode() is enabled then this method will also verify that the specified the server exists and is a valid JPIP server.
    
    Specified by:
    
    canDecodeSource in interface ILcdModelDecoder
    
    Parameters:
    
    aSourceName - the url of the image that is to be tested
    
    Returns:
    
    true if TLcdJPIPModelDecoder 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)
  - decodeRasterReference
```
protected ILcdRasterReference decodeRasterReference(TLcdJPIPModelDescriptor 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
    2. the default model reference decoder
    3. the default model reference and/or bounds
    You typically override this method 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

LuciadLightspeedClass TLcdJPIPModelDecoder

Input sources

Supported transfer protocols

Model structure

Model descriptor

Model reference

Model elements

Releasing resources

Useful settings

Customization

Sample code

Performance tips

Thread safety

Supported versions and specifications

Known limitations

Requirements

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface com.luciad.model.ILcdModelDecoder

Constructor Detail

TLcdJPIPModelDecoder

TLcdJPIPModelDecoder

Method Detail

setModelReferenceDecoder

getModelReferenceDecoder

setDefaultModelReference

getDefaultModelReference

setDefaultBounds

getDefaultBounds

setMinimumTiePointCount

getMinimumTiePointCount

setAllowOrthographicReferencing

isAllowOrthographicReferencing

setMaximumResidualTiePointError

getMaximumResidualTiePointError

setRasterReferencer

getRasterReferencer

setDefaultValue

getDefaultValue

getTransportFactory

setTransportFactory

getImageCacheSize

setImageCacheSize

isQueryServerOnCanDecode

setQueryServerOnCanDecode

getDisplayName

canDecodeSource

decode

decodeRasterReference