getting-started.md

Terraformer

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

Getting Started

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 manipulating 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 separate modules.

Node.js

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

Browser

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

Working with Primitives

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.

Whats Next?

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.