파리 Google Photorealistic 3D Tiles 48.8584° N · 2.2945° E
React 19 · three.js ≥ 0.160 · ESM + CJS + types
React를 위한
실시간 3D
지도
Real-time 3D cartography for React.
React가 마운트한 뒤에는 관여하지 않는 명령형 Three.js 엔진입니다. MapEngine이 카메라와 타일, 레이어를 소유하므로 렌더 루프가 리렌더를 기다리는 일이 없습니다.
npm i @pasquelin/map3d three react react-dom
- 버전
- 0.6.0
- 피어 의존성
- react 19 · three ≥ 0.160
- 빌드
- ESM + CJS + .d.ts
- 라이선스
- PolyForm Noncommercial
실행 가능한 데모
브라우저에서 바로 사용해 보세요
설치도 키도 필요 없습니다. 아래 데모는 푸시할 때마다 이 저장소에서 빌드되어 GitHub Pages가 그대로 제공합니다.
갤러리
궤도에서 보도까지
하나의 라이브러리가 하강 전 구간을 담당합니다. 궤도 지구본, 광역 클러스터링, 지붕 스카이라인, 발밑의 도로명.
-
12 700 km 지구본에서 평면 지도로 타원체 폴백, 지능형 클러스터링
-
9 km 마커와 클러스터 재사용되는 DOM 노드, 범주별 분할
-
3 km 스카이라인과 지평선 기울기와 무관하게 마커는 화면 크기를 유지합니다
-
900 m 좌표 격자 지면에 밀착하고 화면 선 굵기는 일정
-
1,7 m 보행자 모드 눈높이, 중력, 충돌
기능
기본으로 제공되는 것
툴바, 컨트롤, 검색, 좌표 격자, 클러스터링 등 모든 표면은 <Map> 내부에 마운트되고 설정으로 제어됩니다. 데이터만 넣으면 됩니다.
-
실사 3D, 평면 2D
cesiumIonTokenCesium Ion을 통한 Google Photorealistic 3D Tiles, 토큰이 없을 때의 타원체 지구본, 그리고 Google 또는 직접 운영하는 XYZ 서버가 제공하는 2D 베이스맵. -
DOM 마커와 클러스터
markersLayer()네이티브 hover와 포커스, CSS 애니메이션이 동작하는 실제 DOM 노드입니다. 풀링되어 단 한 번의translate3d패스로 기록되며, 움직이는 개체는 새로 만들어지는 대신 미끄러집니다. -
드로잉 편집기
draw사각형과 올가미 선택, 크기 조절과 회전 핸들, 도구별 스타일, 실행 취소와 다시 실행, GeoJSON 입출력. -
뷰포트 기반 실시간 데이터
useLiveData()카메라가 움직일 때 바운딩 박스 단위로 다시 가져오며, 실시간 갱신도 지원합니다. -
MIL-STD-2525D 심볼
동적 임포트9 MB 심볼 SDK는 필요할 때만 로드되며, 심볼을 표시하지 않는 번들에는 절대 포함되지 않습니다. -
타입이 있는 테마와 레이블
theme · labels라이트와 다크,prefers-reduced-motion준수, 전부 번역 가능. 코드에 박아 넣은 문자열이나 값이 어디에도 없습니다.
실제 동작
도구가 일하는 모습
아래 화면은 모두 위에서 열 수 있는 데모 그대로입니다. 목업이 아닙니다.
-
드로잉과 선택크기 조절과 회전 핸들, 실시간 선택 패널, 실행 취소와 다시 실행
-
MIL-STD-2525D 팔레트아군, 적대, 중립, 미상 —— SDK는 필요할 때 로드
-
카탈로그와 데이터 소스소스 하나를 켜면 252개 지점이 들어오고 클러스터가 다시 구성됩니다
-
라이트 테마설정 하나 —— 지도까지 포함해 UI 전체가 따라갑니다
빠른 시작
열두어 줄로 만드는 클러스터 지도
import { Map, markersLayer, type MarkerData } from '@pasquelin/map3d'
type Alert = { title: string }
const alerts: MarkerData<Alert>[] = [
{ id: 1, type: 'critical', position: { lat: 48.8566, lng: 2.3522 }, title: 'Intrusion', data: { title: 'Intrusion' } },
{ id: 2, type: 'info', position: { lat: 48.8606, lng: 2.3376 }, title: 'Patrol', data: { title: 'Patrol' } },
]
export function App() {
return (
<div style={{ height: '100vh' }}>
<Map
center={{ lat: 48.8566, lng: 2.3522 }}
zoom={13}
layers={[markersLayer<Alert>({ points: alerts, cluster: { enabled: true } })]}
/>
</div>
)
}
선택 플러그인 —— IGN Géoplateforme, Windy, 실내 도면 —— 은 별도 저장소에 있으며, 플러그인 API로 직접 만들 수도 있습니다.