TLcdOSGBModelDecoder (LuciadLightspeed API documentation)

java.lang.Object
- com.luciad.format.tiled3d.osgb.TLcdOSGBModelDecoder

All Implemented Interfaces:: ILcdInputStreamFactoryCapable, ILcdModelDecoder

@LcdService(service=ILcdModelDecoder.class,
            priority=20000)
public final class TLcdOSGBModelDecoder
extends Object
implements ILcdModelDecoder, ILcdInputStreamFactoryCapable

This model decoder decodes OpenSceneGraph datasets which are stored in the binary file format (*.osgb files).

Input files

There are 3 different ways to open an OSGB dataset. Each of those is discussed in more detail further down.

File	Required	Entry point	Description
*.lcd_osgb	x	x	A Luciad specific file which defines the origin mapping and the list of root nodes files. See the next section for more info about this file.

File	Required	Entry point	Description
metadata.xml	x	x	An XML file generated by Bentley ContextCapture which defines the model reference and origin of the data set. This file does not define the paths to the root files of the data set. A heuristic will be used to derive those roots, as explained below.

File	Required	Entry point	Description
*.desc	x	x	A text file generated by Airbus Street Factory which defines the root files of the data set.
origin.txt			A text file generated by Airbus Street Factory which defines the origin of the data set. When this file is not available, the decoder will assume the origin is located at (0, 0, 0).

Model reference

When the metadata file(s) do not contain 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.

The `*.lcd_osgb` file

To decode an OSGB dataset, the model decoder requires knowledge of:

The reference in which the data is expressed: this is covered by a separate model reference file which is decoded by the ILcdModelReferenceDecoder (see previous section).
The location of the data: the origin of the coordinate system used in the OSGB data is located at a certain position on the map.
The list of root OSGB files: an OSGB dataset is typically split up in multiple OSGB files. The model decoder must know which OSGB files define the tiles with the least detailed data.

Both the location and the list of root files must be defined in a JSON file with extension .lcd_osgb, which is the entry point for the model decoder. This file contains an "origin" property and a "nodeList":

   {
      "origin": [
                   663550.0,
                   7457852.0,
                   0.0
                ],
      "nodeList": [
                    "Data/Tile_211200012210231200/Tile_211200012210231200.osgb",
                    "Data/Tile_211200012210231203/Tile_211200012210231203.osgb"
                  ]
   }

The `metadata.xml` file

To decode an OSGB dataset, the model decoder requires knowledge of:

The reference in which the data is expressed.
The location of the data: the origin of the coordinate system used in the OSGB data is located at a certain position on the map.
The list of root OSGB files: an OSGB dataset is typically split up in multiple OSGB files. The model decoder must know which OSGB files define the tiles with the least detailed data.

The metadata.xml file generated by Bentley ContextCapture defines the model reference and origin of the data:


   <?xml version="1.0" encoding="utf-8"?>
   <ModelMetadata version="1">
     <!--Spatial Reference System-->
     <SRS>EPSG:32723</SRS>
     <!--Origin in Spatial Reference System-->
     <SRSOrigin>663550,7457852,0</SRSOrigin>
   </ModelMetadata>

To retrieve the root files, the model decoder uses a heuristic. It looks for a Data folder next to the metadata.xml. It assumes the Data folder contains a list of subdirectories, and each of those subdirectories contains a single root file with the same name as that subdirectory but with extension .osgb. This is illustrated below:


   metadata.xml
   Data
     |_ Tile_211200012201331221
     |  |_ Tile_211200012201331221_L13_0.osgb
     |  |_ Tile_211200012201331221_L14_00.osgb
     |  |_ ...
     |  |_ Tile_211200012201331221.osgb <- assumed root when present
     |_ Tile_211200012210201213
     |  |_ Tile_211200012210201213_L13_0.osgb
     |  |_ Tile_211200012210201213_L14_00.osgb
     |  |_ ...
     |  |_ Tile_211200012210201213.osgb <- assumed root when present
     |_ ...

The `*.desc` and `origin.txt` files

To decode an OSGB dataset, the model decoder requires knowledge of:

The reference in which the data is expressed: this is covered by a separate model reference file which is decoded by the ILcdModelReferenceDecoder.
The location of the data: the origin of the coordinate system used in the OSGB data is located at a certain position on the map. This is expressed in the optional origin.txt file. When not available, the origin is assumed to be at (0, 0, 0).
The list of root OSGB files: an OSGB dataset is typically split up in multiple OSGB files. The model decoder must know which OSGB files define the tiles with the least detailed data. The root files are listed in the *.desc file.

The *.desc file generated by Airbus Street Factory defines the list of root tiles by specifying their relative paths (relative to the *.desc file).

   Tile_004_009\Tile_004_009.osgb
   Tile_004_010\Tile_004_010.osgb
   Tile_004_011\Tile_004_011.osgb
   Tile_005_004\Tile_005_004.osgb
   Tile_005_005\Tile_005_005.osgb
   Tile_005_006\Tile_005_006.osgb
   Tile_005_007\Tile_005_007.osgb
   Tile_005_008\Tile_005_008.osgb
   Tile_005_009\Tile_005_009.osgb
   Tile_005_010\Tile_005_010.osgb

The origin.txt file contains the local origin of the dataset. This file consists of the x, y and z values as text separated by a space. An example file would be:

   663550 7457852 0

Supported files

This model decoder only supports certain versions of OSGB, and only a subset of properties. A best-effort was done to support the datasets created by Bentley ContextCapture (popular tool for aerial photogrammetry, version 91), Airbus StreetFactory (popular tool for terrestrial photogrammetry, version 80), Altizure (version 97) and the datasets of version 100.

Supported file transfer protocols

This model decoder supports all transfer protocols that are supported by the InputStreamFactory of this decoder when working with an .lcd_osgb file or a .desc file. When using a metadata.xml file as entry point, the model decoder needs to find the root files which is done by finding files on the file system directly.

Model structure

This model decoder creates a model per *.lcd_osgb file.
All models returned by this model decoder implement ILcd2DBoundsIndexedModel.

Model descriptor

The type name of the model descriptor is "OSGB".

Model elements

The model elements are bounded instances, of which the bounds can be retrieved using the ALcdBounds.fromDomainObject(Object) method.

Thread safety

The decoding of models is not thread-safe.
The decoded models are thread-safe for read access.

Sample code

Visualizing OSGB data sets on a Lightspeed view is done by using this model decoder and the TLsp3DTileLayerBuilder. Currently it is not possible to visualize the data on a GXY view.


   String source = "my_osgb_dataset.lcd_osgb";
   TLcdOSGBModelDecoder modelDecoder = new TLcdOSGBModelDecoder();
   if(modelDecoder.canDecodeSource(source)){
     ILcdModel model = modelDecoder.decode(source);
     ILspLayer layer = TLsp3DTileLayerBuilder.newBuilder().model(model).build();
   }

Since:: 2018.0

Field Summary

Fields
Modifier and Type Field and Description

static String TYPE_NAME
The type name for the decoded models.

Fields
Modifier and Type	Field and Description
`static String`	`TYPE_NAME` The type name for the decoded models.

Constructor Summary

Constructors
Constructor and Description

TLcdOSGBModelDecoder()

Constructors
Constructor and Description
`TLcdOSGBModelDecoder()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`canDecodeSource(String aSourceName)` Checks whether this model decoder can decode the specified data source.
`ILcdModel`	`decode(String aSourceName)` Creates a new model from the given data source.
`ILcdModelReference`	`getDefaultModelReference()` Returns the model reference to be used for models when the model reference decoder is set to null.
`String`	`getDisplayName()` Returns a short, displayable name for the format that is decoded by this `ILcdModelDecoder`.
`ILcdInputStreamFactory`	`getInputStreamFactory()` Returns the input stream factory that is used.
`ILcdModelReferenceDecoder`	`getModelReferenceDecoder()` Returns the decoder used to produce model references.
`void`	`setDefaultModelReference(ILcdModelReference aDefaultModelReference)` Sets the model reference to be used for models when the model reference decoder is set to null.
`void`	`setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory)` Sets the input stream factory to be used.
`void`	`setModelReferenceDecoder(ILcdModelReferenceDecoder aModelReferenceDecoder)` Sets the decoder to use to produce model references for models created with this decoder.

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

- Field Detail
  - TYPE_NAME
```
public static final String TYPE_NAME
```
    The type name for the decoded models.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - TLcdOSGBModelDecoder
```
public TLcdOSGBModelDecoder()
```
- Method Detail
  - 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:
    
    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)
  - setDefaultModelReference
```
public void setDefaultModelReference(ILcdModelReference aDefaultModelReference)
```
    Sets the model reference to be used for models when the model reference decoder is set to null.
    
    Parameters:
    
    aDefaultModelReference - the model reference to be used for models when the model reference decoder is set to null.
    
    See Also:
    
    getDefaultModelReference()
  - getDefaultModelReference
```
public ILcdModelReference getDefaultModelReference()
```
    Returns the model reference to be used for models when the model reference decoder is set to null.
    
    Returns:
    
    the model reference to be used for models when the model reference decoder is set to null.
    
    See Also:
    
    setDefaultModelReference(com.luciad.model.ILcdModelReference)
  - getModelReferenceDecoder
```
public ILcdModelReferenceDecoder getModelReferenceDecoder()
```
    Returns the decoder used to produce model references.
    
    Returns:
    
    the decoder to produce model references.
    
    See Also:
    
    setModelReferenceDecoder(com.luciad.model.ILcdModelReferenceDecoder), setDefaultModelReference(com.luciad.model.ILcdModelReference)
  - setModelReferenceDecoder
```
public void setModelReferenceDecoder(ILcdModelReferenceDecoder aModelReferenceDecoder)
```
    Sets the decoder to use to produce model references for models created with this decoder.
    
    Parameters:
    
    aModelReferenceDecoder - the decoder to use to produce model references for models created with this decoder.
    
    See Also:
    
    getModelReferenceDecoder(), setDefaultModelReference(com.luciad.model.ILcdModelReference)
  - setInputStreamFactory
```
public void setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory)
```
    Description copied from interface: ILcdInputStreamFactoryCapable
    
    Sets the input stream factory to be used.
    
    Specified by:
    
    setInputStreamFactory in interface ILcdInputStreamFactoryCapable
    
    Parameters:
    
    aInputStreamFactory - the input stream factory to be used.
  - 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.

LuciadLightspeedClass TLcdOSGBModelDecoder

Input files

Model reference

The *.lcd_osgb file

The metadata.xml file

The *.desc and origin.txt files

Supported files

Supported file transfer protocols

Model structure

Model descriptor

Model elements

Thread safety

Sample code

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface com.luciad.model.ILcdModelDecoder

Field Detail

TYPE_NAME

Constructor Detail

TLcdOSGBModelDecoder

Method Detail

getDisplayName

canDecodeSource

decode

setDefaultModelReference

getDefaultModelReference

getModelReferenceDecoder

setModelReferenceDecoder

setInputStreamFactory

getInputStreamFactory

The `*.lcd_osgb` file

The `metadata.xml` file

The `*.desc` and `origin.txt` files