@ky23js/geoheightchecker v2.0.0

GeoHeightChecker

Description

Module which implements Turfjs logic and Google elevation api to find the elevationdata (min, max, average) from a single point, multiple points, along a route, inside a certain area.

Installation and requirements

• requirements

  The module requires node and npm.
  Internally relies on @turf/turf and @google/elevation-api

  You will also need to provide your own Google elevation api key

• installation

  npm install --save @23seconds/geoheightchecker

limitations

• Only for node runtime, no browser support
• Only asynchronious implementation

Properties and methods

Properties

• apiKey is the Google Api Key used to make requests to the google servers

  In production this is a write only property

• precision is the value used to determine the amount of samples taken from certain areas

• onlyHeight determines if the result of queries returns only the elevation value or the coordinates aswell

• timeout determines how long the Google Client waits before abandonning the request

• type sets how to interpret the coordinates

  default / undefined will interpret each coordinate on individually
  "line" will create a route among given coordinates and find the highest point along this route
  "polygon" will create a pointgrid inside the polygon an use those coordinates as a whole

• coordinates is an array of longitude and latitude point in object form

  interface Coords{
      latitude: number,
      longitude: number
  }

• units sets/gets the unit of measurements for the output elevation values

• fresh readonly property indicating if the data in results is queried according to currently set properties or they need to be queried again

  Setting precision, type or coordinate properties will render results to be unfresh, a refresh has been automatically scheduled but at this point not yet been completed

• results contains an array of results, results are extensions of Coords type containing an additional elevation property

  interface Result extends Coords{
      elevation: number
  }

Methods

• MinElevation returns the point (or elevation of) the lowest point in the collection / route / area

  @Return

  Promise< Result | number >

• MaxElevation returns the point (or elevation of) the highest point in the collection / route / area

  @Return

  Promise< Result | number >

• AverageElevation returns the average elevation of the collection / route / area

  @Return

  Promise< number >

• ElevationBetween returns an array of Result typed objects whith elevation between supplied boundaries

  @Params

  min: number
  max: number

  @Return

  Array< Result >

• ElevationBelowThreshold returns an array of Result typed objects wih elevation below supplied threshold

  @Params

  max: number

  @Return

  Array< Result >

• ElevationAboveThreshold returns an array of Result typed objects wih elevation above supplied threshold

  @Params

  min: number

  @Return

  Array< Result >

IMPORTANT; Every method will throw an error on failure, depending on the type of error (i.e. Google API or above) which occured the error might contain an error_message of type string

How to use

Setup

Import and create object

const ghc = require('@23seconds/GeoHeightChecker')
const GeoHeightChecker = new ghc(API_KEY, ContructOptions?);

or

const GeoHeightChecker = new (require('@23seconds/GeoHeightChecker'))(API_KEY, ContructOptions?);

The constructor requires an api key following the ApiKey property contrains as the first argument, optionally a second argument can be supplied (see below). These values are all optional, have defaults (see above) and can be changed later on.

class Units {
    "miles": string = "miles";
    "inches": string = "inches";
    "feet": string = "feet";
    "yards": string = "yards";
    "meters": string = "meters";
    "metres": string = "metres";
    "kilometers": string = "kilometers";
};
interface ConstructOptions {
    precision?: number,
    onlyHeight?: boolean,
    timeout?: number
    units?: keyof Units
};

Examples

1. Get the highest elevated point in the collection, returns a number.

       GeoHeightChecker.coordinates = [
           {
               latitude: 50.91822671076888,
               longitude: 5.360175021607509
           },
           {
               latitude: 50.91754721116603,
               longitude: 5.363260801565685
           },
           {
               latitude: 50.91983640276154,
               longitude: 5.3638107425965
           }
       ];
       GeoHeightChecker.MaxElevation()
           .then((a) =>
               console.dir(a) // 141.53
           )
           .catch((e) =>
               console.error(e)
           );

2. Get the highest elevated point inside the polygon area, returns the height aswell as the coordinates of the point.

   GeoHeightChecker.coordinates = [
       {
           latitude: 50.91822671076888,
           longitude: 5.360175021607509
       },
       {
           latitude: 50.91754721116603,
           longitude: 5.363260801565685
       },
       {
           latitude: 50.91983640276154,
           longitude: 5.3638107425965
       }
   ];
   GeoHeightChecker.type = "polygon";
   GeoHeightChecker.onlyHeight = false;
   GeoHeightChecker.MaxElevation()
       .then((a) =>
           console.dir(a)
           // elevation: 144.28   
           // latitude: 50.91846598940352,  
           // longitude: 5.363341862647593, 
       )
       .catch((e) =>
           console.error(e)
       );

3. Get highest elevated point alongside a route covering the given coordinates, return the height alongside the coordinates of the highest point, sample the route every 1 meter (note that 1 segment can be broken down in to at max 512 samples)

   GeoHeightChecker.coordinates = [
       {
           latitude: 50.91822671076888,
           longitude: 5.360175021607509
       },
       {
           latitude: 50.91754721116603,
           longitude: 5.363260801565685
       },
       {
           latitude: 50.91983640276154,
           longitude: 5.3638107425965
       }
   ];
   GeoHeightChecker.type = "line";
   GeoHeightChecker.onlyHeight = false;
   GeoHeightChecker.precision = 1;
   GeoHeightChecker.units = "meters"
   GeoHeightChecker.MaxElevation()
       .then((a) =>
           console.dir(a)
           // elevation: 42.51,  
           // latitude: 50.91822671076888,        
           // longitude: 5.360175021607509 
       )
       .catch((e) =>
           console.error(e)
       );