Utility Library for CesiumJS

CesiumJS
1

New Open Source Library: Enhanced Cesium.js Utilities

Hi Cesium community! :waving_hand:

I’ve been working with Cesium for a while and noticed some common challenges that kept coming up in projects. I created a utility library to address these and wanted to share it with the community.

Problems This Solves

:globe_showing_europe_africa: Multiple Terrain Sources
Ever needed to combine high-res terrain for a specific area with global terrain? Cesium only supports one terrain provider at a time.

:building_construction: Collection Management
Managing thousands of instances without built-in tagging or filtering gets unwieldy fast.

:sparkles: Visual Highlighting
No built-in way to highlight selected entities with silhouettes or surface effects.

Solutions

Hybrid terrain sources:

import { HybridTerrainProvider } from "@juun-roh/cesium-utils";

const provider = TerrainProvider.fromUrl("your-terrain-url");
const tiles: HybridTerrainProvider.TerrainRegion["tiles"] = new Map();

// set custom region from zoom level and tile coordinates
// Level 13, tiles covering specific geographic area
tiles.set(13, {
  x: [13963, 13967], // Tile X coordinates (west to east)
  y: [2389, 2393],   // Tile Y coordinates (north to south)
});

const region: HybridTerrainProvider.TerrainRegion = {
  provider,
  tiles,
};

const terrainProvider = new HybridTerrainProvider({
  regions: [
    // multiple regions
    region,
  ],
  defaultProvider: worldTerrain
});

viewer.terrainProvider = terrainProvider;

This works as:

  • worldTerrain as the default provider
  • Custom regions override specific tile coordinates at defined zoom levels of default provider.
  • Fallback to ellipsoid terrain where tile data is unavailable.

Screenshot 2025-08-04 at 1.30.40 PM
Screenshot 2025-08-04 at 1.30.40 PM1536×1382 252 KB

mixed terrain (ellipsoid + world)

You can see other API examples on GitHub.

What I’m Looking For

  • Feedback on the API design
  • Real-world use cases I might have missed
  • Community input on the roadmap
  • Contributors interested in expanding functionality

The library is MIT licensed and designed to be lightweight with tree-shaking support.

:books: Documentation
:package: NPM Package
:wrench: GitHub Repository

Would love to hear your thoughts and experiences with these kinds of challenges!

3 Likes
2

Hey @Juun_Roh, thanks for sharing! We’re always happy to see what people in the community are doing with CesiumJS.

It sounds like some of the features you’ve implemented could help others. Specifically I’m pretty sure I’ve seen the request for multiple terrain sources before. We’re always open to community contributions and happy to review PRs from external contributors! Please check out our contributing guide if you’re interested in contributing any of these improvements back to the API.

1 Like
3

Hi @jjspace, thank you for the feedback and the invitation to contribute!

I’m definitely interested in working toward integrating the feature. You’re right that it addresses a commonly requested feature - I originally built it to solve specific terrain mixing challenges in production projects. The current implementation works for my use cases, but it would need refinement for more general usage.

Should I start by reviewing the contributing guide you linked, or would you prefer to discuss the technical approach first?

4

Yes, @Juun_Roh Please refer to the contributing guide and other documentation we have first. There’s a lot of good information in there.

would you prefer to discuss the technical approach first?

If you have a fairly stable implementation/API then you can start with a PR and we can work to review it. If the code and/or approach is still a bit up in the air and you think it needs more discussion then starting with an issue would be good.

5

The library has a separate development environment and wasn’t designed for integration into Cesium core. Let me start with an issue explaining the concepts and ideas for the terrain mixing feature.

Thanks for the guidance!

6

This is really good, thanks for sharing. I’ll try to involve myself at a later stage, happy to contribute as I’ve got various utility classes and event-driven approaches to dealing with entity interactions and the like (unless you’re allergic to RxJS …), an extra layer of entity identification and dynamic property control, and so on.

Just wanted to say thanks, and I’ll check it in more detail after this dark deadline I’ve got at the moment.

Cheers,

Alex

7

Actually just quickly, it would be great if you created exports of those odd types in the main package to avoid typing things like myTiles:HybridTerrainProvider.TerrainRegion["tiles"] = ... which could be import { HybridTerrainProvider, HybridTiles } from “util-package” instead and then define myTiles:HybridTiles = ... , it would just makes it cleaner and simpler to read the code.

Cheers,

Alex

1 Like
8

Hi @Alexander_Johannesen :waving_hand:
The types you mentioned are exported on terrain/index.ts.

import HybridTerrainProvider from "./hybrid-terrain-provider.js";

export { HybridTerrainProvider };

export type TerrainTiles = NonNullable<HybridTerrainProvider.TerrainRegion["tiles"]>;
export type TerrainRegion = HybridTerrainProvider.TerrainRegion;
export type TerrainOptions = HybridTerrainProvider.ConstructorOptions;

I’ve refactored types using namespace recently, and forgot to export these in main module :frowning:
Thanks for feedback!

1 Like