cesium-heatbox 0.1.17 → 0.1.18

package/CHANGELOG.md

@@ -9,6 +9,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 > **Note**: 将来の予定・ロードマップは [ROADMAP.md](ROADMAP.md) および [GitHub Issues](https://github.com/hiro-nyon/cesium-heatbox/issues) で管理されています。
 
+## [0.1.18] - 2025-11-18
+
+### Added
+- **Layer aggregation pipeline**: `Heatbox` の `aggregation` オプションでレイヤカテゴリ別にボクセルを集計し、`layerStats`/`layerTop`/`layers`（トップN）などの統計を取得できるようにしました。プロパティベースと `keyResolver` の両方をサポートし、ピッキング説明文にもレイヤ構成を表示できます。
+- **Examples & ADR**: `examples/aggregation/*` と `docs/adr/ADR-0014-v0.1.18-voxel-layer-aggregation.md` を追加し、単一/複数ソースのユースケースや推奨値を示しました。
+- **Helper utilities**: `src/utils/cesiumProperty.js`、`src/utils/escapeHtml.js` を追加し、レイヤ統計の整形と Cesium Property ラッパーを共通化しました。
+
+### Changed
+- **DataProcessor / GeometryRenderer**: レイヤ集計のために内部データ構造を拡張し、グローバル統計とピッキング説明を自動生成するよう更新しました。
+- **Validation & constants**: 参照テーブルを拡充し、`aggregation.topN` や `aggregation.byProperty` などの検証を強化しました。
+- **テスト**: `test/core/aggregation.test.js`、`test/integration/aggregation.test.js`、`test/performance/aggregation-performance.test.js` を追加/拡張し、層別集計の回帰・性能を担保しました。
+
+### Documentation
+- README/Wiki にレイヤ集計ガイドを追記し、日本語/英語のコード例、ベストプラクティス、Spatial ID セットアップガイドを更新しました。
+
 ## [0.1.15-alpha.4] - 2025-10-10
 
 ### Added

package/README.md

@@ -521,6 +521,170 @@ const heatbox = new Heatbox(viewer, {
 
 See [Spatial ID Examples](examples/spatial-id/) for details.
 
+## レイヤ別集約 / Layer Aggregation
+
+### 日本語
+
+**v0.1.18新機能**: ボクセル内のエンティティをカテゴリ・種別・データソース等のレイヤで集約できるようになりました。
+
+#### 概要
+
+従来のボクセルごとの総エンティティ数に加え、各ボクセル内のエンティティを**レイヤ（カテゴリ）別**に集計できます：
+
+- **プロパティベース集約**: エンティティの特定プロパティをレイヤキーとして使用
+- **カスタムリゾルバ**: 任意のロジックでレイヤキーを決定
+- **ボクセルごとの内訳**: 各ボクセルの支配的レイヤ（layerTop）と詳細内訳（layerStats）
+- **グローバル統計**: 全ボクセルを通じた上位Nレイヤの集計
+- **ピッキング統合**: ボクセルクリック時にレイヤ構成を表示
+
+#### 基本的な使用方法
+
+```javascript
+import { Heatbox } from 'cesium-heatbox';
+
+// プロパティベース集約（建物種別）
+const heatbox = new Heatbox(viewer, {
+  aggregation: {
+    enabled: true,
+    byProperty: 'buildingType',  // entity.properties.buildingType をレイヤキーとして使用
+    showInDescription: true,     // ボクセル説明文にレイヤ内訳を表示
+    topN: 10                     // 統計情報で上位10レイヤを返却
+  }
+});
+
+await heatbox.createFromEntities(entities);
+
+// グローバル統計の確認
+const stats = heatbox.getStatistics();
+console.log(stats.layers);
+// [
+//   { key: 'residential', total: 5234 },
+//   { key: 'commercial', total: 2103 },
+//   { key: 'industrial', total: 987 }
+// ]
+```
+
+#### カスタムリゾルバ
+
+```javascript
+const heatbox = new Heatbox(viewer, {
+  aggregation: {
+    enabled: true,
+    keyResolver: (entity) => {
+      // カスタムロジックでレイヤキーを決定
+      const hour = new Date(entity.timestamp).getHours();
+      return hour < 12 ? 'morning' : 'afternoon';
+    }
+  }
+});
+```
+
+#### ボクセルピッキング
+
+ボクセルをクリックすると、レイヤ構成が表示されます：
+
+```
+ボクセル構成:
+- residential: 30 (60%)
+- commercial: 15 (30%)
+- industrial: 5 (10%)
+```
+
+#### ベストプラクティス
+
+- **カテゴリカルキーを使用**: タイムスタンプやIDなど連続値は避け、カテゴリ値を使用してください
+- **ユニークレイヤ数を制限**: ボクセルあたり100未満のユニークレイヤを推奨
+- **エラーハンドリング**: `keyResolver`は文字列を返すべきです。エラー時は'unknown'にフォールバックします
+
+#### パフォーマンス
+
+- **メモリ**: ボクセルあたりのユニークレイヤあたり ~8-16 バイト
+- **処理時間**: 有効時 ≤ +10% オーバーヘッド
+- **無効時**: オーバーヘッドなし（デフォルト）
+
+詳細は[集約使用例](examples/aggregation/)を参照してください。
+
+### English
+
+**v0.1.18 New Feature**: Aggregate entities within voxels by category, type, data source, or custom layers.
+
+#### Overview
+
+In addition to total entity counts per voxel, you can now aggregate entities by **layers (categories)**:
+
+- **Property-based aggregation**: Use a specific entity property as the layer key
+- **Custom resolver**: Determine layer keys with arbitrary logic
+- **Per-voxel breakdown**: Dominant layer (layerTop) and detailed breakdown (layerStats) for each voxel
+- **Global statistics**: Top-N layer aggregation across all voxels
+- **Picking integration**: Display layer composition when clicking voxels
+
+#### Basic Usage
+
+```javascript
+import { Heatbox } from 'cesium-heatbox';
+
+// Property-based aggregation (building types)
+const heatbox = new Heatbox(viewer, {
+  aggregation: {
+    enabled: true,
+    byProperty: 'buildingType',  // Use entity.properties.buildingType as layer key
+    showInDescription: true,     // Show layer breakdown in voxel description
+    topN: 10                     // Return top 10 layers in statistics
+  }
+});
+
+await heatbox.createFromEntities(entities);
+
+// Check global statistics
+const stats = heatbox.getStatistics();
+console.log(stats.layers);
+// [
+//   { key: 'residential', total: 5234 },
+//   { key: 'commercial', total: 2103 },
+//   { key: 'industrial', total: 987 }
+// ]
+```
+
+#### Custom Resolver
+
+```javascript
+const heatbox = new Heatbox(viewer, {
+  aggregation: {
+    enabled: true,
+    keyResolver: (entity) => {
+      // Custom logic to determine layer key
+      const hour = new Date(entity.timestamp).getHours();
+      return hour < 12 ? 'morning' : 'afternoon';
+    }
+  }
+});
+```
+
+#### Voxel Picking
+
+When you click a voxel, the layer composition is displayed:
+
+```
+Voxel Composition:
+- residential: 30 (60%)
+- commercial: 15 (30%)
+- industrial: 5 (10%)
+```
+
+#### Best Practices
+
+- **Use categorical keys**: Avoid continuous values like timestamps or IDs; use categorical values
+- **Limit unique layers**: Keep unique layer count < 100 per voxel for optimal performance
+- **Error handling**: `keyResolver` should return strings; errors fall back to 'unknown'
+
+#### Performance
+
+- **Memory**: ~8-16 bytes per unique layer per voxel
+- **Processing**: ≤ +10% overhead when enabled
+- **No overhead**: When disabled (default)
+
+See [Aggregation Examples](examples/aggregation/) for details.
+
 ## API
 
 ### 日本語