Terraformer

# Terraformer Core

## 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 `Terraformer.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 new `Terraformer.Primitive` objects by passing it a valid GeoJSON Object. This will return the a `Terraformer.Primitive` of the type that corresponds with type of 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 objects coordinates to the web mercator spatial reference.
`toGeographic()` | `this` | Converts this GeoJSON objects coordinates to geographic coordinates.
`envelope()` | `Envelope` | Return 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` | Returns the convex hull of this primitive as a `Polygon`.
`contains(<Geometry> geometry)` | `Boolean` | Returns `true` if the passed `GeoJSON Geometry` object is completely contains this primitive.
`within(<Geometry> geometry)` | `Boolean` | Returns `true` if the passed `GeoJSON Geometry` object is completely within this primitive.
`interesects(<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 like `[longitude, latitude]`.

    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 coordinates 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 an array that is valid coordinate array for GeoJSON MultiLineString.

    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 an array that is a valid coordinates for a GeoJSON Polygon.

    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 to the end of the coordinate array. Equivalent to `polygon.coordinates.push([3,4])`.
`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.

## 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 coordinates 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 GeometryCollection)[/glossary/#Geometrycollection].

### 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 coordinates 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([45.65, -122.27], 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 objects coordinates to the web mercator spatial reference. This is an in place modification of the passed object.
`toGeographic(<GeoJSON> geojson)` | `GeoJSON` | Converts this GeoJSON objects 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 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` | Return 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 a `coordinate` array and a `coordinate` and returns `true` if the point falls within the coordinate array.
`polygonContainsPoint(<Polygon> polygon, <Coordinate> coordinate)` | `Boolean` | Accepts 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 `coordinates` and returns `true` if the passed coordinates are equal to each other.