Using the TLcdS57UnifiedModelDecoder

This decoder can deal with both individual cells as catalogue files.

Decoding S-57 data

S-57 data comes as individual cells or as catalogues. The TLcdS57UnifiedModelDecoder is an implementation of ILcdModelDecoder for the decoding of cells as well as catalogues. It can take any S-57 file as input and decode it to an ILcdModel containing S-57 domain objects.

Program: Decoding an S-57 file
ILcdModelDecoder modelDecoder = new TLcdS57UnifiedModelDecoder();
ILcdModel model = modelDecoder.decode("Data/Ecdis/Unencrypted/US5WA51M/US5WA51M.000");

The structure of the returned model depends on whether a cell or a catalogue file was decoded. This structure is described in detail in The S-57 domain model guide.

The TLcdS57UnifiedModelDecoder can decode ENC data, IENC data and AML data. Depending on the input file, it will automatically choose the correct product.

Handling updates

Handling cell update files

The S-57 format foresees a mechanism for the distribution of cell updates. It defines that whenever something has changed to a cell, only the cell changes are distributed, rather than a complete cell with changes included. Original new cell files are stored in files with extension .000. The changes to these cells are stored in update files with file extension .001 for the first update, .002 for the second update, and so on. When a cell is read, the updates of the .001 update file need to be applied first, followed by the changes of the .002 update file, and so on, to obtain an up-to-date version of the cell.

The TLcdS57UnifiedModelDecoder has built-in support for update files. When the decoder decodes a cell, it automatically looks for update files with extensions .001, .002, and so on, in the same directory. The decoder applies those updates directly in the correct order to the original cell file. Updates are applied in a transparent way: once the cell has been decoded into an ILcdModel, the ILcdModel will look as if the cell data were provided in a single, up-to-date cell file.

Working with catalogue updates

Catalogues can also be used to distribute cell updates. After data provider have published the initial version of a catalogue with .000 cell files, they may publish update catalogues that contain update files with extensions .001, .002, and so on, for the cells in the base catalogue, and additional new cells.

Update catalogues cannot be read directly, as they do not contain a reference to the base data. To read a catalogue as well as its updates, put all the catalogues in one directory, and pass this directory to TLcdS57UnifiedModelDecoder.decode(). The decoder will automatically scan the directory, collect all catalogues and apply all cell updates in the correct sequence.

TLcdS57UnifiedModelDecoder supports the direct decoding of directories, but if you need a file handle, you can place a dummy file called 'multicatalog.031' in a common parent directory. TLcdS57UnifiedModelDecoder.canDecode() returns true for these files. You can use this mechanism to merge catalogues of different data providers into a single virtual catalogue. After decoding, the cells will be accessible and visualized as if they were part of one single catalogue.

Tuning the decoding process by using specialized cell and catalogue model decoders

You only need to use the TLcdS57ModelDecoder or the TLcdS57CatalogueModelDecoder if you want to tune the decoding process. If you just want to visualize all the S-57 data, it is recommended to use the TLcdS57UnifiedModelDecoder as shown in Decoding S-57 data.

Specialized cell and catalogue model decoders

As illustrated in Decoding S-57 data you can use the TLcdS57UnifiedModelDecoder to decode S-57 data. However, if you want to have more fine-grained control of the decoding process, you might need to use the TLcdS57ModelDecoder or the TLcdS57CatalogueModelDecoder.

The first decoder can be used to decode individual cell files while the latter can handle catalogue files. Both decoder instances offer various methods to tune the decoding process.

The remainder of this guide illustrates the use of those decoders.

Decoding individual S-57 files

TLcdS57ModelDecoder is an implementation of ILcdModelDecoder for decoding S-57 data. A TLcdS57ModelDecoder can take any S-57 file as input and decode it to an ILcdModel containing S-57 domain objects.

The S-57 model decoder implementation is product-independent. It can decode ENC data, IENC data, AML data or other S-57-based products. Each decoder instance requires product-specific information however, to be able to decode data from a specific product. You can configure an instance for only one S-57 product.

For the ENC, IENC and AML products, you can create a preconfigured model decoder automatically, using TLcdS57ProductConfiguration.createModelDecoder().

Once you have configured the model decoder with the correct product information, you can decode S-57 files using the decode method with an S-57 file as argument:

Program: Decoding an S-57 file
TLcdS57ProductConfiguration s57Configuration = TLcdS57ProductConfiguration.getInstance(ELcdS57ProductType.ENC);
TLcdS57ModelDecoder modelDecoder = s57Configuration.createModelDecoder();
ILcdModel model = modelDecoder.decode("Data/Ecdis/Unencrypted/US5WA51M/US5WA51M.000");

The returned model is an ILcd2DBoundsIndexedModel containing S-57 domain objects. See The S-57 domain model for more details on the S-57 domain model structure.

TLcdS57ProductConfiguration is the central factory for creating and retrieving all S-57 components, as well as information of the product the factory was created for (ENC, IENC or AML). The product configuration instance loads some resources during initialization, so you should reuse it whenever possible, to keep memory overhead minimal.

Decoding S-57 catalogues

S-57 catalogues act as a spatial index of all the cells they contain. They allow for an efficient lookup of the ENC cells that contain data for a given region of interest. The TLcdS57CatalogueModelDecoder allows you to decode catalogues with all their ENC cell data into a single model.

The catalogue model decoder implementation is product-independent; it can decode ENC data, IENC data, AML data or other S-57 based products. The decoder delegates the actual cell decoding to a TLcdS57ModelDecoder, which requires configuration for a specific S-57 product.

For the ENC, IENC and AML products, you can create a catalogue model decoder with preconfigured cell model decoder automatically, using TLcdS57ProductConfiguration.createCatalogueModelDecoder().

Once you have set up the model decoder, you can decode S-57 catalogues by calling the decode(String) method with an S-57 catalogue file:

Program: Decoding an S-57 catalogue
TLcdS57ProductConfiguration s57Configuration = TLcdS57ProductConfiguration.getInstance(ELcdS57ProductType.ENC);
TLcdS57CatalogueModelDecoder modelDecoder = s57Configuration.createCatalogueModelDecoder();
ILcdModel model = modelDecoder.decode("CATALOG.031");

The structure of catalogue models is described in more detail in The S-57 domain model guide.

Catalogues can be very large, and it may not always be possible to load all data in memory at once. Therefore, the catalogue model decoder offers multiple loading policies. The Improving decoding and visualization performance guide describes the usage of the different loading policies in more detail.

Handling updates

Update files are handled in the same way as they are handled by TLcdS57UnifiedModelDecoder. The update process is described in Handling updates.