TLcdGeoJsonModelDecoder (LuciadLightspeed API documentation)

java.lang.Object
- com.luciad.format.geojson.TLcdGeoJsonModelDecoder

All Implemented Interfaces:

ILcdInputStreamFactoryCapable, ILcdModelDecoder
```
@LcdService(service=ILcdModelDecoder.class,
            priority=20000)
public class TLcdGeoJsonModelDecoder
extends Object
implements ILcdModelDecoder, ILcdInputStreamFactoryCapable
```
Decodes a GeoJson FeatureCollection to a Luciad ILcdModel.
Input files

The decoder only accepts source-paths ending with the extension .json, .geojson, or .js.

Format at-a-glance
GeoJson is a text format to represent geospatial vector data.
The input file must contain a single FeatureCollection. See the geojson specification for more details.

A FeatureCollection must at least contain 2 members:
- type: with a value equal to "FeatureCollection"
- features: an array containing zero or more domain objects. In turn, each Feature must at least have:
  - type: with a value equal to "Feature"
  - geometry: a GeoJson geometry
  - properties: properties (as key-value pairs) of the feature
  - id (optional): a unique identifier
A valid GeoJson FeatureCollection containing a single point feature.
```
  {
    type: "FeatureCollection",
    features: [
     {
       type: "Feature",
       geometry: {
        type: "Point",
        coordinates: [4.668864,50.864871],
       },
       properties: {
          poi: "Luciad NV HQ"
       }
     }
    ]
  }
  
```
Supported file transfer protocols
This model decoder supports all transfer protocols that are supported by the input stream factory of this decoder.
Model structure
- This model decoder creates a model per GeoJson file.
- All models returned by this model decoder implement ILcd2DBoundsIndexedModel.
Model descriptor
The model descriptor of this model is a TLcdGeoJsonModelDescriptor.
Model elements
Each feature of the feature collection is decoded to a domain object. Each domain object implements ILcdShapeList and ILcdDataObject.
Geometries
The decoder supports all 7 GeoJson geometries: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, GeometryCollection. These geometries can be consumed through existing Luciad shape interfaces.
- Point: decoded as a ILcdShapeList containing a single ILcdPoint
- LineString: decoded as a ILcdShapeList containing a single ILcdPolyline
- Polygon: decoded as a ILcdShapeList
  - containing a single ILcdPolygon when the polygon is defined by a single outline
  - containing a single ILcdComplexPolygon when the polygon is defined by an outline and one or more interior rings.
- MultiPoint: decoded as a ILcdShapeList containing a single ILcdPolyPoint
- MultiLineString: decoded as a ILcdShapeList containing multiple ILcdPolyline
- MultiPolygon: decoded as a ILcdShapeList containing a combination of
  - ILcdPolygon when a polygon consist only of a single outline
  - ILcdComplexPolygon when a polygon consist only of a single outline and one or more interiour rings
- GeometryCollection: decoded as a ILcdShapeList containing a combination of zero or more ILcdPoint, ILcdPolypoint, ILcdPolyLine, ILcdPolygon, ILcdComplexPolygon.
Properties summary

The properties of the GeoJson feature can be accessed through the methods of the ILcdDataObject interface.

It is typically the case that all features in a GeoJson FeatureCollection share the same properties. However, this is not required.

The decoder will construct a single ILcdDataType which is shared by all Features in the collection.

Below are some typical examples.
Example 1: the ILcdDataType of the features in this collection has 2 properties: "poi" and "country".
```
 {
    type: "FeatureCollection",
    features: [
     {
       type: "Feature",
       geometry: {
        type: "Point",
        coordinates: [4.668864,50.864871]
       },
       properties: {
          poi: "Luciad NV HQ",
          country: "Belgium"
       }
     },
     {
       type: "Feature",
       geometry: {
        type: "Point",
        coordinates: [-77.340020,38.946660],
       },
       properties: {
          poi: "Luciad Inc HQ",
          country: "United States of America"
       }
     }
    ]
  }
  
```
Example 2: the ILcdDataType of the features in this collection have 3 properties: "poi", "country" and "state". The value of the "state" property of the first feature is null.
```
 {
    type: "FeatureCollection",
    features: [
     {
       type: "Feature",
       geometry: {
        type: "Point",
        coordinates: [4.668864,50.864871],
        properties: {
          poi: "Luciad NV HQ",
          country: "Belgium"
        }
       }
     },
     {
       type: "Feature",
       geometry: {
        type: "Point",
        coordinates: [-77.340020,38.946660],
        properties: {
          poi: "Luciad Inc HQ",
          country: "United States of America",
          state: "VA"
        }
       }
     }
    ]
  }


  
```
id summary
When an id-property is present on a geojson-feature, it is added to the data-type and annotated with a PrimaryKey annotation. The name of this id-property is dynamically determined so it does not conflict with an existing property-name which is present on the properties object. Typically, this name is "uid", if there is not already a property named like that. To determine the property name of the id-property, you can do:
```
        String primaryKeyPropertyName = null;
        TLcdPrimaryKeyAnnotation annotation = aDataType.getAnnotation(TLcdPrimaryKeyAnnotation.class);
        if(annotation != null){
          primaryKeyPropertyName = annotation.getProperty().getName();
        }
 
```
Data Model Name

It is often useful to identify the model with an appropriate name. For example, you might have other components in your code that - depending on a given model - perform different actions.

You can configure the name of the data model and the name of the data type explicitly using
- setDataModelName
- setDataTypeName
When these are not set, default values based on the name of the model source will be used.

Property names

Property names must be a string.
```
   {
     "this is a string": "good property name",
     thisIsAString: "also a good property name",
     0: "bad property name. This json is illegal and cannot be decoded."
   }
 
```
Property type conversion

For details about the Json format, please visit json.org

A value in Json can only be one of these types: String, number, object (a collection of key-value pairs), array (a list of values), true, false, and null.

These types are mapped to a TLcdDataType (in the case of primitives) or a TLcdDataProperty.CollectionType (in the case of collections) in the following manner:
- String: TLcdCoreDataTypes.STRING_TYPE
- Number:
  - TLcdCoreDataTypes.INTEGER_TYPE: if the number has no decimal point.
  - TLcdCoreDataTypes.LONG_TYPE: if the number has no decimal point and does not fit in a 32 bit integer.
  - TLcdCoreDataTypes.DOUBLE_TYPE: if the number has a decimal point.
- true/false: TLcdCoreDataTypes.BOOLEAN_TYPE
- array: TLcdDataProperty.CollectionType.LIST.
- object: TLcdDataProperty.CollectionType.MAP.
Model reference
The decoder supports named spatial references, but not linked spatial references. Please refer to the geojson specification for details.

The decoder only supports references from the EPSG organization, as well as the standard OGC CRS:84 reference.

When a given spatial reference cannot be decoded, an error will be thrown.

When no spatial reference is present, the default WGS 84 geographic reference will be used.

Only spatial references are parsed which are present on the FeatureCollection. Nested spatial references are ignored.
Example 3: An example GeoJson file with a valid named spatial reference.
```
 {
    type: "FeatureCollection",
    "crs": {
      "type": "name",
      "properties": {
        "name": "urn:ogc:def:crs:OGC:1.3:CRS84"
      }
     },
    features: [
     {
       type: "Feature",
       geometry: {
        type: "Point",
        coordinates: [4.668864,50.864871],
        properties: {
          poi: "Luciad NV HQ",
          country: "Belgium"
        }
       }
     },
     {
       type: "Feature",
       geometry: {
        type: "Point",
        coordinates: [-77.340020,38.946660],
        properties: {
          poi: "Luciad Inc HQ",
          country: "United States of America",
          state: "VA"
        }
       }
     }
    ]
  }
  
```
Sample code
```
 ILcdModelDecoder decoder = new TLcdGeoJsonModelDecoder();
 ILcdModel model = decoder.decode("world.geojson");
 
```
Thread safety
- The decoded models are thread-safe for read access when taking a read lock.
Since:

2012.1

Constructor Summary

Constructors
Constructor and Description

TLcdGeoJsonModelDecoder()
Create a new model decoder for GeoJson sources.

Constructors
Constructor and Description
`TLcdGeoJsonModelDecoder()` Create a new model decoder for GeoJson sources.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`canDecodeSource(String aSourceName)` The method will return `true` only when aSourceName ends in .geojson, .json, or .js.
`ILcdModel`	`decode(String aSourceName)` Creates a new model from the source.
`static ILcdDataObject`	`decodeFeature(InputStream aGeoJsonFeatureInputStream, ILcdModelReference aModelReference, TLcdDataType aDataType)` Decodes a geojson string to a data object.
`String`	`getDataModelName()` Gets the data model name.
`TLcdDataType`	`getDataType()` Get the user provided data type.
`String`	`getDataTypeName()` Gets the data type name.
`ILcdModelReference`	`getDefaultModelReference()` Retrieve the default model reference.
`String`	`getDisplayName()` A short label for the format.
`ILcdInputStreamFactory`	`getInputStreamFactory()` Returns the input stream factory that is used.
`ILcdModelReferenceParser`	`getModelReferenceParser()` Get the reference parser that is used by this decoder.
`protected ILcdShape`	`parseCustomGeometry(String aJsonNode, ILcdModelReference aModelReference)` This method is used by the decoder to parse custom geometry that is normally not allowed in GeoJSON.
`static ILcdShape`	`parseGeometry(InputStream aInputStream, ILcdModelReference aModelReference)` Parses a single GeoJson geometry object to an `ILcdShape`.
`void`	`setDataModelName(String aDataModelName)` Sets the data model name.
`void`	`setDataTypeName(String aDataTypeName)` Sets the data type name used by the decoder.
`void`	`setDefaultModelReference(ILcdModelReference aModelReference)` Sets the default model reference.
`void`	`setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory)` Sets the input stream factory to be used.
`void`	`setModelElementType(TLcdDataType aDataType)` Sets a user provided data type.
`void`	`setModelReferenceParser(ILcdModelReferenceParser aModelReferenceParser)` Set the reference parser the decoder will use to parse a spatial reference.

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

Constructor Detail

TLcdGeoJsonModelDecoder

public TLcdGeoJsonModelDecoder()

Create a new model decoder for GeoJson sources.


 TLcdGeoJsonModelDecoder myGeoJsonModelDecoder = new TLcdGeoJsonModelDecoder();

Method Detail

setModelElementType
```
public void setModelElementType(TLcdDataType aDataType)
```
Sets a user provided data type. When decoding a model, the decoder will apply this data type to the elements in the model. When this is not set, the decoder will derive the data type automatically from the input GeoJson. It must be possible to map the values of the GeoJson features into the properties of this data type. Missing GeoJson values will be ignored. Note that this method and both setDataModelName and setDataTypeName are mutually exclusive. The data model name and type name of aDataType have priority over any names that were set with the setDataModelName or setDataTypeName methods.

Parameters:

aDataType - the data type to use when decoding. It may only contain properties of the primitive types INTEGER_TYPE, LONG_TYPE, FLOAT_TYPE, DOUBLE_TYPE, NUMBER_TYPE, STRING_TYPE, OBJECT_TYPE, STRING_TYPE, BOOLEAN_TYPE, STRING_TYPE, OBJECT_TYPE or of the collection types MAP and LIST.

Since:

2013.1

getDataType
```
public TLcdDataType getDataType()
```
Get the user provided data type. By default, this value is null.

Returns:

the user provided data type

getDisplayName
```
public String getDisplayName()
```
A short label for the format. For example, this is often used in open-file dialogs.

Specified by:

getDisplayName in interface ILcdModelDecoder

Returns:

geojson.org:GeoJSON

canDecodeSource
```
public boolean canDecodeSource(String aSourceName)
```
The method will return true only when aSourceName ends in .geojson, .json, or .js.

Specified by:

canDecodeSource in interface ILcdModelDecoder

Parameters:

aSourceName - the data source to be verified; typically a file name or a URL.

Returns:

boolean indicating whether the source can be decoded.

See Also:

ILcdModelDecoder.decode(String), ILcdModelDecoder.decodeModelMetadata(String)

decode
```
public ILcdModel decode(String aSourceName)
                 throws IOException
```
Creates a new model from the source. This model implements ILcdModel.

The source must contain a valid GeoJson FeatureCollection. For convenience, it will also support a single GeoJson Feature, a single GeoJson Geometry, or a an array of GeoJson features. To decode a single feature, note that you can also use the static decodeFeature method.

Specified by:

decode in interface ILcdModelDecoder

Parameters:

aSourceName - the data source to be decoded; typically a file name or a URL.

Returns:

the model

Throws:

IOException

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)

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.

getModelReferenceParser
```
public ILcdModelReferenceParser getModelReferenceParser()
```
Get the reference parser that is used by this decoder.

Returns:

The reference parser used by this decoder.

Since:

2016.1

setModelReferenceParser
```
public void setModelReferenceParser(ILcdModelReferenceParser aModelReferenceParser)
```
Set the reference parser the decoder will use to parse a spatial reference.

Parameters:

aModelReferenceParser - The reference parser for the decoder to use.

Since:

2016.1

setDefaultModelReference
```
public void setDefaultModelReference(ILcdModelReference aModelReference)
```
Sets the default model reference. This is a fallback reference that will be used when no reference is present in the input file. If no default model reference is set, EPSG:4326 will be used as default when the file only contains 2D coordinates, or EPSG:4979 if the file also contains Z-coordinates.

Parameters:

aModelReference - the model reference used as a default, or null if no custom default model reference should be set.

getDefaultModelReference
```
public ILcdModelReference getDefaultModelReference()
```
Retrieve the default model reference.

Returns:

the default model reference, or null if no custom default model reference is set.

setDataTypeName
```
public void setDataTypeName(String aDataTypeName)
```
Sets the data type name used by the decoder. The model-elements contained in the decoded model will have this name. Note that this name is not used if the user has set the data type explicitly with setModelElementType.

Parameters:

aDataTypeName - the data type name

getDataTypeName
```
public String getDataTypeName()
```
Gets the data type name.

Returns:

the data type name

setDataModelName
```
public void setDataModelName(String aDataModelName)
```
Sets the data model name. When decoding a source-file, this value will be used for the data model name of the model. The default value is null. If this value is null, the file-name will be used for the data model name. Note that this name is not used if the user has set the data type explicitly with setModelElementType.

Parameters:

aDataModelName - the data model name

getDataModelName
```
public String getDataModelName()
```
Gets the data model name.

Returns:

the data model name.

decodeFeature
```
public static ILcdDataObject decodeFeature(InputStream aGeoJsonFeatureInputStream,
                                           ILcdModelReference aModelReference,
                                           TLcdDataType aDataType)
                                    throws IOException
```
Decodes a geojson string to a data object. See also the TLcdGeoJsonModelEncoder.exportFeature(Object, java.io.OutputStream) static method for the reverse operation. Note: When using this method to decode a feature, parseCustomGeometry(String, ILcdModelReference) is not called.

Parameters:

aGeoJsonFeatureInputStream - the json feature. It must be a stream for a UTF-8 string.

aModelReference - the model reference of the feature. If this is null, the WGS86 geodetic reference is used.

aDataType - the data type of the feature.

Returns:

the data object.

Throws:

IOException - Thrown when the feature cannot be decoded. This is often caused by invalid GeoJson.

Since:

2013.1

parseGeometry

public static ILcdShape parseGeometry(InputStream aInputStream,
                                      ILcdModelReference aModelReference)
                               throws IOException

Parses a single GeoJson geometry object to an ILcdShape.

The following table shows which geometries are parsed to which shape types:

Geometry	Parsed to
`Point`	An `ILcdPoint`
`MultiPoint`	An `ILcdShapeList` containing zero or more `ILcdPoint` instances
`LineString`	An `ILcdPolyline`
`MultiLineString`	An `ILcdShapeList` containing zero or more `ILcdPolyline` instances
`Polygon`	An `ILcdPolygon` if the polygon consists of only one ring, or an `ILcdComplexPolygon` otherwise
`MultiPolygon`	An `ILcdShapeList` containing zero or more `ILcdPolygon` or `ILcdComplexPolygon` instances
`GeometryCollection`	An `ILcdShapeList` containing any combination of above-mentioned shapes.

Note: When using this method to decode a geometry, parseCustomGeometry(String, ILcdModelReference) is not called.

Parameters:: aInputStream - the GeoJson geometry object to parse.; aModelReference - the model reference in which the geometry is defined.
Returns:: the parsed geometry.
Throws:: IOException - If the parsing fails.
Since:: 2021.1

parseCustomGeometry
```
protected ILcdShape parseCustomGeometry(String aJsonNode,
                                        ILcdModelReference aModelReference)
                                 throws IOException
```
This method is used by the decoder to parse custom geometry that is normally not allowed in GeoJSON. To support custom shapes this method needs to be overwritten, the default implementation throws an IOException.

Parameters:

aJsonNode - the json node representing the custom geometry

aModelReference - the model reference

Returns:

the parsed shape, the default implementation throws an IOException.

Throws:

IOException

Since:

2016.1

LuciadLightspeedClass TLcdGeoJsonModelDecoder

Input files

Format at-a-glance

Supported file transfer protocols

Model structure

Model descriptor

Model elements

Geometries

Properties summary

id summary

Data Model Name

Property names

Property type conversion

Model reference

Sample code

Thread safety

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface com.luciad.model.ILcdModelDecoder

Constructor Detail

TLcdGeoJsonModelDecoder

Method Detail

setModelElementType

getDataType

getDisplayName

canDecodeSource

decode

setInputStreamFactory

getInputStreamFactory

getModelReferenceParser

setModelReferenceParser

setDefaultModelReference

getDefaultModelReference

setDataTypeName

getDataTypeName

setDataModelName

getDataModelName

decodeFeature

parseGeometry

parseCustomGeometry