@uoa-css-lab/duckscatter 1.3.0

package/dist/renderer/shaders.js

@@ -0,0 +1,216 @@
+/**
+ * 散布図レンダリング用WGSLシェーダーコード
+ */
+/**
+ * ビューポート境界とLODに基づいて可視ポイントをフィルタリングするコンピュートシェーダー
+ * ワークグループローカルのアトミック操作を使用してグローバルアトミックの競合を軽減
+ */
+export const filterComputeShader = `
+struct Point {
+  x: f32,
+  y: f32,
+  color: u32,
+  size: f32,
+}
+
+struct FilterUniforms {
+  worldBoundsMin: vec2<f32>,
+  worldBoundsMax: vec2<f32>,
+  lodThreshold: u32,
+  totalPoints: u32,
+  activeFilterMask: u32,
+  _padding: u32,
+  filterRangeMin: vec4<f32>,
+  filterRangeMax: vec4<f32>,
+}
+
+@group(0) @binding(0) var<storage, read> allPoints: array<Point>;
+@group(0) @binding(1) var<storage, read_write> visibleIndices: array<u32>;
+@group(0) @binding(2) var<storage, read_write> counter: atomic<u32>;
+@group(0) @binding(3) var<uniform> uniforms: FilterUniforms;
+@group(0) @binding(4) var<storage, read> filterColumns: array<vec4<f32>>;
+
+var<workgroup> localCount: atomic<u32>;
+var<workgroup> localIndices: array<u32, 256>;
+var<workgroup> globalOffset: u32;
+
+fn pcgHash(input: u32) -> u32 {
+    let state = input * 747796405u + 2891336453u;
+    let word = ((state >> ((state >> 28u) + 4u)) ^ state) * 277803737u;
+    return (word >> 22u) ^ word;
+}
+
+@compute @workgroup_size(256)
+fn main(
+  @builtin(global_invocation_id) globalId: vec3<u32>,
+  @builtin(local_invocation_id) localId: vec3<u32>
+) {
+  let idx = globalId.x;
+  let lid = localId.x;
+
+  if (lid == 0u) {
+    atomicStore(&localCount, 0u);
+  }
+  workgroupBarrier();
+
+  var myLocalSlot: u32 = 0xFFFFFFFFu;
+  if (idx < uniforms.totalPoints) {
+    let hash = pcgHash(idx);
+    var isVisible = hash <= uniforms.lodThreshold;
+
+    if (isVisible) {
+      let point = allPoints[idx];
+
+      isVisible = point.x >= uniforms.worldBoundsMin.x && point.x <= uniforms.worldBoundsMax.x &&
+                  point.y >= uniforms.worldBoundsMin.y && point.y <= uniforms.worldBoundsMax.y;
+    }
+
+    if (isVisible && uniforms.activeFilterMask != 0u) {
+      let filterData = filterColumns[idx];
+
+      if ((uniforms.activeFilterMask & 1u) != 0u) {
+        isVisible = isVisible &&
+                    filterData.x >= uniforms.filterRangeMin.x &&
+                    filterData.x <= uniforms.filterRangeMax.x;
+      }
+      if ((uniforms.activeFilterMask & 2u) != 0u) {
+        isVisible = isVisible &&
+                    filterData.y >= uniforms.filterRangeMin.y &&
+                    filterData.y <= uniforms.filterRangeMax.y;
+      }
+      if ((uniforms.activeFilterMask & 4u) != 0u) {
+        isVisible = isVisible &&
+                    filterData.z >= uniforms.filterRangeMin.z &&
+                    filterData.z <= uniforms.filterRangeMax.z;
+      }
+      if ((uniforms.activeFilterMask & 8u) != 0u) {
+        isVisible = isVisible &&
+                    filterData.w >= uniforms.filterRangeMin.w &&
+                    filterData.w <= uniforms.filterRangeMax.w;
+      }
+    }
+
+    if (isVisible) {
+      myLocalSlot = atomicAdd(&localCount, 1u);
+      localIndices[myLocalSlot] = idx;
+    }
+  }
+  workgroupBarrier();
+
+  let count = atomicLoad(&localCount);
+  if (lid == 0u && count > 0u) {
+    globalOffset = atomicAdd(&counter, count);
+  }
+  workgroupBarrier();
+
+  if (lid < count) {
+    visibleIndices[globalOffset + lid] = localIndices[lid];
+  }
+}
+`;
+/**
+ * カウンターから間接描画バッファを更新するコンピュートシェーダー
+ */
+export const updateIndirectShader = `
+struct DrawIndexedIndirect {
+  indexCount: u32,
+  instanceCount: u32,
+  firstIndex: u32,
+  baseVertex: u32,
+  firstInstance: u32,
+}
+
+@group(0) @binding(0) var<storage, read> counter: u32;
+@group(0) @binding(1) var<storage, read_write> indirect: DrawIndexedIndirect;
+
+@compute @workgroup_size(1)
+fn main() {
+  indirect.indexCount = 6u;
+  indirect.instanceCount = counter;
+  indirect.firstIndex = 0u;
+  indirect.baseVertex = 0u;
+  indirect.firstInstance = 0u;
+}
+`;
+export const scatterVertexShader = `
+struct Point {
+  x: f32,
+  y: f32,
+  color: u32,
+  size: f32,
+}
+
+struct Uniforms {
+  viewMatrix: mat4x4<f32>,
+  zoomScale: f32,
+  viewportWidth: f32,
+  viewportHeight: f32,
+  pointAlpha: f32,
+  pointSizeScale: f32,
+  _padding1: f32,
+  _padding2: f32,
+  _padding3: f32,
+}
+
+struct VertexOutput {
+  @builtin(position) position: vec4<f32>,
+  @location(0) color: vec4<f32>,
+  @location(1) pointCoord: vec2<f32>,
+}
+
+@group(0) @binding(0) var<uniform> uniforms: Uniforms;
+@group(0) @binding(1) var<storage, read> allPoints: array<Point>;
+@group(0) @binding(2) var<storage, read> visibleIndices: array<u32>;
+
+fn unpackColor(argb: u32) -> vec4<f32> {
+  let a = f32((argb >> 24u) & 0xFFu) / 255.0;
+  let r = f32((argb >> 16u) & 0xFFu) / 255.0;
+  let g = f32((argb >> 8u) & 0xFFu) / 255.0;
+  let b = f32(argb & 0xFFu) / 255.0;
+  return vec4<f32>(r, g, b, a);
+}
+
+@vertex
+fn vertexMain(
+  @location(0) quadPosition: vec2<f32>,
+  @builtin(instance_index) instanceIdx: u32
+) -> VertexOutput {
+  var output: VertexOutput;
+
+  let pointIdx = visibleIndices[instanceIdx];
+  let point = allPoints[pointIdx];
+
+  let clipPos = uniforms.viewMatrix * vec4<f32>(point.x, point.y, 0.0, 1.0);
+
+  let pixelToClipX = 2.0 / uniforms.viewportWidth;
+  let pixelToClipY = 2.0 / uniforms.viewportHeight;
+  let zoomScale = uniforms.zoomScale;
+
+  let scaledSize = point.size * uniforms.pointSizeScale;
+  let offsetClip = vec2<f32>(
+    quadPosition.x * scaledSize * pixelToClipX * zoomScale,
+    quadPosition.y * scaledSize * pixelToClipY * zoomScale
+  );
+
+  output.position = clipPos + vec4<f32>(offsetClip, 0.0, 0.0);
+  output.color = unpackColor(point.color);
+
+  output.pointCoord = (quadPosition + 1.0) * 0.5;
+
+  return output;
+}
+
+@fragment
+fn fragmentMain(input: VertexOutput) -> @location(0) vec4<f32> {
+  let d = input.pointCoord - vec2<f32>(0.5);
+  let distSq = dot(d, d);
+
+  if (distSq > 0.25) {
+    discard;
+  }
+
+  let alpha = smoothstep(0.25, 0.23, distSq);
+
+  return vec4<f32>(input.color.rgb, input.color.a * alpha * uniforms.pointAlpha);
+}
+`;

package/dist/renderer/webgpu-context.d.ts

@@ -0,0 +1,20 @@
+/**
+ * WebGPUコンテキストを管理するクラス
+ */
+export declare class WebGPUContext {
+    /** GPUデバイスインスタンス */
+    device: GPUDevice | null;
+    /** キャンバスのWebGPUコンテキスト */
+    context: GPUCanvasContext | null;
+    /** テクスチャフォーマット */
+    format: GPUTextureFormat;
+    /**
+     * WebGPUを初期化する
+     * @param canvas 描画対象のHTMLCanvasElement
+     */
+    initialize(canvas: HTMLCanvasElement): Promise<void>;
+    /**
+     * WebGPUリソースを破棄する
+     */
+    destroy(): void;
+}

package/dist/renderer/webgpu-context.js

@@ -0,0 +1,88 @@
+/**
+ * WebGPUコンテキストを管理するクラス
+ */
+export class WebGPUContext {
+    constructor() {
+        /** GPUデバイスインスタンス */
+        this.device = null;
+        /** キャンバスのWebGPUコンテキスト */
+        this.context = null;
+        /** テクスチャフォーマット */
+        this.format = 'bgra8unorm';
+    }
+    /**
+     * WebGPUを初期化する
+     * @param canvas 描画対象のHTMLCanvasElement
+     */
+    async initialize(canvas) {
+        if (!navigator.gpu) {
+            throw new Error('WebGPU is not supported in this browser. ' +
+                'Please use Chrome 113+, Edge 113+, or Safari 18+ with WebGPU enabled.');
+        }
+        let adapter = null;
+        try {
+            adapter = await navigator.gpu.requestAdapter({
+                powerPreference: 'high-performance',
+            });
+        }
+        catch {
+            // empty
+        }
+        if (!adapter) {
+            try {
+                adapter = await navigator.gpu.requestAdapter();
+            }
+            catch {
+                // empty
+            }
+        }
+        if (!adapter) {
+            try {
+                adapter = await navigator.gpu.requestAdapter({
+                    powerPreference: 'low-power',
+                });
+            }
+            catch {
+                // empty
+            }
+        }
+        if (!adapter) {
+            throw new Error('Failed to get GPU adapter. Possible reasons:\n' +
+                '1. WebGPU is disabled in browser flags\n' +
+                '2. Your GPU is blocklisted\n' +
+                '3. GPU drivers need updating\n' +
+                '4. Running in a virtual machine without GPU access\n\n' +
+                'For Chrome/Edge: Visit chrome://gpu to check WebGPU status\n' +
+                'For Safari: Ensure macOS Sonoma 14.4+ with Safari 18+');
+        }
+        try {
+            this.device = await adapter.requestDevice();
+        }
+        catch (e) {
+            throw new Error(`Failed to get GPU device: ${e}`);
+        }
+        if (!this.device) {
+            throw new Error('Failed to get GPU device: Device is null');
+        }
+        this.context = canvas.getContext('webgpu');
+        if (!this.context) {
+            throw new Error('Failed to get WebGPU context from canvas');
+        }
+        this.format = navigator.gpu.getPreferredCanvasFormat();
+        this.context.configure({
+            device: this.device,
+            format: this.format,
+            alphaMode: 'premultiplied',
+        });
+    }
+    /**
+     * WebGPUリソースを破棄する
+     */
+    destroy() {
+        if (this.device) {
+            this.device.destroy();
+            this.device = null;
+        }
+        this.context = null;
+    }
+}

package/dist/scatter-plot.d.ts

@@ -0,0 +1,210 @@
+import type { Label, ScatterPlotOptions, ScatterPlotEventMap, PointId, LabelIdentifier } from './types.js';
+import { type ParquetData } from './data/index.js';
+import { EventEmitter } from './event-emitter.js';
+/**
+ * WebGPUを使用して散布図を描画するメインクラス
+ *
+ * このクラスは3つの異なるレイヤーのファサード/コーディネーターとして機能する:
+ * - DataLayer: データ取得とクエリ管理を担当
+ * - GpuLayer: WebGPUレンダリングと変換を管理（LODと境界計算もGPU側で実行）
+ * - LabelLayer: ラベル用の2Dキャンバスオーバーレイを担当
+ */
+export declare class ScatterPlot extends EventEmitter<ScatterPlotEventMap> {
+    private readonly dataLayer;
+    private gpuLayer;
+    private labelLayer;
+    private readonly dataUrl;
+    private readonly labelUrl?;
+    /** GPUフィルターカラム名→インデックスのマッピング */
+    private gpuFilterColumnMapping;
+    /**
+     * ScatterPlotインスタンスを作成する
+     * @param options 散布図の設定オプション
+     */
+    constructor(options: ScatterPlotOptions);
+    /**
+     * WebGPUを初期化し、レンダリングリソースを作成する
+     */
+    initialize(): Promise<void>;
+    /**
+     * データ変更時のハンドラ（sizeSql, colorSql, whereConditions変更時）
+     */
+    private handleDataChanged;
+    /**
+     * URLからラベルデータを読み込み、エラーハンドリングを行う
+     * @param url ラベルデータのURL
+     */
+    private loadLabelsFromUrl;
+    /**
+     * 初期化エラーをScatterPlotError型に分類する
+     * @param e 発生した例外
+     * @returns 分類されたScatterPlotErrorオブジェクト
+     */
+    private categorizeInitError;
+    /**
+     * エラーイベントを発行する。リスナーが登録されていない場合はconsole.warnに出力する
+     * @param error 発行するエラーオブジェクト
+     */
+    private emitError;
+    /**
+     * 散布図をレンダリングする（GPUレイヤーとラベルの両方）
+     */
+    render(): void;
+    /**
+     * GeoJSONデータからラベルを読み込む
+     * @param geojsonData ラベルポイントを含むGeoJSON FeatureCollection
+     */
+    loadLabels(geojsonData: any): void;
+    /**
+     * プロットデータを更新して再レンダリングする
+     * @param options 更新する設定オプション
+     */
+    update(options: Partial<ScatterPlotOptions>): Promise<void>;
+    /**
+     * キャンバスをリサイズして再レンダリングする
+     * @param width 新しい幅（ピクセル）
+     * @param height 新しい高さ（ピクセル）
+     */
+    resize(width: number, height: number): void;
+    /**
+     * ズームレベルを設定する
+     * @param zoom ズームレベル（1.0 = 通常、>1.0 = ズームイン、<1.0 = ズームアウト）
+     */
+    setZoom(zoom: number): void;
+    /**
+     * 現在のズームレベルを取得する
+     * @returns 現在のズームレベル
+     */
+    getZoom(): number;
+    /**
+     * 指定した倍率でズームインする
+     * @param factor ズーム倍率（デフォルト: 1.2）
+     */
+    zoomIn(factor?: number): void;
+    /**
+     * 指定した倍率でズームアウトする
+     * @param factor ズーム倍率（デフォルト: 1.2）
+     */
+    zoomOut(factor?: number): void;
+    /**
+     * 指定した画面座標を中心にズームする
+     * @param newZoom 新しいズームレベル
+     * @param screenX 画面X座標（キャンバスピクセル単位）
+     * @param screenY 画面Y座標（キャンバスピクセル単位）
+     */
+    zoomToPoint(newZoom: number, screenX: number, screenY: number): void;
+    /**
+     * ズームとパンをデフォルト値にリセットする
+     */
+    resetView(): void;
+    /**
+     * パンオフセットを設定する
+     * @param x 正規化座標でのX方向パンオフセット（-1から1）
+     * @param y 正規化座標でのY方向パンオフセット（-1から1）
+     */
+    setPan(x: number, y: number): void;
+    /**
+     * 現在のパンオフセットを取得する
+     * @returns x, y座標を含むオブジェクト
+     */
+    getPan(): {
+        x: number;
+        y: number;
+    };
+    /**
+     * 指定した差分だけパンする
+     * @param dx 正規化座標でのX方向の差分
+     * @param dy 正規化座標でのY方向の差分
+     */
+    pan(dx: number, dy: number): void;
+    /**
+     * ラベルレイヤーのビュー変換をGPUレイヤーと同期する
+     */
+    private syncLabelViewTransform;
+    /**
+     * ラベルレイヤーからのポイントホバーイベントを処理する
+     * @param data ホバー中のポイントデータ（またはnull）
+     * @param userCallback ユーザー定義のコールバック
+     */
+    private handlePointHover;
+    /**
+     * GpuWhereConditionをGpuLayer用の形式に変換する
+     * @param conditions ユーザー指定のGPUフィルター条件
+     * @returns GpuLayer用のフィルター条件配列
+     */
+    private convertGpuWhereConditions;
+    /**
+     * カスタムSQLクエリを実行する
+     * @param query 実行するSQLクエリ文字列またはtoStringメソッドを持つオブジェクト
+     * @returns クエリ結果のParquetData
+     */
+    runQuery(query: string | {
+        toString: () => string;
+    }): Promise<ParquetData | undefined>;
+    /**
+     * 読み込まれたすべてのラベルを取得する
+     * @returns ラベルの配列
+     */
+    getLabels(): Label[];
+    /**
+     * IDを指定してプログラム的にポイントをホバー状態にする
+     * @param pointId ホバーするポイントのidColumn値
+     * @returns ポイントが見つかりホバーされた場合はtrue、そうでない場合はfalse
+     */
+    setPointHover(pointId: PointId): Promise<boolean>;
+    /**
+     * ポイントのホバー状態をクリアする
+     */
+    clearPointHover(): void;
+    /**
+     * 現在ホバー中のポイントデータを取得する
+     * @returns ホバー中の場合はポイントデータ、そうでない場合はnull
+     */
+    getHoveredPoint(): {
+        row: any[];
+        columns: string[];
+    } | null;
+    /**
+     * プログラム的にラベルをホバー状態にする
+     * @param identifier ラベル識別子（テキストまたはクラスターで識別）
+     * @returns ラベルが見つかりホバーされた場合はtrue、そうでない場合はfalse
+     */
+    setLabelHover(identifier: LabelIdentifier): boolean;
+    /**
+     * ラベルのホバー状態をクリアする
+     */
+    clearLabelHover(): void;
+    /**
+     * 現在ホバー中のラベルを取得する
+     * @returns ホバー中の場合はラベル、そうでない場合はnull
+     */
+    getHoveredLabel(): Label | null;
+    /**
+     * すべてのホバー状態をクリアする（ポイントとラベルの両方）
+     */
+    clearAllHover(): void;
+    /**
+     * グローバル透明度を設定する
+     * @param alpha 透明度 (0.0-1.0)
+     */
+    setPointAlpha(alpha: number): void;
+    /**
+     * 現在のグローバル透明度を取得する
+     * @returns 現在の透明度値 (0.0-1.0)
+     */
+    getPointAlpha(): number;
+    /**
+     * グローバルサイズスケールを設定する
+     * @param scale サイズスケール (0.01以上)
+     */
+    setPointSizeScale(scale: number): void;
+    /**
+     * 現在のグローバルサイズスケールを取得する
+     * @returns 現在のサイズスケール値
+     */
+    getPointSizeScale(): number;
+    /**
+     * リソースを破棄する
+     */
+    destroy(): Promise<void>;
+}