Class KMLCodec

Decodes KML and KMZ files (strings, ArrayBuffers, and Blobs) into KMLPlacemarkFeature and KMLGroundOverlayFeature instances. Other features are emitted from events:

KMLNetworkLinkFeatures are emitted via the "KMLNetworkLink" event. Network Links reference separate KML files that should be decoded in a new LuciadRIA model and layer, for example KMLModel and KMLLayer.
KMLGroundOverlayFeatures are emitted via the "KMLGroundOverlay" event. Ground Overlays should be handled in a layer (see createGroundOverlayLayer).
KMLFolderContainers are emitted via the "KMLTree" event. These features are used to represent the structure of the KML file, including traversed KMLScreenOverlayFeatures and KMLGroundOverlayFeatures. These "container" features are not rendered on the map. They exist to facilitate GUI creation.

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 defined in the source KML are resolved according to the KML specification. Externally referenced styles are not resolved.

Supported versions

The current version of LuciadRIA supports the KML 2.3 standard.

This codec decodes only 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
ExtendedData (defined via: Data, SchemaData and foreign-namespace elements)

Limitations

Cross-Origin requests that do not contain an "Access-Control-Allow-Origin" header in the response cannot be loaded.
Camera positions are not supported.
LOD regions are not supported.
Collada models are not supported.
PhotoOverlays are not supported.
SchemaData: only local schemaUrl references in the same file are supported (e.g. #S1 points to the local <Schema id="S1">).

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

  const codec = new KMLCodec();
  const handle = codec.on("KMLNetworkLink", (networkLink: KMLNetworkLinkFeature) => {
    // Create a KML layer from the received network link.
  });
  const cursor = codec.decode({content: "<kml>...</kml>"});

Since

2020.1

Hierarchy (View Summary)

Codec<KMLFeature>
- KMLCodec

Implements

Evented

Index

Constructors

constructor

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

Overrides Codec.constructor

Methods

decode

decode(
    options: CodecDecodeOptions,
):
    | Cursor<KMLFeature<KMLFeatureProperties>>
    | Promise<Cursor<KMLFeature<KMLFeatureProperties>>>
Decodes KML content (string, ArrayBuffer, or Blob) into a cursor of KMLFeature. The cursor yields KMLPlacemarkFeature and KMLGroundOverlayFeature instances.

Other feature types are emitted as events:
- KMLNetworkLinkFeature via the "KMLNetworkLink" event.
- KMLGroundOverlayFeature via the "KMLGroundOverlay" event.
- KMLScreenOverlayFeature via the "KMLScreenOverlay" event.
Parameters
- options: CodecDecodeOptions
  The content to decode.
  
  CodecDecodeOptions.reference is ignored (KML coordinates are in WGS 84).
  
  CodecDecodeOptions.contentType is not required. KMZ is auto-detected and unpacked in memory before parsing.
  
  Bundled KMZ image resources are processed (supported: .png, .jpeg, .gif, .tiff).
Returns
| Cursor<KMLFeature<KMLFeatureProperties>>
| Promise<Cursor<KMLFeature<KMLFeatureProperties>>>
A Cursor of KMLFeature, or a Promise resolving to one for asynchronous inputs (for example, KMZ/Blob)

Overrides Codec.decode

encode

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

Overrides Codec.encode

Events

on

on(
    event: "KMLNetworkLink",
    callback: (networkLink: KMLNetworkLinkFeature) => 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: KMLNetworkLinkFeature) => void
  The callback function to be executed when KMLNetworkLinkFeature objects are decoded by the KMLCodec.decode function.
- Optionalcontext: any
  The context in which the callback function should be invoked.
  
  "KMLNetworkLink"
Returns Handle
Implementation of Evented.on
on(
    event: "KMLTree",
    callback: (rootArray: KMLFeature<KMLFeatureProperties>[]) => 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: KMLFeature<KMLFeatureProperties>[]) => void
  The callback function to be executed when the KMLCodec.decode function is called.
- Optionalcontext: any
  The context in which the function should be invoked.
  
  "KMLTree"
Returns Handle
Implementation of Evented.on
on(
    event: "KMLGroundOverlay",
    callback: (groundOverlay: KMLGroundOverlayFeature) => 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: KMLGroundOverlayFeature) => void
  The callback function to be executed when the KMLCodec.decode function is called.
- Optionalcontext: any
  The context in which the function should be invoked.
  
  "KMLGroundOverlay"
Returns Handle
Implementation of Evented.on
on(
    event: "KMLScreenOverlay",
    callback: (screenOverlay: KMLScreenOverlayFeature) => 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: KMLScreenOverlayFeature) => void
  The callback function to be executed when the KMLCodec.decode function is called.
- Optionalcontext: 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
on(
    event: "KMLFatalError",
    callback: (errorMessage: string) => 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: string) => void
  The callback function to be executed when the KMLCodec encounters a fatal error.
- Optionalcontext: any
  The context in which the function should be invoked.
  
  "KMLFatalError"
Returns Handle
Since
2021.0

Implementation of Evented.on

Class KMLCodec

Since

Hierarchy (View Summary)

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

on

Parameters

Returns Handle

Parameters

Returns Handle

Parameters

Returns Handle

Parameters

Returns Handle

Since

Parameters

Returns Handle

Since

Settings

On This Page

Class KMLCodec

Since

Hierarchy (View Summary)

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

on

Parameters

Returns Handle

Parameters

Returns Handle

Parameters

Returns Handle

Parameters

Returns Handle

Since

Parameters

Returns Handle

Since

Settings

On This Page

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