@uoa-css-lab/duckscatter 1.3.0

package/dist/scatter-plot.js

@@ -0,0 +1,450 @@
+import { DataLayer } from './data/index.js';
+import { GpuLayer } from './renderer/index.js';
+import { LabelLayer } from './ui/index.js';
+import { EventEmitter } from './event-emitter.js';
+import { createError } from './errors.js';
+/**
+ * WebGPUを使用して散布図を描画するメインクラス
+ *
+ * このクラスは3つの異なるレイヤーのファサード/コーディネーターとして機能する:
+ * - DataLayer: データ取得とクエリ管理を担当
+ * - GpuLayer: WebGPUレンダリングと変換を管理（LODと境界計算もGPU側で実行）
+ * - LabelLayer: ラベル用の2Dキャンバスオーバーレイを担当
+ */
+export class ScatterPlot extends EventEmitter {
+    /**
+     * ScatterPlotインスタンスを作成する
+     * @param options 散布図の設定オプション
+     */
+    constructor(options) {
+        super();
+        /** GPUフィルターカラム名→インデックスのマッピング */
+        this.gpuFilterColumnMapping = new Map();
+        this.dataLayer = new DataLayer({
+            sizeSql: options.data.sizeSql,
+            colorSql: options.data.colorSql,
+            whereConditions: options.data.whereConditions,
+            gpuFilterColumns: options.data.gpuFilterColumns,
+            idColumn: options.data.idColumn,
+            onError: (error) => this.emitError(error),
+            onDataChanged: () => this.handleDataChanged(),
+        });
+        this.gpuLayer = new GpuLayer({
+            canvas: options.canvas,
+            backgroundColor: options.gpu?.backgroundColor,
+            visiblePointLimit: options.data.visiblePointLimit,
+        });
+        this.labelLayer = new LabelLayer({
+            canvas: options.canvas,
+            labelFontSize: options.labels?.fontSize,
+            filterLambda: options.labels?.filterLambda,
+            onLabelClick: options.labels?.onClick,
+            onPointHover: (data) => this.handlePointHover(data, options.interaction?.onPointHover),
+            onLabelHover: options.interaction?.onLabelHover,
+            hoverOutlineOptions: options.labels?.hoverOutlineOptions,
+            dataLayer: this.dataLayer,
+        });
+        this.dataUrl = options.dataUrl;
+        this.labelUrl = options.labels?.url;
+    }
+    /**
+     * WebGPUを初期化し、レンダリングリソースを作成する
+     */
+    async initialize() {
+        try {
+            const allPointsData = await this.dataLayer.initialize(this.dataUrl);
+            await this.gpuLayer.initialize(allPointsData);
+            const gpuFilterData = await this.dataLayer.loadGpuFilterColumns();
+            if (gpuFilterData) {
+                this.gpuLayer.uploadFilterColumns(gpuFilterData.data, gpuFilterData.columnCount);
+                this.gpuFilterColumnMapping = gpuFilterData.columnMapping;
+            }
+            this.labelLayer.initialize();
+        }
+        catch (e) {
+            const error = this.categorizeInitError(e);
+            this.emitError(error);
+            return;
+        }
+        if (this.labelUrl) {
+            await this.loadLabelsFromUrl(this.labelUrl);
+        }
+    }
+    /**
+     * データ変更時のハンドラ（sizeSql, colorSql, whereConditions変更時）
+     */
+    async handleDataChanged() {
+        try {
+            const allPointsData = await this.dataLayer.loadAllPoints();
+            this.gpuLayer.uploadAllPoints(allPointsData);
+            this.render();
+        }
+        catch (e) {
+            this.emitError(createError('QUERY_FAILED', 'Failed to reload data after options change', {
+                cause: e instanceof Error ? e : undefined,
+            }));
+        }
+    }
+    /**
+     * URLからラベルデータを読み込み、エラーハンドリングを行う
+     * @param url ラベルデータのURL
+     */
+    async loadLabelsFromUrl(url) {
+        try {
+            const response = await fetch(url);
+            if (!response.ok) {
+                this.emitError(createError('LABEL_FETCH_FAILED', `Failed to fetch labels: ${response.status} ${response.statusText}`, {
+                    context: { url, status: response.status },
+                }));
+                return;
+            }
+            const labelData = await response.json();
+            this.loadLabels(labelData);
+            await this.dataLayer.loadLabelData(labelData);
+        }
+        catch (e) {
+            this.emitError(createError('LABEL_FETCH_FAILED', 'Network error while fetching labels', {
+                cause: e instanceof Error ? e : undefined,
+                context: { url },
+            }));
+        }
+    }
+    /**
+     * 初期化エラーをScatterPlotError型に分類する
+     * @param e 発生した例外
+     * @returns 分類されたScatterPlotErrorオブジェクト
+     */
+    categorizeInitError(e) {
+        const message = e instanceof Error ? e.message : String(e);
+        const cause = e instanceof Error ? e : undefined;
+        if (message.includes('WebGPU is not supported')) {
+            return createError('WEBGPU_NOT_SUPPORTED', message, { cause });
+        }
+        if (message.includes('GPU adapter') || message.includes('Failed to get GPU adapter')) {
+            return createError('GPU_ADAPTER_NOT_AVAILABLE', message, { cause });
+        }
+        if (message.includes('GPU device') || message.includes('Failed to get GPU device')) {
+            return createError('GPU_DEVICE_FAILED', message, { cause });
+        }
+        if (message.includes('WebGPU context') || message.includes('Failed to get WebGPU context')) {
+            return createError('WEBGPU_CONTEXT_FAILED', message, { cause });
+        }
+        if (message.includes('Database not initialized') || message.includes('not initialized')) {
+            return createError('DATA_LAYER_NOT_INITIALIZED', message, { cause });
+        }
+        if (message.includes('Parquet') || message.includes('parquet') || message.includes('load')) {
+            return createError('PARQUET_LOAD_FAILED', message, { cause });
+        }
+        return createError('WEBGPU_NOT_SUPPORTED', message, { cause });
+    }
+    /**
+     * エラーイベントを発行する。リスナーが登録されていない場合はconsole.warnに出力する
+     * @param error 発行するエラーオブジェクト
+     */
+    emitError(error) {
+        const hasListeners = this.emit('error', error);
+        if (!hasListeners) {
+            // eslint-disable-next-line no-console
+            console.warn('[duckscatter]', `${error.code}: ${error.message}`);
+        }
+    }
+    /**
+     * 散布図をレンダリングする（GPUレイヤーとラベルの両方）
+     */
+    render() {
+        this.gpuLayer.render();
+        this.labelLayer.render();
+    }
+    /**
+     * GeoJSONデータからラベルを読み込む
+     * @param geojsonData ラベルポイントを含むGeoJSON FeatureCollection
+     */
+    loadLabels(geojsonData) {
+        this.labelLayer.loadLabels(geojsonData);
+        this.render();
+    }
+    /**
+     * プロットデータを更新して再レンダリングする
+     * @param options 更新する設定オプション
+     */
+    async update(options) {
+        if (options.data !== undefined) {
+            const result = this.dataLayer.updateOptions({
+                sizeSql: options.data.sizeSql,
+                colorSql: options.data.colorSql,
+                whereConditions: options.data.whereConditions,
+                gpuFilterColumns: options.data.gpuFilterColumns,
+            });
+            if (result.gpuFilterColumnsChanged) {
+                const gpuFilterData = await this.dataLayer.loadGpuFilterColumns();
+                if (gpuFilterData) {
+                    this.gpuLayer.uploadFilterColumns(gpuFilterData.data, gpuFilterData.columnCount);
+                    this.gpuFilterColumnMapping = gpuFilterData.columnMapping;
+                }
+                else {
+                    this.gpuFilterColumnMapping.clear();
+                }
+            }
+            if (options.data.gpuWhereConditions !== undefined) {
+                const conditions = this.convertGpuWhereConditions(options.data.gpuWhereConditions);
+                this.gpuLayer.setGpuFilterConditions(conditions);
+            }
+        }
+        if (options.gpu !== undefined || options.data?.visiblePointLimit !== undefined) {
+            this.gpuLayer.updateOptions({
+                backgroundColor: options.gpu?.backgroundColor,
+                visiblePointLimit: options.data?.visiblePointLimit,
+            });
+        }
+        if (options.labels !== undefined) {
+            this.labelLayer.updateOptions({
+                labelFontSize: options.labels.fontSize,
+                filterLambda: options.labels.filterLambda,
+                onLabelClick: options.labels.onClick,
+                hoverOutlineOptions: options.labels.hoverOutlineOptions,
+            });
+            if (options.labels.url !== undefined) {
+                await this.loadLabelsFromUrl(options.labels.url);
+            }
+        }
+        if (options.interaction !== undefined) {
+            this.labelLayer.updateOptions({
+                onPointHover: (data) => this.handlePointHover(data, options.interaction?.onPointHover),
+                onLabelHover: options.interaction.onLabelHover,
+            });
+        }
+        this.render();
+    }
+    /**
+     * キャンバスをリサイズして再レンダリングする
+     * @param width 新しい幅（ピクセル）
+     * @param height 新しい高さ（ピクセル）
+     */
+    resize(width, height) {
+        this.gpuLayer.resize(width, height);
+        this.labelLayer.resize(width, height);
+        this.render();
+    }
+    /**
+     * ズームレベルを設定する
+     * @param zoom ズームレベル（1.0 = 通常、>1.0 = ズームイン、<1.0 = ズームアウト）
+     */
+    setZoom(zoom) {
+        this.gpuLayer.setZoom(zoom);
+        this.syncLabelViewTransform();
+        this.render();
+    }
+    /**
+     * 現在のズームレベルを取得する
+     * @returns 現在のズームレベル
+     */
+    getZoom() {
+        return this.gpuLayer.getZoom();
+    }
+    /**
+     * 指定した倍率でズームインする
+     * @param factor ズーム倍率（デフォルト: 1.2）
+     */
+    zoomIn(factor = 1.2) {
+        this.setZoom(this.gpuLayer.getZoom() * factor);
+    }
+    /**
+     * 指定した倍率でズームアウトする
+     * @param factor ズーム倍率（デフォルト: 1.2）
+     */
+    zoomOut(factor = 1.2) {
+        this.setZoom(this.gpuLayer.getZoom() / factor);
+    }
+    /**
+     * 指定した画面座標を中心にズームする
+     * @param newZoom 新しいズームレベル
+     * @param screenX 画面X座標（キャンバスピクセル単位）
+     * @param screenY 画面Y座標（キャンバスピクセル単位）
+     */
+    zoomToPoint(newZoom, screenX, screenY) {
+        this.gpuLayer.zoomToPoint(newZoom, screenX, screenY);
+        this.syncLabelViewTransform();
+        this.render();
+    }
+    /**
+     * ズームとパンをデフォルト値にリセットする
+     */
+    resetView() {
+        this.gpuLayer.setZoom(1.0);
+        this.gpuLayer.setPan(0.0, 0.0);
+        this.syncLabelViewTransform();
+        this.render();
+    }
+    /**
+     * パンオフセットを設定する
+     * @param x 正規化座標でのX方向パンオフセット（-1から1）
+     * @param y 正規化座標でのY方向パンオフセット（-1から1）
+     */
+    setPan(x, y) {
+        this.gpuLayer.setPan(x, y);
+        this.syncLabelViewTransform();
+        this.render();
+    }
+    /**
+     * 現在のパンオフセットを取得する
+     * @returns x, y座標を含むオブジェクト
+     */
+    getPan() {
+        return this.gpuLayer.getPan();
+    }
+    /**
+     * 指定した差分だけパンする
+     * @param dx 正規化座標でのX方向の差分
+     * @param dy 正規化座標でのY方向の差分
+     */
+    pan(dx, dy) {
+        const currentPan = this.gpuLayer.getPan();
+        this.setPan(currentPan.x + dx, currentPan.y + dy);
+    }
+    /**
+     * ラベルレイヤーのビュー変換をGPUレイヤーと同期する
+     */
+    syncLabelViewTransform() {
+        const pan = this.gpuLayer.getPan();
+        this.labelLayer.updateViewTransform(this.gpuLayer.getZoom(), pan.x, pan.y);
+    }
+    /**
+     * ラベルレイヤーからのポイントホバーイベントを処理する
+     * @param data ホバー中のポイントデータ（またはnull）
+     * @param userCallback ユーザー定義のコールバック
+     */
+    handlePointHover(data, userCallback) {
+        if (userCallback) {
+            userCallback(data);
+        }
+    }
+    /**
+     * GpuWhereConditionをGpuLayer用の形式に変換する
+     * @param conditions ユーザー指定のGPUフィルター条件
+     * @returns GpuLayer用のフィルター条件配列
+     */
+    convertGpuWhereConditions(conditions) {
+        return conditions
+            .filter((c) => this.gpuFilterColumnMapping.has(c.column))
+            .map((c) => ({
+            columnIndex: this.gpuFilterColumnMapping.get(c.column),
+            min: c.min ?? -Infinity,
+            max: c.max ?? Infinity,
+        }));
+    }
+    /**
+     * カスタムSQLクエリを実行する
+     * @param query 実行するSQLクエリ文字列またはtoStringメソッドを持つオブジェクト
+     * @returns クエリ結果のParquetData
+     */
+    async runQuery(query) {
+        return await this.dataLayer.executeQuery(query);
+    }
+    /**
+     * 読み込まれたすべてのラベルを取得する
+     * @returns ラベルの配列
+     */
+    getLabels() {
+        return this.labelLayer.getLabels();
+    }
+    /**
+     * IDを指定してプログラム的にポイントをホバー状態にする
+     * @param pointId ホバーするポイントのidColumn値
+     * @returns ポイントが見つかりホバーされた場合はtrue、そうでない場合はfalse
+     */
+    async setPointHover(pointId) {
+        if (!this.dataLayer.isInitialized()) {
+            return false;
+        }
+        const pointData = await this.dataLayer.findPointById(pointId);
+        if (!pointData) {
+            return false;
+        }
+        this.labelLayer.setHoveredPoint(pointData);
+        return true;
+    }
+    /**
+     * ポイントのホバー状態をクリアする
+     */
+    clearPointHover() {
+        this.labelLayer.setHoveredPoint(null);
+    }
+    /**
+     * 現在ホバー中のポイントデータを取得する
+     * @returns ホバー中の場合はポイントデータ、そうでない場合はnull
+     */
+    getHoveredPoint() {
+        return this.labelLayer.getHoveredPoint();
+    }
+    /**
+     * プログラム的にラベルをホバー状態にする
+     * @param identifier ラベル識別子（テキストまたはクラスターで識別）
+     * @returns ラベルが見つかりホバーされた場合はtrue、そうでない場合はfalse
+     */
+    setLabelHover(identifier) {
+        const label = this.labelLayer.findLabel(identifier);
+        if (!label) {
+            return false;
+        }
+        this.labelLayer.setHoveredLabel(label);
+        return true;
+    }
+    /**
+     * ラベルのホバー状態をクリアする
+     */
+    clearLabelHover() {
+        this.labelLayer.setHoveredLabel(null);
+    }
+    /**
+     * 現在ホバー中のラベルを取得する
+     * @returns ホバー中の場合はラベル、そうでない場合はnull
+     */
+    getHoveredLabel() {
+        return this.labelLayer.getHoveredLabel();
+    }
+    /**
+     * すべてのホバー状態をクリアする（ポイントとラベルの両方）
+     */
+    clearAllHover() {
+        this.labelLayer.setHoveredPoint(null);
+        this.labelLayer.setHoveredLabel(null);
+    }
+    /**
+     * グローバル透明度を設定する
+     * @param alpha 透明度 (0.0-1.0)
+     */
+    setPointAlpha(alpha) {
+        this.gpuLayer.setPointAlpha(alpha);
+        this.render();
+    }
+    /**
+     * 現在のグローバル透明度を取得する
+     * @returns 現在の透明度値 (0.0-1.0)
+     */
+    getPointAlpha() {
+        return this.gpuLayer.getPointAlpha();
+    }
+    /**
+     * グローバルサイズスケールを設定する
+     * @param scale サイズスケール (0.01以上)
+     */
+    setPointSizeScale(scale) {
+        this.gpuLayer.setPointSizeScale(scale);
+        this.render();
+    }
+    /**
+     * 現在のグローバルサイズスケールを取得する
+     * @returns 現在のサイズスケール値
+     */
+    getPointSizeScale() {
+        return this.gpuLayer.getPointSizeScale();
+    }
+    /**
+     * リソースを破棄する
+     */
+    async destroy() {
+        await this.dataLayer.destroy();
+        this.gpuLayer.destroy();
+        this.labelLayer.destroy();
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,171 @@
+/**
+ * duckscatterライブラリの型定義
+ */
+export type LabelFilterLambda = (properties: Record<string, any>) => boolean;
+export type PointHoverCallback = (data: {
+    row: any[];
+    columns: string[];
+} | null) => void;
+/** ポイント識別子の型（idColumnの値） */
+export type PointId = string | number;
+/** プログラムによるホバー制御用のラベル識別子 */
+export interface LabelIdentifier {
+    /** テキストでラベルを識別 */
+    text?: string;
+    /** クラスター番号でラベルを識別 */
+    cluster?: number;
+}
+/** ラベルがホバーされた時に発火するコールバック */
+export type LabelHoverCallback = (label: Label | null) => void;
+export interface ColorRGBA {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+export interface HoverOutlineOptions {
+    /** ホバーアウトラインを有効化（デフォルト: true） */
+    enabled?: boolean;
+    /** アウトラインの線色（デフォルト: 白） */
+    color?: string;
+    /** アウトラインの線幅（ピクセル単位、デフォルト: 2） */
+    width?: number;
+    minimumHoverSize?: number;
+    outlinedPointAddition?: number;
+}
+export interface Label {
+    /** 表示するラベルテキスト */
+    text: string;
+    /** データ空間でのX座標 */
+    x: number;
+    /** データ空間でのY座標 */
+    y: number;
+    /** オプションのラベルプロパティ */
+    cluster?: number;
+    count?: number;
+    /** 元のGeoJSONフィーチャーのプロパティ */
+    properties?: Record<string, any>;
+}
+/**
+ * データクエリ用のWHERE条件フィルター
+ */
+/** 数値比較演算子 */
+export type NumericOperator = '>=' | '>' | '<=' | '<';
+/** 文字列比較演算子 */
+export type StringOperator = 'contains' | 'equals' | 'startsWith' | 'endsWith';
+/** 数値フィルター条件 */
+export interface NumericFilter {
+    type: 'numeric';
+    column: string;
+    operator: NumericOperator;
+    value: number;
+}
+/** 文字列フィルター条件 */
+export interface StringFilter {
+    type: 'string';
+    column: string;
+    operator: StringOperator;
+    value: string;
+}
+/** 生SQLフィルター条件 */
+export interface RawSqlFilter {
+    type: 'raw';
+    sql: string;
+}
+/** すべてのWHERE条件の共用体型 */
+export type WhereCondition = NumericFilter | StringFilter | RawSqlFilter;
+/** GPUフィルター条件 (range only) */
+export interface GpuWhereCondition {
+    /** フィルター対象のカラム名 (gpuFilterColumnsで指定した名前) */
+    column: string;
+    /** 最小値 (指定しない場合は -Infinity) */
+    min?: number;
+    /** 最大値 (指定しない場合は +Infinity) */
+    max?: number;
+}
+export interface DataOptions {
+    /** レンダリングする表示ポイントの最大数 */
+    visiblePointLimit?: number;
+    /** ポイントサイズ用のSQL式（例: "LOG(favorite_count + 1) * 2 + 2"） */
+    sizeSql?: string;
+    /** ポイントカラー用のSQL式（ARGB 32bit整数、例: "0xFF0000FF"） */
+    colorSql?: string;
+    /** データをフィルタリングするWHERE条件（ANDのみ） */
+    whereConditions?: WhereCondition[];
+    /** GPUでフィルタリングするカラム名 (最大4つ) */
+    gpuFilterColumns?: string[];
+    /** GPU側で実行するフィルター条件 */
+    gpuWhereConditions?: GpuWhereCondition[];
+    /** ポイントを識別するカラム名 */
+    idColumn: string;
+}
+export interface GpuOptions {
+    /** 背景色（デフォルト: 透明な黒） */
+    backgroundColor?: ColorRGBA;
+    /** グローバル透明度 (0.0-1.0, デフォルト: 1.0) */
+    pointAlpha?: number;
+    /** グローバルサイズスケール (デフォルト: 1.0) */
+    pointSizeScale?: number;
+}
+export interface LabelOptions {
+    /** ラベルGeoJSONデータを取得するURL（初期化時に自動ロード） */
+    url?: string;
+    /** ラベルのフォントサイズ（ピクセル単位、デフォルト: 12） */
+    fontSize?: number;
+    /** プロパティに基づいてラベルの表示を制御するフィルター関数 */
+    filterLambda?: LabelFilterLambda;
+    /** ラベルがクリックされた時に発火するコールバック */
+    onClick?: (label: Label) => void;
+    /** ポイントホバーアウトラインの外観オプション */
+    hoverOutlineOptions?: HoverOutlineOptions;
+}
+export interface InteractionOptions {
+    /** ポイントがホバーされた時に発火するコールバック */
+    onPointHover?: PointHoverCallback;
+    /** ラベルがホバーされた時に発火するコールバック */
+    onLabelHover?: LabelHoverCallback;
+}
+export interface ScatterPlotOptions {
+    /** レンダリング先のCanvas要素 */
+    canvas: HTMLCanvasElement;
+    /** Parquetデータを取得するURL */
+    dataUrl: string;
+    /** データレイヤーオプション */
+    data: DataOptions;
+    /** GPUレンダリングオプション */
+    gpu?: GpuOptions;
+    /** ラベルレイヤーオプション */
+    labels?: LabelOptions;
+    /** インタラクションコールバック */
+    interaction?: InteractionOptions;
+}
+/**
+ * エラーハンドリング型
+ */
+/** エラー重大度レベル */
+export type ErrorSeverity = 'fatal' | 'error' | 'warning';
+/** エラーカテゴリ */
+export type ErrorCategory = 'webgpu' | 'data' | 'label' | 'query' | 'network';
+/** すべての可能なエラーのエラーコード */
+export type ErrorCode = 'WEBGPU_NOT_SUPPORTED' | 'GPU_ADAPTER_NOT_AVAILABLE' | 'GPU_DEVICE_FAILED' | 'WEBGPU_CONTEXT_FAILED' | 'DATA_LAYER_NOT_INITIALIZED' | 'PARQUET_LOAD_FAILED' | 'QUERY_FAILED' | 'LABEL_FETCH_FAILED' | 'LABEL_PARSE_FAILED' | 'NETWORK_ERROR';
+/** エラーイベントペイロード */
+export interface ScatterPlotError {
+    /** プログラムによるハンドリング用のエラーコード */
+    code: ErrorCode;
+    /** エラーカテゴリ */
+    category: ErrorCategory;
+    /** エラー重大度 */
+    severity: ErrorSeverity;
+    /** 人が読めるエラーメッセージ */
+    message: string;
+    /** 利用可能な場合、元のエラーオブジェクト */
+    cause?: Error;
+    /** 追加のコンテキスト情報 */
+    context?: Record<string, unknown>;
+    /** エラーが発生したタイムスタンプ */
+    timestamp: number;
+}
+/** ScatterPlot EventEmitter用のイベントマップ */
+export interface ScatterPlotEventMap {
+    error: ScatterPlotError;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ui/index.d.ts

@@ -0,0 +1 @@
+export { LabelLayer } from './label-layer.js';

package/dist/ui/index.js

@@ -0,0 +1 @@
+export { LabelLayer } from './label-layer.js';