@trakit/objects 0.0.9 → 0.0.10

package/API/Geography/Functions.d.ts

@@ -0,0 +1,237 @@
+import { IPoint } from '../Geometry/Interfaces';
+import { int } from '../Types';
+import { ILatLng, ILatLngBounds } from './Interfaces';
+/**
+ * The default precision used to serialize latlngs.
+ */
+export declare const DEFAULT_PRECISION = 6;
+/**
+ * The radius of the Earth in meters taken from the GRS-80, NAD83, and WGS-84 standards.
+ */
+export declare const EARTH_RADIUS: number;
+/**
+ * The ellipsoid of the Earth taken from the WGS-84 standard.
+ * @default ~298.2572
+ */
+export declare const EARTH_ELLIPSOID: number;
+/**
+ * Inversion of the ellipsoid value for calculations.
+ */
+export declare const EARTH_FLATENING: number;
+/**
+ * The minor axis radius of an ellipsoid Earth as per WGS-84.
+ * @default ~6356752.3142
+ */
+export declare const EARTH_RADIUS_MINOR: number;
+/**
+ * The surface area of the Earth in meters squared.
+ * @default 511207893395811
+ */
+export declare const EARTH_SURFACE: number;
+/**
+ *
+ */
+export declare const EARTH_RADIUS_RATIO: number;
+/**
+ *
+ */
+export declare const EARTH_RADIUS_ECCENT: number;
+/**
+ *
+ */
+export declare const EARTH_RADIUS_COM: number;
+/**
+ *
+ */
+export declare const TILE_SIZE_PX: number;
+/**
+ *
+ */
+export declare const MAX_TILE_LAT: number;
+/**
+ *
+ */
+export declare const MAX_TILE_LNG: number;
+/**
+ * Determines the map width and height (in pixels) at a specified level of detail.
+ * @param zoom	Level of detail, from 1 (lowest detail) to 23 (highest detail).
+ * @returns The map width and height in pixels.
+ */
+export declare function tileMapSize(zoom: int): int;
+/**
+ * Converts tile coordinates into pixel coordinates of the upper-left pixel of the specified tile.
+ * @param tile
+*/
+export declare function tileToPixel(tile: IPoint): IPoint;
+/**
+ * Converts pixel coordinates into tile coordinates of the tile containing the specified pixel.
+ * @param pixel
+ */
+export declare function pixelToTile(pixel: IPoint): IPoint;
+/**
+ * Converts a pixel coordinate into a LatLng at a specified level of detail.
+ * @param pixel
+ * @param zoom	Level of detail, from 1 (lowest detail) to 23 (highest detail).
+ */
+export declare function pixelToLatlng(pixel: IPoint, zoom: int): ILatLng;
+/**
+ * Converts a LatLng into a pixel coordinate at a specified level of detail.
+ * @param latlng
+ * @param zoom	Level of detail, from 1 (lowest detail) to 23 (highest detail).
+ */
+export declare function latlngToPixel(latlng: ILatLng, zoom: int): IPoint;
+/**
+ * Converts tile coordinates into a lat/lng boundary representing a complete tile.
+ * @param tile
+ * @param zoom	Level of detail, from 1 (lowest detail) to 23 (highest detail).
+ * @param grow	Number of pixels to grow the tilesize (helps with detecting stroke/border overlaps).
+ */
+export declare function tileToBounds(tile: IPoint, zoom: int, grow?: number): ILatLngBounds;
+/**
+ * Converts pixel coordinates of a tile into a lat/lng boundary.
+ * @param pixel
+ * @param zoom	Level of detail, from 1 (lowest detail) to 23 (highest detail).
+ * @param grow	Number of pixels to grow the tilesize (helps with detecting stroke/border overlaps).
+ */
+export declare function pixelToBounds(pixel: IPoint, zoom: int, grow?: number): ILatLngBounds;
+/**
+ * Returns the number of meters per pixel at the given latitude and zoom level.
+ * @param lat
+ * @param zoom
+ */
+export declare function metresPerPixel(lat: number, zoom: int): number;
+/**
+ * Checks to see if a given latitude is at one of the poles.
+ * @param latitude
+ */
+export declare function LATITUDE_IS_POLE(latitude: number): boolean;
+/**
+ * Normalizes a latitude value between +/- 90.
+ * Values of greater than 90 are returned as 90, and values less than -90 are returned as -90.
+ * @param latitude
+ * @param edge
+ */
+export declare function LATITUDE_NORMALIZED(latitude: number, edge?: number): number;
+/**
+ * Normalizes a longitude value between +/- 180.
+ * Values of greater than 180 are returned as a negative difference of 360, and values less than -180 are returned as a positive difference of 360.
+ * @param longitude
+ * @param latitude	When given, will check if the latitude is a pole, and converts the longitude to zero.
+ */
+export declare function LONGITUDE_NORMALIZED(longitude: number, latitude?: number): number;
+/**
+ * The distance in meters before considering to coordinates to have the same location.
+ * @default 0.000000001
+ */
+export declare const MAX_SAME_DISTANCE = 1e-9;
+/**
+ * Bearing from coordinate A to coordinate B in degrees from North.
+ * @param first	The starting coordinate.
+ * @param last	The ending coordinate.
+ * @return		Degrees from North.
+ */
+export declare function LATLNG_ANGLE(first: ILatLng, last: ILatLng): number;
+/**
+ * Calculates the distance between two coordinates on a sphere.
+ * @param first	The starting coordinate.
+ * @param last	The ending coordinate.
+ */
+export declare function LATLNG_DISTANCE(first: ILatLng, last: ILatLng): number;
+/**
+ * Calculates the distance between two coordinates on a Bessel 1841 ellipsoid.
+ * @param start	The starting coordinate.
+ * @param end	The ending coordinate.
+ */
+export declare function LATLNG_DISTANCE_VINCENTY(start: ILatLng, end: ILatLng): number;
+/**
+ * Calculates the orthogonal height of a triangle.  The orthogonal height is
+ * calculated by drawing a line between the coordinate A and coordinate B,
+ * then getting the length of a line drawn up from the line to the mid
+ * coordinate at a 90 degree angle.
+ * @param first		Left-most coordinate on the great circle.
+ * @param middle	Top-most coordinate's latitude.
+ * @param last		Right-most coordinate's longitude on the great circle.
+ * @return			Value is negative when distance is to the right, and positive when distance to the left.
+ */
+export declare function LATLNG_GREAT_CIRCLE(first: ILatLng, middle: ILatLng, last: ILatLng): number;
+/**
+ * Calculates the final coordinate based on the given starting coordinate and vector.
+ * @param pin		The staring coordinate.
+ * @param meters	The distance away from this LatLng.
+ * @param bearing	The direction in which to calculate the new position in degrees from North.
+ * @throws {Error}	Either latitude or longitude is NaN.
+ */
+export declare function LATLNG_TRANSLATE(pin: ILatLng, meters: number, bearing: number): ILatLng;
+/**
+ * Calculates the mid-point between to given coordinate.
+ * @param first		Left-most coordinate.
+ * @param last		Right-most coordinate.
+ * @throws {Error}	Either latitude or longitude is NaN.
+ */
+export declare function LATLNG_MIDPOINT(first: ILatLng, last: ILatLng): ILatLng;
+/**
+ * Calculates the spherical-cap area occupied by the given radial distance.
+ * @param pin		The coordinate at which to calculate the area.
+ * @param radius	The distance from the centre of the circle to any point along the edge.
+ */
+export declare function SPHERECAP_AREA(pin: ILatLng, radius: number): void;
+/**
+ * Calculates the length of the given route.
+ * @param route
+ */
+export declare function ROUTE_LENGTH(route: ILatLng[]): number;
+/**
+ * Performs a Douglas-Peucker path reduction based on the given tolerance.
+ * @param route		The array of coordinates representing a path.
+ * @param tolerance	Distance (in meters) threshold for candidate coordinates.  Default is 0.
+ */
+export declare function ROUTE_PEUCKER(route: ILatLng[], tolerance: number): ILatLng[];
+/**
+ * An implementation of Google's Encoded Polyline Algorithm format.
+ * https://developers.google.com/maps/documentation/utilities/polylinealgorithm
+ * @param route		The array of coordinates representing a path.
+ * @param precision			Optional number of decimal places to use to calculate the results.  Default is 5.
+ */
+export declare function ROUTE_ENCODE(route: ILatLng[], precision?: number): string;
+/**
+ * An implementation of Google's Decoded Polyline Algorithm format.
+ * https://developers.google.com/maps/documentation/utilities/polylinealgorithm
+ * @param route			The encoded string which represents the coordinates in a path.
+ * @param precision			Optional number of decimal places used to recalculate the results.  Default is 5.
+ */
+export declare function ROUTE_DECODE(route: string, precision?: number): ILatLng[];
+/**
+ * Finds the widest section of the given route.
+ * This is useful for path reduction and reorientation.
+ * @param route		The array of coordinates representing a path
+ * @return			An array of three items; the first is the widest distance, and the others are the start and end index within the given route.
+ */
+export declare function GEOFENCE_WIDEST(route: ILatLng[]): [number, number, number];
+/**
+ * Performs a Douglas-Peucker path reduction on a polygon for the given
+ * tolerance. The start/end coordinates are variable and the end coordinate
+ * is trimmed from the result.
+ * @param route		The array of coordinates representing a path
+ * @param tolerance	Distance (in meters) threshold for candidate coordinates.  Default is 0.
+ */
+export declare function GEOFENCE_PEUCKER(route: ILatLng[], tolerance?: number): ILatLng[];
+/**
+ * Calculates the total area occupied by the given geofence.
+ * @param route		The array of coordinates representing a geofence.
+ * @throws {Error}	Not enough coordinates.
+ */
+export declare function GEOFENCE_AREA(route: ILatLng[]): number;
+/**
+ * A utility export function to determine if a given coordinate is inside the given geofence.
+ * @param route	The array of coordinates represents the path of the polygon.
+ * @param pin	The coordinate to be checked.
+ */
+export declare function GEOFENCE_CONTAINS(route: ILatLng[], pin: ILatLng): boolean;
+/**
+ * Wraps the given coordinates into a polygonal path.
+ * The given coordinates do not need to be a path.
+ * The returned path is not closed.
+ * @param coordinates	The array of coordinates on which to create the non-closed path
+ */
+export declare function GEOFENCE_WRAPPER(route: ILatLng[]): ILatLng[];
+//# sourceMappingURL=Functions.d.ts.map

package/API/Geography/Interfaces.d.ts

@@ -0,0 +1,151 @@
+import { datetime, nothing } from '../Types';
+/**
+ * A coordinate on the Earth.
+ */
+export interface ILatLng {
+    /**
+     * Latitude.
+     */
+    lat: number;
+    /**
+     * Longitude.
+     */
+    lng: number;
+}
+/**
+ * Returns true if the given pin conforms to the {@link ILatLng} interface.
+ * @param pin
+ * @returns
+ */
+export declare function ILatLng_instanceOf(pin: any): pin is ILatLng;
+/**
+ *
+ * @param dot
+ * @returns
+ */
+export declare function ILatLng_clone(dot: ILatLng): ILatLng;
+/**
+ * GPS position information.
+ */
+export interface IPosition extends ILatLng {
+    /**
+     * Speed
+     */
+    speed: number | nothing;
+    /**
+     * Direction of travel
+     */
+    bearing: number | nothing;
+    /**
+     * Distance in meters from the sea level
+     */
+    altitude: number | nothing;
+    /**
+     * Threshold in meters for the accuracy of a position
+     */
+    accuracy: number | nothing;
+    /**
+     * The Date/Time of the GPS reading
+     */
+    dts: datetime;
+    /**
+     * A description of the current road-segment
+     */
+    address: string | nothing;
+    /**
+     * A better description of the current road-segment
+     */
+    streetAddress: IStreetAddress | nothing;
+    /**
+     * The posted speed limit for the road segment
+     */
+    speedLimit: number | nothing;
+}
+/**
+ * Returns true if the given pin conforms to the {@link IPosition} interface.
+ * @param pin
+ * @returns
+ */
+export declare function IPosition_instanceOf(pin: any): pin is IPosition;
+/**
+ * A road segment description.
+ */
+export interface IStreetAddress {
+    /**
+     * House number.
+     */
+    number: string | null;
+    /**
+     * Full street name.
+     */
+    street: string | null;
+    /**
+     * City name.
+     */
+    city: string | null;
+    /**
+     * Region name.
+     */
+    region: string | null;
+    /**
+     * Province or state code.
+     * Codes should be a value from ISO 3166-2.
+     */
+    province: string;
+    /**
+     * Country code.
+     * Codes should be a value from ISO 3166-1 alpha-2.
+     */
+    country: string;
+    /**
+     * Postal or zip code.
+     */
+    postal: string | null;
+    /**
+     * Indicates that there is a toll for the current road segment.
+     */
+    isToll: boolean | null;
+}
+/**
+ * Returns true if the given pin conforms to the {@link IStreetAddress} interface.
+ * @param address
+ * @returns
+ */
+export declare function IStreetAddress_instanceOf(address: any): address is IStreetAddress;
+/**
+ * A rectangular boundary on a flat surface.
+ */
+export interface ILatLngBounds {
+    /**
+     * Northern latitude
+     */
+    north: number;
+    /**
+     * Eastern longitude
+     */
+    east: number;
+    /**
+     * Southern latitude
+     */
+    south: number;
+    /**
+     * Western longitude
+     */
+    west: number;
+}
+/**
+ * Returns true if the given box conforms to the {@link ILatLngBounds} interface.
+ * @param box
+ */
+export declare function ILatLngBounds_instanceOf(box: any): box is ILatLngBounds;
+/**
+ *
+ * @param box
+ * @returns
+ */
+export declare function ILatLngBounds_clone(box: ILatLngBounds): ILatLngBounds;
+/**
+ * The types used to extend a {@link LatLngBounds}'s edges.
+ */
+export type LatLngBoundsExpansion = ILatLng | ILatLngBounds | LatLngBoundsExpansion[];
+//# sourceMappingURL=Interfaces.d.ts.map

package/API/Geography/LatLng.d.ts

@@ -0,0 +1,87 @@
+import { Point } from '../Geometry/Point';
+import { JsonObject } from '../Types';
+import { ILatLng } from './Interfaces';
+import { LatLngBounds } from './LatLngBounds';
+/**
+ * A coordinate on the Earth.
+ */
+export declare class LatLng implements ILatLng {
+    /**
+     * Let's consider the zero-zero coordinates to be invalid.
+     */
+    static readonly INVALID: LatLng;
+    /**
+     *
+     * @param json
+     */
+    static fromJSON(json: ILatLng | JsonObject): LatLng;
+    /**
+     *
+     * @param latlng
+     * @param delimiter
+     * @returns
+     */
+    static fromString(latlng: string, delimiter?: string): LatLng;
+    /**
+     * Latitude
+     */
+    readonly lat: number;
+    /**
+     * Longitude
+     */
+    readonly lng: number;
+    constructor(lat: number, lng: number);
+    /**
+     * Returns a string representation of this {@link LatLng}.
+     * @param delimiter	The boundary is delimited by a comma (,) by default, but you can override with your own value.
+     * @returns A string in the format of "lat,lng".
+     */
+    toString(delimiter?: string): string;
+    /**
+     * Creates a literal of this {@link LatLng}.
+     * Used internally by {@link JSON.stringify}.
+     */
+    toJSON(): ILatLng;
+    /**
+     * Compares this LatLng to another to see if they are equivalent.
+     * @param other		The other LatLng to compare
+     * @param tolerance	Distance tolerance before considering two nearly identical coordinates to be equal.
+     */
+    isEqual(other: ILatLng, tolerance?: number): boolean;
+    /**
+     * Returns true if this coordinate is not NaN and not zero-zero.
+     */
+    isValid(): boolean;
+    /**
+     * Calculates the distance across the surface of the globe to another coordinate
+     * @param pin
+     */
+    distanceTo(pin: ILatLng): number;
+    /**
+     * Calculates the starting bearing across the surface of the globe from the current coordinate to the given coordinate
+     * @param pin
+     */
+    bearingTo(pin: ILatLng): number;
+    /**
+     * Returns a new coordinate at the given distance and bearing from this coordinate
+     * @param meters
+     * @param bearing
+     */
+    toTranslated(meters: number, bearing: number): LatLng;
+    /**
+     * Returns a new LatLng at the half-way point between this and the given LatLng.
+     * @param pin	The other coordinate.
+     * @throws {Error}	Either latitude or longitude is NaN
+     */
+    toBetween(pin: ILatLng): LatLng;
+    /**
+     * Creates a Point based on the given magnifier.
+     */
+    toRadians(magnifier?: number): Point;
+    /**
+     * Creates a square LatLngBounds centred around this LatLng.
+     * @param radius	The closest distance (in meters) from this coordinate to the edges of the new LatLngBounds.
+     */
+    toBounds(radius: number): LatLngBounds;
+}
+//# sourceMappingURL=LatLng.d.ts.map

package/API/Geography/LatLngBounds.d.ts

@@ -0,0 +1,147 @@
+import { ISerializable } from '../Interfaces/ISerializable';
+import { JsonObject } from '../Types';
+import { ILatLng, ILatLngBounds, LatLngBoundsExpansion } from './Interfaces';
+import { LatLng } from './LatLng';
+/**
+ * A boundary on the globe
+ */
+export declare class LatLngBounds implements ILatLngBounds, ISerializable {
+    /**
+     *
+     * @param json
+     */
+    static fromJSON(json: ILatLngBounds | JsonObject): LatLngBounds;
+    /**
+     * Northern latitude
+     */
+    north: number;
+    /**
+     * Eastern longitude
+     */
+    east: number;
+    /**
+     * Southern latitude
+     */
+    south: number;
+    /**
+     * Western longitude
+     */
+    west: number;
+    constructor(...args: LatLngBoundsExpansion[]);
+    /**
+     * Returns a string representation of this {@link LatLng}.
+     * @param delimiter	The boundary is delimited by a comma (,) by default, but you can override with your own value.
+     * @returns A string in the format of "lat,lng".
+     */
+    toString(delimiter?: string): string;
+    /**
+     * Creates a literal of this {@link LatLngBounds}.
+     * Used internally by {@link JSON.stringify}.
+     */
+    toJSON(): {
+        north: number;
+        east: number;
+        south: number;
+        west: number;
+    };
+    /**
+     * Compares this LatLng to another to see if they are equivalent.
+     * @param other		The other LatLng to compare
+     * @param tolerance	Distance tolerance before considering two nearly identical coordinates to be equal.
+     */
+    isEqual(other: ILatLngBounds, tolerance?: number): boolean;
+    /**
+     *
+     */
+    isValid(): boolean;
+    /**
+     *
+     */
+    isEmpty(): boolean;
+    /**
+     * Checks if a {@link LatLng} is contained within this boundary.
+     * @param pin	The point to check
+     */
+    contains(pin: ILatLng): boolean;
+    /**
+     * Checks if a {@link LatLngBounds} is contained within this boundary.
+     * @expose
+     * @this {LatLngBounds}
+     * @param bounds	The other boundary to check
+     */
+    encloses(bounds: ILatLngBounds): boolean;
+    /**
+     * Checks if a {@link LatLngBounds} overlaps this boundary.
+     * Also returns true if either boundary's {@link LatLngBounds#encloses} returns true.
+     * @param other	The other boundary to check
+     */
+    overlaps(other: ILatLngBounds): boolean;
+    /**
+     *
+     * @param object
+     */
+    private __expander;
+    /**
+     * Extends the boundary to envelop the given point(s) but does not automatically
+     *		validate. This comes in efficient when doing many operations on a single
+     *		PointBounds
+     */
+    expand(latlngs: LatLngBoundsExpansion): this;
+    /**
+     * Extends the boundary to envelop the given point(s) and automatically validates
+     */
+    extend(latlngs: LatLngBoundsExpansion): this;
+    /**
+     *
+     */
+    getCentre(): LatLng;
+    /**
+     *
+     */
+    getNorthEast(): LatLng;
+    /**
+     *
+     */
+    getNorthWest(): LatLng;
+    /**
+     *
+     */
+    getSouthEast(): LatLng;
+    /**
+     *
+     */
+    getSouthWest(): LatLng;
+    /**
+     * The mid-point coordinate between the north east and north west corners.
+     */
+    getNorthMiddle(): LatLng;
+    /**
+     * The mid-point coordinate between the south east and south west corners.
+     */
+    getSouthMiddle(): LatLng;
+    /**
+     * The mid-point coordinate between the north east and north west corners.
+     */
+    getEastMiddle(): LatLng;
+    /**
+     * The mid-point coordinate between the south east and south west corners.
+     */
+    getWestMiddle(): LatLng;
+    /**
+     * The distance in meters between the north-east corner and the south-west corner.
+     */
+    getDiagonalDistance(): number;
+    /**
+     * The distance in meters between the north-most border and the south-most border.
+     */
+    getLatitudinalDistance(): number;
+    /**
+     * The distance in meters between the east-most and the west-most points along the border closest to the equator.
+     */
+    getLongitudinalDistance(): number;
+    /**
+     *
+     */
+    validate(): this;
+}
+//# sourceMappingURL=LatLngBounds.d.ts.map

package/API/Geography/Position.d.ts

@@ -0,0 +1,75 @@
+import { datetime, JsonObject, nothing } from '../Types';
+import { IPosition, IStreetAddress } from './Interfaces';
+import { LatLng } from './LatLng';
+import { StreetAddress } from './StreetAddress';
+/**
+ * GPS position information
+ */
+export declare class Position extends LatLng implements IPosition {
+    /**
+     *
+     * @param json
+     * @returns
+     */
+    static fromJSON(json: IPosition | JsonObject): Position;
+    /**
+     * Speed
+     */
+    readonly speed: number;
+    /**
+     * Direction of travel
+     */
+    readonly bearing: number;
+    /**
+     * Distance in meters from the sea level
+     */
+    readonly altitude: number;
+    /**
+     * Threshold in meters for the accuracy of a position
+     */
+    readonly accuracy: number;
+    /**
+     * The Date/Time of the GPS reading
+     */
+    readonly date: Date;
+    /**
+     * The Date/Time of the GPS reading
+     */
+    get dts(): string;
+    /**
+     * A better description of the current road-segment
+     */
+    readonly streetAddress: StreetAddress | null;
+    /**
+     * The posted speed limit for the road segment
+     */
+    readonly speedLimit: number | nothing;
+    /**
+     * Provider Identifier
+     */
+    readonly origin: string;
+    /**
+     * The road segment description
+     */
+    readonly address: string;
+    constructor(lat?: number | nothing, lng?: number | nothing, speed?: number | nothing, bearing?: number | nothing, accuracy?: number | nothing, dts?: Date | number | datetime | nothing, address?: string | nothing, limit?: number | nothing, altitude?: number | nothing, street?: IStreetAddress | JsonObject | nothing);
+    /**
+     * Returns a text representation of this position.
+     * Returned strings cannot be converted back into {@link Position}
+     * objects, so don't use this for deserialization.
+     * @param delimiter
+     */
+    toString(delimiter?: string): string;
+    /**
+     * Creates a literal of this {@link Position}.
+     * Used internally by {@link JSON.stringify}.
+     */
+    toJSON(): IPosition;
+    /**
+     *
+     * @param position
+     * @returns
+     */
+    isEqual(position: Position | IPosition): boolean;
+}
+//# sourceMappingURL=Position.d.ts.map