196 lines
10 KiB
HTML
196 lines
10 KiB
HTML
<!doctype html>
|
|
<html>
|
|
<head>
|
|
<title>Planetary.js: Awesome interactive globes for the web</title>
|
|
<link href='http://fonts.googleapis.com/css?family=Source+Sans+Pro:400,700|Open+Sans:300italic,400,300,700' rel='stylesheet' type='text/css'>
|
|
<link type="text/css" rel="stylesheet" href="/semantic/css/semantic.min.css">
|
|
<link type="text/css" rel="stylesheet" href="/css/planetaryjs.css">
|
|
|
|
<meta charset="utf-8" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
<meta content="IE=edge,chrome=1" http-equiv="X-UA-Compatible">
|
|
|
|
<link href="/css/prism.css" rel="stylesheet">
|
|
</head>
|
|
<body>
|
|
<div class='ui fixed inverted large menu main-menu'>
|
|
<div class='items'>
|
|
<a class='item title' href='/'>
|
|
<i class='globe icon'></i>Planetary.js
|
|
</a>
|
|
<span class='spacer hide-on-mobile'></span>
|
|
<a class='item minor' href='https://github.com/BinaryMuse/planetary.js/releases'>
|
|
<i class='download icon'></i><span class='hide-on-mobile'>Download</span>
|
|
</a>
|
|
<a class='item minor ' href='/examples/'>
|
|
<i class='laptop icon'></i><span class='hide-on-mobile'>Examples</span>
|
|
</a>
|
|
<a class='item minor active' href='/documentation/'>
|
|
<i class='book icon'></i><span class='hide-on-mobile'>Documentation</span>
|
|
</a>
|
|
<a class='item minor' href='https://github.com/BinaryMuse/planetary.js'>
|
|
<i class='github alternate icon'></i><span class='hide-on-mobile'>Fork on GitHub</span>
|
|
</a>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
<div class='content container'>
|
|
<div class='page ui slim stackable grid'>
|
|
<div class='four wide column'>
|
|
<div class='ui fluid vertical menu'>
|
|
<a class='red item ' href='/documentation/index.html'>
|
|
Introduction
|
|
<i class='icon home'></i>
|
|
</a>
|
|
<a class='blue item ' href='/documentation/core.html'>
|
|
Core API
|
|
<i class='icon setting'></i>
|
|
</a>
|
|
<a class='orange item active' href='/documentation/planet.html'>
|
|
Planet API
|
|
<i class='icon globe'></i>
|
|
</a>
|
|
<a class='teal item ' href='/documentation/plugins.html'>
|
|
Plugins
|
|
<i class='icon edit'></i>
|
|
</a>
|
|
<a class='purple item with-subitems ' href='/documentation/builtin.html'>
|
|
Built-In Plugins
|
|
<i class='icon bolt'></i>
|
|
</a>
|
|
<div class='item contains-subitems'>
|
|
<div class='menu'>
|
|
<a class='item ' href='/documentation/builtin_earth.html'>Earth</a>
|
|
<a class='item ' href='/documentation/builtin_topojson.html'>TopoJSON</a>
|
|
<a class='item ' href='/documentation/builtin_oceans.html'>Oceans</a>
|
|
<a class='item ' href='/documentation/builtin_land.html'>Land</a>
|
|
<a class='item ' href='/documentation/builtin_borders.html'>Borders</a>
|
|
<a class='item ' href='/documentation/builtin_pings.html'>Pings</a>
|
|
<a class='item ' href='/documentation/builtin_zoom.html'>Zoom</a>
|
|
<a class='item ' href='/documentation/builtin_drag.html'>Drag</a>
|
|
</div>
|
|
</div>
|
|
<a class='red item ' href='/documentation/faq.html'>
|
|
FAQ
|
|
<i class='icon help'></i>
|
|
</a>
|
|
<a class='green item ' href='/documentation/help.html'>
|
|
Getting Help
|
|
<i class='icon phone'></i>
|
|
</a>
|
|
</div>
|
|
</div>
|
|
|
|
<div class='twelve wide column'>
|
|
<h1>Planet API</h1>
|
|
<p>A "planet" represents a single globe and its rendering instructions. It is created from the <code>planetaryjs.planet()</code> method; see the <a href="/documentation/core.html">Core API</a> documentation for more details.</p>
|
|
<p><strong><code>planet.loadPlugin(plugin)</code></strong></p>
|
|
<p>Planetary.js uses a plugin architecture for all its functionality. While you can load plugins at the global library level, Planetary.js also allows you to load plugins for specific planets. <strong>If a planet is drawn and no plugins have been loaded globally and no plugins have been loaded for the specific planet instance, it will use the default <code>earth</code> and <code>pings</code> plugins.</strong></p>
|
|
<div class='ui raise segment'>
|
|
<div class='ui red ribbon label'>JavaScript</div>
|
|
|
|
<pre><code class="language-javascript">planet.loadPlugin(somePlugin);
|
|
planet.loadPlugin(somePluginGenerator());</code></pre>
|
|
<p></div></p>
|
|
<p>For more information on the plugin system and API, please see the <a href="/documentation/plugins.html">Plugins</a> documentation.</p>
|
|
<p><strong><code>planet.projection</code></strong></p>
|
|
<p>The core of a planet's data model is an <a href="https://github.com/mbostock/d3/wiki/Geo-Projections"><code>d3.geo.projection</code></a> (specifically, an orthographic projection), which is exposed by a planet by <code>planet.projection</code>. You can use this object to control various aspects of the planet. The D3 documentation covers the methods in considerable detail, so <a href="https://github.com/mbostock/d3/wiki/Geo-Projections">be sure to check it out</a>; many of the examples on this site also use the projection object to operate.</p>
|
|
<div class='ui raise segment'>
|
|
<div class='ui red ribbon label'>JavaScript</div>
|
|
|
|
<pre><code class="language-javascript">planet.projection
|
|
.scale(width / 2)
|
|
.rotate([60, -10, 0]);</code></pre>
|
|
<p></div></p>
|
|
<p><strong><code>planet.path</code></strong></p>
|
|
<p><code>planet.path</code> is a <a href="https://github.com/mbostock/d3/wiki/Geo-Paths"><code>d3.geo.path</code></a> which uses the planet's internal projection to generate path data for geographical features. Its <code>context</code> method is commonly used by internal plugins to take a canvas context and return a path generator that can be used to draw on the globe.</p>
|
|
<div class='ui raise segment'>
|
|
<div class='ui red ribbon label'>JavaScript</div>
|
|
|
|
<pre><code class="language-javascript">canvasContext.beginPath();
|
|
planet.path.context(canvasContext)(geoFeature);
|
|
canvasContext.fill();</code></pre>
|
|
<p></div></p>
|
|
<p><strong><code>planet.plugins</code></strong></p>
|
|
<p>Planetary.js provides an empty object that plugins may use to store public data and methods. If a plugin is well-behaved, it will keep all its properties on the object under a single key (usually one that share's the plugin's name).</p>
|
|
<p><strong><code>planet.canvas</code> and <code>planet.context</code></strong></p>
|
|
<p>Once you call <code>draw</code> on a planet instance, Planetary.js will set the <code>canvas</code> and <code>context</code> properties to the canvas and its context, respectively.</p>
|
|
<p><strong><code>planet.onInit( function([done]){} )</code></strong></p>
|
|
<p>Registers a function to be called when the planet is initialized (which happens after a call to <code>draw</code> and after any loaded plugins have been initialized). This is mostly used by plugins to initialize themselves when the planet "boots."</p>
|
|
<p>If the provided callback function takes any parameters, it will be a "done" function that must be called once the initialization function finishes any asynchronous work before the planet will continue to initialize.</p>
|
|
<div class='ui raise segment'>
|
|
<div class='ui red ribbon label'>JavaScript</div>
|
|
|
|
<pre><code class="language-javascript">planet.onInit(function() {
|
|
doSomeSetupStuff();
|
|
});
|
|
|
|
planet.onInit(function(done) {
|
|
doSomeAsynchronousSetupStuff(function() {
|
|
done();
|
|
});
|
|
});</code></pre>
|
|
<p></div></p>
|
|
<p><strong><code>planet.onDraw( function(){} )</code></strong></p>
|
|
<p>Registers a function to be called each time the globe redraws itself. This is mostly used by plugins to draw plugin-specific data or otherwise animate the globe.</p>
|
|
<div class='ui raise segment'>
|
|
<div class='ui red ribbon label'>JavaScript</div>
|
|
|
|
<pre><code class="language-javascript">planet.onDraw(function() {
|
|
var rotation = planet.projection.rotate();
|
|
rotation[0] += 1;
|
|
if (rotation[0] >= 180) rotation[0] -= 360;
|
|
planet.projection.rotate(rotation);
|
|
});</code></pre>
|
|
<p></div></p>
|
|
<p><strong><code>planet.withSavedContext( function(context){} )</code></strong></p>
|
|
<p>Calls the function with the current canvas context as a parameter, wrapping the function call in <code>context.save()</code> and <code>context.restore()</code>. Use this function any time you're going to modify the context to ensure it gets put back to the way it was.</p>
|
|
<div class='ui raise segment'>
|
|
<div class='ui red ribbon label'>JavaScript</div>
|
|
|
|
<pre><code class="language-javascript">planet.onDraw(function() {
|
|
planet.withSavedContext(function(context) {
|
|
context.beginPath();
|
|
planet.path.context(context)({type: 'Sphere'});
|
|
context.fillStyle = 'black';
|
|
context.fill();
|
|
});
|
|
});</code></pre>
|
|
<p></div></p>
|
|
<p><strong><code>planet.draw(canvas)</code></strong></p>
|
|
<p>Begins drawing the globe onto the given canvas. <code>canvas</code> should be a raw DOM element (e.g. as returned by <code>document.getElementById</code>). Specifically, if it is wrapped by D3 or jQuery, you need to unwrap it with something like <code>wrappedCanvas[0]</code>.</p>
|
|
<p>Calling <code>draw</code> will perform the following operations:</p>
|
|
<ol>
|
|
<li>Initialize each loaded plugin by calling the plugin function.</li>
|
|
<li>Set <code>planet.canvas</code> and <code>planet.context</code> to the canvas and the canvas' context, respectively.</li>
|
|
<li>Run each registered <code>onInit</code> hook in the order it was registered (note that <code>onInit</code> calls made by plugins will not be made until step 1, after <code>draw</code> has been called).</li>
|
|
<li>Start the animation loop, each tick clearing the canvas and calling any registered <code>onDraw</code> hooks in order.</li>
|
|
</ol>
|
|
<div class='ui raise segment'>
|
|
<div class='ui blue ribbon label'>HTML</div>
|
|
|
|
<pre><code class="language-html"><canvas id='myCanvas' width='123' height='456'></canvas></code></pre>
|
|
<div class='ui red ribbon label'>JavaScript</div>
|
|
|
|
<pre><code class="language-javascript">var canvas = document.getElementById('myCanvas');
|
|
planet.draw(canvas);</code></pre>
|
|
<p></div></p>
|
|
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<script type='text/javascript' src='/js/prism.js'></script>
|
|
<script>
|
|
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
|
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
|
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
|
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
|
|
|
|
ga('create', 'UA-46705270-1', 'planetaryjs.com');
|
|
ga('send', 'pageview');
|
|
</script>
|
|
|
|
</body>
|
|
</html>
|