Terraformer Core

  1. Terraformer.Primitive
    1. Constructor
    2. Methods
  2. Terraformer.Point
    1. Constructor
  3. Terraformer.MultiPoint
    1. Constructor
    2. Methods
  4. Terraformer.LineString
    1. Constructor
    2. Methods
  5. Terraformer.MultiLineString
    1. Constructor
    2. Methods
  6. Terraformer.Polygon
    1. Constructor
    2. Methods
  7. Terraformer.MultiPolygon
    1. Constructor
    2. Methods
  8. Terraformer.Feature
    1. Constructor
  9. Terraformer.FeatureCollection
    1. Constructor
    2. Methods
  10. Terraformer.GeometryCollection
    1. Constructor
    2. Methods
  11. Terraformer.Circle
    1. Constructor
    2. Methods
  12. Terraformer.Tools
    1. Spatial Reference Conversions
    2. Calculations
    3. Comparisons

Link Terraformer.Primitive Back to Top

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.

Link Constructor Back to Top

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

Link Methods Back to Top

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.

Link Terraformer.Point Back to Top

A JavaScript object representing a GeoJSON Point.

Link Constructor Back to Top

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]);

Link Terraformer.MultiPoint Back to Top

A JavaScript object representing a GeoJSON MultiPoint.

Link Constructor Back to Top

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] ]);

Link Methods Back to Top

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.

Link Terraformer.LineString Back to Top

A JavaScript object representing a GeoJSON LineString.

Link Constructor Back to Top

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] ]);

Link Methods Back to Top

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)

Link Terraformer.MultiLineString Back to Top

A JavaScript object representing a GeoJSON MultiLineString.

Link Constructor Back to Top

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]]
]);

Link Methods Back to Top

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.

Link Terraformer.Polygon Back to Top

A JavaScript object representing a GeoJSON Polygon.

Link Constructor Back to Top

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] ]
]);

Link Methods Back to Top

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.

Link Terraformer.MultiPolygon Back to Top

A JavaScript object representing a GeoJSON MultiPolygon.

Link Constructor Back to Top

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] ]
  ]
]);

Link Methods Back to Top

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.

Link Terraformer.Feature Back to Top

A JavaScript object representing a GeoJSON Feature.

Link Constructor Back to Top

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] ]
  ]
});

Link Terraformer.FeatureCollection Back to Top

A JavaScript object representing a GeoJSON FeatureCollection.

Link Constructor Back to Top

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]);

Link Methods Back to Top

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.

Link Terraformer.GeometryCollection Back to Top

A JavaScript object representing a GeoJSON Geometry Collection.

Link Constructor Back to Top

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]);

Link Methods Back to Top

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.

Link Terraformer.Circle Back to Top

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.

Link Constructor Back to Top

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);

Link Methods Back to Top

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.

Link Terraformer.Tools Back to Top

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

Link Spatial Reference Conversions Back to Top

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 functionagainst 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.

Link Calculations Back to Top

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.

Link Comparisons Back to Top

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