ol-elevation-parser

OpenLayers Elevation Parser

Tiny module to retrieve and parse data to create elevation profiles and/or volume calculations from raster sources. This will sample the provided geometries and then parse the elevation data from differents Open Layers sources, using raster grayscale or color processed rgbs as source.

Tested with OpenLayers version 6, 7 and 8.

How it works

Supported sources:

• XYZ
• TileWMS
• TileImage
• GeoTIFF
• Custom function to retrieve data from an API or so

Supported color formats:

• Terrarium
• Mapbox
• Geoserver raster grayscale MDE (16, 24, 32 bits, etc) using getFeatureInfo function (very slow to calculate LineStrings and Polygons, but useful in some specific cases).
• Custom color processing (you must provide the function to decode the pixel RGB values)

Supported geometries:

Supports calculations from Points, LineStrings and Polygons. Each of these geometries is processed diferently:

• Points: in this case, there is no further processing, the coordinates of each point are consulted according to the configured method (see calculateZMethod) and the same supplied coordinates are returned with the z value embedded.
• LineStrings: here it's necessary to resample the geometry to assemble the profile, and make requests only of those sampled points. The greater the number of samples (see samples), the longer it will take, but the better the quality of the profile will be. In the the sampling, the length of that line is divided into x number of parts to obtain the coordinates of each of the extremes. Then, the vertices of the geometry are also added to those sampled coordinates.
• Polygons: two different samples are made:
  • on the one hand, the contour of the polygon, to which the same procedure as the LineStrings is applied. This contour is useful to obtain the base level that borders the area, which allows the volume of the polygon to be calculated later.
  • on the other hand, the area. To calculate this, a sampling is done in the form of a grid (see sampleSizeArea), from which an interior point is obtained. Each of those points is requested. The greater the number of samples, the longer it will take, but the greater the accuracy of the calculation.

Examples

• Basic usage using Geotiff sources: create an OpenLayers map instance and add Ol Elevation Parser as a control See example.

Usage

import ElevationParser from 'ol-elevation-parser';

import TileWMS from 'ol/source/TileWMS.js';
import LineString from 'ol/geom/LineString.js';
import Feature from 'ol/Feature.js';

var elevationLayer = new TileWMS({
    url: 'http://localhost:8080/geoserver/dipsohdev/ows',
    serverType: 'geoserver',
    crossOrigin: null,
    interpolate: false,
    params: {
        SERVICE: 'wms',
        LAYERS: 'mdeIgnRgb'
    }
});

var options = {
    source: elevationLayer,
    calculateZMethod: 'getFeatureInfo',
    tilesResolution: 'current',
    samples: 50, // For LineStrings and Polygons contour
    sampleSizeArea: 'auto', // For Polygons area
    noDataValue: -10000,
    smooth: 0
};

var elevationParser = new ElevationParser(options);

// Add control the the Open Layers map instance
map.addControl(elevationParser);

var lineStringFeature = new Feature(new LineString(/*...*/));

const data = await elevationParser.getElevationValues(feature);

Changelog

See CHANGELOG for details of changes in each release.

Install

Browser

JS

Load ol-elevation-parser.js after OpenLayers. Elevation Parser is available as ElevationParser.

<script src="https://unpkg.com/ol-elevation-parser@1.3.18"></script>

Parcel, Webpack, etc.

NPM package: ol-elevation-parser.

Install the package via npm

npm install ol-elevation-parser

JS

import ElevationParser from 'ol-elevation-parser';

TypeScript type definition

TypeScript types are shipped with the project in the dist directory and should be automatically used in a TypeScript project. Interfaces are provided for the Options.

API

Table of Contents

• ElevationParser
  • Parameters
  • getElevationValues
    • Parameters
  • getSource
  • setSource
    • Parameters
  • getSamples
  • setSamples
    • Parameters
  • getSampleSizeArea
  • setSampleSizeArea
    • Parameters
  • getCalculateZMethod
  • setCalculateZMethod
    • Parameters
  • getSmooth
  • setSmooth
    • Parameters
  • getNoDataValue
  • setNoDataValue
    • Parameters
  • getTilesResolution
  • setTilesResolution
    • Parameters
  • getBands
  • setBands
    • Parameters
  • getTimeout
  • setTimeout
    • Parameters
  • getMaxTilesResolution
  • getCurrentViewResolution
  • setMap
    • Parameters
• mainCoords
• contourCoords
• ElevationParserEventTypes
• IGetElevationValues
  • gridPolygons
• CoordinatesXYZ
• CoordinatesXY
• IElevationCoords
  • mainCoords
  • contourCoords
• RasterSources
• CustomSourceFn
• ElevationValuesIndividualOptions
• Options
  • source
  • calculateZMethod
  • tilesResolution
  • bands
  • samples
  • sampleSizeArea
  • smooth
  • noDataValue
  • timeout
  • verbose

ElevationParser

Extends ol/control/Control~Control

Parameters

• options Options

getElevationValues

Get Feature's elevation values. Use custom options to overwrite the general ones for specific cases

Parameters

• feature Feature<(LineString | Point | Polygon)>
• customOptions ElevationValuesIndividualOptions (optional, default null)

Returns Promise<(IGetElevationValues | Error)>

getSource

Returns any

setSource

Parameters

• source any
• silent (optional, default false)

Returns void

getSamples

Returns any

setSamples

Parameters

• samples any
• silent (optional, default false)

Returns void

getSampleSizeArea

Returns any

setSampleSizeArea

Parameters

• sampleSizeArea any
• silent boolean

Returns void

getCalculateZMethod

Returns any

setCalculateZMethod

Parameters

• calculateZMethod any
• silent (optional, default false)

Returns void

getSmooth

Returns any

setSmooth

Parameters

• smooth any
• silent (optional, default false)

Returns void

getNoDataValue

Returns any

setNoDataValue

Parameters

• noDataValue any
• silent (optional, default false)

Returns void

getTilesResolution

Returns any

setTilesResolution

Parameters

• tilesResolution any
• silent (optional, default false)

Returns void

getBands

Returns any

setBands

Parameters

• bands any
• silent (optional, default false)

Returns void

getTimeout

Returns any

setTimeout

Parameters

• timeout any
• silent (optional, default false)

Returns void

getMaxTilesResolution

Maximum tile resolution of the image source Only if the source is a raster

Returns number

getCurrentViewResolution

Current view resolution Unsupported if the view of a GeoTIFF is used in the map

Returns number

setMap

Parameters

• map Map

Returns void

mainCoords

Sampled coordinates from LineStrings, Point coordinates, or sampled coordinates from Polygons, obtained by subdividing the area in multiples squares and getting each center point.

Type: Array<CoordinatesXY>

contourCoords

Contour coordinates from Polygons features.

Type: Array<CoordinatesXY>

ElevationParserEventTypes

[type]

Type: ("change:samples" | "change:sampleSizeArea" | "change:source" | "change:calculateZMethod" | "change:noDataValue" | "change:smooth" | "change:bands" | "change:tilesResolution" | "change:timeout")

IGetElevationValues

Extends IElevationCoords

[interface]

gridPolygons

Sampled Polygons Useful to to calculate fill and cut values on ovolume measurements

Type: Array<Feature<Polygon>>

CoordinatesXYZ

[type]

Type: [number, number, number]

CoordinatesXY

[type]

Type: [number, number]

IElevationCoords

[interface]

mainCoords

Sampled coordinates from LineStrings, Point coordinates, or sampled coordinates from Polygons, obtained by subdividing the area in multiples squares and getting each center point.

Type: Array<CoordinatesXYZ>

contourCoords

Contour coordinates from Polygons features.

Type: Array<CoordinatesXYZ>

RasterSources

[type]

Type: (TileWMS | TileImage | XYZ | GeoTIFF)

CustomSourceFn

[type]

Type: function (originalFeature: Feature<(LineString | Point | Polygon)>, sampledCoords: any): Promise<IElevationCoords>

ElevationValuesIndividualOptions

[interface]

Options

Extends Omit<ControlOptions, 'target'>

[interface]

source

Source from which it is obtained the elevation values. If not provided, the zGraph would be not displayed.

If a Raster source is used and the option resolution is set to max, provide the maxZoom attribute to allow download the data in the higher resolution available.

Also, you can provide a custom function to call an API or other methods to obtain the data.

Type: (RasterSources | CustomSourceFn)

calculateZMethod

To obtain the elevation values from the diferrents sources, you can:

• Calculate the zValues from the rgb pixel data (TileImage and XYZ source formats need this):

  • Mapbox preset: (r * 256 * 256 + g * 256 + b) * 0.1 - 10000
  • Terrarium preset: (r * 256 + g + b / 256) - 32768
  • Provided your custom function to calculate elevation from the rgb pixel data

• Making requests to the geoserver (TileWMS source) getFeatureInfo: make requests to the source url using service getFeatureInfo

By default:

• TileWMS format use 'getFeatureInfo' requests to the source_url to obtain the values.
• TileImage and XYZ formats are calculated from the pixel data using 'Mapbox' preset.

Type: ("getFeatureInfo" | "Mapbox" | "Terrarium" | function (r: number, g: number, b: number): number)

tilesResolution

Only used if calculateZMethod is not getFeatureInfo.

This sets the resolution in wich the tiles are downloaded to calculate the z values.

If max, the tiles will be downloaded using the maximum quality possible, but you have to configure the maxZoom attribute of the source to prevent requesting inexisting tiles. Using max provides the maximum quality, but the requests are gonna be in higher number and would be slower. Use the method getMaxTilesResolution to get the max resolution in a number number.

´current´ uses the current view resolution of the map. If the source is visible in the map, the already downloaded tiles would be used to the calculations so is it's the faster method. Use the method getCurrentViewResolution to get the curent view resolution number. Doesn't work if the source is GeoTIFF and the map use its view

´current´ is the default

Type: (number | "max" | "current")

bands

Only used if calculateZMethod is not getFeatureInfo.

Default is 4

Type: number

samples

To obtain the elevation values on each distance measurement, multiples samples are taken across the line. This number is used as equally percentage steps across the geom, plus all the vertices positions.

• getFeatureInfo on TileWMS sources will make one request per sample
• TileImageand XYZ are calculated across each pixel after downloading the required tiles. The bigger the number, the greater the quality of the elevation data, but slower response times and bigger overhead (principally on getFeatureInfo method). This value is used to sample LinesStrings and Polygons contour 50 is the default

Type: (number | function (length: number): number)

sampleSizeArea

To obtain the elevation values on a volume measurement, multiples samples are taken across the polygon. The value provided must be in meters. The bigger the number, the greater the quality of the measurement, but slower response times and bigger overhead (principally on getFeatureInfo method). 'auto' is the default

Type: (number | "auto" | function (area: number): number)

smooth

Smooth result values on LineStrings measurements 0 is the default (no smoothing)

Type: number

noDataValue

When calculating the zGraph statistics from the raster dataset, you can choose to ignore specific values with the NoDataValue parameter. These values are considerated as transparency, so probably you want these replaced by 0.

-10000 is the default false to disable

Type: (number | false)

timeout

Timeout in ms to wait before close the requests

5000 ms is the default

Type: number

verbose

console.log to help debug the code false is the default

Type: boolean

TODO

• Remove axios
• Improve README and documentation
• Add jest
• Add check/msg for invalid geometries
• Add live example