Class S2Map

The S2 Map GPU Engine 🌎 🗺️

  ad88888ba   ad888888b,    88b           d88
 d8"     "8b d8"     "88    888b         d888
 Y8,                 a8P    88`8b       d8'88
 `Y8aaaaa,        ,d8P"     88 `8b     d8' 88 ,adPPYYba, 8b,dPPYba,  ,adPPYba,
   `"""""8b,    a8P"        88  `8b   d8'  88 ""     `Y8 88P'    "8a I8[    ""
         `8b  a8P'          88   `8b d8'   88 ,adPPPPP88 88       d8  `"Y8ba,
 Y8a     a8P d8"            88    `888'    88 88,    ,88 88b,   ,a8" aa    ]8I
  "Y88888P"  88888888888    88     `8'     88 `"8bbdP"Y8 88`YbbdP"'  `"YbbdP"'
                                                         88
                                                         88

Description

Both an S2 and WM Projection Map Engine Powered by WebGL1, WebGL2, and WebGPU.

Basic JS/TS example:

Note that the most important components to build a map are the MapOptions and the StyleDefinition.

import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions, StyleDefinition } from 's2maps-gpu';

// build a style guide of sources to fetch and layers to render
const style: StyleDefinition = { ... };
// setup options for the map
const options: MapOptions = {
  container: 'map', // the ID of the HTML element to render the map into
  // You can reference a canvas instead of a container:
  // canvas: userPulledCanvasElement
  style,
};
// Build the map
const map = new S2Map(options);

HTML Example

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Display a map</title>
    <meta name="viewport" content="initial-scale=1,width=device-width" />
    <!-- import s2maps-gpu. BE SURE TO CHECK AND UPDATE TO LATEST VERSION -->
    <script src="https://opens2.com/s2maps-gpu/v0.18.0/s2maps-gpu.min.js" crossorigin="anonymous"></script>
    <link rel="stylesheet" href="https://opens2.com/s2maps-gpu/v0.18.0/s2maps-gpu.min.css" />
  </head>
  <body>
    <div id="map"></div>
    <script>
      // grab container div
      const container = document.getElementById('map');
      // setup map style
      const style = { ... };
      // create the map
      const map = new S2Map({ style, container });
    </script>
  </body>
</html>

Events

ready: fired when the map is ready to be interacted with / make API calls. Ships this map S2Map
mouseleave: fired when the mouse leaves the map. Ships MouseLeaveMessage
mouseenter: fired when the mouse enters the map. Ships MouseEnterMessage
click: fired when the user clicks on the map. Ships MouseClickMessage
view: fired when the map view changes. Ships ViewMessage
screenshot: fired as a result of a screenshot that was requested. Ships a Uint8ClampedArray
rendered: fired when the map is fully rendered.
delete: fired to ping that the map is deleting itself.

API

S2Map.setDarkMode: Update the state of the map's UI mode. True for dark-mode, false for light-mode
S2Map.getContainer: Get the HTML element that the map is rendered into
S2Map.getCanvasContainer: Get the HTML element that the map's canvas is rendered into
S2Map.getContainerDimensions: Get the dimensions of the map's container as a [width, height] tuple
S2Map.setStyle: Set a new style, replacing the current one if it exists
S2Map.updateStyle: Update the map's current style with new attributes, by checking for changes and updating accordingly
S2Map.setMoveState: Update the users ability to move the map around or not.
S2Map.setZoomState: Update the users ability to zoom the map in and out or not.
S2Map.getView: Get the current projector's view of the world
S2Map.jumpTo: Jump to a specific location's longitude, latitude, and optionally zoom
S2Map.easeTo: Use an easing function to travel to a specific location's longitude, latitude, and optionally zoom
S2Map.flyTo: Use an easing function to fly to a specific location's longitude, latitude, and optionally zoom
S2Map.addSource: Add a new source to the map. Sources are references to data and how to fetch it.
S2Map.updateSource: Update a source already added to the map and control the method the map updates the source
S2Map.resetSource: Reset a source's data already added to the map and control the method the map updates the source
S2Map.deleteSource: Delete a source's data from the map
S2Map.addLayer: Add a new style layer to the map
S2Map.updateLayer: Update the an existing style layer in a map given the layer's name or index
S2Map.deleteLayer: Delete an existing style layer in a map given the layer's name or index
S2Map.reorderLayers: Reorder layers in the map.
S2Map.addMarker: Add new marker(s) to the map
S2Map.removeMarker: Delete a marker or collection of markers from the map
S2Map.screenshot: Take a screenshot of the current state of the map. Returns the screenshot as a Uint8ClampedArray
S2Map.awaitFullyRendered: Async function to wait for the map to have all source and layer data rendered to the screen
S2Map.delete: Delete the map instance and cleanup all it's resources

Future API

getBounds & setBounds
setProjection & getProjection
getStyle

Converters

MapLibre Map Options Converter: See plugins.convertMaplibreOptions
MapLibre Style Converter: See plugins.convertMaplibreStyle

Plugins

Sync map movements between multiple maps: See plugins.syncMove

Frameworks

React: See frameworks.ReactS2MapGPU
Vue: See frameworks.VueS2MapGPU

Hierarchy

EventTarget
- S2Map

Constructors

constructor

new S2Map(options?: MapOptions): S2Map
Parameters
- options: MapOptions = ...
  map options
Returns S2Map
Overrides EventTarget.constructor

Methods

addEventListener

addEventListener(
    type: string,
    listener: EventListenerOrEventListenerObject,
    options?: boolean | AddEventListenerOptions,
): void
Add an event listener overriding the original
Parameters
- type: string
  type of event called
- listener: EventListenerOrEventListenerObject
  event listener
- Optionaloptions: boolean | AddEventListenerOptions
  event listener options
Returns void
Overrides EventTarget.addEventListener

addLayer

addLayer(layer: LayerStyle, nameIndex?: string | number): void
Add a new style layer to the map
- If the nameIndex is a string, it will search through the existing layers for the layer with that name and add the layer at said index
- If the nameIndex is a number, it will add the layer at that index in the style.layers array.
- If no nameIndex is provided, it will add the layer at the end
Example
```
import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions } from 's2maps-gpu';

const options: MapOptions = { ... };
const map = new S2Map(options);
// Add a new style layer to the map
map.addLayer({ source: 'world', type: 'fill', color: 'red', ... });
```
Parameters
- layer: LayerStyle
  The style layer to add
- OptionalnameIndex: string | number
  The index to add the layer at
Returns void

addMarker

addMarker(
markers: MarkerDefinition | MarkerDefinition[],
sourceName?: string,
): void
Add new marker(s) to the map
- See MarkerDefinition to see the shape of a marker
Example
```
import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions } from 's2maps-gpu';

const options: MapOptions = { ... };
const map = new S2Map(options);
// add a new marker
map.addMarker({ id: 22, lat: 0, lon: 0, html: '<div>hello</div>' });
```
Parameters
- markers: MarkerDefinition | MarkerDefinition[]
  A single marker or an array of markers
- sourceName: string = '_markers'
  The name of the source to add the marker(s) to. [Default: "_markers"]
Returns void

addSource

addSource(sourceName: string, href: string): void

Add a new source to the map. Sources are references to data and how to fetch it.

Example

import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions } from 's2maps-gpu';

const options: MapOptions = { ... };
const map = new S2Map(options);
// Add a new source to the map
map.addSource('TheFreakinMoon', 'http://yup-im-the-moon.com/');

Parameters

sourceName: string
Name of the source
href: string
the location of the source data

Returns void

awaitFullyRendered

awaitFullyRendered(): Promise<void>

Async function to wait for the map to have all source and layer data rendered to the screen

Useful for ensuring the map is rendered before running tests, starting an animation, making changes, etc.

Example

import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions } from 's2maps-gpu';

const options: MapOptions = { ... };
const map = new S2Map(options);
// wait for the map to be full rendered before making future changes
await map.awaitFullyRendered();
// do more stuff

Returns Promise<void>

delete

delete(): void

Delete the map instance and cleanup all it's resources

Example

import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions } from 's2maps-gpu';

const options: MapOptions = { ... }
const map = new S2Map(options)
// do something with the map
map.delete() // cleanup

Returns void

deleteLayer

deleteLayer(nameIndex: string | number): void
Delete an existing style layer in a map given the layer's name or index
- If the nameIndex is a string, it will search through the existing layers for the layer with that name and update the layer at said index
- If the nameIndex is a number, it will use the layer at that index in the style.layers array.
Example
```
import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions } from 's2maps-gpu';

const options: MapOptions = { ... };
const map = new S2Map(options);
// Delete an existing layer
map.updateLayer(12);
```
Parameters
- nameIndex: string | number
  The index/name of the style layer to delete
Returns void

deleteSource

deleteSource(sourceNames: string | string[]): void

Delete a source's data from the map

Example

import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions } from 's2maps-gpu';

const options: MapOptions = { ... };
const map = new S2Map(options);
// Add a new source to the map
map.addSource('TheFreakinMoon', 'http://yup-im-the-moon.com/');
// Do stuff ...

// we are done rendering the moon
map.deleteSource(['TheFreakinMoon', 'anotherSourceWeDontWantAnymore']);

Parameters

sourceNames: string | string[]
A single sourceName or an array of source names

Returns void

easeTo

easeTo(directions?: AnimationDirections): void

Use an easing function to travel to a specific location's longitude, latitude, and optionally zoom

Example

import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions } from 's2maps-gpu';

const options: MapOptions = { ..., view: { lon: 0, lat: 0, zoom: 0 } };
const map = new S2Map(options);
// wait for map to load, then jump to a specific location
await map.awaitFullLoaded();
map.easeTo(-120, 60, 7);

Parameters

Optionaldirections: AnimationDirections
animation guide for travel directions, speed, and easing

Returns void

flyTo

flyTo(directions?: AnimationDirections): void

Use an easing function to fly to a specific location's longitude, latitude, and optionally zoom

Example

import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions } from 's2maps-gpu';

const options: MapOptions = { ..., view: { lon: 0, lat: 0, zoom: 0 } };
const map = new S2Map(options);
// wait for map to load, then jump to a specific location
await map.awaitFullLoaded();
map.flyTo(-120, 60, 7);

Parameters

Optionaldirections: AnimationDirections
animation guide for travel directions, speed, and easing

Returns void

getCanvasContainer

getCanvasContainer(): HTMLElement
Get the HTML element that the map's canvas is rendered into

Returns HTMLElement
The HTML element

getContainer

getContainer(): undefined | HTMLElement
Get the HTML element that the map is rendered into

Returns undefined | HTMLElement
The HTML element

getContainerDimensions

getContainerDimensions(): null | [width: number, height: number]
Get the dimensions of the map's container

Returns null | [width: number, height: number]
The dimensions of the map's container

getView

getView(): Promise<Required<View>>

Get the current projector's view of the world

Example

import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions, View } from 's2maps-gpu';

const options: MapOptions = { ..., view: { lon: 0, lat: 0, zoom: 0 } };
const map = new S2Map(options);
// Get a filled in view object
const view: Required<View> = await map.getView();

Returns Promise<Required<View>>

A filled in View object

Example

import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions } from 's2maps-gpu';

const options: MapOptions = { ..., view: { lon: 0, lat: 0, zoom: 0 } };
const map = new S2Map(options);
// wait for map to load, then jump to a specific location
await map.awaitFullLoaded();
map.jumpTo({ lon: -120, lat: 60, zoom: 7 });

Parameters

view: View
The view to jump to

Returns void

removeMarker

removeMarker(ids: number | number[], sourceName?: string): void
Delete a marker or collection of markers from the map

Example
```
import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions } from 's2maps-gpu';

const options: MapOptions = { ... };
const map = new S2Map(options);
// add a new marker
map.removeMarker(22);
```
Parameters
- ids: number | number[]
  A single marker id or an array of marker ids to delete
- sourceName: string = '_markers'
  The name of the source to remove the marker(s) from. [Default: "_markers"]
Returns void

reorderLayers

reorderLayers(layerChanges: Record<number, number>): void

Reorder layers in the map.

The key is the index of the layer to move
The value is the index to move the layer to

Example

import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions } from 's2maps-gpu';

const options: MapOptions = { ... };
const map = new S2Map(options);
// Reorder layers
map.reorderLayers({ 0: 1, 1: 0 });

Parameters

layerChanges: Record<number, number>
The guide of how to reorder the layers

Returns void

resetSource

resetSource(
    sourceNames: [sourceName: string, href: string][],
    keepCache?: boolean,
    awaitReplace?: boolean,
): void
Reset a source's data already added to the map and control the method the map updates the source

Example
```
import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions } from 's2maps-gpu';

const options: MapOptions = { ... };
const map = new S2Map(options);
// Add a new source to the map
map.addSource('TheFreakinMoon', 'http://yup-im-the-moon.com/');
// change the location of the moon
map.resetSource(['TheFreakinMoon'], false, true);
```
Parameters
- sourceNames: [sourceName: string, href: string][]
  Array of [sourceName, href]. Href is optional but if provided, the source href will be updated
- keepCache: boolean = false
  Whether to keep the cache or not. don't delete any tiles, request replacements for all (for s2json since it's locally cached and fast)
- awaitReplace: boolean = false
  Whether to await the replacement of tiles or not. to avoid flickering (i.e. adding/removing markers), we can wait for an update (from source+tile workers) on how the tile should look
Returns void

screenshot

screenshot(): Promise<null | Uint8ClampedArray<ArrayBufferLike>>

Take a screenshot of the current state of the map. Returns the screenshot as an Uint8ClampedArray.

Example

import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions } from 's2maps-gpu';

const options: MapOptions = { ... };
const map = new S2Map(options);
// wait for the map to be full rendered
await map.awaitFullyRendered();
// request the current screen
const screen = await map.screenshot();

Returns Promise<null | Uint8ClampedArray<ArrayBufferLike>>

An RGBA encoded Uint8ClampedArray that is of size canvas.width * canvas.height

setDarkMode

setDarkMode(state?: boolean): void

Update the state of the map's UI mode.

Example

import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions } from 's2maps-gpu';

const options: MapOptions = { ..., darkMode: false };
const map = new S2Map(options);
// do something with the map
map.setDarkMode(true);

Parameters

state: boolean = false
which UI mode to set the map to. true for dark-mode, false for light-mode

Returns void

setMoveState

setMoveState(state: boolean): void

Update the users ability to move the map around or not.

Example

import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions } from 's2maps-gpu';

const options: MapOptions = { ..., canMove: false };
const map = new S2Map(options);
// Update the move state so the user can move around
const screen = map.setMoveState(true);

Parameters

state: boolean
Sets the move state. If true, the user can move the map.

Returns void

setStyle

setStyle(style: StyleDefinition, ignorePosition?: boolean): Promise<void>
Set a new style, replacing the current one if it exists

Example
```
import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions, StyleDefinition } from 's2maps-gpu';

const options: MapOptions = { ... };
const map = new S2Map(options);
// setup and set a new style
const style: StyleDefinition = { ... };
await map.setStyle(style);
```
Parameters
- style: StyleDefinition
  The user defined style of how data should be rendered
- ignorePosition: boolean = true
  if set to true, don't update the map's position to the style's view guide [Default=true]
Returns Promise<void>

setZoomState

setZoomState(state: boolean): void

Update the users ability to zoom the map in and out or not.

Example

import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions } from 's2maps-gpu';

const options: MapOptions = { ..., canZoom: false };
const map = new S2Map(options);
// Update the zoom state so the user can update the zoom position
const screen = map.setZoomState(true);

Parameters

state: boolean
Sets the zoom state. If true, the user can zoom the map in and out.

Returns void

updateLayer

updateLayer(
    layer: LayerStyle,
    nameIndex: string | number,
    fullUpdate?: boolean,
): void
Update the an existing style layer in a map given the layer's name or index
- If the nameIndex is a string, it will search through the existing layers for the layer with that name and update the layer at said index
- If the nameIndex is a number, it will use the layer at that index in the style.layers array.
Example
```
import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions } from 's2maps-gpu';

const options: MapOptions = { ... };
const map = new S2Map(options);
// Update the style layer
map.updateLayer({ source: 'world', type: 'fill', color: 'red', ... }, 12);
```
Parameters
- layer: LayerStyle
  The style layer to update/replace the old layer with
- nameIndex: string | number
  The index/name of the style layer to update
- fullUpdate: boolean = true
  If true, force a full re-render of the layer. Recommended to keep true unless you know what you're doing
Returns void

updateSource

updateSource(
    sourceName: string,
    href: string,
    keepCache?: boolean,
    awaitReplace?: boolean,
): void
Update a source already added to the map and control the method the map updates the source

Example
```
import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions } from 's2maps-gpu';

const options: MapOptions = { ... };
const map = new S2Map(options);
// Add a new source to the map
map.addSource('TheFreakinMoon', 'http://yup-im-the-moon.com/');
// change the location of the moon
map.updateSource('TheFreakinMoon', 'http://now-im-the-moon.com/', false, true);
```
Parameters
- sourceName: string
  Name of the source
- href: string
  the new location of the source
- keepCache: boolean = true
  Whether to keep the cache or not. don't delete any tiles, request replacements for all (for s2json since it's locally cached and fast)
- awaitReplace: boolean = true
  Whether to await the replacement of tiles or not. to avoid flickering (i.e. adding/removing markers), we can wait for an update (from source+tile workers) on how the tile should look
Returns void

updateStyle

updateStyle(style: StyleDefinition): void

Update the map's current style with new attributes, by checking for changes and updating accordingly

Example

import { S2Map } from 's2maps-gpu'; // or you can access it via the global `window.S2Map`
import type { MapOptions, StyleDefinition } from 's2maps-gpu';

const options: MapOptions = { ..., style: { ... } };
const map = new S2Map(options);
// Update the style with new attributes
const newStyle: StyleDefinition = { ... };
map.updateStyle(newStyle);

Parameters

style: StyleDefinition
The new style to update the old style with

Class S2Map

The S2 Map GPU Engine 🌎 🗺️

Description

Basic JS/TS example:

HTML Example

Events

API

Future API

Converters

Plugins

Frameworks

Hierarchy

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns S2Map

Methods

addEventListener

Parameters

Returns void

addLayer

Example

Parameters

Returns void

addMarker

Example

Parameters

Returns void

addSource

Example

Parameters

Returns void

awaitFullyRendered

Example

Returns Promise<void>

delete

Example

Returns void

deleteLayer

Example

Parameters

Returns void

deleteSource

Example

Parameters

Returns void

easeTo

Example

Parameters

Returns void

flyTo

Example

Parameters

Returns void

getCanvasContainer

Returns HTMLElement

getContainer

Returns undefined | HTMLElement

getContainerDimensions

Returns null | [width: number, height: number]

getView

Example

Returns Promise<Required<View>>

jumpTo

Example

Parameters

Returns void

removeMarker

Example

Parameters

Returns void

reorderLayers

Example

Parameters

Returns void

resetSource

Example