[디지털 트윈] React에서 CesiumJS 사용하기

728x90

React에서 CesiumJS 사용하기 

CesiumJS는 3D 지구본과 도시 시각화를 위한 오픈소스 라이브러리입니다.

디지털 트윈 프로젝트를 준비하며, 웹 브라우저 상에서 3D 지도를 구현해보려 합니다. 본격적인 개발에 앞서 CesiumJS 환경을 먼저 구성하고, 간단한 예시 지도를 띄워보는 과정을 진행했습니다. 또한 이번 작업은 폐쇄망(인터넷이 단절된 환경)을 전제로 하기 때문에, Cesium Ion은 사용하지 않습니다.

 

---

개발 환경

• Node v22.16.0
• React v19.1.0 (TypeScript) + Vite

개발 순서

1. Cesium 설치하기
2. 정적 리소스 복사하기
3. Cesium 환경 설정하기
4. 기본 뷰어 코드 작성하기 (Ion 제거)

참고 사이트

• CesiumJS 공식 사이트 : https://cesium.com/platform/cesiumjs/

 

---

1.  Cesium 설치하기

먼저 Cesium을 설치합니다. 이 단계는 인터넷 연결이 가능한 개발 환경에서 진행해야 합니다.

npm install cesium

설치 후 node_modules/cesium 경로에 Cesium 관련 모든 리소스가 포함됩니다.

 

---

2.  정적 리소스 복사하기

Cesium은 .js, .wasm, .glsl, .png, .ttf 등 다양한 정적 리소스를 런타임에 직접 요청합니다.
Vite에서 이를 자동 처리하기 위해, 우리는 vite-plugin-static-copy를 사용해 Cesium 리소스를 빌드시 /dist/cesiumStatic/ 폴더로 복사합니다.
이와 함께 CESIUM_BASE_URL 경로도 /cesiumStatic으로 지정해 Cesium이 필요한 리소스를 올바르게 불러올 수 있도록 설정합니다.

플러그인 설치 명령어

npm install vite-plugin-static-copy --save-dev

vite.config.ts 설정 (예시)

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { viteStaticCopy } from 'vite-plugin-static-copy';
import path from 'path';

const cesiumSource = 'node_modules/cesium/Build/Cesium';
const cesiumBaseUrl = 'cesiumStatic';

export default defineConfig({
  define: {
    CESIUM_BASE_URL: JSON.stringify(`/${cesiumBaseUrl}`),
  },
  plugins: [
    react(),
    viteStaticCopy({
      targets: [
        { src: `${cesiumSource}/Assets`, dest: cesiumBaseUrl },
        { src: `${cesiumSource}/Widgets`, dest: cesiumBaseUrl },
        { src: `${cesiumSource}/ThirdParty`, dest: cesiumBaseUrl },
        { src: `${cesiumSource}/Workers`, dest: cesiumBaseUrl },
      ],
    }),
  ],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
});

 

---

3.  Viewer 띄우기 (Cesium Ion 없이)

import { useEffect, useRef } from 'react';
import * as Cesium from 'cesium';
import 'cesium/Build/Cesium/Widgets/widgets.css';

const CesiumViewer = () => {
  const viewerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    Cesium.Ion.defaultAccessToken = ''; // Ion 완전 비활성화

    const viewer = new Cesium.Viewer(viewerRef.current!, {
      // imageryProvider					// 지도 타일(이미지) 제공자
      terrainProvider: new Cesium.EllipsoidTerrainProvider(),	// 지형 높낮이 정보 제공자
      // 상단 메뉴
      geocoder: false ,			// 검색 버튼
      homeButton: false,            	// 홈 버튼
      sceneModePicker: false,       	// 2D/3D 전환 버튼
      baseLayerPicker: true,		// 지도 종류 변환 버튼
      navigationHelpButton: false,  	// 도움말 버튼
      // 하단 메뉴
      creditContainer: document.createElement("div"), // Cesium ion 로고
      animation: false,         		// 시계 UI
      timeline: false,          		// 하단 타임라인
      fullscreenButton: false,  		// 풀스크린 버튼
    });
	
    // 지구 표시 관련
    viewer.imageryLayers.removeAll();
    viewer.scene.globe.show = true;		
    
    return () => viewer.destroy();
  }, []);

  return (
    <div ref={viewerRef} style={{ width: '100%', height: '100vh' }} />
  );
};

export default CesiumViewer;

 

---

4.  실행 결과

처음 실행하면, 파란 지구가 보입니다.

화면 상단에 지도 타입을 선택할 수 있는 옵션이 있습니다.

예시로 OpenStreetMap을 클릭하면, 아래와 같이 동작합니다.

 

---

다음 글 보기

[디지털 트윈] React에 CesiumJS로 건물 정보 띄우기

 

---