Class KMLCodec

Decodes KML and KMZ files (strings, ArrayBuffers, and Blobs) into a KMLPlacemarkFeatures, KMLGroundOverlayFeatures. Other features are emitted from events:

KMLNetworkLinkFeatures are emitted using the "KMLNetworkLink" event. Network Links are separate KML Files that should be decoded separately in a new LuciadRIA model and layer (e.g. KMLModel and KMLLayer.
KMLGroundOverlayFeatures are emitted using the "KMLGroundOverlay" event. Ground Overlays should be handled in a layer, cf createGroundOverlayLayer.
KMLFolderContainers are emitted using the "KMLTree" event. These features are used to represent the structure of the KML file, complete with the traversed KMLScreenOverlayFeatures and KMLGroundOverlayFeatures. These "container" features are not rendered on the map, and are used to facilitate the creation of a GUI.

A KMLCodec is typically used by a Store to decode strings into LuciadRIA KMLFeatures. Consult the class documentation of the Store class for more information.

Styles are resolved according to the KML specification, as long as they are defined in the original KML file. Externally referenced styles are not resolved.

Supported versions

The current version of LuciadRIA supports the KML 2.3 standard.

Limitations

This KML Codec will only decode the following features:
- Placemarks and internal styles
- Shared Styles
- NetworkLinks (references to other KML files)
- KMZ files that consist of a single zipped KML-file and image resources. KML files that reference packaged resources are not currently supported.
- GroundOverlays
- ScreenOverlays
Cross-Origin requests that do not contain an "Access-Control-Allow-Origin" header in the response can not be loaded.
Camera positions are not supported.
LOD regions are not supported.
Collada models are not supported.
PhotoOverlays are not supported.

NOTE: This codec only handles well-formed, serialized KML documents and does not handle extensions to the KML Specification.

const codec = new KMLCodec();
const nlHandle = codec.on(KMLNetworkLinkEvent, (networkLink: KMLNetworkLinkFeature) => {});
const cursor = codec.decode({ content: "<kml>...</kml>" });

Since

2020.1

Hierarchy (view full)

Codec<KMLFeature>
- KMLCodec

Implements

Evented

Index

Constructors

constructor

new KMLCodec(options?): KMLCodec
Creates a KML codec that can decode KML 2.3 strings.
Parameters
- Optional options: KMLCodecConstructorOptions
  an object literal that contains configuration settings for the codec.
Returns KMLCodec
Since
2020.1

Overrides Codec.constructor

Methods

decode

decode(options): Cursor<KMLFeature<KMLFeatureProperties>> | Promise<Cursor<KMLFeature<KMLFeatureProperties>>>
Converts content from a string, ArrayBuffer, or Blob into a cursor of KMLPlacemarkFeatures KMLGroundOverlayFeatures.

KML Network Link elements are emitted as KMLNetworkLinkFeature objects with the "KMLNetworkLink" event. KML Ground Overlay elements are emitted as KMLGroundOverlayFeature objects with the "KMLGroundOverlay" event. KML Screen overlay elements are emitted as KMLScreenOverlayFeature objects with the "KMLScreenOverlay" event.
Parameters
- options: CodecDecodeOptions
  The content to decode. Note that CodecDecodeOptions.reference will be ignored, as the KML specification stipulates that all KML coordinates should be interpreted using WGS 84. The CodecDecodeOptions.contentType is also unnecessary, and the codec will automatically determine whether the content is a KMZ that must be uncompressed before attempting to parse it. If the content is a KMZ file, then it will be uncompressed in memory and then parsed as a KML file. Bundled image resources in a KMZ file are also processed. Supported bundled image formats: '.png', '.jpeg', '.gif' and '.tiff'.
Returns Cursor<KMLFeature<KMLFeatureProperties>> | Promise<Cursor<KMLFeature<KMLFeatureProperties>>>
Overrides Codec.decode

encode

encode(cursor): EncodeResult
This is not yet implemented and will throw a ProgrammingError if it is used.
Parameters
- cursor: Cursor<Feature<null | Shape, FeatureProperties>>
  Defines the KMLFeatures to be encoded.
Returns EncodeResult
The encoded version of the features.

Overrides Codec.encode

Events

"KMLNetworkLink" event

on("KMLNetworkLink", callback: ((networkLink) => void), context?: any) : Handle
Registers a callback function for the "KMLNetworkLink" event to process KMLNetworkLinkFeatures. This event is fired by the cursor when it identifies a <NetworkLink> element in the document.
Parameters
- event: "KMLNetworkLink"
  Always set to "KMLNetworkLink" for this event type.
- callback: ((networkLink) => void)
  The callback function to be executed when KMLNetworkLinkFeature objects are decoded by the KMLCodec.decode function.
  - - (networkLink): void
    - Parameters
      networkLink: KMLNetworkLinkFeature
      Returns void
- Optional context: any
  The context in which the callback function should be invoked.
  
  "KMLNetworkLink"
Returns Handle
Implementation of Evented.on

"KMLTree" event

on("KMLTree", callback: ((rootArray) => void), context?: any) : Handle
Registers a callback function for the "KMLTree" event. The callback function receives an array of KMLFeatures. This event is fired when the cursor has finished processing, and contains all of the previously processed and emitted nodes from that cursor.
Parameters
- event: "KMLTree"
  Always set to "KMLTree" for this event type.
- callback: ((rootArray) => void)
  The callback function to be executed when the KMLCodec.decode function is called.
  - - (rootArray): void
    - Parameters
      rootArray: KMLFeature<KMLFeatureProperties>[]
      Returns void
- Optional context: any
  The context in which the function should be invoked.
  
  "KMLTree"
Returns Handle
Implementation of Evented.on

"KMLGroundOverlay" event

on("KMLGroundOverlay", callback: ((groundOverlay) => void), context?: any) : Handle
Registers a callback function for the "KMLGroundOverlay" event, that allows a listener to process KMLGroundOverlayFeatures. This event is triggered by the cursor whenever it identifies a <GroundOverlay> element in the document.
Parameters
- event: "KMLGroundOverlay"
  Always set to "KMLGroundOverlay" for this event type.
- callback: ((groundOverlay) => void)
  The callback function to be executed when the KMLCodec.decode function is called.
  - - (groundOverlay): void
    - Parameters
      groundOverlay: KMLGroundOverlayFeature
      Returns void
- Optional context: any
  The context in which the function should be invoked.
  
  "KMLGroundOverlay"
Returns Handle
Implementation of Evented.on

"KMLScreenOverlay" event

on("KMLScreenOverlay", callback: ((screenOverlay) => void), context?: any) : Handle
Registers a callback function for the "KMLScreenOverlay" event, that allows a listener to process KMLScreenOverlayFeatures. This event is triggered by the cursor whenever it identifies a <ScreenOverlay> element in the document.
Parameters
- event: "KMLScreenOverlay"
  Always set to "KMLScreenOverlay" for this event type.
- callback: ((screenOverlay) => void)
  The callback function to be executed when the KMLCodec.decode function is called.
  - - (screenOverlay): void
    - Parameters
      screenOverlay: KMLScreenOverlayFeature
      Returns void
- Optional context: any
  The context in which the function should be invoked.
Returns Handle
a handle to the registered callback with a single function 'remove'. This function can be used to unregister the callback function.

"KMLScreenOverlay"

Since
2021.0

Implementation of Evented.on

"KMLFatalError" event

on("KMLFatalError", callback: ((errorMessage) => void), context?: any) : Handle
Registers a callback function for the "KMLFatalError" event, that allows a listener to process errors which cause the KMLCodec to abort operations.
Parameters
- event: "KMLFatalError"
  Always set to "KMLFatalError" for this event type.
- callback: ((errorMessage) => void)
  The callback function to be executed when the KMLCodec encounters a fatal error.
  - - (errorMessage): void
    - Parameters
      errorMessage: string
      Returns void
- Optional context: any
  The context in which the function should be invoked.
  
  "KMLFatalError"
Returns Handle
Since
2021.0

Implementation of Evented.on

Class KMLCodec

Supported versions

Limitations

Since

Hierarchy (view full)

Implements

Index

Constructors

Methods

Events

Constructors

constructor

Parameters

Returns KMLCodec

Since

Methods

decode

Parameters

Returns Cursor<KMLFeature<KMLFeatureProperties>> | Promise<Cursor<KMLFeature<KMLFeatureProperties>>>

encode

Parameters

Returns EncodeResult

Events

"KMLNetworkLink" event

Parameters

Parameters

Returns void

Returns Handle

"KMLTree" event

Parameters

Parameters

Returns void

Returns Handle

"KMLGroundOverlay" event

Parameters

Parameters

Returns void

Returns Handle

"KMLScreenOverlay" event

Parameters

Parameters

Returns void

Returns Handle

Since

"KMLFatalError" event

Parameters

Parameters

Returns void

Returns Handle

Since

Settings

Member Visibility

Theme

On This Page