stac-layer v0.15.0

stac-layer

Visualize STAC Data on a LeafletJS Map

install

npm install stac-layer

supported data types

• STAC Collection
• Item Collection
• STAC API Collections
• STAC API Items
• STAC Item
• STAC Asset

usage

import stacLayer from 'stac-layer';

// create your Leaflet map
const map = L.map('map');

// create layer
const layer = await stacLayer(
  data,
  {
    displayOverview: true,
    displayPreview: false
  }
);

// add layer to map
layer.addTo(map);

// fit map to layer
map.fitBounds(layer.getBounds());

advanced usage

using a tiler

There's are a couple different ways to use a tiler to serve images of assets that are Cloud-Optimized GeoTIFFs.

tileUrlTemplate

You can set tileUrlTemplate, which will be passed to Leaflet's TileLayer. This will apply to whichever asset stac-layer chooses as the best GeoTIFF for visualization.

// a STAC Feature
const layer = await stacLayer(data, {
  tileUrlTemplate: "https://tiles.rdnt.io/tiles/{z}/{x}/{y}@2x?url={url}"
});

buildTileUrlTemplate

If you need more dynamic customization, consider passing in a buildTileUrlTemplate function. You can use this function to change the tile url and its parameters depending on the type of asset.

const layer = await stacLayer(data, {
  buildTileUrlTemplate: ({
    href, // the url to the GeoTIFF
    asset, // the STAC Asset object
    key, // the key or name in the assets object that points to the particular asset
    item, // the STAC item / feature
    bounds, // LatLngBounds of the STAC asset
    isCOG: true, // true if the asset is definitely a cloud-optimized GeoTIFF
    isVisual: true, // true when the asset's key is "visual" (case-insensitive)
  }) => {
    // assets has three bands of RGB, so no need to specify bands
    if (isVisual) return "https://tiles.rdnt.io/tiles/{z}/{x}/{y}@2x?url={url}";

    // select first three bands for non-visual assets, such as NAIP 4-band imagery
    // where we might want to ignore the Near-Infrared Band
    else return "https://tiles.rdnt.io/tiles/{z}/{x}/{y}@2x?url={url}&bands=1,2,3"
  }
});

useTileLayerAsFallback

If you'd like to only use a tiler if GeoRasterLayer fails, set useTileLayerAsFallback to true.

const layer = await stacLayer(data, {
  tileUrlTemplate: "https://tiles.rdnt.io/tiles/{z}/{x}/{y}@2x?url={url}",
  useTileLayerAsFallback: true
});

listening to click events

STAC Layer added a "stac" property to Leaflet's onClick events that include the STAC information of what the user clicked. It can be a STAC collection, feature, asset, or even an array of assets when a composite of multiple assets are being visualized.

const featureCollection = ....; // a GeoJSON Feature Collection of STAC Features

const layer = await stacLayer(featureCollection);
layer.on("click", e => {
  const { type, data } = e.stac;
  // type is one of "Collection", "Feature", "Assets", or "Asset"
  // data is the item that was clicked in the collection
});

accessing meta information

Sometimes you might like to know information about what is being visualized. You can access this information through the stac key attached to the layer.

const layer = await stacLayer(data, options);

layer.stac could be the following

{
  "assets": [
    {
      "key": "visual",
      "asset": {
        "href": "https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2.tif",
        "type": "image/tiff; application=geotiff; profile=cloud-optimized",
        "title": "3-Band Visual",
        "roles": [
          "visual"
        ],
        "eo:bands": [
          {
            "name": "band3",
            "common_name": "red",
            "center_wavelength": 645,
            "full_width_half_max": 90
          },
          {
            "name": "band2",
            "common_name": "green",
            "center_wavelength": 560,
            "full_width_half_max": 80
          },
          {
            "name": "band1",
            "common_name": "blue",
            "center_wavelength": 470,
            "full_width_half_max": 70
          }
        ]
      }
    }
  ],
  "bands": [
    {
      "name": "band3",
      "common_name": "red",
      "center_wavelength": 645,
      "full_width_half_max": 90
    },
    {
      "name": "band2",
      "common_name": "green",
      "center_wavelength": 560,
      "full_width_half_max": 80
    },
    {
      "name": "band1",
      "common_name": "blue",
      "center_wavelength": 470,
      "full_width_half_max": 70
    }
  ]
}

listening to fallback events

STAC Layer fires a custom "fallback" event when an error occurs rendering with GeoRasterLayer and it falls back to trying to use a tiler

const layer = await stacLayer(data, options);
layer.on("fallback", event => {
  // event.error is the initial LeafletJS error event
  // that triggered the fallback

  // layer.stac metadata may change after fallback
  // so good to check again now
});