@uoa-css-lab/duckscatter 1.3.0

package/dist/errors.js

@@ -0,0 +1,58 @@
+/**
+ * エラーコードからカテゴリへのマッピング
+ */
+const categoryMap = {
+    WEBGPU_NOT_SUPPORTED: 'webgpu',
+    GPU_ADAPTER_NOT_AVAILABLE: 'webgpu',
+    GPU_DEVICE_FAILED: 'webgpu',
+    WEBGPU_CONTEXT_FAILED: 'webgpu',
+    DATA_LAYER_NOT_INITIALIZED: 'data',
+    PARQUET_LOAD_FAILED: 'data',
+    QUERY_FAILED: 'query',
+    LABEL_FETCH_FAILED: 'label',
+    LABEL_PARSE_FAILED: 'label',
+    NETWORK_ERROR: 'network',
+};
+/**
+ * エラーコードから重大度レベルへのマッピング
+ */
+const severityMap = {
+    WEBGPU_NOT_SUPPORTED: 'fatal',
+    GPU_ADAPTER_NOT_AVAILABLE: 'fatal',
+    GPU_DEVICE_FAILED: 'fatal',
+    WEBGPU_CONTEXT_FAILED: 'fatal',
+    DATA_LAYER_NOT_INITIALIZED: 'fatal',
+    PARQUET_LOAD_FAILED: 'fatal',
+    QUERY_FAILED: 'error',
+    NETWORK_ERROR: 'error',
+    LABEL_FETCH_FAILED: 'warning',
+    LABEL_PARSE_FAILED: 'warning',
+};
+/**
+ * 指定されたコードとメッセージでScatterPlotErrorオブジェクトを作成する
+ *
+ * @param code エラーコード
+ * @param message 人間が読めるエラーメッセージ
+ * @param options 追加オプション
+ * @returns ScatterPlotErrorオブジェクト
+ *
+ * @example
+ * ```typescript
+ * const error = createError(
+ *   'WEBGPU_NOT_SUPPORTED',
+ *   'WebGPU is not supported in this browser',
+ *   { context: { userAgent: navigator.userAgent } }
+ * );
+ * ```
+ */
+export function createError(code, message, options) {
+    return {
+        code,
+        category: categoryMap[code],
+        severity: severityMap[code],
+        message,
+        cause: options?.cause,
+        context: options?.context,
+        timestamp: Date.now(),
+    };
+}

package/dist/event-emitter.d.ts

@@ -0,0 +1,62 @@
+/**
+ * イベントハンドラー関数の型
+ */
+export type EventHandler<T = unknown> = (event: T) => void;
+/**
+ * ブラウザ環境向けの軽量なEventEmitter実装
+ * 外部依存なしで型安全なイベントハンドリングを提供する
+ *
+ * @example
+ * ```typescript
+ * interface MyEvents {
+ *   data: { value: number };
+ *   error: Error;
+ * }
+ *
+ * class MyClass extends EventEmitter<MyEvents> {
+ *   doSomething() {
+ *     this.emit('data', { value: 42 });
+ *   }
+ * }
+ *
+ * const instance = new MyClass();
+ * instance.on('data', (event) => console.log(event.value));
+ * ```
+ */
+export declare class EventEmitter<T extends {
+    [K in keyof T]: unknown;
+}> {
+    /** イベント名からハンドラーのセットへのマップ */
+    private listeners;
+    /**
+     * 指定されたイベントに対してハンドラーを登録する
+     *
+     * @param event リッスンするイベント名
+     * @param handler イベント発生時に呼び出されるハンドラー関数
+     * @returns メソッドチェーン用のthisインスタンス
+     */
+    on<K extends keyof T>(event: K, handler: EventHandler<T[K]>): this;
+    /**
+     * 指定されたイベントからハンドラーを削除する
+     *
+     * @param event イベント名
+     * @param handler 削除するハンドラー関数
+     * @returns メソッドチェーン用のthisインスタンス
+     */
+    off<K extends keyof T>(event: K, handler: EventHandler<T[K]>): this;
+    /**
+     * 登録されたすべてのハンドラーにイベントを発行する
+     *
+     * @param event 発行するイベント名
+     * @param data ハンドラーに渡すイベントデータ
+     * @returns リスナーがあればtrue、なければfalse
+     */
+    protected emit<K extends keyof T>(event: K, data: T[K]): boolean;
+    /**
+     * 指定されたイベント、またはすべてのイベントのリスナーを削除する
+     *
+     * @param event イベント名（省略時はすべてのリスナーを削除）
+     * @returns メソッドチェーン用のthisインスタンス
+     */
+    removeAllListeners(event?: keyof T): this;
+}

package/dist/event-emitter.js

@@ -0,0 +1,82 @@
+/**
+ * ブラウザ環境向けの軽量なEventEmitter実装
+ * 外部依存なしで型安全なイベントハンドリングを提供する
+ *
+ * @example
+ * ```typescript
+ * interface MyEvents {
+ *   data: { value: number };
+ *   error: Error;
+ * }
+ *
+ * class MyClass extends EventEmitter<MyEvents> {
+ *   doSomething() {
+ *     this.emit('data', { value: 42 });
+ *   }
+ * }
+ *
+ * const instance = new MyClass();
+ * instance.on('data', (event) => console.log(event.value));
+ * ```
+ */
+export class EventEmitter {
+    constructor() {
+        /** イベント名からハンドラーのセットへのマップ */
+        this.listeners = new Map();
+    }
+    /**
+     * 指定されたイベントに対してハンドラーを登録する
+     *
+     * @param event リッスンするイベント名
+     * @param handler イベント発生時に呼び出されるハンドラー関数
+     * @returns メソッドチェーン用のthisインスタンス
+     */
+    on(event, handler) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(handler);
+        return this;
+    }
+    /**
+     * 指定されたイベントからハンドラーを削除する
+     *
+     * @param event イベント名
+     * @param handler 削除するハンドラー関数
+     * @returns メソッドチェーン用のthisインスタンス
+     */
+    off(event, handler) {
+        this.listeners.get(event)?.delete(handler);
+        return this;
+    }
+    /**
+     * 登録されたすべてのハンドラーにイベントを発行する
+     *
+     * @param event 発行するイベント名
+     * @param data ハンドラーに渡すイベントデータ
+     * @returns リスナーがあればtrue、なければfalse
+     */
+    emit(event, data) {
+        const handlers = this.listeners.get(event);
+        if (!handlers || handlers.size === 0) {
+            return false;
+        }
+        handlers.forEach((handler) => handler(data));
+        return true;
+    }
+    /**
+     * 指定されたイベント、またはすべてのイベントのリスナーを削除する
+     *
+     * @param event イベント名（省略時はすべてのリスナーを削除）
+     * @returns メソッドチェーン用のthisインスタンス
+     */
+    removeAllListeners(event) {
+        if (event) {
+            this.listeners.delete(event);
+        }
+        else {
+            this.listeners.clear();
+        }
+        return this;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * duckscatter - WebGPUを使用して散布図を描画するTypeScriptライブラリ
+ */
+export { ScatterPlot } from './scatter-plot.js';
+export type { ColorRGBA, ScatterPlotOptions, Label, WhereCondition, NumericFilter, StringFilter, RawSqlFilter, NumericOperator, StringOperator, GpuWhereCondition, ErrorSeverity, ErrorCategory, ErrorCode, ScatterPlotError, ScatterPlotEventMap, PointId, LabelIdentifier, LabelHoverCallback, } from './types.js';
+export { diagnoseWebGPU } from './diagnostics.js';
+export type { WebGPUDiagnostics } from './diagnostics.js';
+/**
+ * 現在の環境でWebGPUがサポートされているかを確認する
+ * @returns WebGPUがサポートされている場合はtrue、そうでない場合はfalse
+ */
+export declare function isWebGPUSupported(): boolean;

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * duckscatter - WebGPUを使用して散布図を描画するTypeScriptライブラリ
+ */
+export { ScatterPlot } from './scatter-plot.js';
+export { diagnoseWebGPU } from './diagnostics.js';
+/**
+ * 現在の環境でWebGPUがサポートされているかを確認する
+ * @returns WebGPUがサポートされている場合はtrue、そうでない場合はfalse
+ */
+export function isWebGPUSupported() {
+    // navigatorオブジェクトにgpuプロパティが存在するかをチェック
+    return 'gpu' in navigator;
+}

package/dist/renderer/gpu-layer.d.ts

@@ -0,0 +1,204 @@
+import type { ColorRGBA } from '../types.js';
+/**
+ * GPU用に処理されたポイントデータ
+ */
+export interface AllPointsData {
+    /** インスタンスデータ (x, y, color, size) の Float32Array */
+    instanceData: Float32Array;
+    /** 全ポイント数 */
+    totalCount: number;
+}
+/**
+ * GpuLayerの設定オプション
+ */
+export interface GpuLayerOptions {
+    /** 描画対象のHTMLCanvasElement */
+    canvas: HTMLCanvasElement;
+    /** 背景色（デフォルト: 透明な黒） */
+    backgroundColor?: ColorRGBA;
+    /** 表示可能なポイントの最大数（デフォルト: 5000000） */
+    visiblePointLimit?: number;
+}
+/**
+ * WebGPUレンダリングを担当するレイヤー
+ * 責務:
+ * - WebGPUコンテキストとパイプラインの管理
+ * - GPUバッファの作成と管理
+ * - コンピュートシェーダーによるLODフィルタリング
+ * - Indirect Drawingによるレンダリング
+ */
+export declare class GpuLayer {
+    /** WebGPUコンテキスト */
+    private context;
+    /** 描画対象のキャンバス */
+    private readonly canvas;
+    /** レンダーパイプライン */
+    private renderPipeline;
+    /** フィルタリング用コンピュートパイプライン */
+    private filterPipeline;
+    /** Indirect Buffer更新用コンピュートパイプライン */
+    private updateIndirectPipeline;
+    /** クワッド頂点バッファ（stepMode: 'vertex'） */
+    private quadVertexBuffer;
+    /** 全ポイントデータバッファ (Storage) */
+    private allPointsBuffer;
+    /** 可視ポイントインデックスバッファ (Storage) */
+    private visibleIndicesBuffer;
+    /** アトミックカウンターバッファ (Storage) */
+    private atomicCounterBuffer;
+    /** Indirect Drawingパラメータバッファ */
+    private indirectBuffer;
+    /** インデックスバッファ */
+    private indexBuffer;
+    /** レンダリング用ユニフォームバッファ */
+    private renderUniformBuffer;
+    /** コンピュート用ユニフォームバッファ */
+    private computeUniformBuffer;
+    /** GPUフィルターカラムデータバッファ */
+    private filterColumnsBuffer;
+    /** GPUフィルター条件 */
+    private gpuFilterConditions;
+    /** GPUフィルターカラム数 */
+    private gpuFilterColumnCount;
+    /** レンダリング用バインドグループ */
+    private renderBindGroup;
+    /** フィルタリング用バインドグループ */
+    private filterBindGroup;
+    /** Indirect更新用バインドグループ */
+    private updateIndirectBindGroup;
+    /** 全ポイント数 */
+    private totalPointCount;
+    /** 背景色 */
+    private backgroundColor;
+    /** 表示可能なポイントの最大数 */
+    private visiblePointLimit;
+    /** フィルタリング結果が有効かどうか */
+    private filterResultValid;
+    /** 現在のズームレベル */
+    private zoom;
+    /** 現在のX方向パンオフセット */
+    private panX;
+    /** 現在のY方向パンオフセット */
+    private panY;
+    /** グローバル透明度 (0.0-1.0) */
+    private pointAlpha;
+    /** グローバルサイズスケール */
+    private pointSizeScale;
+    /**
+     * GpuLayerインスタンスを作成する
+     * @param options 設定オプション
+     */
+    constructor(options: GpuLayerOptions);
+    /**
+     * WebGPUを初期化し、レンダリングリソースを作成する
+     * @param initialData 初期データ
+     */
+    initialize(initialData: AllPointsData): Promise<void>;
+    /**
+     * パイプラインを作成する
+     */
+    private createPipelines;
+    /**
+     * バッファを作成する
+     * @param data 初期データ
+     */
+    private createBuffers;
+    /**
+     * バインドグループを作成する
+     */
+    private createBindGroups;
+    /**
+     * 全ポイントデータをアップロードする
+     * @param data 新しいポイントデータ
+     */
+    uploadAllPoints(data: AllPointsData): void;
+    /**
+     * ビュー行列を作成する
+     */
+    private createViewMatrix;
+    /**
+     * LOD閾値を計算する
+     * ズームレベルに応じて表示するポイント数を制限する
+     */
+    private calculateLodThreshold;
+    /**
+     * ユニフォームを更新する
+     */
+    updateUniforms(): void;
+    /**
+     * 散布図をレンダリングする
+     */
+    render(): void;
+    /**
+     * キャンバスをリサイズし、ビューポートを更新する
+     */
+    resize(width: number, height: number): void;
+    /**
+     * ズームレベルを設定する
+     */
+    setZoom(zoom: number): void;
+    /**
+     * 現在のズームレベルを取得する
+     */
+    getZoom(): number;
+    /**
+     * パンオフセットを設定する
+     */
+    setPan(x: number, y: number): void;
+    /**
+     * 現在のパンオフセットを取得する
+     */
+    getPan(): {
+        x: number;
+        y: number;
+    };
+    /**
+     * 指定した画面座標を中心にズームする
+     */
+    zoomToPoint(newZoom: number, screenX: number, screenY: number): void;
+    /**
+     * GPUレイヤーの設定オプションを更新する
+     */
+    updateOptions(options: Partial<GpuLayerOptions>): void;
+    /**
+     * GPUフィルターカラムデータをアップロードする
+     * @param data フィルターカラムデータ（各ポイントに4カラム分のf32、totalPoints * 4 floats）
+     * @param columnCount 有効なカラム数（0-4）
+     */
+    uploadFilterColumns(data: Float32Array, columnCount: number): void;
+    /**
+     * GPUフィルター条件を設定する
+     * @param conditions フィルター条件の配列
+     */
+    setGpuFilterConditions(conditions: {
+        columnIndex: number;
+        min: number;
+        max: number;
+    }[]): void;
+    /**
+     * GPUフィルター条件をクリアする
+     */
+    clearGpuFilterConditions(): void;
+    /**
+     * グローバル透明度を設定する
+     * @param alpha 透明度 (0.0-1.0)
+     */
+    setPointAlpha(alpha: number): void;
+    /**
+     * 現在のグローバル透明度を取得する
+     */
+    getPointAlpha(): number;
+    /**
+     * グローバルサイズスケールを設定する
+     * @param scale サイズスケール (0.01以上)
+     */
+    setPointSizeScale(scale: number): void;
+    /**
+     * 現在のグローバルサイズスケールを取得する
+     */
+    getPointSizeScale(): number;
+    /**
+     * リソースを破棄する
+     */
+    destroy(): void;
+}