JW's AI_Stash

CesiumJS 업데이트 정리 (2025-01-02 ~ 2026-05-14)

71 min read

CesiumJS 업데이트 정리

출처: CesiumGS/cesium CHANGES.md 최종 확인일: 2026-05-14 npm 최신 버전: cesium@1.141.0 (2026-05-14 기준)

📋 버전 목록

버전릴리즈 날짜주요 키워드
1.1412026-05-01Node 22 필수, EdgeDisplayMode, 벡터 타일 메타데이터, EquirectangularPanorama 조명 수정
1.1402026-04-01WebGL2 필수(빌보드/레이블), 벡터 프리미티브 API, WMTS GetFeatureInfo, PathGraphics.relativeTo
1.1392026-03-02Cartesian ES6 Classes, UINT 메타데이터 부호 변경, 파노라마 지원
1.1382026-02-02Intel Arc GPU 지터 수정, 복셀 메모리 개선, 2D/CV 픽 수정
1.1372026-01-05BENTLEY_materials_point/line_style, 빌보드 WebGL2 예고, clamped 레이블 수정
1.1362025-12-01scene.pickAsync (비동기 픽), 지형 픽 쿼드트리, 빌보드 수정
1.1352025-11-03KHR_gaussian_splatting 확장 전환, drillPick 너비우선, Cesium3DTilesTerrainProvider
1.1342025-10-01Voxel WebGL2 필수, defaultValue 제거, Google2DImageryProvider
1.1332025-09-02ITwinData options 객체 전용, Ellipsoid.MARS, Gaussian 구면 조화
1.1322025-08-012D 폴리곤 컬링, 재질 깜빡임, Gaussian Splat 다수 수정
1.1312025-07-01HeightReference, GaussianSplat 버그 수정, OffscreenCanvas
1.130.12025-06-16SPZ Gaussian Splat 압축, 정수 텍스처 포맷
1.1302025-06-02VoxelPrimitive 셰이더 API 변경, 이미지리 드레이핑, 3D 텍스처
1.1292025-05-01VoxelProvider 경계 API 변경, GLSL 데모, 폴리라인 수정
1.1282025-04-01Camera.getPickRay 좌표계 수정, iTwin 공유키, defaultValue 폐기
1.1272025-03-03EXT_primitive_voxels, VoxelContent API, TextureAtlas 리팩토링
1.1262025-02-03createGooglePhotorealistic3DTileset API 제거, iTwin 지리공간 기능
1.1252025-01-02iTwin 플랫폼 확장, environmentMapOptions, VoxelPrimitive 이벤트

📦 1.141 - 2026-05-01

추가일: 2026-05-14

🔴 Breaking Changes (주요 변경 사항)

  • 최소 Node.js 버전 22.0.0 상향

    • CesiumJS 빌드 및 개발 환경에서 요구하는 최소 Node.js 버전이 22.0.0으로 상향되었습니다.
    • 기술적 배경: Node 22는 V8 12.4 엔진과 안정화된 ESM/CJS 상호 운용성, 최신 WebStream API 등을 포함합니다. CesiumJS 빌드 스크립트와 개발 도구가 해당 기능들을 활용하면서 구버전 Node 지원이 제거되었습니다.
    • 영향: Node 20 이하에서 CesiumJS를 빌드하거나 개발 서버(npm start)를 실행하는 경우 동작하지 않을 수 있습니다. 런타임(브라우저)에서 사용하는 사용자에게는 영향이 없지만, CI/CD 파이프라인이나 로컬 개발 환경의 Node 버전을 확인해야 합니다.
    • 확인 및 마이그레이션: 
      # Node 버전 확인
node --version
 
# nvm 사용 시 22 설치 및 전환
nvm install 22
nvm use 22

  • BufferPrimitiveCollection 속성 readonly 전환

    • BufferPointCollection, BufferPolylineCollection, BufferPolygonCollection의 modelMatrix, boundingVolume, boundingVolumeWC 속성이 readonly로 전환되었습니다.
    • 상세 설명: 속성 자체에 재할당(reassign)은 불가능하지만, 객체 내부 값은 수정할 수 있습니다(예: collection.modelMatrix[0] = ...은 동작). 1.140에서 실험적으로 도입된 고성능 벡터 프리미티브 API의 안정화 과정에서 변경되었습니다.
    • 마이그레이션 가이드: 
      // ❌ 이전 방식 (재할당 - 더 이상 동작하지 않음)
// bufferPoints.modelMatrix = newMatrix;
 
// ✅ 새로운 방식 (Matrix4.clone으로 in-place 수정)
Cesium.Matrix4.clone(newMatrix, bufferPoints.modelMatrix);

🟢 추가 기능 (Additions)

  • EdgeDisplayMode 및 edgeDisplayMode 속성 — 모델/3D 타일셋 에지 렌더링 제어

    • 새로운 enum EdgeDisplayMode와 Model.edgeDisplayMode, Cesium3DTileset.edgeDisplayMode 속성이 추가되어 EXT_mesh_primitive_edge_visibility 확장에서 정의된 에지 렌더링을 제어할 수 있습니다.
    • 기술적 배경: EXT_mesh_primitive_edge_visibility는 메시 프리미티브의 어떤 에지를 시각적으로 강조할지 명시하는 glTF 확장으로, CAD/BIM 모델의 윤곽선 표현이나 기술 도면 스타일 시각화에 활용됩니다. 이번 추가로 런타임에서 에지 표시 방식을 동적으로 전환할 수 있게 되었습니다.
    • 활용 시나리오: BIM 모델에서 평소에는 에지를 숨기다가 분석 모드에서만 윤곽선을 표시하거나, 3D 타일셋의 건물 외곽선을 강조하는 시각화에 활용합니다.
    • 활용 방법 예시: 
      // 모델 로드 후 에지 표시 모드 설정
const tileset = await Cesium.Cesium3DTileset.fromUrl('tileset.json');
tileset.edgeDisplayMode = Cesium.EdgeDisplayMode.VISIBLE;
// 또는 EdgeDisplayMode.HIDDEN, EdgeDisplayMode.DEFAULT 등
viewer.scene.primitives.add(tileset);

  • 벡터 타일셋에서 EXT_structural_metadata 속성 지원

    • 벡터(vector) 타일셋에서 EXT_structural_metadata 확장 기반의 속성(properties)을 사용할 수 있습니다.
    • 상세 설명: 기존에는 메시 기반 3D 타일셋에서만 EXT_structural_metadata로 정의된 메타데이터에 접근할 수 있었지만, 1.141부터는 벡터 타일셋(점/선/폴리곤 피처)에서도 동일하게 속성 테이블, 속성 텍스처 등의 메타데이터를 활용할 수 있습니다.
    • 영향: 벡터 타일에 인구 통계, 카테고리 분류, 시계열 값 같은 풍부한 속성을 부착하여 커스텀 셰이더 스타일링이나 피처 단위 정보 표시에 활용할 수 있게 되었습니다.

  • 신규 lint 단계 npm run sg-scan — JSDoc 및 타입 정의 회귀 감지

    • JSDoc 주석과 TypeScript 타입 정의(.d.ts) 회귀(regression)를 사전에 감지하는 sg-scan 정적 분석 단계가 추가되었습니다.
    • 영향: CesiumJS에 기여하는 개발자에게 적용되는 변경이며, 라이브러리 사용자에게는 직접 영향이 없습니다. 다만 향후 타입 정의 품질이 향상될 것으로 기대됩니다.

🔧 수정 사항 (Fixes)

  • 에지 가시성 데이터를 포함한 퇴화 삼각형(degenerate triangle) 로드 시 DeveloperError 수정

    • EXT_mesh_primitive_edge_visibility 확장과 함께 퇴화 삼각형(degenerate triangle, 면적이 0인 삼각형)을 포함하는 3D 타일을 로드할 때 발생하던 DeveloperError를 수정했습니다.
    • 상세 설명: 일부 CAD 변환 도구에서 생성된 메시는 좌표가 동일한 정점들로 구성된 퇴화 삼각형을 포함할 수 있습니다. 기존에는 이러한 메시에 에지 가시성 데이터가 결합되면 내부 검증 로직에서 에러를 발생시켰지만, 이제 이를 안전하게 처리합니다.

  • pickModel 공용 유틸리티로 리팩토링 — 코드 중복 제거

    • pickModel 내부 로직이 공용 유틸리티 함수로 리팩토링되어 중복 코드가 제거되었습니다. 동작상의 변화는 없지만 코드 베이스 유지보수성이 향상되었습니다.

  • EquirectangularPanorama 조명 문제 수정

    • 등장방형(Equirectangular) 파노라마에 조명(Lighting)이 잘못 적용되던 버그가 수정되었습니다.
    • 상세 설명: EquirectangularPanorama는 360도 파노라마 배경 이미지를 표시하는 기능으로, 하늘 박스(SkyBox) 대신 실사 배경을 사용할 때 활용됩니다. 기존에는 씬(scene)의 조명 설정이 파노라마에 의도치 않게 영향을 주어 파노라마 이미지가 어둡게 렌더링되거나 색상이 왜곡되는 현상이 발생했습니다. 이번 수정으로 파노라마가 원본 이미지 색상 그대로 표시됩니다.
    • 영향: 실내 환경, 드론 촬영 파노라마, 가상 투어 등 EquirectangularPanorama를 배경으로 사용하는 애플리케이션에서 이미지 품질이 개선됩니다.
    • 활용 방법 예시: 
      // EquirectangularPanorama 사용 예시
viewer.scene.skyBox.show = false;
viewer.scene.backgroundColor = Cesium.Color.TRANSPARENT;
 
const panorama = new Cesium.EquirectangularPanorama({
  url: 'panorama.jpg'
});
viewer.scene.skyAtmosphere.show = false;

  • 지상 프리미티브 배치(ground primitive batch)에서 엔티티 제거 시 stale showsUpdated 상태 수정

    • 엔티티가 지상 프리미티브 배치에서 제거된 뒤에도 내부 showsUpdated 플래그가 갱신되지 않고 남아 있던 문제를 수정했습니다.
    • 영향: 다수의 폴리곤/폴리라인 엔티티를 동적으로 추가·제거하는 시나리오(예: 실시간 GIS 분석, 시계열 데이터 시각화)에서 표시 상태가 어긋나거나 잔상이 남는 문제가 해결됩니다.

  • pickModel의 non-worldspace 인스턴스 변환 행렬 곱셈 오류 수정

    • 인스턴스가 월드스페이스가 아닌 좌표계로 정의된 모델에서 pickModel이 잘못된 행렬 곱셈을 수행하던 문제를 수정했습니다.
    • 영향: EXT_mesh_gpu_instancing 등을 사용해 로컬 좌표계 기반 인스턴스를 정의한 모델에서 정확한 픽 결과를 얻을 수 있습니다.

  • SkyBox.show JSDoc 수정 — TypeScript 호환성 향상

    • SkyBox.show 속성의 JSDoc 선언이 프로토타입 프로퍼티(prototype property)로 올바르게 수정되었습니다.
    • 상세 설명: 이전에는 SkyBox.show의 JSDoc 타입 선언이 잘못되어 있어, TypeScript 환경에서 타입 추론 오류나 IDE 자동완성 문제가 발생할 수 있었습니다. 이번 수정으로 TypeScript 프로젝트나 타입 체크 도구를 사용하는 개발자들이 더 정확한 타입 지원을 받을 수 있습니다.
    • 영향: TypeScript 기반 Cesium 프로젝트에서 viewer.scene.skyBox.show를 사용할 때 타입 오류가 사라집니다.

📦 1.140 - 2026-04-01

추가일: 2026-04-10

🔴 Breaking Changes (주요 변경 사항)

  • 빌보드 및 레이블에 WebGL 2 또는 ANGLE_instanced_arrays 필수
    • 빌보드(Billboard)와 레이블(Label)이 이제 WebGL 2, 또는 WebGL 1 + ANGLE_instanced_arrays 확장 + MAX_VERTEX_TEXTURE_IMAGE_UNITS > 0을 지원하는 디바이스를 반드시 요구합니다.
    • 기술적 배경: 빌보드/레이블 렌더링이 인스턴스드 렌더링(instanced rendering) 방식으로 전환되었습니다. 이 방식은 수천 개의 포인트 피처를 GPU에서 효율적으로 한 번에 처리할 수 있어 성능이 크게 향상되지만, WebGL 2 또는 해당 확장이 없는 구형 환경에서는 동작하지 않습니다.
    • 영향: 구형 모바일 기기나 Internet Explorer(레거시) 환경에서는 빌보드/레이블이 렌더링되지 않을 수 있습니다. 대부분의 현대 브라우저는 WebGL 2를 지원합니다.
    • 확인 방법: 
      // WebGL 2 지원 여부 확인
const canvas = document.createElement('canvas');
const gl2 = canvas.getContext('webgl2');
console.log('WebGL 2 지원:', gl2 !== null);

🟢 추가 기능 (Additions)

  • 실험적 고성능 벡터 프리미티브 API: BufferPointCollection, BufferPolylineCollection, BufferPolygonCollection

    • 성능에 최적화된 새로운 벡터 프리미티브 API가 실험적으로 추가되었습니다.
    • 기술적 배경: 기존 PointPrimitiveCollection, PolylineCollection은 유연하지만 수십만 개의 객체를 다룰 때 성능 한계가 있었습니다. 새로운 Buffer 기반 API는 GPU 버퍼에 직접 데이터를 기록하는 방식으로 대용량 벡터 데이터를 훨씬 효율적으로 렌더링합니다.
    • 활용 방법 예시: 
      // 실험적 고성능 포인트 컬렉션
const bufferPoints = new Cesium.BufferPointCollection();
bufferPoints.add({
  position: Cesium.Cartesian3.fromDegrees(127.0, 37.5),
  color: Cesium.Color.RED,
  pixelSize: 5
});
viewer.scene.primitives.add(bufferPoints);

  • ITwin Gaussian Splat 3D Tiles 지원

    • ITwinData.createTilesetForRealityDataId에서 ITwinPlatform.RealityDataType.GaussianSplat3DTiles 타입의 현실 데이터 로드가 지원됩니다.

  • OffscreenCanvas를 ImageryTypes로 전달 가능

    • OffscreenCanvas를 이미지리 타입으로 직접 전달할 수 있게 되었습니다. Web Worker 기반 이미지 생성 결과를 이미지리 레이어로 활용할 수 있습니다.

  • WMTS GetFeatureInfo 지원 추가

    • WebMapTileServiceImageryProvider에 GetFeatureInfo 지원이 추가되어 pickFeatures를 사용할 수 있게 되었습니다.
    • KVP 방식과 RESTful WMTS 서비스 모두 지원합니다.
    • 새 파라미터: enablePickFeatures, getFeatureInfoFormats, getFeatureInfoUrl, getFeatureInfoParameters
    • 활용 방법 예시: 
      const wmtsProvider = new Cesium.WebMapTileServiceImageryProvider({
  url: 'https://example.com/wmts',
  layer: 'myLayer',
  style: 'default',
  tileMatrixSetID: 'EPSG:4326',
  enablePickFeatures: true,
  getFeatureInfoFormats: [
    new Cesium.GetFeatureInfoFormat('json', 'application/json')
  ],
  getFeatureInfoUrl: 'https://example.com/wmts/getFeatureInfo'
});

  • 커스텀 셰이더에서 double-precision 메타데이터 다운캐스팅 지원

    • 커스텀 셰이더에서 double-precision 메타데이터 타입을 다운캐스팅을 통해 제한적으로 지원합니다.

  • PathGraphics.relativeTo — 상대 참조 프레임 지원

    • 엔티티의 PathGraphics를 다른 엔티티 기준 또는 다른 참조 프레임(reference frame)에서 표시할 수 있는 PathGraphics.relativeTo 속성이 추가되었습니다.
    • 활용 시나리오: 두 이동하는 엔티티 사이의 상대적 경로를 추적하거나, 특정 로컬 좌표계를 기준으로 경로를 표현할 때 유용합니다.

🔧 수정 사항 (Fixes)

  • heightReference 사용 시 레이블 텍스트/배경 정렬 오류 수정

    • CLAMP_TO_GROUND, CLAMP_TO_TERRAIN, CLAMP_TO_TILE 사용 시 간헐적으로 레이블 텍스트와 배경이 어긋나는 문제를 수정했습니다.

  • Gaussian Splat SPZ 파일 디코딩 크래시 수정

    • 고차(high degree) 구면 조화를 포함한 대형 SPZ 파일 디코딩 시 발생하는 크래시를 수정했습니다.

  • Gaussian Splat modelMatrix 적용 오류 수정

    • tileset 변환 시 스플랫 위치/회전/스케일에 modelMatrix가 올바르게 적용되지 않던 문제와, 구면 조화 뷰 방향이 잘못된 좌표계에서 평가되던 문제를 수정했습니다.

  • 1600만 이상 스플랫 렌더링 시 WebGL 크래시 수정

  • Gaussian Splat 메모리 누수 수정

  • 커스텀 셰이더에서 클래스 레벨 메타데이터 부재 시 비활성화 방지

    • 클래스 정의에 메타데이터가 있는 한, 개별 프리미티브에 메타데이터가 없어도 커스텀 셰이더가 비활성화되지 않도록 수정했습니다.

  • SkyBox.show = false 무시되던 버그 수정

  • ClippingPolygon 다중 사용 시 성능 이슈 수정

  • I3S 디코더 접근자 min/max 값 계산 오류 수정

  • 카메라 transform 설정 시 줌 동작 수정

    • 엔티티 추적 또는 lookAt 사용 시 카메라 줌이 비정상적으로 동작하던 문제를 수정했습니다.

  • 복셀 레이마처(raymarcher)에서 형상이 무한히 얇을 때 0 스텝 스킵 수정

  • 포인트 클라우드 커스텀 스타일링 회귀 수정

📦 1.139 - 2026-03-02

추가일: 2026-04-10

🔴 Breaking Changes (주요 변경 사항)

  • Cartesian2, Cartesian3, Cartesian4가 ES6 클래스로 전환

    • Cartesian2, Cartesian3, Cartesian4가 ES6 Class로 변환되었습니다. 대부분의 사용자에게는 영향이 없지만, 정적 팩토리 메서드에 new 키워드를 사용하면 오류가 발생합니다.
    • 중요: new Cartesian3.fromArray(...) 같은 패턴은 이제 TypeError를 발생시킵니다.
    • 마이그레이션 가이드: 
      // ❌ 오류 발생 (static factory에 new 사용)
// const pos = new Cesium.Cartesian3.fromArray([1, 2, 3]);
// const pos = new Cesium.Cartesian3.fromDegrees(127, 37, 100);
 
// ✅ 올바른 방식 (new 없이 팩토리 메서드 호출)
const pos = Cesium.Cartesian3.fromArray([1, 2, 3]);
const pos2 = Cesium.Cartesian3.fromDegrees(127, 37, 100);
 
// ✅ 생성자 직접 호출 시에는 new 사용
const pos3 = new Cesium.Cartesian3(x, y, z);
    • 주의: 향후 더 많은 클래스가 ES6 Class로 마이그레이션될 예정입니다.

  • 커스텀 셰이더에서 UINT 메타데이터 타입 부호 변경

    • EXT_structural_metadata 확장에서 파생된 메타데이터를 사용하는 커스텀 셰이더에서, unsigned integer 메타데이터 타입이 더 이상 signed integer로 자동 캐스팅되지 않습니다.
    • 영향: int myMetadata = vsInput.metadata.myUintMetadata 같은 UINT 타입을 int 변수에 직접 대입하는 코드는 컴파일 오류가 발생합니다.
    • 마이그레이션 가이드: 
      // ❌ 이전 방식 (UINT → int 암묵적 캐스팅, 이제 컴파일 오류)
// int myMetadata = vsInput.metadata.myUintMetadata;
 
// ✅ 새로운 방식 (uint 타입으로 선언)
uint myMetadata = vsInput.metadata.myUintMetadata;
 
// 또는 명시적 캐스팅
int myMetadataInt = int(vsInput.metadata.myUintMetadata);

  • 포인트 클라우드 속성의 커스텀 프래그먼트 셰이더 정밀도 수정 (동작 변경)

    • 커스텀 프래그먼트 셰이더에서 포인트 클라우드 속성 접근 시 정밀도가 수정되었습니다. 기존 셰이더 동작이 변경될 수 있습니다.

🟢 추가 기능 (Additions)

  • 파노라마 지원 — EquirectangularPanorama, CubeMapPanorama, GoogleStreetViewCubeMapPanoramaProvider

    • 새로운 클래스 EquirectangularPanorama와 CubeMapPanorama가 추가되어 파노라마 이미지를 3D 씬 안에서 렌더링할 수 있게 되었습니다.
    • GoogleStreetViewCubeMapPanoramaProvider를 사용하면 Google Street View Static API에서 큐브맵 면(face)을 로드하여 파노라마 뷰를 구현할 수 있습니다.
    • 활용 시나리오: 드론 촬영 360도 이미지를 씬에 배치하거나, 가상 투어(virtual tour) 애플리케이션에서 특정 위치의 거리 뷰를 표시하는 데 활용합니다.
    • 활용 방법 예시: 
      // Google Street View 큐브맵 파노라마
const provider = new Cesium.GoogleStreetViewCubeMapPanoramaProvider({
  key: 'YOUR_GOOGLE_API_KEY'
});
const panorama = new Cesium.CubeMapPanorama({
  provider: provider,
  position: Cesium.Cartesian3.fromDegrees(127.0, 37.5, 10)
});
viewer.scene.primitives.add(panorama);

  • 빌보드/레이블 깊이 테스트 옵션 추가

    • BillboardCollection과 LabelCollection에 세밀한 깊이 테스트 제어 옵션이 추가되었습니다:
      • coarseDepthTestDistance: 대략적인 깊이 테스트 적용 거리
      • threePointDepthTestDistance: 세 점 기반 정밀 깊이 테스트 적용 거리

  • 프로퍼티 텍스처에서 더 많은 메타데이터 타입 지원

    • 커스텀 셰이더의 property textures에서 더 많은 메타데이터 타입을 접근할 수 있게 되었습니다.

  • 프로퍼티 테이블 메타데이터를 커스텀 셰이더에서 접근 가능

    • EXT_structural_metadata 확장의 property tables 메타데이터를 커스텀 셰이더에서 직접 접근할 수 있게 되었습니다.

  • AttributeCompression.encodeRGB8 / decodeRGB8 추가

    • 색상을 패킹/언패킹하는 유틸리티 메서드가 추가되었습니다.

🔧 수정 사항 (Fixes)

  • Gaussian Splat 스냅샷/정렬 업데이트 레이스 컨디션 수정

    • 명시적 스냅샷 상태 관리로 깜빡임, WebGL 드로우 오류, LOD 전환 성능 불안정 문제를 해결했습니다.

  • 여러 Gaussian Splat 프리미티브 동시 렌더링 시 깜빡임 수정

  • Billboard.disableDepthTestDistance = 0일 때 깊이 테스트 수정

  • 수평선 근처에서 빌보드 깊이 테스트 수정

  • Columbus View에서 낮/밤 알파 셰이더 캐시 조회 수정

  • 포인트가 원형 대신 정사각형으로 렌더링되도록 회귀 수정

    • BENTLEY_materials_point_style glTF 확장에서 지정한 경우에만 원형으로 렌더링됩니다.

  • OpenCageGeocoderService 좌표 스위칭 버그 수정

  • CustomShader 메타데이터 변수 탐지 정규식 수정

📦 1.138 - 2026-02-02

추가일: 2026-04-10

🟢 추가 기능 (Additions)

  • EXT_textureInfo_constant_lod glTF 확장 지원
    • EXT_textureInfo_constant_lod glTF 확장이 지원됩니다. 이 확장은 텍스처 샘플링 시 일정한 LOD(Level of Detail) 레벨을 강제하여 특정 렌더링 효과를 구현할 때 활용됩니다.

🔧 수정 사항 (Fixes)

  • Intel Arc GPU에서 지터(jitter) 아티팩트 수정

    • Intel Arc GPU에서 특정 지오메트리가 흔들리는 것처럼 보이는 지터 아티팩트가 수정되었습니다.
    • 상세 설명: Intel Arc GPU의 셰이더 정밀도 처리 방식이 NVIDIA/AMD와 달라 발생하던 문제입니다. 버텍스 위치 계산 로직을 개선하여 해결했습니다.

  • 복셀 메모리 사용량 개선 — Megatexture에서 Texture3D로 전환

    • Megatexture를 Texture3D로 재구현하여 복셀(voxel) 데이터의 메모리 효율이 크게 향상되었습니다.
    • 기술적 배경: 기존 Megatexture는 3D 볼류메트릭 데이터를 2D 텍스처 아틀라스에 저장하는 방식이었습니다. 이제 실제 3D 텍스처를 사용하므로 GPU 메모리 접근 패턴이 최적화되고 메모리 오버헤드가 감소합니다.

  • 2D/Columbus View 모드에서 픽(pick) 결과 undefined 오류 수정

    • 2D 및 Columbus View(CV) 씬 모드에서 픽킹 결과가 간헐적으로 undefined를 반환하던 여러 문제를 수정했습니다.

  • 일부 폰트/문자에서 레이블 크기 계산 오류 수정

  • Viewer의 ellipsoid 접근 시 타입 오류 수정

  • 엔티티 클러스터링 오류 수정

  • DynamicEnvironmentMapManager에서 maximumCubeMapSize = 0일 때 오류 수정

📦 1.137 - 2026-01-05

추가일: 2026-04-10

🟡 Deprecated (향후 제거 예정)

  • 1.140부터 빌보드/레이블에 WebGL 2 또는 ANGLE_instanced_arrays 필수 예고
    • CesiumJS 1.140부터 빌보드와 레이블이 WebGL 2, 또는 WebGL 1 + ANGLE_instanced_arrays + MAX_VERTEX_TEXTURE_IMAGE_UNITS > 0을 요구하게 됩니다.
    • 사전 대응: 대상 환경이 이 요구사항을 충족하는지 확인하고, 필요 시 WebGL 2를 명시적으로 요청하도록 설정을 업데이트하세요.
    • 확인 방법: 
      const viewer = new Cesium.Viewer('cesiumContainer', {
  contextOptions: {
    webgl: { antialias: true }
    // requestWebGl1: false (기본값, WebGL 2 허용)
  }
});

🟢 추가 기능 (Additions)

  • BENTLEY_materials_point_style glTF 확장 지원

    • 포인트 프리미티브에 직경(diameter) 속성을 지정하고 glTF 로드 시 적용할 수 있는 BENTLEY_materials_point_style 확장이 지원됩니다.
    • 활용 시나리오: CAD 소프트웨어에서 내보낸 포인트 클라우드 데이터에서 점의 크기를 glTF 파일 내에서 직접 정의하고 CesiumJS에서 렌더링합니다.

  • BENTLEY_materials_line_style glTF 확장 지원

    • BENTLEY_materials_line_style 확장이 지원되어 CAD 스타일의 선 시각화가 가능합니다. 선과 엣지에 width(화면 픽셀 단위)와 pattern(16비트 on/off 반복 패턴) 속성을 지정할 수 있습니다.
    • 기술적 배경: WebGL은 1픽셀 이상의 선 너비를 지원하지 않으므로, 각 엣지를 쿼드(4개 정점, 2개 삼각형)로 테셀레이션하여 엣지 방향에 수직으로 확장하는 방식으로 구현됩니다.

  • EXT_mesh_primitive_edge_visibility를 쿼드 기반 렌더링으로 리팩토링

    • gl_line 프리미티브 대신 쿼드 기반 렌더링으로 전환되어 가변 선 너비가 지원됩니다.

🔧 수정 사항 (Fixes)

  • 고정된(clamped) 레이블 삭제 후 재생성 시 위치 결정 오류 수정

    • CLAMP_TO_* HeightReference를 사용하는 레이블을 삭제했다가 다시 생성할 때 위치가 잘못 계산되던 문제를 수정했습니다.

  • 대형 빌보드 컬렉션에서 텍스처 좌표 오류 수정

    • 많은 수의 빌보드가 있는 컬렉션에서 텍스처 좌표가 잘못 계산되던 문제를 수정했습니다.

📦 1.136 - 2025-12-01

추가일: 2026-04-10

🟢 추가 기능 (Additions)

  • scene.pickAsync — GPU 블로킹 없는 비동기 픽킹

    • scene.pickAsync가 추가되어 WebGL2에서 GPU를 블로킹하지 않는 비동기 픽킹이 가능합니다.
    • 기술적 배경: 기존 scene.pick은 GPU에서 픽킹 결과를 즉시 읽어야 하므로 GPU 동기화가 발생하여 프레임 레이트에 영향을 줄 수 있었습니다. pickAsync는 GPU 렌더링과 결과 읽기를 분리하여 성능 저하 없이 픽킹을 수행합니다.
    • 활용 방법 예시: 
      // 비동기 픽킹 (GPU 블로킹 없음)
const pickedObject = await viewer.scene.pickAsync(
  new Cesium.Cartesian2(event.clientX, event.clientY)
);
if (pickedObject) {
  console.log('선택된 객체:', pickedObject.id);
}

  • 지형 픽킹 쿼드트리로 성능 향상

    • 지형 픽킹에 새로운 쿼드트리(quadtree) 자료구조를 도입하여 지형 위 위치 계산 성능이 향상되었습니다.
    • 기술적 배경: 지형 높이 계산 시 이전에는 모든 지형 타일을 순차 검색했습니다. 쿼드트리를 사용하면 대상 지점이 포함된 타일을 O(log n)으로 찾을 수 있어 픽킹 속도가 향상됩니다.

🔧 수정 사항 (Fixes)

  • 빌보드의 SVG 스케일링 개선

    • 빌보드에 SVG 이미지를 사용할 때 크기 조정이 올바르게 되지 않던 문제를 개선했습니다.

  • imageSubRegion을 사용하는 빌보드 렌더링 수정

    • 빌보드에서 imageSubRegion(이미지의 특정 영역만 사용)을 설정했을 때 예상대로 렌더링되지 않던 문제를 수정했습니다.

  • 빌보드/레이블이 모델을 뚫고 나오는 깊이 테스트 버그 수정

    • 빌보드와 레이블이 3D 모델을 뚫고 앞으로 나오는 깊이 테스트 문제를 수정했습니다.

  • 빌보드 주변에 예상치 못한 아웃라인 아티팩트 수정

    • 오랫동안 보고되던(#4525) 빌보드 주변의 아웃라인 아티팩트가 수정되었습니다.

📦 1.135 - 2025-11-03

추가일: 2026-04-10

🔴 Breaking Changes (주요 변경 사항)

  • KHR_spz_gaussian_splats_compression 확장 제거 — 새로운 표준으로 전환

    • KHR_spz_gaussian_splats_compression 확장 지원이 완전히 제거되었습니다. 최신 3D 가우시안 스플래팅 glTF 확장인 KHR_gaussian_splatting 및 **KHR_gaussian_splatting_compression_spz_2**로 전환해야 합니다.
    • 기술적 배경: Khronos Group이 가우시안 스플래팅 표준화를 진행하면서 KHR_spz_gaussian_splats_compression의 초안이 KHR_gaussian_splatting 계열로 재정립되었습니다. 이전 확장은 표준에서 제외되었습니다.
    • 대응 방법: 기존 Gaussian Splatting 3D Tiles를 새로운 확장 형식으로 **재타일링(re-tiling)**해야 합니다. 재타일링 없이는 1.135 이후 버전에서 로드되지 않습니다.

  • scene.drillPick이 너비 우선(breadth-first) 탐색으로 변경

    • scene.drillPick의 검색 전략이 깊이 우선(depth-first)에서 **너비 우선(breadth-first)**으로 변경되었습니다.
    • 영향: width와 height 값이 크고 limit을 사용하는 경우, 이전과 다른 엔티티가 선택될 수 있습니다. 이제 카메라에서 더 가까운 엔티티가 우선 선택됩니다.
    • 마이그레이션 가이드: 
      const pickedObjects = viewer.scene.drillPick(
  windowPosition,
  limit,    // 최대 반환 수
  width,    // 픽킹 영역 너비 (픽셀)
  height    // 픽킹 영역 높이 (픽셀)
);
// 이제 카메라에 더 가까운 객체가 먼저 반환됩니다

🟢 추가 기능 (Additions)

  • Cesium3DTilesTerrainProvider — 3D Tiles를 지형으로 로드 (실험적)

    • 3D Tiles를 지형 데이터로 로드할 수 있는 Cesium3DTilesTerrainProvider가 실험적으로 추가되었습니다.
    • 기술적 배경: 기존에는 Quantized Mesh 형식의 지형 타일셋만 지형으로 사용할 수 있었습니다. 이제 3D Tiles도 지형으로 사용할 수 있어, BIM/CAD 3D Tiles를 지형의 일부로 통합하거나 고정밀 지형 표면을 3D Tiles로 제공할 수 있습니다.
    • 주의: 모든 종류의 3D Tiles가 지원되는 것은 아닙니다. 지형 역할에 적합한 메시 타입만 사용 가능합니다.

  • EXT_mesh_primitive_edge_visibility glTF 확장 지원

    • EXT_mesh_primitive_edge_visibility glTF 확장이 지원됩니다. CAD 모델의 엣지(윤곽선)를 시각화하는 데 사용됩니다.
    • 재질 색상 및 선 스타일 오버라이드를 반영하여 렌더링합니다.

🔧 수정 사항 (Fixes)

  • scene.drillPick 성능 향상
  • 프리미티브 제거 시 성능 향상
  • 지형 쿼드트리의 커스텀 데이터 처리 성능 향상
  • 타원체형 복셀의 수직 과장(vertical exaggeration) 수정
  • 3D Tiles 1.1 subtree 파일의 콘텐츠 바운딩 볼륨 파싱 수정
  • 이벤트 콜백 내에서 새 리스너 추가 시 무한 루프 수정
    • 이벤트 콜백 실행 중에 새로운 리스너를 추가했을 때 무한 루프가 발생하는 버그를 수정했습니다.
  • label.show = false 상태에서 속성 업데이트 시 레이블 배경 문제 수정
  • 여러 PolygonGeometry 인스턴스를 가진 GroundPrimitive 픽킹 오류 수정
  • 드레이핑(draped) 이미지리 레이어 제거 시 렌더링 상태 미업데이트 수정
  • 루트 타일에 월드 변환이 없는 Gaussian Splat 타일셋 정밀도 문제 수정
  • post-render 콜백 내에서 추가 콜백 등록 시 무한 재귀 수정

📦 1.134 - 2025-10-01

추가일: 2026-04-10

📌 Sandcastle이 새 버전으로 업데이트되었습니다. 레거시 앱은 2025년 11월 3일까지 유지됩니다.

🔴 Breaking Changes (주요 변경 사항)

  • Voxel 렌더링에 WebGL2 컨텍스트 필수

    • Voxel(복셀) 렌더링이 이제 WebGL2 컨텍스트를 반드시 요구합니다. CesiumJS 1.101부터 WebGL2가 기본으로 활성화되어 있습니다.
    • 주의: contextOptions에서 requestWebGl1: true로 설정되어 있다면 복셀이 렌더링되지 않습니다.
    • 확인 및 수정: 
      // ❌ 복셀 렌더링 불가 설정
// const viewer = new Cesium.Viewer('cesiumContainer', {
//   contextOptions: { requestWebGl1: true }
// });
 
// ✅ 복셀 렌더링 가능 (기본 설정)
const viewer = new Cesium.Viewer('cesiumContainer');
// 또는 명시적으로 WebGL2 요청
const viewer2 = new Cesium.Viewer('cesiumContainer', {
  contextOptions: { requestWebGl1: false }
});

  • defaultValue 함수 완전 제거

    • 1.128에서 폐기 예고되었던 defaultValue 함수가 이 버전에서 완전히 제거되었습니다.
    • 마이그레이션 가이드: 
      // ❌ 오류 발생 (함수가 제거됨)
// const value = Cesium.defaultValue(options.color, Cesium.Color.WHITE);
 
// ✅ 새로운 방식 (널 병합 연산자)
const value = options.color ?? Cesium.Color.WHITE;

  • defaultValue.EMPTY_OBJECT 완전 제거

    • Frozen.EMPTY_OBJECT를 사용하세요. 
      // ❌ 오류 발생
// const opts = Cesium.defaultValue.EMPTY_OBJECT;
 
// ✅ 새로운 방식
const opts = Cesium.Frozen.EMPTY_OBJECT;

🟢 추가 기능 (Additions)

  • Google2DImageryProvider — Google Maps 2D 이미지리 로드

    • Google Maps 2D Tiles API에서 이미지리를 로드하는 Google2DImageryProvider가 추가되었습니다.
    • 활용 방법 예시: 
      const imagery = new Cesium.Google2DImageryProvider({
  key: 'YOUR_GOOGLE_MAPS_API_KEY'
});
viewer.imageryLayers.addImageryProvider(imagery);

  • Material 클래스에 비동기 팩토리 메서드 추가

    • Material에 리소스 로딩을 기다릴 수 있는 비동기 팩토리 메서드가 추가되었습니다. 이를 통해 Material이 완전히 로드된 이후에 렌더링을 시작하도록 보장할 수 있습니다.

🔧 수정 사항 (Fixes)

  • 작은 폰트 레이블의 글리프 수직 정렬 수정
  • 복셀 레이마칭의 눈 좌표(eye coordinates) 변환으로 대용량 데이터셋 정밀도 개선
  • Gaussian Splat 모델의 잘못된 정렬 결과로 인한 깜빡임 아티팩트 수정
  • 여러 Gaussian Splat 타일셋 인스턴스의 타일 위치 오류 수정
  • requestRenderMode 활성화 시 지오메트리 엔티티 렌더링 수정
  • Event 클래스 성능 향상 및 메모리 사용량 감소
  • 고정된(clamped) 레이블 성능 향상
  • Material 타입에서 서브 재질 참조 수정
  • 잘못된 PNTS 파일 로드 시 런타임 오류 방지
  • 구형 브라우저 지원을 위한 createImageBitmap 옵션 업데이트 롤백

📦 1.133 - 2025-09-02

추가일: 2026-04-10

🔴 Breaking Changes (주요 변경 사항)

  • ITwinData. 함수의 개별 인자 폴백 제거*
    • ITwinData.* 함수들에서 개별 인수(argument) 폴백이 완전히 제거되었습니다. 이제 반드시 옵션 객체(options object) 방식만 사용해야 합니다.
    • 마이그레이션 가이드: 
      // ❌ 이전 방식 (1.132에서 폐기 예고, 1.133에서 제거)
// const tileset = await Cesium.ITwinData.createTilesetFromIModelId(
//   accessToken, iModelId, changesetId
// );
 
// ✅ 새로운 방식 (options 객체 사용)
const tileset = await Cesium.ITwinData.createTilesetFromIModelId({
  accessToken: 'yourToken',
  iModelId: 'yourIModelId',
  changesetId: 'yourChangesetId'
});

🟡 Deprecated (향후 제거 예정)

  • KHR_spz_gaussian_splats_compression 확장 폐기 예고 (1.135에서 제거)
    • KHR_spz_gaussian_splats_compression 확장이 폐기되고 1.135 버전에서 제거됩니다.
    • 대체: KHR_gaussian_splatting 및 KHR_gaussian_splatting_compression_spz_2로 전환하세요.
    • 기한: 2025년 11월 1일 전에 기존 Gaussian Splatting 3D Tiles를 재타일링하세요.

🟢 추가 기능 (Additions)

  • EXT_mesh_primitive_restart glTF 확장 지원

    • EXT_mesh_primitive_restart glTF 확장이 지원됩니다. 인덱스 버퍼에서 특정 인덱스 값을 프리미티브 재시작 신호로 사용하여 복잡한 메시 위상(topology)을 표현할 수 있습니다.

  • Gaussian Splat에 구면 조화(Spherical Harmonics) 지원 — SPZ 포맷

    • Gaussian Splat에 구면 조화(SH, Spherical Harmonics) 계수가 지원됩니다. SPZ 압축 포맷과 함께 사용됩니다.
    • 기술적 배경: 구면 조화는 뷰 방향에 따라 색상이 달라지는 표현(view-dependent appearance)을 가능하게 합니다. 반사광, 광택 표면 등 복잡한 재질 표현의 정확도가 향상됩니다.
    • 활용 시나리오: 고품질 Gaussian Splat 데이터셋(NeRF 기반 재구성 등)에서 뷰에 따른 색상 변화를 정확히 표현하는 데 활용됩니다.

  • Ellipsoid.MARS — 화성 타원체 추가

    • 화성 지형 및 이미지리에 사용할 수 있는 Ellipsoid.MARS가 추가되었습니다.
    • 활용 방법 예시: 
      // 화성 타원체 사용
const viewer = new Cesium.Viewer('cesiumContainer', {
  globe: new Cesium.Globe(Cesium.Ellipsoid.MARS)
});

  • ITwinData.createTilesetForRealityDataId에 Cesium3DTileset 생성자 옵션 전달 가능

    • ITwinData.createTilesetForRealityDataId로 생성되는 타일셋에 Cesium3DTileset 생성자 옵션을 직접 전달할 수 있게 되었습니다.

🔧 수정 사항 (Fixes)

  • 카메라 뷰 밖 Gaussian Splat 타일셋이 렌더링되던 문제 수정
  • WMTS 최소 4개 타일 임계값 제거
  • 바이너리 파트 없는 배치 테이블 포함 PNTS 파일 크래시 수정
  • ClippingPolygon으로 숨겨진 영역 픽킹 오류 수정

📦 1.132 - 2025-08-01

추가일: 2026-04-10

🟡 Deprecated (향후 제거 예정)

  • ITwinData. 함수의 개별 인수 방식 폐기 (1.133에서 제거)*
    • 모든 ITwinData.* 함수가 개별 인수 대신 options 파라미터를 사용하도록 업데이트되었습니다. 기존 개별 인수 방식은 1.133에서 제거됩니다.
    • 마이그레이션 예시: 
      // ❌ 폐기된 방식 (1.133에서 제거)
// await Cesium.ITwinData.createTilesetFromIModelId(token, iModelId, changesetId);
 
// ✅ 새로운 방식
await Cesium.ITwinData.createTilesetFromIModelId({
  accessToken: token,
  iModelId: iModelId,
  changesetId: changesetId
});

🟢 추가 기능 (Additions)

  • CustomShader 샘플 실시간 수정 지원 확장

    • CustomShader 샌드캐슬 샘플이 런타임(실시간)에 셰이더 코드를 수정하는 기능을 지원하도록 확장되었습니다. 개발 시 셰이더를 편리하게 테스트할 수 있습니다.

  • Sampler와 Texture3D에 wrapR 속성 추가

    • 3D 텍스처의 세 번째 차원(깊이 방향) 래핑 모드를 제어하는 wrapR 속성이 Sampler와 Texture3D에 추가되었습니다.
    • 기술적 배경: 2D 텍스처는 wrapS(수평)와 wrapT(수직) 래핑만 있지만, 3D 텍스처는 추가로 wrapR(깊이 방향) 래핑이 필요합니다.

  • iTwin Mesh Export에서 특정 Changeset 로드 지원

    • ITwinData.createTilesetFromIModelId에서 특정 changeset을 지정하여 로드할 수 있게 되었습니다. BIM 모델의 특정 시점 데이터를 정확히 가져올 수 있습니다.

🔧 수정 사항 (Fixes)

  • 2D 씬 모드에서 폴리곤 컬링 오류 수정

    • 2D 씬 모드에서 폴리곤이 잘못 컬링(화면 밖으로 판단하여 렌더링하지 않음)되던 오랜 버그를 수정했습니다.

  • 속성 변경 시 재질(material) 깜빡임 수정

    • 재질 속성을 런타임에 변경할 때 순간적으로 깜빡이던 현상을 수정했습니다.

  • 타일셋에 드레이핑(draped)된 이미지리 레이어 가시성 업데이트 수정

    • 이미지리 레이어의 가시성(visibility) 변경이 드레이핑된 이미지에 반영되지 않던 문제를 수정했습니다.

  • 여러 타일을 가진 Gaussian Splat 타일셋 씬에서 제거 시 예외 수정

  • glTF/tileset/modelMatrix 변환 시 Gaussian Splat 렌더링 오류 수정

    • glTF transform, tileset transform, model matrix로 스케일링된 Gaussian Splat 렌더링 오류를 수정했습니다.

  • 레이블 배경 반투명도 문제 수정

  • Scene 속성/함수 타입에 undefined 가능성 명확히 표시

    • Scene의 많은 속성과 함수 타입이 undefined를 반환할 수 있음을 TypeScript 타입 정의에 명확히 표시했습니다.

  • Cesium3DTileset.show = false 시 Gaussian Splat 렌더링 수정

  • PointCloudShading.normalShading = false 설정 시 법선 셰이딩 비활성화 수정

    • 포인트 클라우드에 법선(normal) 데이터가 있어도 normalShading: false로 설정하면 법선 셰이딩이 비활성화됩니다.

  • GPU 버텍스 변환의 정밀도 오류 감소

    • GPU 버텍스 변환 연산을 개선하여 정밀도 오류(floating point precision error)를 줄였습니다.

  • glTF up-axis에 대한 Gaussian Splat 방향 수정 (spz-loader 0.3.0 업데이트)

📦 1.131 - 2025-07-01

추가일: 2026-04-10

🟢 추가 기능 (Additions)

  • HeightReference 지원 — Cesium3DTileset 포인트 피처 지형 고정

    • Cesium3DTileset.ConstructorOptions에 HeightReference 속성이 추가되어, 3D Tile 벡터 데이터의 포인트 피처를 지형 또는 3D Tiles 표면에 고정(clamp)할 수 있게 되었습니다.
    • 기술적 배경: 기존에는 포인트 피처가 절대 높이(WGS84 좌표)로만 렌더링되어 지형 위에 떠 있거나 지형 아래에 묻히는 문제가 있었습니다. HeightReference를 이용하면 지형 표면이나 3D Tiles에 정확히 붙어서 렌더링됩니다.
    • 활용 방법 예시: 
      const tileset = await Cesium.Cesium3DTileset.fromUrl(url, {
  heightReference: Cesium.HeightReference.CLAMP_TO_TERRAIN,
});
viewer.scene.primitives.add(tileset);

  • OffscreenCanvas & ImageBitmap을 Material 유니폼에 직접 전달 가능

    • Material 유니폼에 OffscreenCanvas 및 ImageBitmap 객체를 직접 넘길 수 있게 되었습니다.
    • 기술적 배경: 이전에는 Canvas나 이미지를 Material에 전달하려면 일반 Canvas나 HTML 이미지 요소를 사용해야 했습니다. OffscreenCanvas는 Web Worker에서 렌더링 작업을 분리하여 메인 스레드 부하를 줄여주는 최신 API입니다. 이제 Worker 기반 이미지 처리 결과를 바로 Material 텍스처로 활용할 수 있습니다.
    • 활용 방법 예시: 
      // Web Worker에서 생성된 OffscreenCanvas를 Material 유니폼으로 사용
const offscreenCanvas = new OffscreenCanvas(256, 256);
const ctx = offscreenCanvas.getContext('2d');
ctx.fillStyle = 'red';
ctx.fillRect(0, 0, 256, 256);
 
const material = new Cesium.Material({
  fabric: {
    type: 'Image',
    uniforms: { image: offscreenCanvas }
  }
});

🔧 수정 사항 (Fixes)

  • createImageBitmap 폐기 옵션 사용 수정

    • 내부적으로 createImageBitmap 호출 시 deprecated된 옵션이 사용되던 문제를 수정했습니다. 최신 브라우저 표준과의 호환성이 향상됩니다.
    • 상세 설명: createImageBitmap API의 일부 옵션이 브라우저 표준에서 폐기되면서 콘솔 경고가 발생하던 문제를 해결했습니다.

  • 원통형(cylindrical) 복셀 레이마칭 스텝 크기 수정

    • 원통형 복셀 셰이더에서 레이마칭(raymarching) 스텝 크기가 잘못 계산되던 버그를 수정했습니다.
    • 상세 설명: 레이마칭은 3D 볼류메트릭 데이터를 렌더링할 때 광선을 따라 샘플을 추출하는 기법입니다. 스텝 크기가 잘못되면 렌더링 품질이 저하되거나 아티팩트가 발생합니다. 원통형 복셀에서 이 버그가 수정되어 더 정확한 볼류메트릭 렌더링이 가능합니다.

  • GaussianSplatPrimitive의 tileset modelMatrix 변경 처리 수정

    • GaussianSplatPrimitive에서 tileset의 modelMatrix(이동/회전)가 변경될 때 올바르게 처리되지 않던 버그를 수정했습니다.
    • 상세 설명: 가우시안 스플래팅(Gaussian Splatting) 렌더링 시 tileset을 이동하거나 회전시키면 스플래트가 잘못된 위치에 표시되는 문제가 있었습니다. 이 수정으로 동적 위치 변경이 올바르게 반영됩니다.

📦 1.130.1 - 2025-06-16

추가일: 2026-04-10

🟢 추가 기능 (Additions)

  • SPZ 압축을 사용한 가우시안 스플래팅(Gaussian Splatting) 실험적 지원

    • 3D Tiles에서 KHR_spz_gaussian_splats_compression glTF 확장 초안을 사용하는 SPZ 압축 가우시안 스플랫 로딩을 실험적으로 지원합니다.
    • 기술적 배경: 가우시안 스플래팅(Gaussian Splatting, 이하 GS)은 포인트 클라우드 기반의 3D 장면을 매우 사실적으로 렌더링하는 최신 기술입니다. SPZ(Scalable Point Zip) 압축은 GS 데이터를 효율적으로 압축하여 전송 대역폭을 줄입니다. KHR_spz_gaussian_splats_compression은 Khronos Group이 주도하는 glTF 표준 확장으로, 3D Tiles 생태계와의 통합을 목표로 합니다.
    • 실제 사용 시나리오: 대형 건물이나 도시 스케일의 3D 가우시안 스플랫 데이터를 웹에서 스트리밍하는 경우, SPZ 압축으로 용량을 대폭 줄이면서도 고품질 렌더링을 유지할 수 있습니다.
    • 활용 방법 예시: 
      // SPZ 압축 가우시안 스플랫 3D Tiles 로드 (실험적 기능)
const tileset = await Cesium.Cesium3DTileset.fromUrl(
  'https://example.com/gaussian_splat_tileset/tileset.json'
);
viewer.scene.primitives.add(tileset);
viewer.zoomTo(tileset);

  • 정수 텍스처 포맷 지원 추가

    • 다음 정수 텍스처 포맷을 지원합니다: R32I, RG32I, RGB32I, RGBA32I, R32UI, RG32UI, RGB32UI, RGBA32UI
    • 기술적 배경: 기존 WebGL/WebGL2 텍스처는 주로 부동소수점(float)이나 정규화된 정수 형식을 사용했습니다. 비정규화 32비트 정수 텍스처는 정밀한 인덱스 데이터, ID 맵, 카운터 데이터 등을 GPU에서 직접 처리할 때 유용합니다.

📦 1.130 - 2025-06-02

추가일: 2026-04-10

🔴 Breaking Changes (주요 변경 사항)

  • VoxelPrimitive 셰이더 API 변경 — FragmentInput 구조체 재구성
    • VoxelPrimitive용 CustomShader의 FragmentInput 구조체가 CustomShader 문서와 일관성을 갖도록 개편되었습니다.
    • 상세 설명: VoxelPrimitive와 Cesium3DTileset / Model 간의 CustomShader 사용 방식 차이가 이제 Custom Shader Guide에 명확히 문서화되었습니다.
    • 주요 변경 항목:
      • 비표준 위치 속성 fsInput.voxel.positionUv, fsInput.voxel.positionShapeUv, fsInput.voxel.positionLocal이 제거되고, 단일 눈 좌표(eye coordinate) 위치 fsInput.attributes.positionEC로 대체되었습니다.
      • 모델 좌표계 법선 fsInput.voxel.surfaceNormal이 눈 좌표계 법선 fsInput.attributes.normalEC로 대체되었습니다.
    • 마이그레이션 가이드: 
      // ❌ 이전 방식 (1.130 이전)
// vec3 voxelNormal = normalize(czm_normal * fsInput.voxel.surfaceNormal);
 
// ✅ 새로운 방식 (1.130 이후)
vec3 voxelNormal = fsInput.attributes.normalEC;
      // ❌ 이전 방식: 복셀 UV 공간 위치 접근
// vec3 posUV = fsInput.voxel.positionUv;
 
// ✅ 새로운 방식: 눈 좌표계 위치 사용
vec4 posEC = vec4(fsInput.attributes.positionEC, 1.0);

🟢 추가 기능 (Additions)

  • 3D Tiles 위에 이미지리(imagery) 드레이핑 기본 지원

    • 3D Tiles 표면 위에 2D 이미지리(위성/항공 이미지 등)를 씌우는 드레이핑(draping) 기능의 기초 지원이 추가되었습니다.
    • 기술적 배경: 기존에는 지형 타일셋(Terrain)에만 이미지리를 씌울 수 있었습니다. 3D 건물이나 지물 타일셋에 고해상도 위성/항공 이미지를 직접 투영하는 것은 불가능했습니다. 이 기능을 통해 3D Tiles 위에도 이미지리를 드레이핑할 수 있게 됩니다.
    • 실제 사용 시나리오: 도시 3D Tiles 위에 최신 위성이미지를 드레이핑하여 건물 외벽에 실제 텍스처처럼 표현하거나, 시뮬레이션 목적으로 3D 지물에 특수 오버레이를 입히는 등의 활용이 가능합니다.

  • 3D 텍스처 지원 및 Volume Cloud 샌드캐슬 예제 추가

    • 3D 텍스처(3D Texture) 지원이 추가되었고, 이를 활용한 볼류메트릭 클라우드(Volume Cloud) 샌드캐슬 예제가 추가되었습니다.
    • 기술적 배경: 3D 텍스처는 너비×높이×깊이 3차원 데이터를 저장하는 텍스처로, 구름, 안개, 연기 같은 볼류메트릭 효과나 의료 CT 데이터 시각화에 유용합니다.

🔧 수정 사항 (Fixes)

  • 직교 카메라(orthographic camera)에서 복셀 렌더링 수정
    • 직교 투영 모드에서 복셀이 올바르게 렌더링되지 않던 문제를 수정했습니다.
    • 상세 설명: 직교 카메라는 원근감 없이 평행 투영을 사용하는 모드입니다. 이 모드에서 복셀 데이터가 잘못된 깊이 계산으로 인해 렌더링 아티팩트가 발생하던 문제를 수정했습니다.

📦 1.129 - 2025-05-01

추가일: 2026-04-10

🔴 Breaking Changes (주요 변경 사항)

  • VoxelProvider 경계값이 물리적 값(physical values)으로 변경
    • VoxelProvider.minimumBounds와 .maximumBounds가 이제 형상 공간(shape space) 값이 아닌 **물리적 값(physical values)**으로 지정됩니다.
    • 상세 설명: 이전에는 복셀 경계값이 0~1 범위의 정규화된 형상 공간 값으로 지정되었습니다. 이제는 실제 물리적 단위(미터, 도 등)로 지정해야 합니다. 커스텀 VoxelProvider를 구현한 경우 경계값 계산 방식을 수정해야 합니다.
    • 마이그레이션 가이드: 
      // ❌ 이전 방식: 0~1 정규화 값 (shape space)
// provider.minimumBounds = new Cesium.Cartesian3(0.0, 0.0, 0.0);
// provider.maximumBounds = new Cesium.Cartesian3(1.0, 1.0, 1.0);
 
// ✅ 새로운 방식: 실제 물리적 값 (경위도 라디안, 고도 미터 등)
provider.minimumBounds = new Cesium.Cartesian3(
  Cesium.Math.toRadians(-180), // 경도 최솟값
  Cesium.Math.toRadians(-90),  // 위도 최솟값
  0                            // 고도 최솟값 (미터)
);
provider.maximumBounds = new Cesium.Cartesian3(
  Cesium.Math.toRadians(180),  // 경도 최댓값
  Cesium.Math.toRadians(90),   // 위도 최댓값
  100000                       // 고도 최댓값 (미터)
);

🟢 추가 기능 (Additions)

  • “Material with Custom GLSL” 샌드캐슬 데모 추가
    • 커스텀 GLSL 셰이더를 사용한 Material을 구현하는 샌드캐슬 데모 예제가 추가되었습니다.
    • 기술적 배경: CesiumJS에서 Material API는 지형, 폴리곤, 엔티티 등에 커스텀 시각 효과를 적용할 수 있는 강력한 기능입니다. GLSL 셰이더를 직접 작성하면 기본 제공 Material 이상의 고급 효과(그라디언트, 애니메이션 텍스처, 물리 기반 효과 등)를 구현할 수 있습니다.

🔧 수정 사항 (Fixes)

  • QuadtreePrimitive.updateHeights 위치 Cartographic 변환 수정

    • QuadtreePrimitive.updateHeights가 콜백 호출 전에 위치를 Cartographic으로 변환하도록 수정되었습니다.
    • 상세 설명: 이전 커밋(53889cb)에서 도입된 변경과의 호환성을 보장하고, 불필요한 연산을 줄이기 위한 수정입니다.

  • Polyline*MaterialProperty 너비 아티팩트 수정 (이전 PR 롤백)

    • 폴리라인 Material 속성에서 너비 렌더링 아티팩트가 발생하던 문제를 수정했습니다 (PR #12434 롤백).
    • 상세 설명: 이전 버전에서 폴리라인 너비 렌더링을 개선하려는 시도(#12434)가 새로운 아티팩트를 만들어냈습니다. 이 버전에서는 해당 변경을 롤백하여 안정성을 회복했습니다.

  • Check.typeOf.object 타입 어설션 개선

    • Check.typeOf.object가 object 대신 Record<string|number|symbol, any>를 어설션하도록 수정되어, 어설션 후 속성 접근이 타입 오류 없이 가능해졌습니다.

📦 1.128 - 2025-04-01

추가일: 2026-04-10

🔴 Breaking Changes (주요 변경 사항)

  • Camera.getPickRay가 월드 좌표(world coordinates)로 반환되도록 수정

    • Camera.getPickRay가 이전에 카메라 좌표(camera coordinates)로 결과를 반환하던 버그를 수정했습니다. 이제 문서에 명시된 대로 월드 좌표로 반환됩니다.
    • 영향 범위: Camera.getPickRay 결과를 카메라 좌표로 가정하고 처리하던 코드는 수정이 필요합니다.
    • 마이그레이션 가이드: 
      // ❌ 이전 방식: 카메라 좌표로 결과가 반환되던 버그 동작에 의존
const ray = camera.getPickRay(windowPosition);
// ray가 카메라 좌표였으므로 world로 변환하지 않았음
 
// ✅ 새로운 방식: 이미 월드 좌표이므로 그대로 사용
const ray = camera.getPickRay(windowPosition);
// ray는 이제 올바르게 월드 좌표로 반환됨
 
// 만약 이전처럼 카메라 좌표가 필요하다면:
// camera.inverseViewMatrix를 사용하여 역변환
const rayInCameraSpace = {
  origin: Cesium.Matrix4.multiplyByPoint(
    camera.inverseViewMatrix, ray.origin, new Cesium.Cartesian3()
  ),
  direction: Cesium.Matrix4.multiplyByPointAsVector(
    camera.inverseViewMatrix, ray.direction, new Cesium.Cartesian3()
  )
};

  • VoxelMetadataOrder 비공개(private)로 변경

    • VoxelMetadataOrder가 비공개로 전환되고, VoxelProvider 인터페이스에서 metadataOrder 속성이 제거되었습니다.
    • 상세 설명: 이는 복셀 메타데이터 정렬 방식을 내부 구현 세부 사항으로 은닉하기 위한 API 정리입니다. 커스텀 VoxelProvider를 구현한 경우 metadataOrder 속성 제공을 중단해야 합니다.

🟡 Deprecated (향후 제거 예정)

  • defaultValue 함수 폐기 (1.134에서 제거 예정)

    • defaultValue 함수가 폐기되었으며, 1.134 버전에서 완전히 제거될 예정입니다.
    • 대체 방법: 논리 OR(||) 또는 널 병합 연산자(??)를 사용하세요.
    • 마이그레이션 예시: 
      // ❌ 폐기된 방식
const value = Cesium.defaultValue(options.color, Cesium.Color.WHITE);
 
// ✅ 새로운 방식 (널 병합 연산자 권장)
const value = options.color ?? Cesium.Color.WHITE;
 
// ✅ 또는 논리 OR 사용 (falsy 값도 대체됨 — undefined, null, 0, false, "" 등)
const value = options.color || Cesium.Color.WHITE;

  • defaultValue.EMPTY_OBJECT 폐기 (1.134에서 제거 예정)

    • defaultValue.EMPTY_OBJECT가 폐기되며 1.134 버전에서 제거됩니다.
    • 대체 방법: Frozen.EMPTY_OBJECT를 사용하세요.
    • 마이그레이션 예시: 
      // ❌ 폐기된 방식
const options = Cesium.defaultValue(userOptions, Cesium.defaultValue.EMPTY_OBJECT);
 
// ✅ 새로운 방식
const options = userOptions ?? Cesium.Frozen.EMPTY_OBJECT;

🟢 추가 기능 (Additions)

  • iTwin 공유 키(share keys)를 통한 데이터 로딩 지원

    • 사용자 기반 OAuth 인증 대신 공유 키(share key)를 사용하여 iTwin 데이터를 로딩할 수 있게 되었습니다. 공유 키를 사용하려면 ITwinPlatform.defaultShareKey를 설정하세요.
    • 기술적 배경: 기존 iTwin 데이터 접근은 사용자 OAuth 토큰이 필요했습니다. 공유 키 방식을 사용하면 특정 프로젝트나 데이터셋을 인증 없이 공유하거나, 서버 사이드 렌더링 환경에서 쉽게 데이터에 접근할 수 있습니다.
    • 활용 방법 예시: 
      // 공유 키 설정
Cesium.ITwinPlatform.defaultShareKey = 'your-itwin-share-key';
 
// 이후 일반적인 방법으로 iTwin 데이터 로드
const tileset = await Cesium.Cesium3DTileset.fromUrl(
  Cesium.IonResource.fromAssetId(assetId)
);

  • Frozen.EMPTY_OBJECT 및 Frozen.EMPTY_ARRAY 추가

    • 불필요한 메모리 할당을 방지하기 위한 기본 파라미터 값으로 Frozen.EMPTY_OBJECT와 Frozen.EMPTY_ARRAY가 추가되었습니다.
    • 기술적 배경: 함수의 기본 파라미터로 {} 또는 []를 사용하면 매번 새 객체가 생성됩니다. Frozen.EMPTY_OBJECT는 불변(frozen) 빈 객체로, 재사용되어 GC 압력을 줄입니다.

🔧 수정 사항 (Fixes)

  • 지연된 데이터소스 바운딩 스피어의 엔티티 추적 수정
  • 직교 모드에서 Camera.getPickRay 원점 좌표 수정
  • pixelRatio가 1이 아닌 경우 3D 직교 모드의 줌 수정
  • 원통형 복셀 형상 경계 및 변환 수정
  • 타원체(ellipsoid) 복셀 타일셋의 메타데이터 순서 수정
  • 고해상도 지형 사용 시 updateHeights의 큐 증가로 인한 고정 엔티티 높이 업데이트 중단 수정
  • VaryingType.MAT3 정의 수정

📦 1.127 - 2025-03-03

추가일: 2026-04-10

🔴 Breaking Changes (주요 변경 사항)

  • Cesium3DTilesVoxelProvider가 EXT_primitive_voxels glTF 확장으로 업데이트

    • Cesium3DTilesVoxelProvider가 새로운 EXT_primitive_voxels 확장을 사용하여 glTF 타일을 로드하도록 변경되었습니다. 이전의 커스텀 JSON 형식은 더 이상 지원되지 않습니다.
    • 기술적 배경: EXT_primitive_voxels는 3D Tiles 생태계와의 더 긴밀한 통합을 위한 공식 glTF 확장입니다. 이전에는 비표준 JSON 형식으로 복셀 데이터를 전달했으나, 이제 glTF 표준 기반으로 전환되어 도구 호환성과 상호 운용성이 향상됩니다.
    • 영향: 이전 커스텀 JSON 형식으로 생성된 복셀 타일셋은 재변환이 필요합니다.

  • VoxelProvider.requestData 메서드 반환 타입 변경

    • VoxelProvider 인터페이스의 requestData 메서드가 이제 VoxelContent의 Promise를 반환해야 합니다. 커스텀 제공자는 VoxelContent.fromMetadataArray 메서드를 사용하여 반환 데이터를 구성해야 합니다.
    • 마이그레이션 가이드: 
      // ❌ 이전 방식
// CustomVoxelProvider.prototype.requestData = function(options) {
//   return { ... }; // 직접 데이터 객체 반환
// };
 
// ✅ 새로운 방식
CustomVoxelProvider.prototype.requestData = function(options) {
  const metadataColumn = new Float32Array(options.dataLength);
  // ... metadataColumn에 메타데이터 값 채우기 ...
  const content = Cesium.VoxelContent.fromMetadataArray([metadataColumn]);
  return Promise.resolve(content);
};

  • VoxelCylinderShape 좌표 순서 변경

    • VoxelCylinderShape의 좌표 순서가 (반지름, 각도, 높이) 순서로 변경되었습니다.

🟢 추가 기능 (Additions)

  • VoxelPrimitive.statistics에 texturesByteLength, visited, numberOfTilesWithContentReady 구현
    • 복셀 프리미티브 통계 기능이 강화되었습니다. 통계를 사용하려면 생성자에서 options.calculateStatistics: true로 설정해야 합니다.
    • 활용 방법 예시: 
      const voxelPrimitive = new Cesium.VoxelPrimitive({
  provider: myVoxelProvider,
  calculateStatistics: true // 통계 수집 활성화
});
 
// 통계 접근
console.log(voxelPrimitive.statistics.texturesByteLength);
console.log(voxelPrimitive.statistics.visited);
console.log(voxelPrimitive.statistics.numberOfTilesWithContentReady);

🔧 수정 사항 (Fixes)

  • CustomShader.prototype.destroy를 공개(public) 메서드로 노출

    • CustomShader의 destroy 메서드가 이제 공개 API로 노출되었습니다.

  • polygon/polyline 지오메트리에서 중복 포인트 시 ArcType.RHUMB 오류 수정

    • 폴리곤/폴리라인에 중복 좌표가 포함될 때 ArcType.RHUMB 사용 시 발생하던 오류를 수정했습니다.

  • 3D 직교 모드에서 지상 대기 셰이더 수정

  • 3D 직교 모드에서 줌 수정

  • PrimitiveCollection 내에 중첩된 빌보드 고정(clamp) 수정

  • 레이블 및 빌보드 업데이트 시 검은 깜빡임(black flashes) 오류 수정

  • TextureAtlas 리팩토링

    • 텍스처 아틀라스의 내부 API가 업데이트되었습니다. 비공개 텍스처 아틀라스 API를 사용하는 경우 변경 사항을 확인하세요.
    • 텍스처 아틀라스가 더 보수적으로 크기를 조정합니다. 많은 레이블과 빌보드가 있을 때 텍스처 메모리 오버헤드가 감소합니다.
    • 텍스처 아틀라스가 기존 서브리전(subregion) 좌표를 재사용합니다. 중복 이미지에 대한 중복 텍스처 할당이 방지됩니다.

📦 1.126 - 2025-02-03

추가일: 2026-04-10

🔴 Breaking Changes (주요 변경 사항)

  • createGooglePhotorealistic3DTileset(key) API 제거

    • createGooglePhotorealistic3DTileset(key) 형태(키를 직접 인자로 전달)가 완전히 제거되었습니다. 반드시 옵션 객체 형태를 사용해야 합니다.
    • 마이그레이션 가이드: 
      // ❌ 제거된 방식
// const tileset = await Cesium.createGooglePhotorealistic3DTileset('YOUR_API_KEY');
 
// ✅ 올바른 방식 (옵션 객체 사용)
const tileset = await Cesium.createGooglePhotorealistic3DTileset({
  key: 'YOUR_GOOGLE_API_KEY'
});
viewer.scene.primitives.add(tileset);

  • DataSourceDisplay.ready 동작 변경

    • DataSourceDisplay.ready가 한 번 true로 설정되면 이후 항상 true를 유지하도록 변경되었습니다.
    • 기술적 배경: 이전에는 데이터소스가 업데이트될 때 ready가 잠시 false로 돌아가는 경우가 있었습니다. 이 변경으로 ready 상태가 더 안정적이고 예측 가능해집니다.

🟢 추가 기능 (Additions)

  • ITwinData.loadGeospatialFeatures — Geospatial Features API 지원
    • ITwinData.loadGeospatialFeatures(iTwinId, collectionId) 함수가 추가되어 Bentley의 Geospatial Features API에서 데이터를 로드할 수 있습니다.
    • 기술적 배경: Bentley iTwin 플랫폼의 Geospatial Features API는 GIS 피처 데이터(건물 레이어, 도로망, 수계 등)를 제공합니다. 이 함수를 통해 CesiumJS에서 직접 해당 데이터를 로드하고 시각화할 수 있습니다.
    • 활용 방법 예시: 
      // iTwin Geospatial Features 데이터 로드
const iTwinId = 'your-itwin-id';
const collectionId = 'your-collection-id';
 
const dataSource = await Cesium.ITwinData.loadGeospatialFeatures(
  iTwinId,
  collectionId
);
viewer.dataSources.add(dataSource);
viewer.zoomTo(dataSource);

🔧 수정 사항 (Fixes)

  • Cesium3DTileset.modelMatrix를 초기값으로 리셋 시 오류 수정
  • ClippingPolygon.equals 파라미터 타입 수정
  • Draco 디코딩에서 정규화된 UNSIGNED_BYTE/UNSIGNED_SHORT 버텍스 컬러 수정
  • 문서 내 basemap.nationalmap.gov URL https 수정
  • sinAngle < 1일 때 폴리라인 너비 계산 오류 수정
  • multiple contents에서 외부 타일셋 허용
  • ImageryLayer.fromProviderAsync 타입 정의 수정 (options 파라미터 옵션 표시)
  • Viewer.selectedEntity 설정 시 타입 오류 수정

📦 1.125 - 2025-01-02

추가일: 2026-04-10

🟢 추가 기능 (Additions)

  • iTwin Platform 통합 확장 — Reality Management API의 GeoJSON/KML 지원

    • iTwin Platform과의 통합이 확장되어 Reality Management API에서 GeoJSON 및 KML 데이터를 로드할 수 있게 되었습니다.
    • 기술적 배경: Bentley iTwin의 Reality Management API는 현실 세계 데이터(포인트 클라우드, 메시, GeoJSON/KML 레이어 등)를 관리합니다. 이제 ITwinData.createDataSourceForRealityDataId를 사용하여 해당 데이터를 GeoJSON 또는 KML 형식으로 CesiumJS에서 직접 로드할 수 있습니다.
    • 활용 방법 예시: 
      // Reality Management API에서 GeoJSON/KML 데이터 로드
const dataSource = await Cesium.ITwinData.createDataSourceForRealityDataId(
  accessToken,
  iTwinId,
  realityDataId
);
viewer.dataSources.add(dataSource);
viewer.zoomTo(dataSource);

  • ModelGraphics에 environmentMapOptions 추가

    • ModelGraphics에 environmentMapOptions 속성이 추가되었습니다. 성능상의 이유로 기본적으로 엔티티 위치가 변경되어도 환경 맵이 업데이트되지 않습니다. 위치에 따른 환경 맵 업데이트가 필요하면 environmentMapOptions.maximumPositionEpsilon을 적절히 설정하세요.
    • 기술적 배경: 환경 맵(Image-Based Lighting, IBL)은 주변 환경을 텍스처에 캡처하여 PBR 재질의 반사/조명에 사용됩니다. 매 프레임마다 엔티티 위치에 맞춰 환경 맵을 갱신하면 성능 비용이 크므로, 기본적으로 비활성화하고 필요한 경우에만 활성화하는 방식을 채택했습니다.
    • 활용 방법 예시: 
      // 엔티티 위치에 따른 환경 맵 업데이트 활성화
const entity = viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(127.0, 37.5, 100),
  model: {
    uri: 'model.glb',
    environmentMapOptions: {
      maximumPositionEpsilon: 1.0 // 1미터 이동 시 환경 맵 업데이트
    }
  }
});

  • VoxelPrimitive에 Cesium3DTileset과 동일한 이벤트 추가

    • VoxelPrimitive에 Cesium3DTileset과 동일한 이벤트들이 추가되었습니다: allTilesLoaded, initialTilesLoaded, loadProgress, tileFailed, tileLoad, tileVisible, tileUnload.
    • 기술적 배경: 이전에는 VoxelPrimitive의 로딩 상태를 모니터링하는 공식 이벤트가 없었습니다. 이제 Cesium3DTileset과 동일한 이벤트 인터페이스를 통해 복셀 타일셋의 로딩/언로딩 상태를 추적할 수 있습니다.

🔧 수정 사항 (Fixes)

  • 환경 맵을 사용하는 모델의 메모리 사용량 및 성능 병목 감소

    • 모델에 환경 맵을 사용할 때 발생하던 메모리 사용량 증가 및 성능 저하 문제를 수정했습니다.

  • JulianDate의 소수점 밀리초에 대한 유효한 ISO 문자열 생성 수정

    • JulianDate가 소수점 밀리초를 포함하는 경우에도 항상 유효한 ISO 8601 문자열을 생성하도록 수정되었습니다.

  • 간헐적 z-파이팅(z-fighting) 문제 수정

    • 간헐적으로 발생하던 z-파이팅 현상을 수정했습니다.
    • 기술적 배경: z-파이팅은 두 지오메트리가 거의 같은 깊이에 있을 때 어느 쪽이 앞에 있는지 판단하지 못해 깜빡거리는 현상입니다.

Graph View