three-geospatial: modular GIS rendering for Three.js

What three-geospatial adds to a Three.js application

three-geospatial addresses a specific gap between general-purpose Three.js graphics and specialized geographic rendering. Three.js supplies the rendering foundation, but applications that depict planetary or geospatial scenes can require atmospheric scattering, volumetric clouds, GIS data helpers, and effects that work with those scenes. This repository packages those concerns separately instead of requiring an application to adopt an all-in-one Web GIS stack.

The intended users are developers building spatial or planetary experiences with Three.js and, in the documented examples, React Three Fiber. The repository also identifies `3d-tiles-renderer` and `astronomy-engine` as complementary libraries rather than parts of its own package suite. That positioning matters: three-geospatial is a collection of rendering additions, not a replacement for every service involved in loading tiles, astronomy calculations, mapping, or application state.

There are four publishable npm packages. `@takram/three-atmosphere` implements precomputed atmospheric scattering and is marked Beta. `@takram/three-clouds` provides geospatial volumetric clouds and is also marked Beta. `@takram/three-geospatial`, published from the `core` package, provides fundamental functions for rendering GIS data and is marked Alpha. `@takram/three-geospatial-effects` contains post-processing effects and is marked Alpha. Applications can therefore adopt one concern rather than every package.

The repository also distinguishes publishable packages from examples. Anything outside the four packages listed in the README is considered an example and is not intended for production use. That boundary is easy to overlook because the source tree includes apps, examples, and Storybook material, but it gives integrators a clear packaging rule.

Package boundaries and their intended use

The package split follows rendering concerns. `atmosphere` is dedicated to precomputed atmospheric scattering, which places atmosphere generation in its own package rather than coupling it to clouds or effects. `clouds` focuses on geospatial volumetric clouds. `core` contains the lower-level GIS rendering functions, while `effects` groups post-processing behavior that can be applied around a scene.

This design reduces the amount of functionality an application needs to pull in, but it does not make the packages a simplified application framework. Integration still depends on surrounding libraries and application code. The repository lists `astronomy-engine` as a dependency in the root package configuration and describes it as a complementary astronomy library. It also names `3d-tiles-renderer`, Three.js, and R3F as libraries with which the project is designed to work.

The package table assigns different maturity labels. Neither Beta nor Alpha means the repository claims a finished production package for every use case. The most conservative interpretation is to select the package needed for one rendering feature, validate it inside the target application, and avoid treating the entire collection as a uniform release line.

There is also a more fundamental transition beneath these boundaries. The current architecture uses shader-chunk-based post-processing, while the WebGPU implementation is being rewritten around nodes. The planned WebGPU API will be incompatible with the current one. Package boundaries remain conceptually useful, but consumers should distinguish a normal three-geospatial import from code written for the future node-based interface.

Current WebGL and incoming WebGPU architecture

The documented architecture currently depends on shader chunks for post-processing. The author is working on WebGPU support through a complete API rewrite associated with the move to a node-based approach. According to the README, the new design already performs better and provides more flexibility, but those statements describe the author's development direction rather than an independent performance result.

The planned feature set includes physically plausible atmosphere lookup tables, atmospheric lighting for all materials at large scale, crepuscular rays, light shafts, volumetric shadows on scene objects, geometry-based lens glare, support for transparent and transmission materials, temporal antialiasing, and screen-space shadows. Those items describe intended WebGPU capabilities. The repository's status table reports that WebGPU work for `atmosphere` and `core` is done, `clouds` is in progress, and `effects` is to be merged with `core`.

The future does not necessarily remove WebGL. The README states that a WebGL fallback will remain possible after the node-based implementation supersedes the shader-chunk architecture. However, “possible” is not the same as a documented compatibility guarantee. The repository does not provide a migration guide, nor does it specify how existing custom shader chunks should be translated into nodes.

For an application already built around the current API, this is an adoption constraint rather than a distant footnote. Teams should identify whether their scene depends on custom post-processing or shader chunks before choosing an API target. Teams beginning new WebGPU-oriented work still face an incomplete package transition: clouds remain in progress and effects are not yet represented as a separately completed WebGPU package.

Installing the monorepo and running the first Storybook

The README documents repository development rather than a minimal application installation command. To obtain the source and install its workspace dependencies, clone the repository, enter its directory, and run the package manager command specified by the project.

git clone [email protected]:takram-design-engineering/three-geospatial.git
cd three-geospatial
pnpm install

The repository stores assets with Git LFS. If the checkout does not contain those assets correctly, install Git LFS and pull them with the documented command.

git lfs pull

After installation, the first useful entry point is Storybook because it contains stories for the libraries and demonstrates usage without requiring the reader to construct an application first. Start it with Nx. The default port is 4400.

nx storybook

The reader should expect the Storybook interface on port 4400. A different local port can be requested with the documented `--port` option.

nx storybook --port 8080

Some stories may require external map or terrain credentials. Create a `.env` file in the repository root with `STORYBOOK_GOOGLE_MAP_API_KEY` or `STORYBOOK_ION_API_TOKEN` when the corresponding story needs that service. The README does not claim that either variable is required for every story.

Storybook also drives the documented Nx workspace. `nx build` builds all libraries and apps, `nx build-libs` builds only the libraries, `nx test` runs unit tests, and `nx lint` checks conventions. Library and app targets are mostly inferred, so `nx show project {name}` is the documented way to inspect targets for a specific project.

Repository layout, examples, and build boundaries

The workspace is managed with Nx and organized into several deliberately different areas. The `packages` directory contains the publishable npm packages. The `storybook` directory contains demonstration stories across the libraries. The README says stories are separated from libraries to avoid circular dependencies. Story files and components are separated again to enable fast refresh, which depends on files containing components only.

The `apps` directory contains standalone applications, including a `data` command-line application for generating data. Separate `examples` and `storybook-webgpu` directories are also visible in the repository layout. Their presence should not be confused with the production package set. The README explicitly classifies packages not listed in its package table as examples and says they are not intended for production use.

This separation affects dependency decisions and maintenance. An application can consume a published npm package without pulling the entire application and example surface into production. A developer evaluating integration can inspect Storybook before writing scene code. Contributors, however, work in a larger workspace whose build, lint, test, and format commands operate across multiple projects.

The project is not archived, and its last push was on 2026-05-27. Recent `core` releases include `[email protected]` on 2026-05-06, `[email protected]` on 2026-04-27, and `[email protected]` on 2026-04-05. This shows recent `core` release activity, but the README does not provide an equivalent release schedule for every package. Upgrade planning should therefore track the selected package rather than assuming all four versions move together.

Limitations that affect production evaluation

The clearest limitations are package maturity and the WebGPU transition. The atmosphere and clouds packages are marked Beta, while core and effects are marked Alpha. The README does not define a production-readiness checklist or a support policy for these labels. Code that relies on package internals should be reviewed against the documentation for the exact package and renderer path.

The examples warning is equally important. Only the four named packages are presented as publishable libraries. Other packages under the repository are examples and are explicitly not intended for production use. An application that copies an example package wholesale could therefore adopt code outside the intended support boundary.

The repository also records intermittent Storybook dependency-optimization failures and the browser error `R3F: Hooks can only be used within the Canvas component!`. The author says these problems are more likely around branch changes when a commit has not failed in GitHub Actions. The documented recovery path removes `storybook/node_modules`, resets Nx, and starts Storybook again.

rm -r storybook/node_modules
nx reset
nx storybook

If that does not resolve the problem, the README suggests clearing the browser cache. This is a real operational weakness in the local documentation workflow. A clean build does not guarantee that every branch change produces an immediately usable Storybook instance.

License handling is comparatively simple. The repository identifies the project as MIT licensed. That identifies the license, but applications still need to review the exact package files and dependency terms that apply to their distribution.

How three-geospatial differs from surrounding GIS libraries

The most useful comparison is with `3d-tiles-renderer`, which the README describes as an existing library that works alongside this project. `3d-tiles-renderer` is outside the three-geospatial package suite, while three-geospatial packages atmospheric rendering, volumetric clouds, GIS rendering functions, and scene effects. The repository gives no benchmark or feature matrix comparing their tile-loading behavior, so it would be inaccurate to claim that one replaces the other.

The same boundary applies to `astronomy-engine`. The README identifies it as a complementary astronomy library, and the root `package.json` includes `astronomy-engine` as a dependency. Three-geospatial can provide rendering functions around such a library, but the repository does not say that it supplies general ephemeris calculation or every astronomy service an application needs.

React Three Fiber is also an integration layer rather than the package itself. The stories and repository dependencies show support for a React-based Three.js workflow, while the underlying packages remain render-oriented libraries. This makes three-geospatial suitable for teams already using that stack, but less suitable for someone seeking a complete mapping application with an established application model, UI, data catalog, and deployment service.

Its defining alternative to an all-in-one Web GIS engine is selectivity. Instead of accepting one broad architecture, an application can choose atmosphere without clouds, core without effects, or another single concern. The cost is integration responsibility: the consumer must understand compatibility, package maturity, and renderer transitions.

Editorial conclusion

three-geospatial suits Three.js or React Three Fiber developers evaluating focused atmospheric, cloud, GIS, or post-processing modules. It is a weaker choice for applications that need documented production support across every package or that would be disrupted by the incompatible WebGPU API. Before adoption, verify the status of the required package, review its API documentation, and test the renderer path used by the application, especially if it involves WebGPU.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. takram-design-engineering/three-geospatial on GitHub