gistda-sphere-react

Layer

Built-in data layers, WMS/WMTS/TMS/XYZ tiles, vector styles, heatmaps, 3D tiles and deck.gl layers

<Layer> adds a layer while it's mounted and removes it when it unmounts. It covers Sphere's built-in layers, standard tile services, MapLibre styles and 3D data.

Base map:
Data layers:

import { Layer, SphereMap } from "gistda-sphere-react";

<SphereMap baseLayer="STREETS">
  <Layer preset="TRAFFIC" />
  <Layer name="bluemarble_terrain" type="WMS" url="https://ms.longdo.com/mapproxy/service" opacity={0.6} />
</SphereMap>

Props

Use one of preset, name, style or layer to choose what to show.

PropTypeDescription
presetBuiltInLayerA built-in Sphere layer, e.g. "TRAFFIC".
namestringName of a raster or 3D layer. For WMS this is the WMS layer name.
typeLayerType"Vector" (default), "XYZ", "WMS", "WMTS", "WMTS_REST", "TMS", "Tiles3D" or "I3S".
urlstringTile server or tileset URL.
stylestring | objectA MapLibre style object or style URL: vector tiles, heatmaps, clusters and other MapLibre layers.
layerobjectA ready-made layer added as is: a sphere.Layer, a deck.gl MapboxLayer or a MapLibre layer object.
isBasebooleanUse as the base map instead of adding on top. Prefer SphereMap's baseLayer.
opacitynumber0 to 1.
zIndexnumberLayers with a higher zIndex draw above lower ones.
zoomRangeRangeZoom levels where the layer is visible.
sourceRangeZoom levels the tile server has.
boundBoundOnly request tiles inside this box.
attributionstringAttribution text.
beforeIdstringInsert below this MapLibre layer ID (default: below the map labels).
extraQuerystringExtra query string for tile requests, e.g. "TIME=2024-01-01".
formatstring | falseWMS/WMTS: image MIME type (default image/png). XYZ/TMS/WMTS_REST: file extension (default png). false leaves it out.
srsstringWMS spatial reference or WMTS tile matrix set (default EPSG:3857).
stylesstringWMS/WMTS styles.
versionstringWMS version (default 1.1.1).
tileMatrixPrefixstringWMTS: part of the tile matrix name before the zoom level.
loadOptionsobjectTiles3D/I3S: loaders.gl options under 3d-tiles, i3s or tileset.
pointSizenumberTiles3D point clouds: point radius in pixels.
onTilesetLoad(tileset) => voidTiles3D/I3S: called once the tileset loads, with its cartographicCenter and zoom.
idstringUnique layer ID (default: the name).
optionsRecord<string, unknown>Extra options for new sphere.Layer().

Built-in layers

Base mapsData layers
SIMPLESimple mapTRAFFICLive traffic (refreshes every 3 minutes)
STREETSStreets (default)PM25PM2.5 air quality
STREETS_NIGHTStreets, dark themeHOTSPOTFire hotspots
HYBRIDSatellite with labelsFLOODFlood areas
IMAGESSatellite imageryDROUGHTDrought areas
import { Layer } from "gistda-sphere-react";

<Layer preset="PM25" />

Set the base map with SphereMap's baseLayer prop.

Tile services

import { Layer } from "gistda-sphere-react";

{/* WMS */}
<Layer
  name="bluemarble_terrain"
  type="WMS"
  url="https://ms.longdo.com/mapproxy/service"
  opacity={0.7}
/>

{/* WMTS (key-value) */}
<Layer name="my_layer" type="WMTS" url="https://example.com/wmts" srs="EPSG:3857" />

{/* XYZ from Sphere's own raster server (the default url) */}
<Layer name="thailand_images" type="XYZ" srs="EPSG3857" format="jpeg" />

{/* XYZ from another server: requests https://tiles.example.com/osm/{z}/{x}/{y}.png */}
<Layer name="osm" type="XYZ" url="https://tiles.example.com" />

For XYZ and TMS, Sphere builds tile URLs as {url}/{name}/{srs}/{z}/{x}/{y}.{format}, leaving out srs when it isn't set. Pass format={false} when the server's URLs have no extension.

See Custom WMS layer for a complete example.

MapLibre styles: heatmaps, clusters and vector tiles

style takes a MapLibre style object (or URL). Give its sources IDs that don't clash with other layers:

import { Layer } from "gistda-sphere-react";

<Layer
  style={{
    sources: {
      quakes: { type: "geojson", data: "https://example.com/earthquakes.geojson" },
    },
    layers: [{ id: "quakes-heat", type: "heatmap", source: "quakes" }],
  }}
/>

The 3D and advanced layers guide shows heatmaps, clustering and 3D data in action.

3D tiles and I3S

import { Layer } from "gistda-sphere-react";

<Layer
  name="buildings"
  type="Tiles3D"
  url="https://raw.githubusercontent.com/CesiumGS/3d-tiles-samples/main/1.0/TilesetWithRequestVolume/tileset.json"
  onTilesetLoad={(tileset) => {
    const [lon, lat] = tileset.cartographicCenter ?? [];
    goTo({ center: { lon, lat }, zoom: (tileset.zoom ?? 13) + 3, pitch: 60 });
  }}
/>

type="Tiles3D" loads OGC 3D Tiles (tileset.json), such as these sample buildings from Cesium. For point clouds, set pointSize, and options={{ getPointColor: [37, 99, 235, 255] }} when the points have no colors of their own (deck.gl draws them black). Everything in options goes to deck.gl's Tile3DLayer.

type="I3S" is part of Sphere's API, but Sphere's current runtime can't draw I3S meshes: the tileset loads, then deck.gl reports an error on every frame and nothing appears. Use 3D Tiles until GISTDA fixes it.

deck.gl and raw MapLibre layers

Sphere bundles deck.gl and puts it on window.deck. Wrap a deck.gl layer in deck.MapboxLayer and pass it as layer:

import { Layer } from "gistda-sphere-react";
import { useMemo } from "react";

const model = useMemo(() => {
  const { deck } = window;
  if (!deck) {
    return null;
  }
  return new deck.MapboxLayer({
    id: "model",
    type: deck.ScenegraphLayer,
    data: [{ position: [100.5, 13.7, 0] }],
    getPosition: (d: { position: number[] }) => d.position,
    scenegraph: "https://example.com/model.glb",
  });
}, []);

{model && <Layer layer={model} />}

window.deck is typed as optional, because it only exists once Sphere's script has loaded, so check it first. Inside SphereMap it's always there, since children render once the map is ready. Its members are typed loosely (DeckNamespace), so type your accessors' arguments yourself, as with d above.

Create layer objects once (with useMemo) or outside the component. A new object on every render re-adds the layer each time.

refresh and zoomOffset are also accepted and passed to Sphere unchanged.

On this page