1. Home
  2. Tutorials
  3. Getting started

Get GlobeKit into your Project!

NPM

  1. Ensure you have your GlobeKit API KEY and the corresponding email handy.
  2. npm install globekit-public
  3. Enter API KEY and email when prompted

Ol' Fashioned Javascript

  1. Copy globekit.esm.js into your source directory
  2. Copy gkweb_bg.wasm into your static resources
  3. Get your API Key from your GlobeKit Account Page

Basics

At the heart of GlobeKit is the GlobeKitView object. This object manages all the bits that make GlobeKit work:

  • Canvas - HTMLCanvasElement that provides a WebGLContext to draw into
  • Renderer - The mechanism that manages the WebGLContext draws into the provided HTMLCanvasElement
  • Camera - The view into the 3d world
  • InteractionController - Manages to the users interaction events like tap, pan, pinch, etc.
  • AmbientController - Manages ambient motion of the camera
  • AnimationController - Manages camera animation
  • MovementModel - Manages how the camera responds to pans, pinches, etc
  • Drawable - An object to draw on the Canvas

The GlobeKitView and Drawable objects are used for most GlobeKit applications.

Let's get an actual Hello World going.

Hello World

Before we write any code, we need to descide a few things about our globe like what should the glboe surface look like?

We use a single image to define the surface look of our Icosphere. This offsets a fair portion of runtime computation resources with a little photoshop tweaking during development. There are all kinds of textures available with a bit of searching (try earth textures in your favorite search engine).

GlobeKit Icospheres require a texture in 2:1 aspect ratio where each dimension is equal to a power of 2. For example 2048:1024, 512:256, etc. We have found that 2048:1024 is a good balance of resolution and loadtimes.

Lets get our HTML setup

<!DOCTYPE html>
<html>
  <head>
    <meta content="text/html;charset=utf-8" http-equiv="Content-Type">
    <meta content="utf-8" http-equiv="encoding">
    <style>
      body {
        margin:0;
        padding:0;
        width: 100%;
        height: 100vh;
      }

      #globekit-container {
        margin:0;
        padding:0;
        width: 100%;
        height: 100vh;
        position: relative;
      }

      #globekit-canvas {
        width:100%;
        height:100%;
        margin: 0;
        padding: 0;
      }
    </style>
    
    <script type="module" src="./myGlobe.js"></script>
  </head>
  <body>
    <div id="globekit-container">
      <canvas id="globekit-canvas"></canvas>
    </div>
  </body>
</html>

It should be noted that the canvas element is wrapped in a globekit-container object. The id does not matter other than to set CSS properties. The size of the canvas is determined by CSS.

Now lets jump into some javascript.

Step 1:

The first we need to import our GlobeKitView and Icosphere from globekit.ems.js.

import { GlobeKitView, Icosphere } from "{path/to/globekit.esm.js}";

Step 2:

Now lets setup a basic GlobeKitView options object. This object describes global settings for the GlobeKitView instance. At this point you should log into your account on globekit.co and get the your api key. Then replace {your api key} with the copied key.

const apiKey = {your api key};
const options = {
  apiKey: apiKey,
  wasmPath: {path/to/gkweb_bg.wasm},
};

Step 3:

Now we can create a GlobeKitView instance. Before we call the constructor you will need to get your HTMLCanvasElement using getElementById or something similar. In our example we assume the canvas object is named canvas

this.gkview = new GlobeKitView(canvas, options);

Step 4:

Lets create an Icosphere

this.icosphere = new Icosphere('{path/to/your/image}');

Step 5:

To add the Icosphere to the GlobeKitView, we call the function addDrawable on GlobeKitView. This function takes a callback as a parameter, onInit that gets called once the Drawable has been initialized in the WebGLContext.

Since we dont have any other drawbles to load, we can get our GlobeKitView drawing, by calling the startDrawing function on the GlobeKitView.

this.gkview.addDrawable(this.icosphere, () => {
  this.gkview.startDrawing();
});

And Presto! You should have a simple little globe on your screen, click and drag to move the globe around.

Done!

Here is the complete javascript.

import { GlobeKitView, Icosphere } from "{path/to/globekit.esm.js}";

const apiKey = {your api key};
const options = {
  apiKey: apiKey,
  wasmPath: {path/to/gkweb_bg.wasm},
};

this.gkview = new GlobeKitView(canvas, options);

this.icosphere = new Icosphere('{path/to/image/}');
this.gkview.addDrawable(this.icosphere, () => {
  this.gkview.startDrawing();
});