Package com.luciad.format.gdal

Class TLcdGDALModelDecoder

java.lang.Object
com.luciad.format.gdal.TLcdGDALModelDecoder
All Implemented Interfaces:
ILcdMetadataDecoder, ILcdModelDecoder, ILcdStatusSource
@LcdService(service=ILcdModelDecoder.class, priority=20000) public class TLcdGDALModelDecoder extends Object implements ILcdModelDecoder, ILcdMetadataDecoder, ILcdStatusSource
This decoder can decode raster data using GDAL. It supports verified raster formats for which Luciad doesn't have a proper decoder:
  • ACE2 (*.ace2)
  • Arc/Info Binary Grid (*.adf)
  • Azavea Raster Grid (*.arg, *.json)
  • Magellan BLX Topo (*.blx, *.xlb)
  • BSB Nautical Chart (*.kap)
  • VTP Binary Terrain Format (*.bt)
  • First Generation USGS DOQ (*.doq)
  • ERDAS Imagine (*.img)
  • ENVI .hdr Labelled Raster (*.dat)
  • EOSAT FAST Format (*.fst)
  • Golden Software ASCII Grid (*.grd)
  • Golden Software Binary Grid (*.grd)
  • Golden Software Surfer 7 Binary Grid (*.grd)
  • New Labelled USGS DOQ (*.doq, *.nws)
  • GXF - Grid eXchange File (*.gxf)
  • NOAA .gtx vertical datum shift (*.gtx)
  • HF2/HFZ heightfield raster (*.hf2)
  • SGI Image Format (*.bw, *.rgb, *.rgba, *.sgi)
  • Snow Data Assimilation System (*.hdr)
  • SRTM HGT Format (*.hgt)
  • GDAL Virtual (*.vrt)
  • GeospatialPDF (*.pdf)
Optionally, this decoder can also decode unverified raster formats that are listed as raster formats supported by the GDAL library, using setAllowUnverifiedFormats(boolean). Since this behaviour is unverified the decoder might not succeed in decoding the source.

A raster data file is typically a satellite image which can represent either a measurement (e.g. elevation) or true color (e.g. RGB). It can also be a multi or hyper spectral image as well.

Input Files

FileRequiredEntry pointDescription
*.imgXXThe ERDAS Imagine file
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.

Supported file transfer protocols

  • This model decoder decodes data from a file system.

Model structure

Model descriptor

  • The returned model has a model descriptor with "GDAL/<type>" as type name. The type is obtained from the GDAL library driver, and depends on the format. For example for ERDAS Imagine data the type is "HFA".
  • The model descriptor of the model is a ILcdImageModelDescriptor.
  • The decoded source name is the display name of the model descriptor.

Model reference

Model elements

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.

Sample code

   // decode the model
   TLcdGDALModelDecoder decoder = new TLcdGDALModelDecoder();
   ILcdModel model = decoder.decode(aSource);

   // retrieve the measurements
   Object domainObject = model.elements().nextElement();
   ALcdImage image = ALcdImage.fromDomainObject(domainObject);
For more information on how to integrate GDAL decoded raster data into your application, refer to the GDAL developer's guide.
Since:
2016.0
See Also:

  • Field Details

    • TYPE_NAME

      public static final String TYPE_NAME
      The first part of the type name of the model descriptor; its value is "GDAL". The actual type name is GDAL/<type>, where the type is obtained from the GDAL library driver and depends on the format.
      See Also:

  • Constructor Details

    • TLcdGDALModelDecoder

      public TLcdGDALModelDecoder()

  • Method Details

    • setAllowUnverifiedFormats

      public void setAllowUnverifiedFormats(boolean aAllow)
      Allow decoding of formats that have not been verified by Luciad, including formats for which a proper model decoder exists. The default is off, unless the default itself has been overridden using the system property "com.luciad.format.gdal.allowUnverifiedFormats".
      Parameters:
      aAllow - whether or not to allow decoding of unverified formats
      Since:
      2024.0

    • setModelReferenceDecoder

      public void setModelReferenceDecoder(ILcdModelReferenceDecoder aModelReferenceDecoder)

      Sets the model reference decoder that will be used for creating model references for decoded models. When the model reference decoder is not set, or when it cannot create a model reference for a certain source, the default model reference will be used.

      Parameters:
      aModelReferenceDecoder - the new model reference decoder
      Since:
      2024.1.01

    • getModelReferenceDecoder

      public ILcdModelReferenceDecoder getModelReferenceDecoder()
      Returns the model reference decoder that is used for creating model references for decoded models.
      Returns:
      the model reference decoder
      Since:
      2024.1.01

    • setDefaultModelReference

      public void setDefaultModelReference(ILcdModelReference aDefaultModelReference)
      Sets the default model reference for decoded models, in case the model reference decoder doesn't provide one.
      Parameters:
      aDefaultModelReference - the new default model reference
      Since:
      2024.1.01

    • getDefaultModelReference

      public ILcdModelReference getDefaultModelReference()
      Returns the default model reference for decoded models.
      Returns:
      the default model reference
      Since:
      2024.1.01

    • getDisplayName

      public String getDisplayName()
      Returns "GDAL".
      Specified by:
      getDisplayName in interface ILcdModelDecoder
      Returns:
      "GDAL"

    • canDecodeSource

      public boolean canDecodeSource(String aSourceName)
      Description copied from interface: ILcdModelDecoder
      Checks whether this model decoder can decode the specified data source. It is acceptable for this method to return true for a source name while decode throws an exception for that same source name.

      For performance reasons, we strongly recommend that this will only be a simple test. For example: check the file extension of a file, but not that the file exists or contains expected content.

      Specified by:
      canDecodeSource in interface ILcdModelDecoder
      Parameters:
      aSourceName - the data source to be verified; typically a file name or a URL.
      Returns:
      true if this decoder can likely 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:

    • 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.
      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
      Decodes the metadata from a gdal source and returns a TLcdISO19115Metadata instance.
      Specified by:
      decodeMetadata in interface ILcdMetadataDecoder
      Parameters:
      aSourceName - a gdal source
      Returns:
      a TLcdISO19115Metadata instance which contains paths of all files which are needed to decode the gdal source, null if the metadata can not be decoded.
      Throws:
      IOException - if the source can not be found

    • discoverDataSources

      public List<? extends ILcdDataSource> discoverDataSources(String aPath) throws IOException
      Description copied from interface: ILcdModelDecoder

      Retrieves a set of model-specific ILcdDataSource instances.

      By default, this method:

      Concrete model decoders might choose to return a set of ILcdDataSource, for instance, if the path references a collection of data sources.

      An example where this is useful is for container formats, such as NetCDF. A NetCDF file can contain multiple measurement layers. This ILcdModelDecoder.discoverDataSources(String) method allows you to distinguish between them using ILcdDataSources, where each measurement layer can be referenced to and decoded separately using ILcdModelDecoder.decodeSource(ILcdDataSource)

      Specified by:
      discoverDataSources in interface ILcdModelDecoder
      Parameters:
      aPath - A path to the data source to be decoded; typically a file path or a URL.
      Returns:
      If this model decoder returns true for ILcdModelDecoder.canDecodeSource(String), it will return a list containing at least a single ILcdDataSource.
      Throws:
      IOException - If this model decoder returns false for ILcdModelDecoder.canDecodeSource(String) or if any exceptions caused by IO problems or invalid data occur.

    • canDecodeSource

      public boolean canDecodeSource(ILcdDataSource aDataSource)
      Description copied from interface: ILcdModelDecoder

      Checks whether this model decoder can decode the data source(s), identified by the passed ILcdDataSource.

      For performance reasons, we strongly recommend that this will only be a simple test. For example: check the instance class of aDataSource, or check the file extension if it is a TLcdDataSource.

      The default implementation of this method will check if the given ILcdDataSource is a TLcdDataSource. If not, this method returns false. Otherwise, it delegates the source to the ILcdModelDecoder.canDecodeSource(String) method.

      Specified by:
      canDecodeSource in interface ILcdModelDecoder
      Parameters:
      aDataSource - the ILcdModelSource to be verified.
      Returns:
      true if this decoder can likely decode the data specified by aDataSource, false otherwise.
      See Also:

    • decodeSource

      public ILcdModel decodeSource(ILcdDataSource aDataSource) throws IOException
      Description copied from interface: ILcdModelDecoder

      Creates a new model from the given data source.

      By default, this method:

      Specified by:
      decodeSource in interface ILcdModelDecoder
      Parameters:
      aDataSource - the ILcdDataSource to be decoded.
      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 decodeSource(ILcdDataSource aDataSource) throws IOException {
   try {
     // Perform decoding ...
   } catch (RuntimeException e) {
     throw new IOException(e);
   }
 }
      See Also:

    • addStatusListener

      public void addStatusListener(ILcdStatusListener aListener)
      Description copied from interface: ILcdStatusSource

      Registers the given listener so it will receive status events from this source.

      In case you need to register a listener which keeps a reference to an object with a shorter life-time than this status source, you can use a ALcdWeakStatusListener instance as status listener.

      Specified by:
      addStatusListener in interface ILcdStatusSource
      Parameters:
      aListener - The listener to be notified when the status has changed.

    • removeStatusListener

      public void removeStatusListener(ILcdStatusListener aListener)
      Description copied from interface: ILcdStatusSource
      Removes the specified listener so it is no longer notified.
      Specified by:
      removeStatusListener in interface ILcdStatusSource
      Parameters:
      aListener - The listener to remove.