Skip to content

Latest commit

 

History

History
336 lines (247 loc) · 6.34 KB

README.md

File metadata and controls

336 lines (247 loc) · 6.34 KB
Raw

UNL CORE JS

This library can be used to convert a UNL locationId to/from a latitude/longitude point. It also contains helper functions like retrieving the bounds of a UNL cell or the UNL grid lines for a given boundingbox (these can be used to draw a UNL cell or a UNL grid).

Install

npm install unl-core
yarn add unl-core

TypeScript

npm install @types/unl-core --save-dev
yarn add @types/unl-core --dev

Usage

You can either import certain functions from the package directly:

import { encode } from "unl-core";

or load the whole library:

import UnlCore from "unl-core";

Usage in browser

UnlCore can be used in the browser by taking a local copy, or loading it from jsDelivr: for example,

<!DOCTYPE html><title>locationId example</title><meta charset="utf-8" />
<script type="module">
  import UnlCore from "https://cdn.jsdelivr.net/npm/[email protected]";

  const locationId = UnlCore.encode(52.2, 0.12, 6);
  console.assert(locationId == "u120fw");

  const latlon = UnlCore.decode("u120fw");
  console.assert(JSON.stringify(latlon) == '{"lat":52.1988,"lon":0.115}');
</script>

Usage in Node.js

UnlCore can be used in a Node.js app from npm (currently the esm package is required to load ES-modules):

$ npm install unl-core esm
$ node -r esm
> import UnlCore from 'unl-core';
> const locationId = UnlCore.encode(52.20, 0.12, 6);
> console.assert(locationId == 'u120fw');
> const latlon = UnlCore.decode('u120fw');
> console.assert(JSON.stringify(latlon) == '{"lat":52.1988,"lon":0.115}');

Interfaces

Direction

type Direction = "N" | "S" | "E" | "W";

ElevationType

type ElevationType = "floor" | "heightincm";

Neighbours

interface Neighbours {
  n: string;
  ne: string;
  e: string;
  se: string;
  s: string;
  sw: string;
  w: string;
  nw: string;
}

Point

interface Point {
  lat: number;
  lon: number;
}

Bounds

interface Bounds {
  sw: Point;
  ne: Point;
}

BoundsWithElevation

interface BoundsWithElevation extends Bounds {
  elevation: number;
  elevationType: ElevationType;
}

PointWithElevation

interface PointWithElevation extends Point {
  elevation: number;
  elevationType: ElevationType;
  bounds: BoundsWithElevation;
}

EncodeOptions

interface EncodeOptions {
  elevation: number;
  elevationType: ElevationType;
}

LocationIdWithElevation

interface LocationIdWithElevation {
  elevation: number;
  elevationType: ElevationType;
  locationId: string;
}

Functions

encode(lat: number, lon: number, precision?: number, options?: EncodeOptions): string

Encodes latitude/longitude coordinates to locationId, either to specified precision or to default precision. Elevation information can be optionally specified in options parameter.

UnlCore.encode(52.37686, 4.90065);

Returns a string:

"u173zwbt3"

decode(locationId: string): PointWithElevation

Decodes a locationId to latitude/longitude (location is approximate centre of locationId cell, to reasonable precision).

UnlCore.decode("u173zwbt3");

Returns a Point object:

{
    lat: centerLat,
    lon: centerLon,
    bounds: {
        sw: {
            lat: minLat,
            lon: minLon
        },
        ne: {
            lat: maxLat,
            lon: maxLon
       }
    }
}

bounds(locationId: string): BoundsWithElevation

Returns SW/NE latitude/longitude bounds of specified locationId cell.

UnlCore.bounds("u173zwbt3");

Returns a Bounds object:

{
    sw: {
        lat: minLat,
        lon: minLon
    },
    ne: {
        lat: maxLat,
        lon: maxLon
    },
    elevation: 0,
    elevationType: "floor"
}

function gridLines(bounds: Bounds, precision?: number): Array<[[number, number], [number, number]]>

Returns the vertical and horizontal lines that can be used to draw a UNL grid in the specified SW/NE latitude/longitude bounds and precision. Each line is represented by an array of two coordinates in the format: [[startLon, startLat], [endLon, endLat]].

UnlCore.gridLines({
  sw: {
    lat: 52.369915397800824,
    lon: 4.88533463041897,
  },
  ne: {
    lat: 52.38788170348322,
    lon: 4.91476651006799,
  },
});

Returns an array of lines:

[
   [[startLon, startLat], [endLon, endLat]]
   ...
]

adjacent(locationId: string, direction: Direction): string

Determines adjacent cell in given direction.

UnlCore.adjacent("ezzz@5", "N");

Returns a string:

"gbpb@5"

neighbours(locationId: string): Neighbours

Returns all 8 adjacent cells to specified locationId.

UnlCore.neighbours("ezzz");

Returns a Neighbours object :

{
    n: "gbpb",
    ne: "u000",
    e: "spbp",
    se: "spbn",
    s: "ezzy",
    sw: "ezzw",
    w: "ezzx",
    nw: "gbp8",
}

excludeElevation(locationIdWithElevation: string): LocationIdWithElevation

Returns locationId and elevation properties. It is mainly used by internal functions.

UnlCore.excludeElevation("6gkzwgjz@5");

Returns a LocationIdWithElevation object:

{
    locationId: "6gkzwgjz",
    elevation: 5,
    elevationType: "floor",
}

appendElevation(locationIdWithoutElevation: string, elevation: number, elevationType: ElevationType): string

Adds elevation chars and elevation. It is mainly used by internal functions.

UnlCore.appendElevation("6gkzwgjz", 5);

Returns a string:

"6gkzwgjz@5"

Note

To obtain neighbours as an array, you can use

const neighboursObj = UnlCore.neighbours(locationId);
const neighboursArr = Object.keys(neighboursObj).map(n => neighboursObj[n]);

The parent of a locationId is simply locationId.slice(0, -1).

If you want the locationId converted from Base32 to Base4, you can e.g.:

parseInt(UnlCore.encode(52.20, 0.12, 6), 32).toString(4);

Upgrade to version 2.0 from version 1.0

In version 2.0 we renamed the concept of geohash to locationId. In order to upgrade from version 1.0 you need to:

  • Import UnlCore instead of Geohash from unl-core
  • Get locationId instead of geohash from the answer of methods which returned an object with geohash parameter