Terraformer Core

March 8, 2021 · View on GitHub

Terraformer.Primitive

Terraformer Primitives are JavaScript objects that map directly to their GeoJSON couterparts. Converting a GeoJSON object into a Terraformer Primitive will allow you use convenience methods like point.within(polygon).

Every Primitive inherits from the Terraformer.Primitive base class, thus all other Primitives share the Terraformer.Primitive methods.

There is a Primitive for every type of GeoJSON object, plus a Circle Primitive which represents a circle as a polygon.

Constructor

You create a new Terraformer.Primitive object by passing it a valid GeoJSON Object. This will return a Terraformer.Primitive with the same type as your GeoJSON object.

var point = new Terraformer.Primitive({
  type: "Point",
  coordinates: [1, 2],
});

point instanceof Terraformer.Point; //-> true
point instanceof Terraformer.Primitive; //-> true

point.within(polygon); //-> true or false

Methods

Method	Returns	Description
`toMercator()`	`this`	Converts this GeoJSON object's coordinates to the web mercator spatial reference.
`toGeographic()`	`this`	Converts this GeoJSON object's coordinates to geographic coordinates.
`envelope()`	`Envelope`	Returns an object with `x`, `y`, `w` and `h` suitable for passing to most indexes.
`bbox()`	`BBox`	Returns the GeoJSON Bounding Box for this primitive.
`convexHull()`	`Polygon` or `null`	Returns the convex hull of this primitive as a `Polygon`. Will return `null` if the convex hull cannot be calculated or a valid Polygon cannot be created.
`contains(<Geometry> geometry)`	`Boolean`	Returns `true` if the passed `GeoJSON Geometry` object is completely contained inside this primitive.
`within(<Geometry> geometry)`	`Boolean`	Returns `true` if the passed `GeoJSON Geometry` object is completely within this primitive.
`intersects(<Geometry> geometry)`	`Boolean`	Returns `true` if the passed `GeoJSON Geometry` intersects this primitive.

Terraformer.Point

A JavaScript object representing a GeoJSON Point.

Constructor

Terraformer.Point can be created by passing a GeoJSON Coordinate Pair like [longitude, latitude], with plain x,y, or a valid GeoJSON Point.

var point1 = new Terraformer.Point({
  type: "Point",
  coordinates: [1, 2],
});

var point2 = new Terraformer.Point(1, 2);

var point3 = new Terraformer.Point([1, 2]);

Terraformer.MultiPoint

A JavaScript object representing a GeoJSON MultiPoint.

Constructor

Terraformer.MultiPoint can be created by passing in a valid GeoJSON MultiPoint, or an array of GeoJSON Coordinates.

var multipoint1 = new Terraformer.MultiPoint({
  type: "MultiPoint",
  coordinates: [
    [1, 2],
    [2, 1],
  ],
});

var multipoint2 = new Terraformer.MultiPoint([
  [1, 2],
  [2, 1],
]);

Methods

Method	Returns	Description
`forEach(<Function> function)`	`null`	Iterates over each point. Equivalent to `multipoint.coordinates.forEach(function)`. The function will be called with `point`, `index` and `coordinates`.
`get(<Integer> index)`	`Point`	Returns a `Terraformer.Point` for the point at `index` in the coordinate array.
`addPoint(<Coordinate> coordinate)`	`this`	Adds a new coordinate to the end of the coordinate array. Equivalent to `multipoint.coordinates.push([3,4])`.
`insertPoint(<Coordinate> coordinate, index)`	`this`	Inserts the passed point at the passed index. Equivalent to `multipoint.coordinates.splice(index, 0, point)`
`removePoint(<Integer> index or <Coordinate> coordinate)`	`this`	Removes the point at `index` or the passed Coordinate depending on the type of object passed in.

Terraformer.LineString

A JavaScript object representing a GeoJSON LineString.

Constructor

Terraformer.LineString can be created by passing in a valid GeoJSON LineString, or an array of GeoJSON Coordinates like [longitude, latitude].

var linestring = new Terraformer.LineString({
  type: "LineString",
  coordinates: [
    [1, 2],
    [2, 1],
  ],
});

var linestring = new Terraformer.LineString([
  [1, 2],
  [2, 1],
]);

Methods

Method	Returns	Description
`addVertex(<Coordinate> coordinate)`	`this`	Adds a new coordinate to the end of the coordinate array. Equivalent to `linestring.coordinates.push([3,4])`.
`insertVertex(<Coordinate> coordinate, <Integer> index)`	`this`	Inserts the passed coordinate at the passed index. Equivalent to `linestring.coordinates.splice(index, 0, point)`
`removeVertex(<Integer> index)`	`this`	Removes the coordinate at `index`. Equivalent to calling `linestring.coordinates.splice(remove, 1)`

Terraformer.MultiLineString

A JavaScript object representing a GeoJSON MultiLineString.

Constructor

Terraformer.LineString can be created by passing in a valid GeoJSON MultiLineString, or a GeoJSON MultiLineString coordinate array.

var multilinestring = new Terraformer.MultiLineString({
  type: "LineString",
  coordinates: [
    [1, 2],
    [2, 1],
  ],
});

var multilinestring = new Terraformer.MultiLineString([
  [
    [1, 1],
    [2, 2],
    [3, 4],
  ],
  [
    [0, 1],
    [0, 2],
    [0, 3],
  ],
]);

Methods

Method	Returns	Description
`forEach(<Function> function)`	`null`	Iterates over each LineString. Equivalent to `multilinestring.coordinates.forEach(function)`. The function will be called with `linestring`, `index` and `coordinates`.
`get(<Integer> index)`	`LineString`	Returns a `Terraformer.LineString` for the LineString at `index` in the coordinates array.

Terraformer.Polygon

A JavaScript object representing a GeoJSON Polygon.

Constructor

Terraformer.Polygon can be created by passing in a valid GeoJSON Polygon, or GeoJSON Polygon coordinate array.

var polygon1 = new Terraformer.Polygon({
  type: "Polygon",
  coordinates: [
    [
      [100.0, 0.0],
      [101.0, 0.0],
      [101.0, 1.0],
      [100.0, 1.0],
      [100.0, 0.0],
    ],
    [
      [100.2, 0.2],
      [100.8, 0.2],
      [100.8, 0.8],
      [100.2, 0.8],
      [100.2, 0.2],
    ],
  ],
});

var polygon2 = new Terraformer.Polygon([
  [
    [100.0, 0.0],
    [101.0, 0.0],
    [101.0, 1.0],
    [100.0, 1.0],
    [100.0, 0.0],
  ],
  [
    [100.2, 0.2],
    [100.8, 0.2],
    [100.8, 0.8],
    [100.2, 0.8],
    [100.2, 0.2],
  ],
]);

Methods

Method	Returns	Description
`addVertex(<Coordinate> coordinate)`	`this`	Adds a new coordinate just before the closing coordinate of the linear ring.
`insertVertex(<Coordinate> coordinate, index)`	`this`	Inserts the passed coordinate at the passed index. Equivalent to `polygon.coordinates.splice(index, 0, point)`
`removeVertex(<Integer> index)`	`this`	Removes the coordinate at `index`. Equivalent to calling `polygon.coordinates.splice(remove, 1)`
`close()`	`this`	Ensures that the first and last vertex of the polygon are equal to each other.
`hasHoles()`	Boolean	True if this polygon has holes.
`holes()`	Array `<Polygon>`	Returns an `Array` of `Polygon` objects made from each hole in this polygon.

Terraformer.MultiPolygon

A JavaScript object representing a GeoJSON MultiPolygon.

Constructor

Terraformer.MultiPolygon can be created by passing in a valid GeoJSON MultiPolygon, or an array that is a valid coordinate array for GeoJSON MultiPolygon.

var multipolygon1 = new Terraformer.MultiPolygon({
  type: "MultiPolygon",
  coordinates: [
    [
      [
        [100.0, 0.0],
        [101.0, 0.0],
        [101.0, 1.0],
        [100.0, 1.0],
        [100.0, 0.0],
      ],
    ],
    [
      [
        [100.2, 0.2],
        [100.8, 0.2],
        [100.8, 0.8],
        [100.2, 0.8],
        [100.2, 0.2],
      ],
    ],
  ],
});

var multipolygon2 = new Terraformer.MultiPolygon([
  [
    [
      [100.0, 0.0],
      [101.0, 0.0],
      [101.0, 1.0],
      [100.0, 1.0],
      [100.0, 0.0],
    ],
  ],
  [
    [
      [100.2, 0.2],
      [100.8, 0.2],
      [100.8, 0.8],
      [100.2, 0.8],
      [100.2, 0.2],
    ],
  ],
]);

Methods

Method	Returns	Description
`forEach(<Function> function)`	`null`	Iterates over each LineString. Equivalent to `multipolygon.coordinates.forEach(function)`. The function will be called with `polygon`, `index` and `coordinates`.
`get(<Integer> index)`	`Polygon`	Returns a `Terraformer.Polygon` for the Polygon at `index` in the coordinate array.

Terraformer.Feature

A JavaScript object representing a GeoJSON Feature.

Constructor

Terraformer.Feature can be created by passing in a valid GeoJSON Feature or GeoJSON Geometry.

var feature1 = new Terraformer.Feature({
  type: "Feature",
  geometry: {
    type: "Polygon",
    coordinates: [
      [
        [100.0, 0.0],
        [101.0, 0.0],
        [101.0, 1.0],
        [100.0, 1.0],
        [100.0, 0.0],
      ],
      [
        [100.2, 0.2],
        [100.8, 0.2],
        [100.8, 0.8],
        [100.2, 0.8],
        [100.2, 0.2],
      ],
    ],
  },
});

var feature2 = new Terraformer.Feature({
  type: "Polygon",
  coordinates: [
    [
      [100.0, 0.0],
      [101.0, 0.0],
      [101.0, 1.0],
      [100.0, 1.0],
      [100.0, 0.0],
    ],
    [
      [100.2, 0.2],
      [100.8, 0.2],
      [100.8, 0.8],
      [100.2, 0.8],
      [100.2, 0.2],
    ],
  ],
});

Terraformer.FeatureCollection

A JavaScript object representing a GeoJSON FeatureCollection.

Constructor

Terraformer.FeatureCollection can be created by passing a valid GeoJSON Feature Collection or an array of GeoJSON Features.

var featurecollection1 = new Terraformer.FeatureCollection(
  "type": "FeatureCollection",
  "features": [feature1, feature2]
});

var featurecollection2 = new Terraformer.FeatureCollection([feature1, feature2]);

Methods

Method	Returns	Description
`forEach(<Function> function)`	`null`	Iterates over each Feature. Equivalent to `featurecollection.features.forEach(function)`. The function will be called with `feature`, `index` and `coordinates`.
`get(<Integer> index)`	`Feature`	Returns a `Terraformer.Feature` for the Feature at `index` in the features array.

Terraformer.GeometryCollection

A JavaScript object representing a GeoJSON Geometry Collection.

Constructor

Terraformer.GeometryCollection can be created by passing a valid GeoJSON Geometry Collection or an array of GeoJSON Geometries.

var geometrycollection1 = new Terraformer.GeometryCollection(
  "type": "FeatureCollection",
  "features": [geometry1, geometry2]
});

var geometrycollection2 = new Terraformer.GeometryCollection([geometry1, geometry2]);

Methods

Method	Returns	Description
`forEach(<Function> function)`	`null`	Iterates over each LineString. Equivalent to `geometrycollection.coordinates.forEach(function)`. The function will be called with `geometry`, `index` and `coordinates`.
`get(<Integer> index)`	`Primitive`	Returns a `Terraformer.Primitive` for the Geometry at `index` in the coordinate array.

Terraformer.Circle

The GeoJSON spec does not provide a way to visualize circles. Terraformer.Circle is actual a GeoJSON Feature object that contains a Polygon representing a circle with a certain number of sides.

Constructor

Terraformer.Circle is created with a center, radius, and steps.

Option	Type	Default	Description
`center`	`Coordinate`	`null`	Required A GeoJSON Coordinate in `[x,y]` format.
`radius`	`Integer`	`250`	The radius of the circle in meters.
`steps`	`Integer`	`32`	How many steps will be used to create the polygon that represents the circle.

circle = new Terraformer.Circle([-122.27, 45.65], 500, 64);

circle.contains(point);

Methods

Method	Returns	Description
`recalculate()`	this	Recalculates the circle
`steps(<Integer optional> steps)`	`Integer`	Returns the number of steps to produce the polygon representing the circle. If the `steps` parameter is passed the circle will be recalculated witht he new step count before returning.
`radius(<Integer optional> radius)`	`Integer`	Returns the radius circle. If the `radius` parameter is passed the circle will be recalculated witht he new radius before returning.
`center(<Coordinate optional> center)`	`Coordinates`	Returns the center of the circle. If the `center` parameter is passed the circle will be recalculated with the new center before returning.

Terraformer.Tools

Terraformer also has numerous helper methods for working with GeoJSON and geographic data. These tools work with a mix of lower level GeoJSON constructs like Coordinates, Coordinate Arrays and GeoJSON objects and Terraformer Primitives

Spatial Reference Conversions

Method	Returns	Description
`toMercator(<GeoJSON> geojson)`	`GeoJSON`	Converts this GeoJSON object's coordinates to the web mercator spatial reference. This is an in-place modification of the passed object.
`toGeographic(<GeoJSON> geojson)`	`GeoJSON`	Converts this GeoJSON object's coordinates to geographic coordinates. This is an in-place modification of the passed object.
`applyConverter(<GeoJSON> geojson), function)`	`GeoJSON`	Runs the passed `function`against every `Coordinate` in the `geojson` object. Your `function` will be passed a `Coordinate` and will be expected to return a `Coordinate`.
`positionToMercator(<Coordinate> coordinate)`	`Coordinate`	Converts the passed `Coordinate` to web mercator spatial reference.
`positionToGeographic(<Coordinate> coordinate)`	`Coordinate`	Converts the passed `Coordinate` to geographic coordinates.

Calculations

Method	Returns	Description
`calculateBounds(<GeoJSON> geojson)`	`BBox`	Returns a `GeoJSON bounding box` for the passed geoJSON.
`calculateEnvelope(<GeoJSON> geojson)`	`Envelope`	Returns an object with `x`, `y`, `w`, `h`. Suitable for passing to most indexes.
`convexHull(<GeoJSON> geojson)`	`Coordinates`	Returns an array of `coordinates` representing the convex hull the the passed geoJSON.

Comparisons

Method	Returns	Description
`coordinatesContainPoint(<[Coordinates]> coordinates, <Coordinate> coordinate)`	`Boolean`	Accepts an array of `coordinates` and a `coordinate` and returns `true` if the point falls within the coordinate array.
`polygonContainsPoint(<Polygon> polygon, <Coordinate> coordinate)`	`Boolean`	Accepts the geometry of a polygon and a `coordinate` and returns `true` if the point falls within the polygon.
`arrayIntersectsArray(<[Coordinates]> coordinates, <[Coordinates]> coordinates)`	`Boolean`	Accepts two arrays of `coordinates` and returns `true` if they cross each other at any point.
`coordinatesEqual(<Coordinate> coordinate, <Coordinate> coordinate)`	`Boolean`	Accepts two individual `coordinate` pairs and returns `true` if the passed coordinate pairs are equal to each other.

var pt = [0, 0];
var pt2 = [-111.873779, 40.647303];

var polygon = {
  type: "Polygon",
  coordinates: [
    [
      [-112.074279, 40.52215],
      [-112.074279, 40.853293],
      [-111.610107, 40.853293],
      [-111.610107, 40.52215],
      [-112.074279, 40.52215],
    ],
  ],
};

var polygonGeometry = polygon.coordinates;

Terraformer.Tools.polygonContainsPoint(polygonGeometry, pt);
// returns false
Terraformer.Tools.polygonContainsPoint(polygonGeometry, pt2);
// returns true