문서 / 설정 / React / Cesium

Cesium 설정

Web에서 Cesium을 MapConductor에서 쓰는 절차입니다. 진짜 지구본으로서 3D 표시하고 싶을 때 고릅니다. cesium의 정적 애셋을 빌드에 포함하는 설정이 필요합니다.

PACKAGE

react-for-cesium

API KEY

불필요

CSS

필요

3D CAMERA

진짜

데모 보기매장 지도 · React ↗

시작하기 전에

Node.js 18 이상

정적 애셋을 배포할 수 있는 빌드 설정(Vite 등)

STEP 01

설치한다

cesium은 패키지에 동봉되어 있습니다.

terminalnpm

npm install @mapconductor/js-sdk-core @mapconductor/js-sdk-react \
            @mapconductor/react-for-cesium

STEP 02

스타일시트를 읽어 들인다

앱의 엔트리 포인트에서 한 번만 읽어 들입니다. 잊으면 지도의 위치나 컨트롤의 겉모습이 무너집니다.

main.tsxTypeScript

import '@mapconductor/react-for-cesium/style.css';

STEP 03

Cesium의 정적 애셋을 배포한다

Cesium은 Workers・Assets・Widgets・ThirdParty 같은 정적 파일을 실행 시에 읽어 들입니다. 이것들을 배포 경로에 복사하고, CESIUM_BASE_URL로 그 장소를 알려 줄 필요가 있습니다. 샘플 앱(examples/basic/vite.config.ts)이 이 설정의 실례입니다.

vite.config.tsTypeScript

// Copy node_modules/cesium/Build/Cesium/{Workers,Assets,Widgets,ThirdParty}
// into your output directory, then tell Cesium where they live:
define: {
  CESIUM_BASE_URL: JSON.stringify('/cesiumStatic/'),
}

동작 확인

여기까지 보이면 완료

지구본이 나오면 완료입니다.

CesiumMap.tsxTypeScript · React

import { useState } from 'react';
import { createGeoPoint, createMapCameraPosition, createMarkerState } from '@mapconductor/js-sdk-core';
import { Marker } from '@mapconductor/js-sdk-react';
import { CesiumDesign, CesiumMapView, useCesiumMapViewState } from '@mapconductor/react-for-cesium';
import '@mapconductor/react-for-cesium/style.css';

const TOKYO = createGeoPoint({ latitude: 35.6812, longitude: 139.7671 });

export function CesiumMap() {
  const state = useCesiumMapViewState({
    mapDesignType: CesiumDesign.Default,
    cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
  });
  const [markerState] = useState(() => createMarkerState({ id: 'tokyo', position: TOKYO }));

  return (
    <CesiumMapView state={state} style={{ height: 480 }}>
      <Marker state={markerState} />
    </CesiumMapView>
  );
}

지도 디자인

CesiumDesign은 Cesium의 ImageryProvider를 감싼 상수입니다.

CesiumDesign

Notes

Default

OpenStreetMap의 타일. 귀속 표시 포함

None

이미지 레이어 없음

잘 안 될 때

콘솔에 Worker나 애셋의 404가 나온다

정적 애셋의 복사와 CESIUM_BASE_URL의 설정을 확인합니다. Cesium은 이것들을 실행 시에 가지러 갑니다.

번들이 크다

cesium은 큰 라이브러리입니다. 3D 표시가 필요한 화면만을 동적 import로 잘라내 주세요.

개발 시에만 지도가 이중으로 초기화된다

React StrictMode는 effect를 2번 실행합니다. 각 프로바이더는 이것을 감지해 한쪽을 파기하도록 되어 있으므로, StrictMode를 뺄 필요는 없습니다.

Cesium은 진짜 3D 카메라를 가지기 때문에, tilt나 bearing이 그대로 반영됩니다. Leaflet이나 OpenLayers의 의사 3D와는 거동이 다릅니다.