Nighttime Pachinko Marathon

    unl-core
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/unl-core package

    3.0.1 • Public • Published

    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/unl-core@2.0.2";
    
      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;
    }

    PointWithElevation

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

    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: {
            n: maxLat,
            e: maxLon,
            s: minLat,
            w: minLon
        }
    }

    bounds(locationId: string): Bounds

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

    UnlCore.bounds("u173zwbt3");

    Returns a Bounds object:

    {
        n: maxLat,
        e: maxLon,
        s: minLat,
        w: minLon
    }

    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({
      n: 52.38788170348322,
      e: 4.91476651006799,
      s: 52.369915397800824,
      w: 4.88533463041897
    });

    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

    Install

    npm i unl-core

    Homepage

    unl.global

    DownloadsWeekly Downloads

    204

    Version

    3.0.1

    License

    MIT

    Unpacked Size

    83.3 kB

    Total Files

    11

    Last publish

    Collaborators

    • unl