# Terraformer

Terraformer is an open source (MIT licensed) Javascript geo toolkit, built for the server and the browser.

## Link Getting Started Back to Top

Terraformer is broken into multiple small packages to give you the functionality you need while still remaining extremely lightweight.

There are currently several packages in the Terraformer ecosystem.

- Terraformer - The core library for manipilating GeoJSON and performaing calculations. Most other modules rely on `terraformer`.
- ArcGIS Parser - Parses ArcGIS geometry objects to GeoJSON and vice-versa.
- WKT Parser - Parses basic WKT (Well Known Text) strings to and from GeoJSON.
- GeoStore - A JavaScript database for storing and querying collections of GeoJSON Features. GeoStores also need an index module and a backing store which are distributed as seperate modules.

### Link Node.js Back to Top

Install the core module with NPM and then require it in your Node program.

    $ npm install terraformer

    var Terraformer = require('terraformer');

If needed, supporting packages can be added too.

    require('terraformer-arcgis-parser');
    require('terraformer-wkt-parser');
    require('terraformer-geostore');

### Link Browser Back to Top

To use the Terraformer library, include a reference to it using a `<script>` tag.

    <script src="https://unpkg.com/terraformer@1.0.7"></script>

To utilize supporting packages, you must load their source as well.

    <script src="https://unpkg.com/terraformer-arcgis-parser@1.0.5"></script>
    <script src="https://unpkg.com/terraformer-wkt-parser@1.1.2"></script>

To see Terraformer in action in the browser, check out our live demos.

## Link Working with Primitives Back to Top

Most of the core Terraformer libray centers around using `Primitives`, which wrap GeoJSON objects and provide additional functionality.

You can create a new Terraformer.Primitive with any GeoJSON object.

    var polygon = new Terraformer.Primitive({
      "type": "Polygon",
      "coordinates": [
        [
          [-122.66589403152467, 45.52290150862236],
          [-122.66926288604736, 45.52291654238294],
          [-122.67115116119385, 45.518406234030586],
          [-122.67325401306151, 45.514000817199715],
          [-122.6684260368347, 45.5127377671934],
          [-122.66765356063841, 45.51694782364431],
          [-122.66589403152467, 45.52290150862236 ]
        ]
      ]
    });

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

Now that you have a point and a polygon primitive, you can use many of the primitive helper methods.

    // add a new vertex to our polygon
    polygon.insertVertex([-122.6708507537842, 45.513188859735436], 2);

    // figure out if our point is within our polygon
    point.within(polygon); // returns true

You can also have Terraformer perform many geometric operations like convex hulls and bounding boxes.

    var convexHull = polygon.convexHull();

    point.within(convexHull); // returns true

    var boundingBox = polygon.bbox(); // returns the geojson bounding box for this object.

## Link Whats Next? Back to Top

Start exploring all the options you have working with Primitives and the core library. Then start exploring other modules.

Terraformer GeoStore is a JavaScript database for indexing and querying large amounds of GeoJSON. You can use multiple types of spatial indexes and backing stores for your data.

You can also convert data between different formats like ArcGIS Geometries and Well Known Text. Since Terraformer is a modular framework, you can pick and choose the pieces to use in your own application.