city3d-stac-map

A map-first STAC visualizer with native support for 3D city models. Built as part of a research project at TU Delft to bring CityJSON, CityGML, and other 3D city model formats into the STAC ecosystem.

Live demo: city3d-stac-map

What is this?

This project extends stac-map (by Development Seed) with native support for the STAC City3D Extension — a proposed STAC extension for describing 3D city model datasets.

The viewer understands city3d:* metadata fields and renders them as rich, interactive panels, including:

• Level of Detail (LoD) badges with support for decimal LoDs (per Biljecki et al.)
• City object types grouped by category (Buildings, Infrastructure, Water, Vegetation, Terrain)
• Appearance features — semantic surfaces, textures, materials
• CRS display with links to epsg.io
• Attribute schemas and city object statistics
• Support for both Item properties and Collection summaries

Supported formats

CityJSON, CityJSONSeq, FlatCityBuf, CityGML, OBJ

STAC City3D Extension

The extension adds these fields (prefix city3d:) to STAC Items and Collections:

Field	Type	Description
city3d:version	string	Spec version (e.g. "1.1" for CityJSON)
city3d:city_objects	integer / object	City object count or {min, max, total} stats
city3d:lods	[number]	Levels of Detail
city3d:co_types	[string]	City object types (Building, Bridge, Road, etc.)
city3d:attributes	[object]	Semantic attribute definitions
city3d:semantic_surfaces	boolean	Has semantic surfaces
city3d:textures	boolean	Has textures
city3d:materials	boolean	Has materials

See the full spec at cityjson/stac-city3d.

Features from upstream

In addition to City3D support, this viewer retains all features from stac-map:

• Client-side COG rendering via deck.gl-raster
• Collection rendering via web map services
• stac-geoparquet visualization, upload, and export

Development

Requires Yarn (v1 classic):

git clone [email protected]:cityjson/city3d-stac-map.git
cd city3d-stac-map
yarn install
yarn dev

The dev server starts at http://localhost:5173/stac-map/.

Code quality

yarn lint
yarn format

Testing

yarn playwright install
yarn test

Deployment

The app is deployed as a static site via GitHub Pages. See deploy.yaml.

Custom deployment

You can deploy your own instance using environment variables:

Variable	Description	Default
VITE_BASE_PATH	URL path prefix (e.g., /my-app/)	/stac-map/
VITE_DEFAULT_HREF	STAC resource to load on startup	None (shows intro)

VITE_BASE_PATH=/ VITE_DEFAULT_HREF=https://my-stac-api.com yarn build

Architecture

See docs/architecture.md for details. The core flow is:

Single href (URL param) → fetch STAC resource → render metadata + map

The City3D extension is integrated in:

• src/components/value/city3d.tsx — City3D visualization component
• src/types/stac.d.ts — TypeScript types for City3D fields
• src/components/value.tsx — Integration point for Items and Collections

Acknowledgements

This project is a fork of stac-map by Development Seed. The upstream project provides the core STAC visualization infrastructure that this fork extends.

License

See LICENSE.