openlab-technologies-ontrack-position-estimator

What is this?

This module estimates the position of a train (or anything else, really) at a certain point of time based on departure and arrival location and time. It was published to be used as a part of Open Lab Technologies assignment (CDT 3).

Getting Started

Installation

npm install openlab-technologies-ontrack-position-estimator Doesn't require any extra dependencies.

Example

var pe = require('openlab-technologies-ontrack-position-estimator');

var polyline = [[55.00991,-1.579309999999964],
                [55.01012,-1.5786500000000387],
                [55.01016,-1.5785600000000386],
                [55.01034,-1.5779999999999745],
                [55.01043,-1.5777399999999489],
                [55.01064,-1.5771399999999858],
                [55.01081,-1.5766999999999598],
                [55.0109,-1.57650000000001],
                [55.01108,-1.5760500000000093]];

var startPosition = [55.00983,-1.5795399999999518];
var endPosition = [55.01174,-1.574420000000032];
var startTime = new Date("2017-04-12T07:01:00");
var endTime = new Date("2017-04-12T07:04:00");
var estimationTime = new Date("2017-04-12T07:02:15");

var estimatedPosition = pe.calculatePosition(polyline, startPosition, startTime, endPosition, endTime, estimationTime);
console.log(estimatedPosition);

Usage

Calculate Position

pe.calculatePosition(polyline, startPosition, startTime, endPosition, endTime [, estimationTime])

Estimates the current position given:

• polyline : Array of coordinate point. The points have the format [latitude, longitude]
• startPosition and endPosition : Coordinate points in the format [latitude, longitude] representing the departure and arrival points for the train (entity?) in question. If the points don't fall on the polyline, the departure and arrival will be the points on the polyline that are nearest to the passed points.
• startTime and endTime : Departure and arrival times. Can be Date objects or numbers representing minutes from midnight.
• estimationTime (optional) : The point of time to estimate train position at. Can be a Date object or a number representing minutes from midnight. Default is current time.

LatLng Class

var point = new pe.LatLng(latitude, longitude); 

Creates a LatLng object. Needed for extractPolyline, computeDistanceBetween, and computeLength.

Extracting Part of a Polyline

extractPolyline(polyline, start, end)

Extracts a part of a polyline given the start and end point on or near the polyline.

• polyline : Array of coordinate point. The points have the format [latitude, longitude]
• start and end : LatLng objects representing the start and end points.

Returns the following object

{
   polyline: polylineSlice, 
   start: {
       point : new LatLng(lat, lng); 
       distance : distanceFromStartPoint;
       id : id; 
   }, 
   end: {
       point : new LatLng(lat, lng); //The actual end point for the polyline. 
       distance : nextDistance;
       id : id;
   }
};

Where:

• polyline is the extracted polyline slice. An Array of LatLng objects.
• start and end give information about the starting and ending point of the new polyline.
• point is the actual start point for the polyline. A LatLng object.
• distance is the distance from the given start or end point. Equals 0 if the given point falls on the polyline.
• id is the index of the start or end point in the original polyline array.

Distance Between Two Points

computeDistanceBetween(pt1, pt2)

Computes the distance between two points on a map in meters. Based on calculations from http://www.movable-type.co.uk/scripts/latlong.html.

This uses the ‘haversine’ formula to calculate the great-circle distance between two points – that is, the shortest distance over the earth’s surface – giving an ‘as-the-crow-flies’ distance between the points (ignoring any hills they fly over, of course!)

• pt1 and pt2 : LatLng objects representing the points for which the distance between is required.

Returns the distance in meters.

Polyline Length

Computes the length of a given polyline.

computeLength(polyline)

Where:

• polyline : The polyline to compute the length for. An Array of LatLng objects.

Returns the length of the polyline in meters.

Logging

Toggle verbose output. (Currently doesn't output much). Logging is disabled by default.

setLogging(isLoggingEnabled)

Where:

• isLoggingEnabled is a boolean to enable/disable logging.

Mapping a Point to a Polyline

Maps a given point to the nearest point on the given polyline.

findNearestPoint(polyline, point))

Where:

• polyline is an Array of LatLng points
• point is a LatLng object

Returns the original point's projection on the polyline in the form of a LatLng object.