2nd/10_Wiki/Topics/Frontend/CesiumJS.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-cesiumjs	CesiumJS	10_Wiki/Topics	verified	self	Cesium Cesium.js	none	A	0.9	applied	3d geospatial webgl frontend mapping		2026-05-10	pending	language framework JavaScript / TypeScript WebGL2 / WebGPU

CesiumJS

매 한 줄

"매 browser 의 3D digital globe + geospatial visualization 의 standard". CesiumJS 는 WGS84 ellipsoid 의 정확 globe 의 WebGL/WebGPU 렌더링, 3D Tiles spec 의 reference impl. 2026 도시 digital twin, drone telemetry, satellite tracking, defense visualization 의 dominant choice.

매 핵심

매 핵심 concept

• Viewer: 모든 widget 의 포함 의 main container
• Scene: 3D world (globe, sky, atmosphere)
• Camera: position + heading/pitch/roll, FlyTo 의 지원
• Entity: high-level data-driven object (point, polygon, model)
• Primitive: low-level direct GPU 의 access
• 3D Tiles: streaming hierarchical 3D dataset (city, photogrammetry)
• Terrain: heightmap (Cesium World Terrain, custom)
• Imagery: tile basemap (Bing, Mapbox, OSM)

매 좌표 system

• Cartesian3: ECEF (meters from Earth center)
• Cartographic: lon/lat/height (radians)
• Cesium.Math.toRadians/toDegrees 의 변환

매 응용

1. 도시 3D digital twin (Photogrammetry / CityGML).
2. Drone / vehicle real-time tracking.
3. Satellite orbit visualization (CZML).
4. Construction BIM overlay.
5. Disaster response (flood, wildfire).

💻 패턴

Setup (Vite + npm)

import { Viewer, Cartesian3, Math as CMath, Ion } from 'cesium';
import 'cesium/Build/Cesium/Widgets/widgets.css';

Ion.defaultAccessToken = import.meta.env.VITE_CESIUM_ION_TOKEN;

const viewer = new Viewer('cesiumContainer', {
  terrainProvider: await Cesium.createWorldTerrainAsync(),
});

viewer.camera.flyTo({
  destination: Cartesian3.fromDegrees(-122.4194, 37.7749, 5000),
  orientation: { heading: 0, pitch: CMath.toRadians(-45), roll: 0 },
});

Entity (point + label)

viewer.entities.add({
  position: Cartesian3.fromDegrees(127.0, 37.5, 100),
  point: { pixelSize: 12, color: Cesium.Color.YELLOW },
  label: {
    text: 'Seoul',
    font: '14px sans-serif',
    pixelOffset: new Cesium.Cartesian2(0, -20),
  },
});

3D Tiles (Photogrammetry city)

const tileset = await Cesium.Cesium3DTileset.fromIonAssetId(96188);
viewer.scene.primitives.add(tileset);
await viewer.zoomTo(tileset);

// Style 의 적용
tileset.style = new Cesium.Cesium3DTileStyle({
  color: 'color("white", 0.9)',
  show: '${Height} > 30',
});

glTF model (vehicle)

const drone = viewer.entities.add({
  position: Cartesian3.fromDegrees(127.0, 37.5, 200),
  model: {
    uri: '/models/drone.glb',
    scale: 1.0,
    minimumPixelSize: 64,
  },
  orientation: Cesium.Transforms.headingPitchRollQuaternion(
    Cartesian3.fromDegrees(127.0, 37.5, 200),
    new Cesium.HeadingPitchRoll(0, 0, 0),
  ),
});

CZML (time-dynamic)

const dataSource = await Cesium.CzmlDataSource.load('/data/flight.czml');
viewer.dataSources.add(dataSource);
viewer.clock.shouldAnimate = true;
viewer.trackedEntity = dataSource.entities.values[0];

Real-time WebSocket update

const drone = viewer.entities.add({
  id: 'drone-1',
  position: new Cesium.SampledPositionProperty(),
  point: { pixelSize: 8, color: Cesium.Color.RED },
});

const ws = new WebSocket('wss://api/telemetry');
ws.onmessage = (e) => {
  const { lon, lat, alt, t } = JSON.parse(e.data);
  drone.position.addSample(
    Cesium.JulianDate.fromIso8601(t),
    Cartesian3.fromDegrees(lon, lat, alt),
  );
};

Pick (click → entity)

viewer.screenSpaceEventHandler.setInputAction((click) => {
  const picked = viewer.scene.pick(click.position);
  if (Cesium.defined(picked) && picked.id) {
    console.log('Clicked entity:', picked.id.id);
  }
}, Cesium.ScreenSpaceEventType.LEFT_CLICK);

React 의 통합 (Resium)

import { Viewer, Entity, PointGraphics } from 'resium';
import { Cartesian3 } from 'cesium';

export function Globe() {
  return (
    <Viewer full>
      <Entity position={Cartesian3.fromDegrees(127, 37.5, 100)}>
        <PointGraphics pixelSize={10} />
      </Entity>
    </Viewer>
  );
}

매 결정 기준

상황	Approach
정확 WGS84 globe	CesiumJS
2D map only	Mapbox / MapLibre
Photogrammetry city	3D Tiles + Ion
Time-series telemetry	CZML + SampledPositionProperty
React app	Resium wrapper
Custom shader	Primitive + Material

기본값: Viewer + Entity (90% case 의 충분).

🔗 Graph

• 부모: Geospatial
• 변형: Three.js
• 응용: Digital Twin
• Adjacent: WebGL · WebGPU

🤖 LLM 활용

언제: 3D globe, photogrammetry city, satellite/drone tracking 코드 generation. 언제 X: 단순 2D map (Mapbox/MapLibre 의 lighter).

❌ 안티패턴

• Entity 의 수만 개 add: performance 의 죽음 — 매 Primitive / Cluster 의 사용.
• 모든 frame 의 entity 의 recreate: 매 GC pressure — position 의 update.
• Bundle 전체 import: Cesium 의 매 huge — tree-shake / cesium-vite plugin.
• viewer.scene.requestRender 의 무시 in requestRenderMode: 매 frame 의 frozen.

🧪 검증 / 중복

• Verified (Cesium docs, 3D Tiles OGC spec).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — CesiumJS patterns + 3D Tiles + Resium