Viewer API - Cesium Utils

Cesium Utils Demo

This page demonstrates the capabilities of the @juun-roh/cesium-utils library, a utility package.

Environment

This demonstration is built using Next.js, the React framework, and leverages native Cesium APIs with a lightweight React wrapper for optimal performance and direct access to 3D geospatial capabilities.

Usage

The @juun-roh/cesium-utils package maintains vanilla CesiumJS compatibility, meaning you can use it in any Cesium project regardless of framework choice. The utilities work directly with standard Cesium objects and APIs.

Traditional CesiumJS

For traditional CesiumJS projects, import the utilities directly and use them with your existing viewer setup:

main.js

1
2import * as Cesium from "cesium";
3import { Collection } from "@juun-roh/cesium-utils/collection";
4
5async function main() {
6  let viewer;
7  try {
8    viewer = new Cesium.Viewer("container", viewerOptions);
9    
10    // Create tagged collections for organized entity management
11    const buildings = new Collection({ 
12      collection: viewer.entities, 
13      tag: "building" 
14    });
15    
16    buildings.add(buildingEntity);
17    
18    // Use collection methods for bulk operations
19    buildings.show();
20    buildings.hide();
21    buildings.removeByTag("residential");
22    
23  } catch (error) {
24    console.error("Viewer initialization failed:", error);
25  }
26}
27
28main();

React Integration

When using React, the utilities integrate seamlessly with native Cesium viewers. Access the viewer through React refs or context and apply the utility methods:

viewer.tsx

1import * as Cesium from "cesium";
2import * as React from "react";
3import { Collection } from "@juun-roh/cesium-utils/collection";
4
5export default function CesiumViewer() {
6  const containerRef = React.useRef<HTMLDivElement>(null);
7  const viewerRef = React.useRef<Cesium.Viewer>();
8  const [collections, setCollections] = React.useState<Map<string, Collection>>(new Map());
9
10  React.useEffect(() => {
11    if (!containerRef.current) return;
12
13    // Create native Cesium viewer
14    const viewer = new Cesium.Viewer(containerRef.current, {
15      baseLayerPicker: false,
16      fullscreenButton: false,
17      geocoder: false,
18      infoBox: false,
19      navigationHelpButton: false,
20      scene3DOnly: true,
21      selectionIndicator: false,
22      homeButton: false,
23    });
24
25    viewerRef.current = viewer;
26
27    // Configure viewer UI
28    viewer.bottomContainer.remove();
29
30    // Initialize utility collections
31    const buildingCollection = new Collection({
32      collection: viewer.entities,
33      tag: "building"
34    });
35
36    const roadCollection = new Collection({
37      collection: viewer.entities,
38      tag: "road"
39    });
40
41    setCollections(new Map([
42      ["buildings", buildingCollection],
43      ["roads", roadCollection]
44    ]));
45
46    // Add sample entities
47    buildingCollection.add(buildingEntity);
48    roadCollection.add(roadEntity);
49
50    return () => {
51      if (viewer && !viewer.isDestroyed()) {
52        viewer.destroy();
53      }
54    };
55  }, []);
56
57  return <div ref={containerRef} className="w-full h-full" />;
58}