TsGeo - A Simple Geo Library for TypeScript

TsGeo provides abstractions to geographical coordinates (including support for different ellipsoids) and allows you to calculate geographical distances between coordinates with high precision.

This library can be used in TypeScript project, for instance application under:

• Angular
• Ionic
• ...

This project is an adaptation of phpgeo of mjaschen.

• Documentation
• Installation
• Features
• Examples/Usage
  • Distance between two coordinates (Vincenty's Formula)
  • Simplifying a polyline
  • Polygon contains a point (e.g. "GPS geofence")
  • Formatted output of coordinates
    • Decimal Degrees
    • Degrees/Minutes/Seconds (DMS)
    • GeoJSON
• Credits
• License

Documentation

This project is based on phpgeo so to know the possibilities of this library, you can consult documentation of phpgeo: https://phpgeo.marcusjaschen.de/

Installation

Installing the TsGeo library plugin can be done in one of two ways. NPM installation method enables you to quickly and easily install the library with a simple terminal command, while the manual method enables you to do so via a zip file.

NPM Installation (Preferred)

The simplest way to install this library is via the package manager (NPM) through your system's Terminal (also called the command line). From the root of your project install type:

npm install tsgeo

This will install the TsGeo library into your /node_modules/tsgeo directy within your project.

Manual Installation

To install this library, just download the zip version of this repository and unzip the content of /src sub-directory in your application project.

Features

Info: Transcription of documentation related to TypeScript version is not done. So, please refer to the documentation site of phpgeo for complete and up-to-date documentation!

TsGeo provides the following features (follow the links for examples):

• abstractions of several geometry objects (coordinate/point, line, polyline/GPS track, polygon.
• support for different ellipsoids, e. g. WGS-84
• length/distance/perimeter calculations with different implementations (Haversine, Vincenty)
• Geofence calculation, i. e. answering the question "Is this point contained in that area/polygon?"
• formatting and output of geometry objects (GeoJSON, nice strings, e. g. 18° 54′ 41″ -155° 40′ 42″)
• calculation of a destination point for a given starting point, bearing angle, and distance (spherical or with Vincenty's formula)
• calculation of the perpendicular distance between a point and a line
• getting segments of a polyline/polygon.
• reversing direction of polyline/polygon.

Examples/Usage

This list is incomplete, please visit the phpgeo documentation site for the full monty of documentation and examples!

Distance between two coordinates (Vincenty's Formula)

Use the calculator object directly:

import {Coordinate} from "tsgeo/Coordinate";
import {Vincenty}   from "tsgeo/Distance/Vincenty";

/* Add the following in a method of TS class */

let coordinate1 = new Coordinate(19.820664, -155.468066); // Mauna Kea Summit
let coordinate2 = new Coordinate(20.709722, -156.253333); // Haleakala Summit

let calculator = new Vincenty();

console.log(calculator.getDistance(coordinate1, coordinate2)); // returns 128130.850 (meters; ≈128 kilometers)

or call the getDistance() method of a Coordinate object by injecting a calculator object:

import {Coordinate} from "tsgeo/Coordinate";
import {Vincenty}   from "tsgeo/Distance/Vincenty";

/* Add the following in a method of TS class */

let coordinate1 = new Coordinate(19.820664, -155.468066); // Mauna Kea Summit
let coordinate2 = new Coordinate(20.709722, -156.253333); // Haleakala Summit

console.log(coordinate1.getDistance(coordinate2, new Vincenty())); // returns 128130.850 (meters; ≈128 kilometers)

Simplifying a polyline

Polylines can be simplified to save storage space or bandwidth. Simplification is done with the Ramer–Douglas–Peucker algorithm (AKA Douglas-Peucker algorithm).

import {Coordinate} from "tsgeo/Coordinate";
import {Polyline}   from "tsgeo/Polyline";
import {Vincenty}   from "tsgeo/Distance/Vincenty";

/* Add the following in a method of TS class */

let polyline = new Polyline();
polyline.addPoint(new Coordinate(10.0, 10.0));
polyline.addPoint(new Coordinate(20.0, 20.0));
polyline.addPoint(new Coordinate(30.0, 10.0));

let processor = new Simplify(polyline);

// remove all points which perpendicular distance is less
// than 1500 km from the surrounding points.
let simplified = processor.simplify(1500000);

// simplified is the polyline without the second point (which
// perpendicular distance is ~1046 km and therefore below
// the simplification threshold)

Polygon contains a point (e.g. "GPS geofence")

phpgeo has a polygon implementation which can be used to determinate if a point is contained in it or not. A polygon consists of at least three points. Points are instances of the Coordinate class.

Warning: The calculation gives wrong results if the polygons has points on both sides of the 180/-180 degrees meridian.

import {Coordinate} from "tsgeo/Coordinate";
import {Polygon}   from "tsgeo/Polygon";

/* Add the following in a method of TS class */

let geofence = new Polygon();

geofence.addPoint(new Coordinate(-12.085870,-77.016261));
geofence.addPoint(new Coordinate(-12.086373,-77.033813));
geofence.addPoint(new Coordinate(-12.102823,-77.030938));
geofence.addPoint(new Coordinate(-12.098669,-77.006476));

let outsidePoint = new Coordinate(-12.075452, -76.985079);
let insidePoint = new Coordinate(-12.092542, -77.021540);

console.log(geofence.contains(outsidePoint)); // returns bool(false) the point is outside the polygon
console.log(geofence.contains(insidePoint)); // returns bool(true) the point is inside the polygon

Formatted output of coordinates

You can format a coordinate in different styles.

Decimal Degrees

import {Coordinate}     from "tsgeo/Coordinate";
import {DecimalDegrees} from "tsgeo/Formatter/Coordinate/DecimalDegrees";

/* Add the following in a method of TS class */

let coordinate = new Coordinate(19.820664, -155.468066); // Mauna Kea Summit

console.log(coordinate.format(new DecimalDegrees()));

Degrees/Minutes/Seconds (DMS)

import {Coordinate} from "tsgeo/Coordinate";
import {DMS}        from "tsgeo/Formatter/Coordinate/DMS";

/* Add the following in a method of TS class */

let coordinate = new Coordinate(18.911306, -155.678268); // South Point, HI, USA

let formatter = new DMS();

console.log(coordinate.format(formatter)); // 18° 54′ 41″ -155° 40′ 42″

formatter.setSeparator(", ")
    .useCardinalLetters(true)
    .setUnits(DMS.UNITS_ASCII);

console.log(coordinate.format(formatter)); // 18° 54' 41" N, 155° 40' 42" W

GeoJSON

import {Coordinate} from "tsgeo/Coordinate";
import {GeoJSON}    from "tsgeo/Formatter/Coordinate/GeoJSON";

/* Add the following in a method of TS class */

let coordinate = new Coordinate(18.911306, -155.678268); // South Point, HI, USA

console.log(coordinate.format(new GeoJSON())); // { "type" : "point" , "coordinates" : [ -155.678268, 18.911306 ] }

Credits

• phpgeo of Marcus Jaschen

License

Copyright (c) 2018 clemdesign.

For use under the terms of the MIT license.