Skip to content
This repository has been archived by the owner on Mar 9, 2021. It is now read-only.

Latest commit

 

History

History
467 lines (365 loc) · 29.8 KB

core.md

File metadata and controls

467 lines (365 loc) · 29.8 KB
Raw

Terraformer Core

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

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