사용자 액션 ion 내부 처리
─────────────────────────────────────────────────────────────
[1] Add Data 클릭
│ 대시보드 또는 REST API
▼
[2] Asset Type 선택
│ 3D Model / BIM (AEC) / 3D Capture / Point Cloud / Terrain
▼
[3] 파일 업로드
│ - SaaS: AWS S3 임시 스토리지
│ - Self-Hosted: HTTP 멀티파트 → 로컬 볼륨
│ - 제한: 단일 ZIP 4GB, 파일 수 65,535개
▼
[4] NOT_STARTED → IN_PROGRESS
│ 타일러 컨테이너 기동
│ (SaaS: AWS Batch / Self-Hosted: Kubernetes Jobs)
▼
[5] 타일링 처리
│ - 지오레퍼런싱 자동 인식 또는 수동 입력
│ - LOD 생성, 텍스처 압축, 기하학 압축
│ - 3D Tiles 패키징 (SQLite 또는 파일)
▼
[6] COMPLETE
│ - 고유 assetId 부여
│ - CloudFront(SaaS) 또는 Asset Server(Self-Hosted)로 서빙
│ - Tileset URL: https://assets.ion.cesium.com/{assetId}/tileset.json
▼
[7] CesiumJS에서 사용
const tileset = await Cesium.Cesium3DTileset.fromIonAssetId(assetId);
viewer.scene.primitives.add(tileset);
처리 상태 코드
상태
의미
NOT_STARTED
타일링 대기열 초기화 중
IN_PROGRESS
처리 중 (퍼센트 진행률 포함)
COMPLETE
완료, 스트리밍 가능
DATA_ERROR
업로드된 데이터 자체의 문제 감지
ERROR
알 수 없는 타일링 오류
REST API로 폴링:
GET https://api.cesium.com/v1/assets/{assetId}
→ { "status": "IN_PROGRESS", "percentComplete": 47.2, ... }
일반적인 처리 실패 원인
대부분의 실패는 좌표/단위/원점 문제다. 업로드 전에 이 3가지만 확인해도 90%가 해결된다.
순위
원인
증상
해결
1
지오레퍼런싱(Geo-referencing) 누락
LAS/OBJ가 CRS 없이 업로드 → (0,0) 배치 또는 에러
EPSG 코드 수동 입력 또는 prj/wld 동봉
2
수직 데이터 불일치(Datum Mismatch)
Geoid 기반 높이 vs WGS84 타원체 → 모델이 공중에 뜨거나 지하에 묻힘
Geoid 보정값 적용 후 재업로드
3
로컬 원점 오류
모델 중심이 (0,0,0)이 아닌 극단적 좌표 → 타일링 중 데이터 유실
원점을 모델 중심으로 재배치
4
OBJ 비지원 태그
선(Line) 요소(l 태그) 포함 → 최적화 단계 정지
OBJ에서 line 요소 제거
5
ZIP 크기 초과
단일 ZIP 4GB 또는 65,535개 파일 초과
분할 업로드 또는 폴더 재구성
6
3D_MODEL + position 충돌
REST API로 GLB 업로드 시 position 파라미터와 충돌
glb 내장 좌표 사용 or 명시적 type 분기
사전 체크리스트
[ ] CRS 정보가 파일 또는 동반 파일(prj, wld, json)에 명시되어 있는가?
[ ] 수직 데이터(Geoid vs Ellipsoid)가 정확한가?
[ ] 모델 원점이 합리적 위치(중심 또는 그 근처)인가?
[ ] OBJ인 경우 line(`l`) 요소가 없는가?
[ ] ZIP 압축 시 단일 파일 4GB / 65,535개 미만인가?
[ ] 단위가 m / cm / mm 중 무엇인지 확인했는가?
Self-Hosted vs Cloud
항목
Cesium ion Cloud (SaaS)
Cesium ion Self-Hosted
인프라
Cesium 관리 (AWS + CloudFront)
사용자 Kubernetes 클러스터
타일링 엔진
AWS Batch
Kubernetes Jobs
자산 저장
AWS S3
SQLite + 로컬 파일시스템
인터넷 연결
필수
Air-Gapped 지원 가능
데이터 보안
AWS 보안 정책
내부망 완전 통제
글로벌 기본 데이터
Google/Bing 즉시 이용
별도 라이선스 + 캐싱 설정
업데이트
자동
Helm Chart 수동 업데이트
S3 통합
기본
v1.2 이후 S3 가져오기/내보내기
기능 동등성
—
SaaS와 동등한 기능 제공
Self-Hosted 선택 기준: 데이터를 외부로 내보낼 수 없는 정부·국방·플랜트 / 인터넷이 없는 내부망 / SaaS 트래픽 비용이 과한 초대용량 운영.