# Introduction

Planetary.js is a JavaScript library for building awesome interactive globes. It uses D3 and TopoJSON to parse and render geographic data. Planetary.js uses a plugin-based architecture; even the default functionality is implemented as plugins! This makes Planetary.js extremely flexible.

The documentation is split up into several sections:

- Core API describes the top-level Planetary.js API, including installing and configuring the library and creating new planet instances.
- Planet API describes the API associated with a planet instance, including modifying its properties and accessing a special canvas context that allows you to draw on the globe.
- Plugins describes the plugin architecture of Planetary.js and shows how you can easily build your own plugins to modify the behavior of Planetary.js.
- Built-In Plugins describes each of the built-in plugins in turn, including their public API and how to use them in a project.
- FAQ answers some common question and addresses a few easy-to-miss gotchas.
- Getting Help describes what to do if you still need help after reading this documentation.

## Quick Start

If you want to get up-and-running quickly, or like to experiment and figure things out, you can use this HTML and JavaScript to get a very simple globe up and running.

Note that you'll need to run this page from a web server of some kind so that Planetary.js can load the TopoJSON data via Ajax (Ajax requests don't work when viewing a page directly from the filesystem).

Be sure to check out the examples as well!

HTML

    <html>
    <head>
      <script type='text/javascript' src='http://d3js.org/d3.v3.min.js'></script>
      <script type='text/javascript' src='http://d3js.org/topojson.v1.min.js'></script>
      <script type='text/javascript' src='planetaryjs.min.js'></script>
    </head>
    <body>
      <canvas id='globe' width='500' height='500'></canvas>
      <script type='text/javascript' src='yourApp.js'></script>
    </body>
    </html>

JavaScript

    var planet = planetaryjs.planet();
    // You can remove this statement if `world-110m.json`
    // is in the same path as the HTML page:
    planet.loadPlugin(planetaryjs.plugins.earth({
      topojson: { file: 'http/path/to/world-110m.json' }
    }));
    // Make the planet fit well in its canvas
    planet.projection.scale(250).translate([250, 250]);
    var canvas = document.getElementById('globe');
    planet.draw(canvas);