com.luciad.format.ecw

Advanced Raster ConnectorsClass TLcdECWModelDecoder

java.lang.Object

com.luciad.format.ecw.TLcdECWModelDecoder

All Implemented Interfaces:

ILcdMetadataDecoder, ILcdModelDecoder

@LcdService(service=ILcdModelDecoder.class,
            priority=20000)
public class TLcdECWModelDecoder
extends Object
implements ILcdModelDecoder, ILcdMetadataDecoder

This model decoder decodes georeferenced ER Mapper ECW (Enhanced Compression Wavelet) files

Input files

File	Required	Entry point	Description
*.ecw	x	x	ECW file containing the raster data and possibly specifying a model reference and raster bounds using embedded GeoTIFF tags
*.ers			ERS file specifying a model reference and raster bounds
*.tab			TAB file specifying a model reference and 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.

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 ECW file.
• All models returned by this model decoder implement ILcd2DBoundsIndexedModel.

Model descriptor

• All models returned by this model decoder have a TLcdECWModelDescriptor.
• 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 ECW file.
• 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.

Sample code

 ILcdModelDecoder decoder =
   new TLcdECWModelDecoder();

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

Performance tips

• The decoded rasters load their data lazily. The encoding parameters of the ECW 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

• ECW SDK, Release 3.3

Known limitations

• Some rare EPSG model references are not supported.

Requirements

• This decoder is part of the Advanced Raster Connectors component.
• The native ECW library has to be available in order to be able to use this decoder. Note that on Windows systems, this library requires an up-to-date version of the Microsoft Visual C++ 2013 redistributable.

Nested Class Summary

Nested classes/interfaces inherited from interface com.luciad.format.metadata.model.ILcdMetadataDecoder

ILcdMetadataDecoder.MetadataWithSource

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_DISPLAY_NAME
static double	EPSILON

Constructor Summary

Constructors

Constructor and Description
TLcdECWModelDecoder() Creates a new TLcdECWModelDecoder, with a globally shared buffer for caching tiles.
TLcdECWModelDecoder(ILcdBuffer aBuffer) Creates a new TLcdECWModelDecoder with the given buffer.
TLcdECWModelDecoder(ILcdBuffer aBuffer, ILcdModelReference aDefaultModelReference) Creates a new TLcdECWModelDecoder with the given buffer and default model reference.
TLcdECWModelDecoder(ILcdBuffer aBuffer, ILcdModelReferenceDecoder aModelReferenceDecoder) Creates a new TLcdECWModelDecoder with the given buffer and model reference decoder.
TLcdECWModelDecoder(ILcdBuffer aBuffer, ILcdModelReferenceDecoder aModelReferenceDecoder, ILcdModelReference aDefaultModelReference, int aDefaultValue) Creates a new TLcdECWModelDecoder with the given properties.
TLcdECWModelDecoder(ILcdBuffer aBuffer, ILcdModelReferenceDecoder aModelReferenceDecoder, int aDefaultValue) Creates a new TLcdECWModelDecoder with the given buffer, model reference decoder, and default value.
TLcdECWModelDecoder(ILcdBuffer aBuffer, ILcdModelReference aDefaultModelReference, int aDefaultValue) Creates a new TLcdECWModelDecoder with the given buffer, default model reference, and default value.

Method Summary

Modifier and Type	Method and Description
boolean	canDecodeMetadata(String aSourceName) Tells whether this metadata decoder can likely decode metadata for a given source name.
boolean	canDecodeSource(String aSourceName) Checks whether TLcdECWModelDecoder can decode the given data.
ILcdModel	decode(String aSourceName) Creates a new model from the given data source.
TLcdISO19115Metadata	decodeMetadata(String aSourceName) The ECW metadata has the following structure:
ILcdBounds	getBounds() Sets the default model bounds that is assigned to rasters of the decoded models whose image files don't specify bounds.
ILcdModelReference	getDefaultModelReference() Returns the default model reference that is assigned to decoded models whose image files 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.
long	getMaxCacheSize() Returns the maximum size of the ECW image cache.
double	getMaximumResidualTiePointError() Returns the maximum acceptable average residual error for tie points.
ILcdModelReference	getModelReference() Deprecated. Use getDefaultModelReference().
ILcdModelReferenceDecoder	getModelReferenceDecoder() Returns the model reference decoder that is used for decoded models whose image files don't specify model references.
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.
void	setDefaultModelReference(ILcdModelReference aDefaultModelReference) Sets the default model reference that will be assigned to decoded models whose image files 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	setMaxCacheSize(long aMaxCacheSize) Sets the maximum size of the ECW image cache.
void	setMaximumResidualTiePointError(double aMaximumResidualTiePointError) Sets the maximum acceptable average residual error for tie points, when positioning rasters based TAB files instead of on scaling information.
void	setModelReference(ILcdModelReference aDefaultModelReference) Deprecated. Use setDefaultModelReference(ILcdModelReference).
void	setModelReferenceDecoder(ILcdModelReferenceDecoder aModelReferenceDecoder) Sets the model reference decoder that will be used for decoded models whose image files don't specify model references.

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

Methods inherited from interface com.luciad.format.metadata.model.ILcdMetadataDecoder

findAndDecodeMetadata

Field Detail

DEFAULT_DISPLAY_NAME

public static final String DEFAULT_DISPLAY_NAME

See Also:

Constant Field Values

EPSILON

public static final double EPSILON

See Also:

Constant Field Values

Constructor Detail

TLcdECWModelDecoder

public TLcdECWModelDecoder()

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

See Also:

TLcdSharedBuffer.getBufferInstance()

TLcdECWModelDecoder

public TLcdECWModelDecoder(ILcdBuffer aBuffer)

Creates a new TLcdECWModelDecoder with the given buffer.

Parameters:

aBuffer - the buffer in which pixel data can be decoded and cached.

TLcdECWModelDecoder

public TLcdECWModelDecoder(ILcdBuffer aBuffer,
                           ILcdModelReferenceDecoder aModelReferenceDecoder)

Creates a new TLcdECWModelDecoder 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.

TLcdECWModelDecoder

public TLcdECWModelDecoder(ILcdBuffer aBuffer,
                           ILcdModelReferenceDecoder aModelReferenceDecoder,
                           int aDefaultValue)

Creates a new TLcdECWModelDecoder 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.

TLcdECWModelDecoder

public TLcdECWModelDecoder(ILcdBuffer aBuffer,
                           ILcdModelReference aDefaultModelReference)

Creates a new TLcdECWModelDecoder 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.

TLcdECWModelDecoder

public TLcdECWModelDecoder(ILcdBuffer aBuffer,
                           ILcdModelReference aDefaultModelReference,
                           int aDefaultValue)

Creates a new TLcdECWModelDecoder 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.

TLcdECWModelDecoder

public TLcdECWModelDecoder(ILcdBuffer aBuffer,
                           ILcdModelReferenceDecoder aModelReferenceDecoder,
                           ILcdModelReference aDefaultModelReference,
                           int aDefaultValue)

Creates a new TLcdECWModelDecoder 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 Detail

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:

setModelReferenceDecoder(com.luciad.model.ILcdModelReferenceDecoder)

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.

setModelReference

public void setModelReference(ILcdModelReference aDefaultModelReference)

Deprecated. Use setDefaultModelReference(ILcdModelReference).

getModelReference

public ILcdModelReference getModelReference()

Deprecated. Use getDefaultModelReference().

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.

setMaximumResidualTiePointError

public void setMaximumResidualTiePointError(double aMaximumResidualTiePointError)

Sets the maximum acceptable average residual error for tie points, when positioning rasters based TAB files instead of on scaling information.

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.

getMaximumResidualTiePointError

public double getMaximumResidualTiePointError()

Returns the maximum acceptable average residual error for 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:

ILcdRaster.setDefaultValue(int)

getDefaultValue

public int getDefaultValue()

Returns the default pixel value that is assigned to the rasters of the decoded models.

getMaxCacheSize

public long getMaxCacheSize()

Returns the maximum size of the ECW image cache.

Note that the ECW image cache is currently shared between all ECW images.

The default value is 64MB which should give good performance and reasonable memory usage in almost all cases.

Returns:

the maximum size in bytes

setMaxCacheSize

public void setMaxCacheSize(long aMaxCacheSize)

Sets the maximum size of the ECW image cache.

Parameters:

aMaxCacheSize - the maximum size in bytes

See Also:

getMaxCacheSize()

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 TLcdECWModelDecoder can decode the given data. The extension of the file name should be "ecw" or "ers".

Specified by:

canDecodeSource in interface ILcdModelDecoder

Parameters:

aSourceName - the name of the file that is to be decoded.

Returns:

true if TLcdECWModelDecoder 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)

canDecodeMetadata

public boolean canDecodeMetadata(String aSourceName)

Description copied from interface: ILcdMetadataDecoder

Tells whether this metadata decoder can likely decode metadata for a given source name.

• If true, it is likely that ILcdMetadataDecoder.decodeMetadata(String) will return a non-null TLcdISO19115Metadata object, but it is not a guarantee. The result is optimistic.
• If false, it is guaranteed that ILcdMetadataDecoder.decodeMetadata(String) will throw an exception or return null.

Specified by:

canDecodeMetadata in interface ILcdMetadataDecoder

Parameters:

aSourceName - the source name to decode metadata for

Returns:

true if this metadata decoder can decode metadata for the given source name, false otherwise

decodeMetadata

public TLcdISO19115Metadata decodeMetadata(String aSourceName)
                                    throws IOException

The ECW metadata has the following structure:

 Metadata
   DataIdentification
     Citation
       Title=[ECW data file name, same as identifier code]
       Identifier
         Code=[ECW data file name]
   Describes
     MX_DataSet
       DataFile
         FileName=[ECW data file name]
       SupportFiles
         FileName
           Src=[TAB support file name]*
           Src=[ERS support file name]*
           Src=[REF support file name]*
           Src=[PRJ support file name]*
 

Elements with a '*' are optional. All file names are without parent path, which is needed for portability.

Both the identifier and title contain the data file name. The identifier is authoritative, the title is for display purposes.

Specified by:

decodeMetadata in interface ILcdMetadataDecoder

Parameters:

aSourceName - the source name to decode metadata from

Returns:

the ECW metadata, possibly null

Throws:

IOException - if the metadata cannot be decoded for some reason