Package com.luciad.format.s57

Class TLcdS57ModelDecoder

java.lang.Object
com.luciad.format.s57.TLcdS57ModelDecoder
All Implemented Interfaces:
ILcdMetadataDecoder, ILcdInputStreamFactoryCapable, ILcdModelDecoder, ILcdCloneable, Cloneable
Direct Known Subclasses:
TLcdS63ModelDecoder
public class TLcdS57ModelDecoder extends Object implements ILcdModelDecoder, ILcdMetadataDecoder, ILcdInputStreamFactoryCapable, ILcdCloneable
This model decoder decodes ECDIS S-57 data into ILcdModel objects.

Input files

File Required Entry point Description
*.000 x x The .000 file is the base file for an ENC cell, and should always be present.
*.001, *.002, ... Additional .001, .002, ... update files can be provided, but are not mandatory. The model decoder will start with decoding the .000 base file and continue reading the update files in sequential order, until the update chain is broken (for example, a .002 file will only be read if the preceding .000 and .001 files are present). Update files should be present in the same directory as the base file.

Supported file transfer protocols

  • This model decoder supports all transfer protocols that are supported by the inputStreamFactory of this decoder.

Model structure

  • This model decoder creates a model per ENC cell (.000 file) that is decoded. Updates (.001, .002, ... files) are read and applied to the model automatically. There is no additional hierarchy in the models.
  • All models returned by this model decoder implement ILcd2DBoundsIndexedModel.

Model descriptor

Model elements

  • All model elements implement ILcdS57Object, which is an extension of the ILcdShape interface.
  • Additionally, all model elements also implement ILcdDataObject. As each S-57 object class is mapped onto one datatype, a single model may contain data objects with different data types. Objects with the same object class will have the same datatype and thus properties.
  • All model elements also implement ILcdFeatured. Note that ILcdDataObject is the preferred way of accessing the contents of an object.
  • Depending on the geometric primitive an object represents, the object will be one of the following types:
    ECDIS geometric primitive LuciadLightspeed class LuciadLightspeed geometric primitive interface
    Point TLcdS57Point ILcdPoint
    Line TLcdS57Line ILcdPolyline
    Area TLcdS57Area ILcdComplexPolygon

Sample code


 ILcdModelDecoder decoder = new TLcdS57ModelDecoder();
 ILcdModel model = decoder.decode("US5WA51M.000");

Performance tips

  • The meta object class Coverage (M_COVR, code 302) contains polygon outlines of ENC cells. In case the outline of a cell is not rectangular and a catalogue is used, these Coverage objects will be used by the S-52 visualization package to optimize the rendering performance. If an object class filter is set on this model decoder, excluding the Coverage object class could result in a small performance loss.
  • By default, all object classes are decoded. You can restrict the decoding to the classes you are interested in using the following methods: Restricting the object classes to be decoded will improve decoding performance and reduce memory usage. Take into account that excluding the Coverage object class could result in a performance loss (see previous note). If the system should be fully compliant to the IHO standards, no object classes should be excluded.

Thread safety

  • This model decoder can be used in a multi-threaded environment.
  • Read access to decoded models is thread-safe.

Supported versions and specifications

  • This model decoder supports all ECDIS data, encoded according to the IHO (International Hydrographic Organization) publication S-57 standard ("IHO Transfer Standard for Digital Hydrographic Data, Special Publication No. 57"). This includes InlandECDIS (2.0 to 2.4) and AML data.
  • ECDIS catalogues (recognizable by their suffix .031) can be decoded via the TLcdS57CatalogueModelDecoder.
  • Data, encrypted using the S-63 encryption protocol, can be decoded via the TLcdS63ModelDecoder that is provided in the S-63 component.

Known limitations

  • Only the binary implementation of S-57 is supported (the ENC specification only allows the binary implementation for storage of ENC data).
  • Not all data set descriptive records are taken into account: e.g. units are not decoded, only WGS 1984, WGS 1972 and European 1950 are supported (see S-57 specification, paragraph 1.2.2, 3 and 7.3).
  • Decoding of data dictionary records: not supported. The IHO Object Catalogue is used exclusively (see S-57 specification, paragraph 1.2.4 and 7.5)
  • Faces are not decoded. Faces are only used when the spatial data are encoded using the full topology model; most of the datasets available today are not yet using this model (paragraph 2.2.1 of the S-57 specification gives a detailed overview of the different vector models that are available).
  • Only spatial object classes are stored in the model.
  • The following spatial record fields are not decoded: EL2D, CT2D (see S-57 specification, paragraph 5.1.4.4 and 7.7.1).

See Also:

  • Field Details

  • Constructor Details

  • Method Details

    • setInputStreamFactory

      public void setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory)
      Sets the factory that will create input streams from which models can be decoded.
      Specified by:
      setInputStreamFactory in interface ILcdInputStreamFactoryCapable
      Parameters:
      aInputStreamFactory - the factory that creates an input stream based on a source name.

    • getInputStreamFactory

      public ILcdInputStreamFactory getInputStreamFactory()
      Description copied from interface: ILcdInputStreamFactoryCapable
      Returns the input stream factory that is used.
      Specified by:
      getInputStreamFactory in interface ILcdInputStreamFactoryCapable
      Returns:
      the input stream factory that is used.

    • resetObjectClassSelection

      public void resetObjectClassSelection()
      Resets the list of object classes that is included into decoded models. All object classes will now be included in the models when decoding S-57 files.
      See Also:

    • setObjectClassSelection

      public void setObjectClassSelection(int[] aObjectClasses)
      Sets the list of object classes that is included into decoded models. By default, all object classes are decoded. Excluding the Coverage meta data object class could result in a small rendering performance loss (See 'Performance tips' in the class documentation).
      Parameters:
      aObjectClasses - the object classes to be included in the decoded models. They can be listed in any order, and duplicate entries are allowed.
      See Also:

    • resetExcludedObjectClasses

      public void resetExcludedObjectClasses()
      Resets the list of object classes that is excluded from decoded models. No object classes will now be excluded from the models when decoding S-57 files.
      See Also:

    • setExcludedObjectClasses

      public void setExcludedObjectClasses(int[] aExcludedObjectClasses)
      Sets the list of object classes that is excluded from decoded models. By default, no object classes are excluded. This list has precedence over the list of classes that is included, if specified. Excluding the Coverage meta data object class could result in a small rendering performance loss (See 'Performance tips' in the class documentation).
      Parameters:
      aExcludedObjectClasses - the object classes to be excluded from the decoded models. They can be listed in any order, and duplicate entries are allowed.
      See Also:

    • setObjectClassMap

      public void setObjectClassMap(TLcdS57ObjectClassMap aObjectClassMap)
      Sets the object class map to be used by this model decoder. The object class map is used for retrieving the definitions of object classes and initializing the decoded S-57 objects with their correct datatype.
      Parameters:
      aObjectClassMap - the object class map to be used by this model decoder.

    • getObjectClassMap

      public TLcdS57ObjectClassMap getObjectClassMap()
      Returns the object class map that is used by this model decoder.
      Returns:
      the object class map that is used by this model decoder.

    • setAttributeClassMap

      public void setAttributeClassMap(TLcdS57AttributeClassMap aAttributeClassMap)
      Sets the attribute class map to be used by this model decoder. The attribute class map is used for retrieving the definitions of attributes and initializing the decoded S-57 objects with their correct datatype.
      Parameters:
      aAttributeClassMap - the attribute class map to be used by this model decoder.

    • getAttributeClassMap

      public TLcdS57AttributeClassMap getAttributeClassMap()
      Returns the attribute class map that is used by this model decoder.
      Returns:
      the attribute class map that is used by this model decoder.

    • isPreprocess

      public boolean isPreprocess()
      Returns whether decoded models are preprocessed by the decoder.
      Returns:
      whether decoded models are preprocessed by the decoder.
      See Also:

    • setPreprocess

      public void setPreprocess(boolean aPreprocess)
      Sets whether to preprocess the decoded model using the TLcdS57Preprocessor at the end of the decoding process. Preprocessing may be costly, but is required for correct, S-52 compliant visualization.

      The default value is true.
      Parameters:
      aPreprocess - boolean indicating whether to preprocess the decoded model using the TLcdS57Preprocessor.
      See Also:

    • 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)
      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
      Description copied from interface: ILcdMetadataDecoder
      Decodes the metadata from a given source name as an ISO-19115 metadata object.

      Note that even if ILcdMetadataDecoder.canDecodeMetadata(String) returns true, this method may yet not be able to decode the given source name. While returning null is allowed when this decoder couldn't decode the given source name, implementors are advised to throw an error instead.

      Specified by:
      decodeMetadata in interface ILcdMetadataDecoder
      Parameters:
      aSourceName - the source name to decode metadata from
      Returns:
      a metadata object
      Throws:
      IOException - if the metadata cannot be decoded for some reason
      See Also:

    • clone

      public TLcdS57ModelDecoder clone()
      Description copied from interface: ILcdCloneable

      Makes Object.clone() public.

      When for example extending from java.lang.Object, it can be implemented like this: 
      
 public Object clone() {
   try {
     return super.clone();
   } catch ( CloneNotSupportedException e ) {
     // Cannot happen: extends from Object and implements Cloneable (see also Object.clone)
     throw new RuntimeException( e );
   }
 }
      Specified by:
      clone in interface ILcdCloneable
      Overrides:
      clone in class Object
      See Also: