{"id":13735398,"url":"https://github.com/stac-utils/stac-layer","last_synced_at":"2025-06-23T17:12:20.824Z","repository":{"id":38192754,"uuid":"382864305","full_name":"stac-utils/stac-layer","owner":"stac-utils","description":"Visualize a STAC Item or Collection on a Leaflet Map","archived":false,"fork":false,"pushed_at":"2023-10-14T19:56:17.000Z","size":1920,"stargazers_count":54,"open_issues_count":13,"forks_count":11,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-12T08:05:57.555Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stac-utils.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2021-07-04T13:53:50.000Z","updated_at":"2025-06-03T14:57:41.000Z","dependencies_parsed_at":"2023-09-22T15:40:43.183Z","dependency_job_id":"6814c6d7-fdb5-4572-a209-dcf985f98692","html_url":"https://github.com/stac-utils/stac-layer","commit_stats":{"total_commits":172,"total_committers":4,"mean_commits":43.0,"dds":"0.35465116279069764","last_synced_commit":"f2582109b09e5057a4211c0525969d9400c2007c"},"previous_names":["danieljdufour/stac-layer"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/stac-utils/stac-layer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fstac-layer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fstac-layer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fstac-layer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fstac-layer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stac-utils","download_url":"https://codeload.github.com/stac-utils/stac-layer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fstac-layer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261434124,"owners_count":23157203,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T03:01:06.448Z","updated_at":"2025-06-23T17:12:20.729Z","avatar_url":"https://github.com/stac-utils.png","language":"HTML","funding_links":[],"categories":["`Python` processing of optical imagery (non deep learning)"],"sub_categories":["Cloud Native Geospatial"],"readme":"# stac-layer\n\u003e Visualize [STAC](https://stacspec.org/) data on a [LeafletJS](https://leafletjs.com/) map\n\n\u003cimg src=\"./stac-layer.gif\" height=200\u003e\n\n# Install\n\nTo install the version 1.0.0-beta.1 (rewrite based on stac-js):\n\n```bash\nnpm install stac-layer@next\n```\n\nTo install the old version 0.15.0:\n\n```bash\nnpm install stac-layer\n```\n\n# Supported STAC types\n\n- STAC Collection (+ Assets)\n- STAC Item (+ Assets)\n- STAC API Collections\n- STAC API Items (ItemCollection)\n\n# Usage\n\n```js\nimport stacLayer from 'stac-layer';\n\n// create your Leaflet map\nconst map = L.map('map');\n\n// set options for the STAC layer\nconst options = {\n  // see table below for supported options, for example:\n  resolution: 128,\n  map\n};\n\nconst data = fetch('https://example.com/stac/item.json')\n\n// create layer\nconst layer = stacLayer(data, options);\n\n// if the map option has not been provided:\n// add layer to map and fit map to layer \n// layer.addTo(map);\n// map.fitBounds(layer.getBounds());\n```\n\n## Parameters\n\nThe first parameter `data` is the STAC entity.\nIt can be provided as a plain JavaScript object (i.e. a deserialized STAC JSON) or\nyou can project a [stac-js](https://github.com/m-mohr/stac-js) object.\n- STAC Collection (stac-js: `Collection`)\n- STAC Item (stac-js: `Item`)\n- STAC API Collections (stac-js: `CollectionCollection`)\n- STAC API Items  (stac-js: `ItemCollection`)\n\nThe second parameter `options` allows to customize stac-layer.\nThe following options are supported:\n\n### assets\n\u003e array of objects or strings (default: undefined)\n\nIf you want to show specific assets, provide them as an array here.\nThe array can contain either the asset keys (as strings) or asset objects (plain or stac.js).\nPassing assets via this option will override `displayPreview` and `displayOverview`.\n\n### bands\n\u003e array of numbers (default: undefined)\n\nAn array mapping the bands to the output bands. The following lengths are supported:\n- `1`: Grayscale only\n- `2`: Grayscale + Alpha\n- `3`: RGB only\n- `4`: RGB + Alpha\n\n### baseUrl\n\u003e string (default: the self link of the STAC entity)\n\nThe base URL for relative links.\nShould be provided if the STAC data has no self link and links are not absolute.\n\n### crossOrigin\n\u003e string\\|null (default: undefined)\n\nThe value for the [`crossorigin` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) that is set when loading images through the browser.\n\n### displayGeoTiffByDefault\n\u003e boolean (default: false)\n\nAllow to display non-cloud-optimized GeoTiffs by default, which might not work well for larger files.\n\n### displayPreview\n\u003e boolean (default: false)\n\nAllow to display images that a browser can display (e.g. PNG, JPEG), usually assets with role `thumbnail` or the link with relation type `preview`.\nThe previews are usually not covering the full extents and as such may be placed incorrectly on the map.\nFor performance reasons, it is recommended to enable this option if you pass in STAC API Items.\n\n### displayOverview\n\u003e boolean (default: true)\n\nAllow to display COGS and/or GeoTiffs (depending on `displayGeoTiffByDefault`), usually the assets with role `overview` or `visual`.\n\nFor performance reasons, it is recommended to disable this option if you pass in STAC API Items.\n\n### debugLevel\n\u003e boolean (default: 0)\n\nThe higher the value the more debugging messages will be logged to the console. `0` to disable logging.\n\n### resolution\n\u003e integer (default: 32)\n\nAdjust the display resolution, a power of two such as 32, 64, 128 or 256. By default the value is set to render quickly, but with limited resolution. Increase this value for better resolution, but slower rendering speed (e.g., 128).\n\n### Styling\n\n#### boundsStyle\n\u003e object (default: *Leaflet defaults, but `{fillOpacity: 0}` may be set if layers are shown inside of the bounds*)\n\n[Leaflet Path](https://leafletjs.com/reference.html#path-option) (i.e. the vector style) for the bounds / footprint of the container.\n\n#### collectionStyle\n\u003e object (default: *Leaflet default, but `{fillOpacity: 0, weight: 1, color: '#ff8833'}`*)\n\n[Leaflet Path](https://leafletjs.com/reference.html#path-option) (i.e. the vector style) for individual items of API Items (ItemCollection) or collections of API Collections.\n\n### Display specific assets\n\n#### bbox / latLngBounds\n\u003e 1. [latLngBounds](https://leafletjs.com/reference.html#latlngbounds)\n\u003e 2. [West, South, East, North]\n\u003e \n\u003e Default: undefined\n\nProvide one of these options if you want to override the bounding box for a STAC Asset.\n\n### Using a Tiler\n\nThere's are a couple different ways to use a tiler to serve images of assets \nthat are Cloud-Optimized GeoTIFFs.\n\n**Note:** To enforce using server-side rendering of imagery `useTileLayerAsFallback` must be set to `false` and either `tileUrlTemplate` or `buildTileUrlTemplate` must be given.\n\n#### buildTileUrlTemplate\n\u003e function (default: undefined)\n\nIf you need more dynamic customization, consider passing in an async `buildTileUrlTemplate` function. You can use this function to change the tile url and its parameters depending on the \ntype of asset.\n\n```js\nconst layer = stacLayer(data, {\n  buildTileUrlTemplate: async ({\n    href, // the url to the GeoTIFF\n    asset, // the STAC Asset object\n    key, // the key or name in the assets object that points to the particular asset\n    stac, // the STAC Item or STAC Collection, if available\n    bounds, // LatLngBounds of the STAC asset\n    isCOG: true, // true if the asset is definitely a cloud-optimized GeoTIFF\n  }) =\u003e {\n    let bands = asset.findVisualBands();\n    if (!bands) {\n      return \"https://tiles.rdnt.io/tiles/{z}/{x}/{y}@2x?url={url}\";\n    }\n    else {\n      let indices = [\n        bands.red.index,\n        bands.green.index,\n        bands.blue.index\n      ].join(',');\n      return \"https://tiles.rdnt.io/tiles/{z}/{x}/{y}@2x?url={url}\u0026bands=\" + indices;\n    }\n  }\n});\n```\n\n### tileUrlTemplate\n\u003e string (default: undefined)\n\nYou can set `tileUrlTemplate`, which will be passed to Leaflet's [TileLayer](https://leafletjs.com/reference-1.7.1.html#tilelayer). This will apply to whichever asset stac-layer chooses as the best GeoTIFF for visualization.\n```js\n// a STAC Feature\nconst layer = stacLayer(data, {\n  tileUrlTemplate: \"https://tiles.rdnt.io/tiles/{z}/{x}/{y}@2x?url={url}\"\n});\n```\n\n### useTileLayerAsFallback\n\u003e boolean (default: false)\n\nEnables server-side rendering of imagery in case an error has happened on the client-side.\nIf you'd like to only use a tiler if [GeoRasterLayer](https://github.com/geotiff/georaster-layer-for-leaflet) fails, set `useTileLayerAsFallback` to `true`.\n\n```js\nconst layer = stacLayer(data, {\n  tileUrlTemplate: \"https://tiles.rdnt.io/tiles/{z}/{x}/{y}@2x?url={url}\",\n  useTileLayerAsFallback: true\n});\n```\n\n## Events\n\n## `click`: listening to click events\n\nSTAC 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.\n\n```js\nconst featureCollection = ....; // a GeoJSON Feature Collection of STAC Features\n\nconst layer = stacLayer(featureCollection);\nlayer.on(\"click\", event =\u003e {\n  const { type, data } = event.stac;\n  // type is one of \"Collection\", \"CollectionCollection\", \"Feature\", \"FeatureCollection\" or \"Asset\"\n  // data is the item that was clicked in the collection\n});\n```\n\n## `loaded`: once all imagery is shown\n\nSometimes you might like to know information about what is being visualized.\nYou can access this information through the `loaded` event.\n\n```js\nconst layer = stacLayer(data, options);\nlayer.on(\"loaded\", ({ data }) =\u003e {\n  // data is the stac-js object shown\n});\n```\n\n## `imageLayerAdded`: once a new image layer is added\n\nWhenever a new layer with imagery is added to the map.\nHelps to get information about which data is being visualized.\nHas parameters: `type`, `layer`, `asset`\n\nMultiple types are possible:\n- `tilelayer` A tile server layer. \n- `overview` Overview imagery layer, usually a GeoTiff or COG.\n- `preview` Preview imagery layer, usually a thumbnail in a browser-supported format such as PNG or JPEG.\n\n```js\nconst layer = stacLayer(data, options);\nlayer.on(\"imageLayerAdded\", ({ type, layer, asset }) =\u003e {\n  // type is the type of the layer\n  // layer is the Leaflet layer object\n  // asset can be a stac-js asset object\n});\n```\n\n## `fallback`: listening to fallback events\n\nSTAC Layer fires a custom \"fallback\" event when an error occurs rendering\nwith GeoRasterLayer and it falls back to trying to use a tiler.\n\n```js\nconst layer = stacLayer(data, options);\nlayer.on(\"fallback\", ({ error, asset }) =\u003e {\n  // error is the initial LeafletJS error event that triggered the fallback\n  // asset is the stac-js object for which it errored\n});\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstac-utils%2Fstac-layer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstac-utils%2Fstac-layer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstac-utils%2Fstac-layer/lists"}