Home

This wiki acts as an official documentation for the <little-planet> HTML element.

How to include

The <little-planet> element is distributed via NPM. The canonical way is:

1. npm install little-planet
2. <script type="module" src="node_modules/little-planet"></script>

Alternatively, you can use a CDN (such as jsDelivr or UNPKG) that can provide the necessary hosting:

• <script type="module" src="https://cdn.jsdelivr.net/npm/little-planet"></script>
• <script type="module" src="https://unpkg.com/little-planet"></script>

Basic usage

The easiest way to utilize the <little-planet> element is to simply declare it along with other HTML markup. You need to specify the source image URL and dimensions.

<little-planet src="my-panorama.jpg" width="400" height="400"></little-planet>

There are more HTML attributes that can be specified (see below). Alternatively, the JS API offers full control.

API

HTML

Individual <little-planet> instances can be configured using attributes. Attribute values are only used to initialize the element; this implies that

1. it is pointless to modify them later (they are not reflected to DOM properties),
2. they are not updated on interaction (DOM properties are not reflected back).

This behavior might change in the future.

All valid attributes are:

• width and height specify rendering dimensions. See the Sizes & Resolutions example for an in-depth explanation and sizing options.
• src is the source image URL. Can be both relative or absolute, but note that cross-origin images need to be served with CORS headers.
• static makes the planet/panorama non-interactive. This also means that scrolling (over the image) is propagated to a parent scrollable element, such as the page itself.
• mode specifies one of the two cardinal viewing modes: "planet" or "pano". When absent, the "planet" value is used.

JS/DOM

The JS API is used to configure and modify the <little-planet> at runtime. These properties have the same semantics as attributes:

• width and height (numbers)
• src (string)
• static (boolean)
• mode (string, "planet" or "pano")

These properties are read-only:

• planetSize is the maximum theoretical size of the square planet image
• canvas is a shortcut to the underlying <canvas> element (if you need to access it directly)

These properties are read/write:

• camera is an object describing current camera state; it contains three sub-properties. It is okay to set only some of them:
  • lat (number): latitude, -90 ≤ lat ≤ 90
  • lon (number): longitude, -180 ≤ lon ≤ 180
  • fov (number): field of view (horizontal for landscape, vertical for portrait), 50 ≤ fov ≤ 120

Events

You can listen for the following DOM events:

• load when an image URL is successfully loaded,
• error when the image cannot be fetched