日本語 | English

• Playground: https://hiro-nyon.github.io/cesium-heatbox/
• 背景タイル: CartoDB Light (OSMベース)。高トラフィック時はタイルポリシーにご配慮ください。
• デモは gh-pages ブランチに静的ファイルのみを配置しています。

CesiumJS環境内の既存エンティティを対象とした3Dボクセルベースヒートマップ可視化ライブラリです。

English

A 3D voxel-based heatmap visualization library for existing entities in CesiumJS environments.

• Entityベース: 既存のCesium Entityから自動でデータを取得
• 自動範囲設定: エンティティ分布から最適な直方体（AABB）範囲を自動計算
• 最小ボクセル数: 指定された範囲を内包する最小限のボクセル数で効率的に処理
• 相対的色分け: データ内の最小値・最大値に基づく動的色分け
• 分類エンジン (v1.0.0): classification.scheme（linear/log/equal-interval/quantize/threshold）で色分布を宣言的に指定。colorResolver よりも後順位で、安全に既存コードと共存します
• パフォーマンス最適化: バッチ描画によるスムーズな3D表示

• Entity-based: Automatically retrieves data from existing Cesium Entities
• Automatic Range Setting: Automatically calculates optimal axis-aligned box ranges from entity distribution
• Minimal Voxel Count: Efficient processing with minimum voxel count covering specified ranges
• Relative Color Mapping: Dynamic color mapping based on min/max values within data
• Classification Engine (v1.0.0): Declare linear/log/equal-interval/quantize/threshold schemes via classification.scheme. The classifier complements existing colorResolver logic without breaking priority
• Performance Optimization: Smooth 3D display through batch rendering

よくある代替手法

• 2Dヒートマップ画像の貼り付け（例: heatmap.js を ImageryLayer として投影）
• 点群のクラスタリングやサマリ表示（Cesium の Entity クラスタリング）
• 他可視化フレームワークのレイヤー（例: deck.gl の HeatmapLayer など）

Heatbox の強み

• 真の3Dボクセル表現: Z方向（高度）の分布を体積として可視化でき、2Dの塗りつぶしでは失われる高さ情報を保持
• Entityベースのワークフロー: 既存 Cesium.Entity から直接生成。事前のタイル化やサーバー処理が不要
• 自動ボクセルサイズ決定 (v0.1.4): autoVoxelSize によりデータ範囲と件数から最適サイズを自動計算。パフォーマンスと解像度のバランスを自動化
• オーケストレーション型アーキテクチャ（ADR-0009, v0.1.11）: Single Responsibility Principleに基づく完全な責務分離を実現
• 設定プロファイル機能 (v0.1.12): mobile-fast、desktop-balanced、dense-data、sparse-data で環境別最適化
• パフォーマンス監視 (v0.1.12): リアルタイムオーバーレイでFPS、描画時間、メモリ使用量を可視化
• API一貫性向上 (v0.1.12): 命名規則統一（pitchDegrees/headingDegrees）、outlineRenderMode/emulationScope統合
• 適応制御システム統合 (v0.1.12): Resolver廃止によるadaptiveParamsシステムへの一本化
• デバッグ支援強化 (v0.1.12): getEffectiveOptions()による設定確認とプロファイル詳細取得
  • ColorCalculator: 色計算・カラーマップ処理の専門化
  • VoxelSelector: 密度・カバレッジ・ハイブリッド選択戦略の専門化
  • AdaptiveController: 適応パラメータ・近隣密度計算の専門化
  • GeometryRenderer: エンティティ作成・ジオメトリ管理の専門化
  • VoxelRenderer: 各専門クラスのオーケストレーション役に特化（14.5%性能向上を達成）
• 適応的制御システム: 密度とカメラ距離に基づく動的アウトライン制御と TopN 強調表示
• 自動視点調整 (v0.1.9): データ境界への自動カメラフィット機能で最適な視覚化を実現
• デバッグ境界制御 (v0.1.5): debug.showBounds でバウンディングボックス表示をON/OFF制御
• 知覚均等カラーマップ (v0.1.5): viridis、inferno カラーマップと二極性配色（blue-white-red）をサポート
• TopN強調表示 (v0.1.5): 密度上位N個のボクセルを強調、他を淡色表示する highlightTopN オプション
• 枠線重なり対策 (v0.1.6): voxelGap による間隔調整と outlineOpacity による透明度制御で視認性向上
• 動的枠線制御 (v0.1.6): outlineWidthResolver 関数でボクセル毎の枠線太さを密度に応じて動的調整
• 太線エミュレーション (v0.1.12): outlineRenderMode: 'emulation-only' または emulationScope: 'topn'|'all'（outlineEmulation は非推奨）
• 厚い枠線表示 (v0.1.6.2): enableThickFrames で12個のフレームボックスによる視覚的に厚い枠線を実現
• インセット枠線 (v0.1.6.1): outlineInset で枠線をボックス内側にオフセット（outlineInsetMode で TopN 限定も可）
• Wiki自動同期 (v0.1.6): JSDoc → Markdown 変換による GitHub Wiki の自動更新
• パフォーマンス制御: maxRenderVoxels と内部検証（例: validateVoxelCount）で安定動作を担保
• デバッグ/統計の取得: getStatistics() と getDebugInfo() でレンダリング状態や調整内容を把握可能
• 表現の柔軟性: wireframeOnly、heightBased、カラーマップ設定などで見やすさを調整

適していないケース（指針）

• 数十万〜数百万スケールの体積格子を恒常的に描画する用途 → 専用GPUベースのボリュームレンダリングや3D Tiles等を検討
• 連続体の科学可視化（例: 医用CT/流体のボリュームレンダリング） → 専用のボリュームレンダリング手法が適合

Common Alternatives

• Draped 2D heatmap textures (e.g., heatmap.js projected as an ImageryLayer)
• Point clustering/aggregation using Cesium Entity clustering
• Layers from other visualization frameworks (e.g., deck.gl HeatmapLayer)

Strengths of Heatbox

• True 3D voxel representation: Preserves vertical distribution (Z) as volumetric voxels, unlike 2D color fills
• Entity-based workflow: Builds directly from existing Cesium.Entity objects; no pre-tiling or server-side processing required
• Automatic voxel sizing (v0.1.4): autoVoxelSize estimates optimal size from data extent and counts for balanced quality/performance
• Debug boundary control (v0.1.5): debug.showBounds for bounding box display ON/OFF control
• Perceptually uniform color maps (v0.1.5): viridis, inferno color maps and diverging color scheme (blue-white-red)
• TopN highlighting (v0.1.5): highlightTopN option to emphasize top N density voxels
• Outline overlap mitigation (v0.1.6): voxelGap for spacing and outlineOpacity for transparency control
• Dynamic outline control (v0.1.6): outlineWidthResolver function for density-adaptive outline thickness
• Outline emulation (v0.1.12): use outlineRenderMode: 'emulation-only' or emulationScope: 'topn'|'all' (legacy outlineEmulation is deprecated)
• Thick outline frames (v0.1.6.2): enableThickFrames creates visually thick outlines using 12 frame boxes
• Inset outline (v0.1.6.1): outlineInset to draw outlines inset from faces (outlineInsetMode to limit to TopN)
• Wiki auto-sync (v0.1.6): JSDoc → Markdown conversion for automated GitHub Wiki updates
• Performance guard rails: maxRenderVoxels and internal checks (e.g., validateVoxelCount) for stable rendering
• Debugging and statistics: Introspection via getStatistics() and getDebugInfo()
• Flexible presentation: wireframeOnly, heightBased, and color map presets for readability

When this may not fit

• Persistent rendering of hundreds of thousands to millions of voxels → consider GPU volume rendering or 3D Tiles-based approaches
• Scientific continuous volumes (e.g., CT/CFD) → dedicated volume rendering techniques are more suitable

npm install cesium-heatbox

<!-- UMDバンドルをCDN経由で読み込み -->
<script src="https://unpkg.com/cesium-heatbox@latest/dist/cesium-heatbox.umd.min.js"></script>

git clone https://github.com/hiro-nyon/cesium-heatbox.git
cd cesium-heatbox
npm install
npm run build

npm install cesium-heatbox

<!-- Load UMD bundle via CDN -->
<script src="https://unpkg.com/cesium-heatbox@latest/dist/cesium-heatbox.umd.min.js"></script>

git clone https://github.com/hiro-nyon/cesium-heatbox.git
cd cesium-heatbox
npm install
npm run build

import { Heatbox } from 'cesium-heatbox';

// v0.1.12: プロファイル機能で環境に最適化
const heatbox = new Heatbox(viewer, {
  profile: 'desktop-balanced',     // 自動設定プロファイル  
  voxelSize: { x: 1000, y: 1000, z: 100 },
  opacity: 0.8,
  performanceOverlay: {
    enabled: true,                 // リアルタイム性能監視
    position: 'top-right'
  }
});

// エンティティからヒートマップを作成
const entities = viewer.entities.values;
heatbox.setData(entities);

// v0.1.12: fitView は内部で postRender 一回の実行にスケジュールされ、
// 描画競合を避けつつ Rectangle→BoundingSphere ベースで安定ズームします。
await heatbox.fitView(null, {
  paddingPercent: 0.1,
  pitchDegrees: -35,
  headingDegrees: 0
});

// 統計情報の取得
const statistics = heatbox.getStatistics();
console.log('作成完了:', statistics);

補足（v0.1.12）

• プロファイルの確認/詳細:

const profiles = Heatbox.listProfiles();
const details = Heatbox.getProfileDetails('mobile-fast');

• パフォーマンスオーバーレイのランタイム制御:

heatbox.setPerformanceOverlayEnabled(true, { position: 'bottom-left' });
heatbox.togglePerformanceOverlay();

import { Heatbox } from 'cesium-heatbox';

// v0.1.12: Use configuration profiles for environment optimization
const heatbox = new Heatbox(viewer, {
  profile: 'desktop-balanced',     // Auto-configuration profile
  voxelSize: { x: 1000, y: 1000, z: 100 },
  opacity: 0.8,
  performanceOverlay: {
    enabled: true,                 // Real-time performance monitoring  
    position: 'top-right'
  }
});

// Create heatmap from entities
const entities = viewer.entities.values;
heatbox.setData(entities);

// v0.1.12: Fit view with updated API naming convention
heatbox.fitView({
  paddingPercent: 0.1,
  pitchDegrees: -45,              // Updated naming convention
  headingDegrees: 0
});

// Get statistics
const statistics = heatbox.getStatistics();
console.log('Creation completed:', statistics);

Tips (v0.1.12)

• Profiles overview/details:

const profiles = Heatbox.listProfiles();
const details = Heatbox.getProfileDetails('mobile-fast');

• Runtime control of performance overlay:

heatbox.setPerformanceOverlayEnabled(true, { position: 'bottom-left' });
heatbox.togglePerformanceOverlay();

classification オプションで linear/log/equal-interval/quantize/threshold に加え quantile/jenks を使った分類を宣言的に制御できます。classificationTargets で color / opacity / width を個別に有効化し、adaptiveParams.*Range で不透明度や線幅を補間します。colorResolver が存在する場合は従来どおり resolver が優先されます。

const heatbox = new Heatbox(viewer, {
  voxelSize: 30,
  classification: {
    enabled: true,
    scheme: 'quantile',    // 'linear' | 'log' | 'equal-interval' | 'quantize' | 'threshold' | 'quantile' | 'jenks'
    classes: 5,
    colorMap: ['#0f172a', '#1d4ed8', '#22d3ee', '#f97316', '#facc15'],
    classificationTargets: { color: true, opacity: true, width: true }
  },
  adaptiveParams: {
    boxOpacityRange: [0.35, 0.95],
    outlineOpacityRange: [0.4, 1.0],
    outlineWidthRange: [1, 5]
  }
});

await heatbox.createFromEntities(viewer.entities.values);

const classificationStats = heatbox.getStatistics().classification;
console.log(classificationStats.breaks);        // 自動計算された区切り
console.log(classificationStats.quantiles);     // [Q1, Q2, Q3, Q4]
console.log(classificationStats.jenksBreaks);   // jenks 時: 上限境界
console.log(classificationStats.ckmeansClusters); // jenks 時: クラスタ配列
console.log(classificationStats.histogram);     // { bins, counts }（最大10ビン）```

// UI で凡例を生成
const legendEl = heatbox.createLegend();
// ... 後でオプションを更新した場合
heatbox.updateLegend();

• threshold スキームのみ thresholds 配列が必須です。quantile/jenks はデータ値を必須とし、classes でクラス数を指定します。
• classification.colorMap は単色の配列、または { position, color } 形式のストップ配列を指定できます。
• 統計情報（HeatboxStatistics.classification）には domain / quantiles / jenksBreaks / ckmeansClusters / histogram / breaks が含まれ、凡例（createLegend）やデバッグに利用できます。
• 拡張デモ: examples/advanced/classification-extension-demo.html（color/opacity/width 併用 + quantile/jenks）、エミュレーション時のアウトライン反映は examples/advanced/emulation-opacity-demo.html を参照してください。

The new classification option exposes declarative color schemes (linear/log/equal-interval/quantize/threshold). In v1.0.0 it only drives colors and still yields to a user-provided colorResolver.

const heatbox = new Heatbox(viewer, {
  classification: {
    enabled: true,
    scheme: 'quantize',
    classes: 5,
    colorMap: ['#0f172a', '#1d4ed8', '#22d3ee', '#f97316', '#facc15']
  }
});

await heatbox.createFromEntities(viewer.entities.values);

const classificationStats = heatbox.getStatistics().classification;
console.table({
  scheme: classificationStats.scheme,
  domain: classificationStats.domain,
  breaks: classificationStats.breaks
});

• threshold requires the explicit thresholds array; other schemes derive class breaks automatically from data and the requested classes count.
• classification.colorMap accepts either color strings or stop objects with { position, color }.
• HeatboxStatistics.classification now bundles domain, quantiles, histogram bins, and the computed breaks so you can render custom legends or debugging output.
• See examples/advanced/classification-demo.html for an interactive UI that switches between the five schemes with live palette previews.

v0.1.17新機能: 空間ID（METI準拠 / Ouranos）に基づくタイルグリッドモードに対応しました。

従来の一様グリッドに加え、地理空間タイルシステム（空間ID）を用いたボクセル生成が可能になりました：

• タイルグリッドモード: 経度・緯度・高度を考慮した空間IDベースのボクセル配置
• Ouransos-GEXライブラリ統合: METI準拠の空間ID変換（オプショナル依存）
• フォールバックメカニズム: Ouranos未インストール時は内蔵Web Mercatorベース変換を使用
• 自動ズーム選択: 目標ボクセルサイズ（voxelSize）と緯度から最適なズームレベルを自動決定

空間ID機能は本体のインストールだけで基本的に動作しますが、公式のouranos-gex-lib-for-javascriptを使用する場合は追加の手順が必要です。

ouranos-gex-lib-for-javascriptはGitHub上にビルド済みファイルが含まれていません。そのため、通常のnpm installでは動作しません。以下の特別な手順が必要です：

インストール不要です。cesium-heatbox本体のみをインストールすれば、内蔵のWeb Mercatorベース変換が自動的に使用されます：

npm install cesium-heatbox

このモードでは、Ouranoscが利用できない場合に自動的に内蔵変換に切り替わります。多くの用途で十分な精度を提供します。

METI準拠の高精度な空間ID変換が必要な場合は、以下の手順でOuranosライブラリをセットアップします：

# 1. cesium-heatboxをインストール
npm install cesium-heatbox

# 2. ouranos-gexをオプショナル依存としてインストール
npm install ouranos-gex-lib-for-javascript@github:ouranos-gex/ouranos-gex-lib-for-JavaScript --no-save

# 3. 専用スクリプトでビルド＆セットアップ
npx cesium-heatbox-install-ouranos

Note: npx cesium-heatbox-install-ouranosはnode_modules/cesium-heatbox/tools/install-ouranos.jsを実行します。このスクリプトは：

1. vendor/ディレクトリにOuranosリポジトリをクローン
2. 依存関係をインストールしてビルド
3. ビルド済みファイルをnode_modules/にコピー

正しくインストールされているか確認するには：

import { Heatbox } from 'cesium-heatbox';

const heatbox = new Heatbox(viewer, {
  spatialId: { enabled: true }
});

// 統計情報でプロバイダーを確認
const stats = heatbox.getStatistics();
console.log('Provider:', stats.spatialIdProvider); 
// "ouranos-gex" = 公式ライブラリ使用中
// "fallback" or null = 内蔵変換使用中

問題: npm install後に空間ID機能が動作しない

解決策:

1. node_modules/ouranos-gex-lib-for-javascript/dist/index.jsが存在するか確認
2. 存在しない場合はnpx cesium-heatbox-install-ouranosを実行
3. それでも失敗する場合は、vendor/ディレクトリを削除してから再試行

問題: Module not found: Error: Can't resolve 'ouranos-gex-lib-for-javascript'という警告

解決策: これは正常です。Ouranosはオプショナル依存のため、webpackビルド時に警告が出ますが、実行時には動的importでフォールバックします。警告を無視して問題ありません。

import { Heatbox } from 'cesium-heatbox';

// 空間IDモードを有効化（自動ズーム選択）
const heatbox = new Heatbox(viewer, {
  spatialId: {
    enabled: true,              // 空間IDモードを有効化
    mode: 'tile-grid',          // タイルグリッドモード
    provider: 'ouranos-gex',    // 空間IDプロバイダー
    zoomControl: 'auto',        // 自動ズーム選択
    zoomTolerancePct: 10        // 許容誤差 (%)
  },
  voxelSize: 30  // 目標ボクセルサイズ（メートル）
});

await heatbox.createFromEntities(entities);

// 空間ID統計の確認
const stats = heatbox.getStatistics();
console.log('空間IDズーム:', stats.spatialIdZoom);
console.log('プロバイダー:', stats.spatialIdProvider);

const heatbox = new Heatbox(viewer, {
  spatialId: {
    enabled: true,
    zoom: 25,                    // ズームレベル 25（約1mセル）
    zoomControl: 'manual'        // 手動ズーム
  }
});

• 高緯度対応: ±85.0511°（Web Mercator限界）内で正常動作
• 日付変更線対応: 次バージョン（v0.1.19）で実装予定
• グローバルQA: 高緯度・極地・日付変更線をまたぐケースは v0.1.19 で検証予定

詳細は空間ID使用例を参照してください。

v0.1.17 New Feature: Spatial ID (METI-compliant / Ouranos) tile-grid mode support.

In addition to uniform grids, voxel generation using geospatial tile systems (Spatial ID) is now available:

• Tile-Grid Mode: Spatial ID-based voxel placement considering longitude, latitude, and altitude
• Ouranos-GEX Library Integration: METI-compliant spatial ID conversion (optional dependency)
• Fallback Mechanism: Built-in Web Mercator-based conversion when Ouranos is not installed
• Auto Zoom Selection: Automatically determines optimal zoom level from target voxel size (voxelSize) and latitude

The Spatial ID feature works out of the box with basic installation, but using the official ouranos-gex-lib-for-javascript requires additional setup.

ouranos-gex-lib-for-javascript does not include pre-built files on GitHub. Therefore, standard npm install will not work. Special setup steps are required:

No additional installation needed. Simply install cesium-heatbox and the built-in Web Mercator-based converter will be used automatically:

npm install cesium-heatbox

This mode automatically falls back to the built-in converter when Ouranos is unavailable. It provides sufficient accuracy for most use cases.

If you need METI-compliant high-precision spatial ID conversion, follow these steps to set up the Ouranos library:

# 1. Install cesium-heatbox
npm install cesium-heatbox

# 2. Install ouranos-gex as optional dependency
npm install ouranos-gex-lib-for-javascript@github:ouranos-gex/ouranos-gex-lib-for-JavaScript --no-save

# 3. Build and setup using dedicated script
npx cesium-heatbox-install-ouranos

Note: npx cesium-heatbox-install-ouranos runs node_modules/cesium-heatbox/tools/install-ouranos.js. This script:

1. Clones the Ouranos repository into vendor/ directory
2. Installs dependencies and builds the library
3. Copies built files into node_modules/

To verify correct installation:

import { Heatbox } from 'cesium-heatbox';

const heatbox = new Heatbox(viewer, {
  spatialId: { enabled: true }
});

// Check provider in statistics
const stats = heatbox.getStatistics();
console.log('Provider:', stats.spatialIdProvider); 
// "ouranos-gex" = using official library
// "fallback" or null = using built-in converter

Issue: Spatial ID feature doesn't work after npm install

Solution:

1. Check if node_modules/ouranos-gex-lib-for-javascript/dist/index.js exists
2. If not, run npx cesium-heatbox-install-ouranos
3. If still failing, delete vendor/ directory and retry

Issue: Warning Module not found: Error: Can't resolve 'ouranos-gex-lib-for-javascript'

Solution: This is normal. Ouranos is an optional dependency, so webpack shows warnings during build, but the runtime will dynamically import and fallback. You can safely ignore this warning.

import { Heatbox } from 'cesium-heatbox';

// Enable spatial ID mode with auto zoom
const heatbox = new Heatbox(viewer, {
  spatialId: {
    enabled: true,              // Enable spatial ID mode
    mode: 'tile-grid',          // Tile-grid mode
    provider: 'ouranos-gex',    // Spatial ID provider
    zoomControl: 'auto',        // Auto zoom selection
    zoomTolerancePct: 10        // Tolerance (%)
  },
  voxelSize: 30  // Target voxel size (meters)
});

await heatbox.createFromEntities(entities);

// Check spatial ID statistics
const stats = heatbox.getStatistics();
console.log('Spatial ID zoom:', stats.spatialIdZoom);
console.log('Provider:', stats.spatialIdProvider);

const heatbox = new Heatbox(viewer, {
  spatialId: {
    enabled: true,
    zoom: 25,                    // Zoom level 25 (~1m cells)
    zoomControl: 'manual'        // Manual zoom
  }
});

• High Latitude: Operates normally within ±85.0511° (Web Mercator limit)
• Antimeridian: Planned for next version (v0.1.19)
• Global QA: High-latitude, polar, and antimeridian-crossing cases will be validated in v0.1.19

See Spatial ID Examples for details.

v0.1.18新機能: ボクセル内のエンティティをカテゴリ・種別・データソース等のレイヤで集約できるようになりました。

従来のボクセルごとの総エンティティ数に加え、各ボクセル内のエンティティをレイヤ（カテゴリ）別に集計できます：

• プロパティベース集約: エンティティの特定プロパティをレイヤキーとして使用
• カスタムリゾルバ: 任意のロジックでレイヤキーを決定
• ボクセルごとの内訳: 各ボクセルの支配的レイヤ（layerTop）と詳細内訳（layerStats）
• グローバル統計: 全ボクセルを通じた上位Nレイヤの集計
• ピッキング統合: ボクセルクリック時にレイヤ構成を表示

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 }
// ]

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% オーバーヘッド
• 無効時: オーバーヘッドなし（デフォルト）

詳細は集約使用例を参照してください。

v0.1.18 New Feature: Aggregate entities within voxels by category, type, data source, or custom layers.

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

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 }
// ]

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';
    }
  }
});

When you click a voxel, the layer composition is displayed:

Voxel Composition:
- residential: 30 (60%)
- commercial: 15 (30%)
- industrial: 5 (10%)

• 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'

• Memory: ~8-16 bytes per unique layer per voxel
• Processing: ≤ +10% overhead when enabled
• No overhead: When disabled (default)

See Aggregation Examples for details.

const heatbox = new Heatbox(viewer, options);

パラメータ:

• viewer (Cesium.Viewer): CesiumJSビューワーインスタンス
• options (Object): 設定オプション

• createFromEntities(entities): エンティティからヒートマップを作成
• setVisible(show): 表示/非表示の切り替え
• clear(): ヒートマップをクリア
• getStatistics(): 統計情報を取得

const heatbox = new Heatbox(viewer, options);

Parameters:

• viewer (Cesium.Viewer): CesiumJS viewer instance
• options (Object): Configuration options

• createFromEntities(entities): Create heatmap from entities
• setVisible(show): Toggle visibility
• clear(): Clear heatmap
• getStatistics(): Get statistics

基本的な使用例は examples/ フォルダを参照してください。特に examples/advanced/classification-demo.html では classification.scheme の五つの方式を切り替えながらカラーマップや統計メタデータを確認できます。

Please refer to the examples/ folder for basic usage examples. The examples/advanced/classification-demo.html page demonstrates the five classification schemes with live palette previews and statistics readouts.

英語 → 日本語の順で掲載し、各ページ先頭に言語切替リンク（English | 日本語）を用意しています。
Docs are structured English first, then Japanese. Each page includes a language switch at the top.

• API リファレンス
• クイックスタート
• はじめに
• 移行ガイド 🆕 v0.1.12移行ガイド
• 開発ガイド

• API Reference
• Quick Start
• Getting Started
• Migration Guide 🆕 v0.1.12 Migration Guide
• Development Guide

MIT License - 詳細は LICENSE を参照してください。
MIT License - See LICENSE for details.

プロジェクトへの貢献を歓迎します！詳細は CONTRIBUTING.md を参照してください。

Contributions to the project are welcome! See CONTRIBUTING.md for details.