GeoJsonCodec | LuciadRIA (2023.0.06)

A GeoJsonCodec is responsible for 2 things:

Encode Feature instances to a JavaScript object that adheres to the GeoJSON specification
Decode a GeoJSON JavaScript object into a set of LuciadRIA Feature objects containing LuciadRIA geometries and properties.

Since a 1-on-1 mapping from a GeoJSON geometry to a LuciadRIA shape does not exist, the codec decodes GeoJSON geometries to shapes as follows:
- Points, LineStrings, Polygons GeoJSON geometries are mapped to LuciadRIA Point, Polyline and Polygon or ComplexPolygon instances respectively. Note that a GeoJSON Polygon is decoded to a Polygon, if it only consists of a single ring.
- MultiPoints, MultiLineStrings, MultiPolygons are all mapped to a ShapeList, containing only LuciadRIA Point, Polyline and ComplexPolygon or Polygon instances.
- GeometryCollections are mapped to ShapeList instances.
The codec encodes the shape of the feature to GeoJSON geometries as follows:
- Point and Polyline instances are mapped to GeoJSON Points and LineStrings respectively.
- Polygon and ComplexPolygon instances are all mapped to GeoJSON Polygons.
- ShapeList is always mapped to a GeoJSON GeometryCollection when GeoJsonCodecConstructorOptions.encodeShapeListAsGeometryCollection is set to 'true'.
- Otherwise ShapeList is mapped based on its contents:
GeoJSON does not support any other shapes than Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, GeometryCollection. As such, it cannot support all shapes of LuciadRIA. For example, a Circle cannot be represented directly as a circle in GeoJSON. To deal with such shapes, a custom codec is required. The CreateEdit sample shows how you can create a custom codec for such shapes.

Spatial reference

The reference for shape decoding process is determined in the following way and order:

The reference passed to decode. Use it in case you want to override the reference for each decode request.
The reference passed to the constructor. Allows you to set the reference yourself, overriding what is in the data. If you still want to override for a particular decode() operation, you can still do it, because the step 1 allows it.
The reference specified in the data with the legacy crs field. This reference is used if you don't specify it in step 1 or 2.
The specification default WGS:84 reference is used.

Supported versions

LuciadRIA supports the full feature set of GeoJSON with the following limitations:

CRS reference annotations are not supported.

Type parameters

TFeature: Feature

Represents the type of Feature instances that are handled by the codec. Default type is Feature without restrictions on shape and properties.

Hierarchy

Codec<TFeature>
- GeoJsonCodec

Overview

Constructors

constructor

Methods

Constructors

constructor

(options?: GeoJsonCodecConstructorOptions): GeoJsonCodec

Creates a GeoJSON codec. By default, a GeoJSON Codec decodes 2D geometry which means the z coordinates of points (which usually contains height) is ignored. If the z coordinate must be encoded or decoded as well, pass true to the mode3D property in the options object.

Parameters
- Optional options: GeoJsonCodecConstructorOptions
  
  an object literal that contains configuration settings for the codec.
Returns GeoJsonCodec

Methods

decode

(options: CodecDecodeOptions): Cursor<TFeature>

Overrides Codec.decode

Decodes the server response, which is valid GeoJSON, to a Cursor of Feature instances. This method delegates to GeoJsonCodec.decodeGeometryObject.

A Store instance, used by a LuciadRIA feature layer, uses this method on each Store.query invocation, passing the options parameter containing the data to decode. If CodecDecodeOptions.reference option is present, the decoded features' shapes are encoded with this reference.

Parameters
- options: CodecDecodeOptions
  
  the decoding options
Returns Cursor<TFeature>

featureCursor a Cursor of Feature instances corresponding to the server response.

decodeGeometry

(geometry: string, reference: CoordinateReference): Shape

Decodes a GeoJSON geometry string to a Shape.

Parameters
- geometry: string
  
  The string representation of a shape. The codec assumes this string adheres to the GeoJSON specification.
- reference: CoordinateReference
  
  The spatial reference in which the geometry is defined.
Returns Shape

the corresponding LuciadRIA Shape.

decodeGeometryObject

(geometry: any, reference: CoordinateReference): Shape

Decodes a GeoJSON geometry object to a Shape.

Parameters
- geometry: any
  
  A GeoJSON geometry object, as a JSON object.
- reference: CoordinateReference
  
  The spatial reference in which the geometry is defined.
Returns Shape

the corresponding LuciadRIA Shape.

decodeObject

(object: any, options?: { reference?: CoordinateReference }): Cursor<TFeature>

Decodes an object, which is valid GeoJSON, to a Cursor of Feature instances. This method delegates to GeoJsonCodec.decodeGeometryObject.

Parameters
- object: any
  
  a GeoJSON object
- Optional options: { reference?: CoordinateReference }
  
  an object literal that contain the following optional properties:
  - Optional reference?: CoordinateReference
    
    The spatial reference in which the Feature instances are defined. If provided this reference supersedes the default reference of the GeoJSON data.
Returns Cursor<TFeature>

featureCursor A Cursor of Feature corresponding to the server response.

encode

(featureCursor: Cursor<TFeature>): { content: string; contentType: string }

Overrides Codec.encode

Encodes a Cursor of Feature instances into GeoJSON. This method delegates to GeoJsonCodec.encodeShape.

Parameters
- featureCursor: Cursor<TFeature>
  
  a Cursor of LuciadRIA Feature which must be encoded to the arbitrary representation
Returns { content: string; contentType: string }

An object containing two properties:
- content: the encoded content as a string. This is valid GeoJSON
- contentType: the mime type as a string. It equals "application/json"
- content: string
  
  The encoded content as a string
- contentType: string
  
  The mime type describing how the content was encoded as a string

encodeShape

(shape: Shape): any | null

Encodes a LuciadRIA Shape to a valid GeoJSON geometry.

Parameters
- shape: Shape
  
  A Shape to be encoded to GeoJSON.
Returns any | null

the GeoJSON representation of a shape (as an object, not as a string)

Legend

Module
Object literal
Variable
Function
Function with type parameter
Index signature
Type alias
Type alias with type parameter

Enumeration
Enumeration member
Property
Method

Interface
Interface with type parameter
Constructor
Property
Method
Index signature

Class
Class with type parameter
Constructor
Property
Method
Accessor
Index signature

Inherited constructor
Inherited property
Inherited method
Inherited accessor

Protected property
Protected method
Protected accessor

Private property
Private method
Private accessor

Static property
Static method

Spatial reference

Supported versions

Type parameters

TFeature: Feature

Hierarchy

Overview

Constructors

Methods

Constructors

constructor

Parameters

Optional options: GeoJsonCodecConstructorOptions

Returns GeoJsonCodec

Methods

decode

Parameters

options: CodecDecodeOptions

Returns Cursor<TFeature>

decodeGeometry

Parameters

geometry: string

reference: CoordinateReference

Returns Shape

decodeGeometryObject

Parameters

geometry: any

reference: CoordinateReference

Returns Shape

decodeObject

Parameters

object: any

Optional options: { reference?: CoordinateReference }

Optional reference?: CoordinateReference

Returns Cursor<TFeature>

encode

Parameters

featureCursor: Cursor<TFeature>

Returns { content: string; contentType: string }

content: string

contentType: string

encodeShape

Parameters

shape: Shape

Returns any | null

Legend