Quick Start - hiro-nyon/cesium-heatbox GitHub Wiki

Quick Start Guide (クイックスタートガイド)

English

Target Audience: Those who want to use cesium-heatbox immediately
Time Required: 10-15 minutes
Prerequisites: Node.js 18+, Git, basic JavaScript knowledge

Environment Setup (5 minutes)
Project Setup (3 minutes)
Sample Execution (2 minutes)
Basic Development Work (5 minutes)
Next Steps

Environment Setup (5 minutes)

1. Check Node.js Installation

# Check version
node --version  # v18.0.0 or higher required
npm --version   # v8.0.0 or higher required

If not installed:

Download LTS version from Node.js official site
Run installer

2. Check Git Installation

# Check version
git --version

If not installed:

Download from Git official site
macOS: brew install git
Windows: Install Git for Windows

Project Setup (3 minutes)

1. Install cesium-heatbox

# Install from npm
npm install cesium-heatbox

# Or for development from source
git clone https://github.com/hiro-nyon/cesium-heatbox.git
cd cesium-heatbox
npm install

2. Install Dependencies (if building from source)

# Initial setup
npm install

# Verify success
npm ls --depth=0

3. Basic Operation Check

# Run tests
npm test

# Run build
npm run build

# Check results
ls -la dist/

Expected output:

dist/
├── cesium-heatbox.js
├── cesium-heatbox.min.js
└── cesium-heatbox.umd.js

Sample Execution (2 minutes)

1. Start Development Server

# Start development server
npm run dev

# Check in browser
# Browser should open automatically (usually http://localhost:8080)

2. Check Basic Sample

Verify in browser:

Basic 3D map display
Heatmap configuration UI
Entity generation and heatmap creation buttons

3. Function Test

Generate Entities: Click "Generate Test Entities" button
Create Heatmap: Click "Create Heatmap" button
Change Settings: Adjust voxel size and opacity
Toggle Display: Use "Show/Hide" button to verify

Basic Development Work (5 minutes)

1. Open Code in Editor

# Open with Visual Studio Code
code .

# Or open with other editor
open .

Basic File Structure:

cesium-heatbox/
├── src/                    # Source code
│   ├── Heatbox.js         # Main class
│   ├── core/              # Core functionality
│   └── utils/             # Utilities
├── examples/              # Sample code
│   └── basic/
│       ├── index.html
│       └── app.js
├── test/                  # Test code
└── docs/                  # Documentation

2. Try Simple Changes

Change default voxel size:

// src/utils/constants.js
export const DEFAULT_VOXEL_SIZE = 20;  // Change 20 → 30

Change default colors:

// src/utils/constants.js
export const DEFAULT_MIN_COLOR = [0, 32, 255];     // Blue
export const DEFAULT_MAX_COLOR = [255, 64, 0];     // Red
// → Try changing to other colors

3. Verify Changes

# Check with development server (hot reload)
npm run dev

# Check with tests
npm test

# Check with build
npm run build

4. Commit Changes

# Check changes
git status
git diff

# Commit changes
git add .
git commit -m "chore: update default voxel size to 30"

# Push to GitHub
git push origin main

v0.1.9 New Features (Advanced Usage)

1. Adaptive Rendering with Auto Render Budget

Automatically optimize performance based on device capabilities:

const heatbox = new Heatbox(viewer, {
  maxRenderVoxels: 'auto',        // Auto device detection
  renderLimitStrategy: 'hybrid',   // Smart voxel selection
  autoVoxelSizeMode: 'occupancy'  // Enhanced calculation
});

await heatbox.setData(entities);

// Check applied settings
const stats = heatbox.getStatistics();
console.log(`Device tier: ${stats.renderBudgetTier}`);
console.log(`Auto max voxels: ${stats.autoMaxRenderVoxels}`);
console.log(`Rendered: ${stats.renderedVoxels}/${stats.totalVoxels}`);

2. Smart Camera Positioning

Automatically position camera for optimal data viewing:

// Basic auto-fit
await heatbox.fitView();

// Custom camera angles
await heatbox.fitView(null, {
  heading: 45,      // Camera direction (degrees)
  pitch: -60,       // Camera tilt (degrees)
  paddingPercent: 0.2 // Extra space around data (ratio of data extent)
});

// Auto-fit after data loading
const heatbox = new Heatbox(viewer, {
  autoView: true,  // Automatically execute fitView
  fitViewOptions: { heading: 0, pitch: -45 }
});

3. Rendering Strategy Comparison

Test different voxel selection strategies:

// Dense data areas - use density strategy
const denseHeatbox = new Heatbox(viewer, {
  renderLimitStrategy: 'density',
  maxRenderVoxels: 5000
});

// Wide area coverage - use coverage strategy  
const coverageHeatbox = new Heatbox(viewer, {
  renderLimitStrategy: 'coverage',
  maxRenderVoxels: 5000
});

// Balanced approach - use hybrid strategy
const hybridHeatbox = new Heatbox(viewer, {
  renderLimitStrategy: 'hybrid',
  maxRenderVoxels: 5000
});

4. Enhanced Auto Voxel Sizing

Use mathematical occupancy estimation for optimal voxel size:

const heatbox = new Heatbox(viewer, {
  autoVoxelSize: true,
  autoVoxelSizeMode: 'occupancy', // v0.1.9 enhanced mode
  maxRenderVoxels: 'auto'
});

await heatbox.setData(entities);

// Check calculation results
const stats = heatbox.getStatistics();
console.log(`Original size: ${stats.originalVoxelSize}m`);
console.log(`Final size: ${stats.finalVoxelSize}m`);
console.log(`Adjusted: ${stats.autoAdjusted}`);
console.log(`Reason: ${stats.adjustmentReason}`);

5. Try the Interactive Demo

Experience v0.1.9 features with the comprehensive demo:

# Open advanced demo
open examples/selection-limits/adaptive-rendering-demo.html

The demo includes:

Real-time strategy switching
Device tier visualization
Performance monitoring
Interactive controls for all new features

Next Steps

1. Read Detailed Documentation

development-guide.md: From basics to advanced development
specification.md: Complete project specifications
API.md: Detailed API specifications

2. Practical Development

Feature implementation:

Check v1.0.0 planned features in specification.md
Challenge implementing data source selection functionality
Add test cases
Update documentation

Quality improvement:

Improve test coverage
Optimize performance
Enhance error handling
Improve usability

3. Release Preparation

Alpha release:

# Update version
npm version 0.1.0-alpha.1 --no-git-tag-version

# Create tag
git add .
git commit -m "chore: bump version to 0.1.0-alpha.1"
git tag v0.1.0-alpha.1

# Push
git push origin main
git push origin v0.1.0-alpha.1

Future NPM publication:

# Prepare for publication
npm publish --dry-run

# Publish as alpha
npm publish --tag alpha

Frequently Used Commands

Development:

npm install     # Install dependencies
npm run dev     # Start development server
npm test        # Run tests
npm run build   # Build
npm run lint    # Linting

Git Operations:

git status                    # Check status
git add .                     # Stage changes
git commit -m "message"       # Commit
git push origin main          # Push
git pull origin main          # Pull latest

Troubleshooting:

# Environment reset
rm -rf node_modules package-lock.json
npm install

# Detailed error checking
npm test -- --verbose
npm run build -- --verbose

Frequently Asked Questions

Q: Development server won't start A: Check:

Node.js 18+ installed
npm install succeeded
Port 8080 available

Q: Tests fail A: Try:

npm test -- --verbose for detailed errors
npm install to reinstall dependencies
Run specific test: npm test -- Heatbox.test.js

Q: Build fails A: Check:

No ESLint errors: npm run lint
No type errors: npm run type-check
File paths are correct

Q: Git push error A: Try:

git pull origin main to get latest
Resolve conflicts if any
Push again

Success Tips

Start small: Don't make big changes at once
Test frequently: Always run tests after changes
Commit often: Commit in meaningful units
Read documentation: Check specifications for questions
Don't fear experimentation: Failure is a learning opportunity

Congratulations! Enjoy developing with cesium-heatbox!

日本語

対象: cesium-heatboxを今すぐ使いたい方
所要時間: 10-15分
前提条件: Node.js 18+、Git、基本的なJavaScript知識

環境準備（5分）

1. Node.jsのインストール確認

# バージョン確認
node --version  # v18.0.0以上必要
npm --version   # v8.0.0以上必要

未インストールの場合:

Node.js公式サイトでLTS版をダウンロード
インストーラーを実行

2. Gitのインストール確認

# バージョン確認
git --version

未インストールの場合:

Git公式サイトからダウンロード
macOS: brew install git
Windows: Git for Windowsをインストール

プロジェクトセットアップ（3分）

1. cesium-heatboxのインストール

# npmからインストール
npm install cesium-heatbox

# または開発用にソースから
git clone https://github.com/hiro-nyon/cesium-heatbox.git
cd cesium-heatbox
npm install

2. 依存関係のインストール（ソースからビルドする場合）

# 初回セットアップ
npm install

# 成功確認
npm ls --depth=0

3. 基本動作確認

# テストの実行
npm test

# ビルドの実行
npm run build

# 結果確認
ls -la dist/

期待される出力:

dist/
├── cesium-heatbox.js
├── cesium-heatbox.min.js
└── cesium-heatbox.umd.js

サンプル実行（2分）

1. 開発サーバーの起動

# 開発サーバーを起動
npm run dev

# ブラウザで確認
# 自動的にブラウザが開く（通常はhttp://localhost:8080）

2. 基本サンプルの確認

ブラウザで以下を確認:

基本的な3Dマップが表示される
ヒートマップの設定UI
エンティティ生成・ヒートマップ作成ボタン

3. 機能テスト

エンティティ生成: 「テストエンティティ生成」ボタンをクリック
ヒートマップ作成: 「ヒートマップ作成」ボタンをクリック
設定変更: ボクセルサイズや透明度を調整
表示切り替え: 「表示/非表示」ボタンで確認

基本的な開発作業（5分）

1. コードの編集

エディタでプロジェクトを開く

# Visual Studio Codeで開く
code .

# または他のエディタで開く
open .

基本的なファイル構造

cesium-heatbox/
├── src/                    # ソースコード
│   ├── Heatbox.js         # メインクラス
│   ├── core/              # 核心機能
│   └── utils/             # ユーティリティ
├── examples/              # サンプルコード
│   └── basic/
│       ├── index.html
│       └── app.js
├── test/                  # テストコード
└── docs/                  # ドキュメント

2. 簡単な変更を試す

デフォルトボクセルサイズの変更

// src/utils/constants.js
export const DEFAULT_VOXEL_SIZE = 20;  // 20 → 30に変更

デフォルト色の変更

// src/utils/constants.js
export const DEFAULT_MIN_COLOR = [0, 32, 255];     // 青
export const DEFAULT_MAX_COLOR = [255, 64, 0];     // 赤
// → 他の色に変更してみる

3. 変更の確認

# 開発サーバーで確認（ホットリロード）
npm run dev

# テストで確認
npm test

# ビルドで確認
npm run build

4. 変更のコミット

# 変更を確認
git status
git diff

# 変更をコミット
git add .
git commit -m "chore: update default voxel size to 30"

# GitHubにプッシュ
git push origin main

次のステップ

1. 詳細なドキュメントを読む

development-guide.md: 開発の基本から応用まで
specification.md: プロジェクトの全体仕様
API.md: API仕様の詳細

2. 実践的な開発

新機能の実装

specification.mdでv1.0.0の計画機能を確認
データソース選択機能の実装にチャレンジ
テストケースの追加
ドキュメントの更新

品質向上

テストカバレッジの向上
パフォーマンスの最適化
エラーハンドリングの改善
ユーザビリティの向上

3. リリースの準備

Alpha版リリース

# バージョン更新
npm version 0.1.0-alpha.1 --no-git-tag-version

# タグ作成
git add .
git commit -m "chore: bump version to 0.1.0-alpha.1"
git tag v0.1.0-alpha.1

# プッシュ
git push origin main
git push origin v0.1.0-alpha.1

NPM公開（手動実行時）

# 公開準備
npm publish --dry-run

# プレリリース（alpha/beta/rc など）として公開
npm publish --tag alpha

# 安定版として公開（latest）
npm publish --tag latest

頻繁に使うコマンド一覧

開発時

# 依存関係のインストール
npm install

# 開発サーバー起動
npm run dev

# テスト実行
npm test

# ビルド
npm run build

# リンティング
npm run lint

Git操作

# 状態確認
git status

# 変更をコミット
git add .
git commit -m "commit message"

# プッシュ
git push origin main

# 最新版を取得
git pull origin main

トラブルシューティング

# 環境リセット
rm -rf node_modules package-lock.json
npm install

# 詳細エラー確認
npm test -- --verbose
npm run build -- --verbose

よくある質問

Q: 開発サーバーが起動しない

A: 以下を確認してください

Node.js 18+がインストールされているか
npm installが成功したか
ポート8080が使用可能か

Q: テストが失敗する

A: 以下を試してください

npm test -- --verboseで詳細エラーを確認
npm installで依存関係を再インストール
個別のテストファイルを実行: npm test -- Heatbox.test.js

Q: ビルドが失敗する