@uoa-css-lab/duckscatter 1.3.0

package/.github/dependabot.yml

@@ -0,0 +1,42 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 50
+    labels:
+      - "dependencies"
+    groups:
+      dependencies:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 50
+    labels:
+      - "dependencies"
+    groups:
+      dependencies:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "npm"
+    directory: "/examples/next"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 50
+    labels:
+      - "dependencies"
+    groups:
+      dependencies:
+        patterns:
+          - "*"

package/.github/workflows/ci.yaml

@@ -0,0 +1,111 @@
+on:
+  push:
+    branches:
+      - development
+    tags:
+      - v*
+  pull_request:
+    paths-ignore:
+      - '**.md'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 20
+      - uses: actions/cache@v5
+        with:
+          path: node_modules
+          key: ${{ hashFiles('package-lock.json') }}
+      - run: npm install
+      - name: build
+        run: npm run build
+      - uses: actions/cache/save@v5
+        with:
+          path: dist
+          key: dist-${{ github.sha }}
+
+  lint:
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 20
+      - uses: actions/cache@v5
+        with:
+          path: "**/node_modules"
+          key: ${{ hashFiles('package-lock.json', 'examples/next/package-lock.json') }}
+      - run: npm install
+      - run: npm install --prefix examples/next
+      - uses: actions/cache/restore@v5
+        with:
+          path: dist
+          key: dist-${{ github.sha }}
+      - name: lint
+        run: npm run lint:all
+
+  test:
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 20
+      - uses: actions/cache@v5
+        with:
+          path: "**/node_modules"
+          key: ${{ hashFiles('package-lock.json') }}
+      - run: npm install
+      - uses: actions/cache/restore@v5
+        with:
+          path: dist
+          key: dist-${{ github.sha }}
+      - name: test
+        run: npm run test
+
+  publish:
+    runs-on: ubuntu-latest
+    needs:
+      - build
+      - lint
+      - test
+    if: startsWith(github.ref, 'refs/tags/')
+    permissions:
+      packages: write
+      contents: read
+    strategy:
+      matrix:
+        registry-url:
+          - https://npm.pkg.github.com
+          - https://registry.npmjs.org
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        if: ${{ matrix.registry-url == 'https://npm.pkg.github.com' }}
+        with:
+          node-version: 20
+          registry-url: ${{ matrix.registry-url }}
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - uses: actions/setup-node@v6
+        if: ${{ matrix.registry-url == 'https://registry.npmjs.org' }}
+        with:
+          node-version: 20
+          registry-url: ${{ matrix.registry-url }}
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPMJS_TOKEN }}
+      - uses: actions/cache/restore@v5
+        with:
+          path: dist
+          key: dist-${{ github.sha }}
+      - run: npm publish --registry ${{ matrix.registry-url }} --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ matrix.registry-url == 'https://npm.pkg.github.com' && secrets.GITHUB_TOKEN || secrets.NPMJS_TOKEN }}

package/.github/workflows/release.yml

@@ -0,0 +1,55 @@
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: version
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+          - premajor
+          - prerelease
+      preid:
+        description: preid
+        type: choice
+        options:
+          - ""
+          - rc
+          - alpha
+
+jobs:
+  create-tag:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      actions: write
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - name: Generate a token
+        id: generate-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ secrets.RELEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+      - uses: actions/checkout@v6
+        with:
+          token: ${{ steps.generate-token.outputs.token }}
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 20
+
+      - run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - if: ${{ github.event.inputs.preid == '' }}
+        run: npm version ${{ github.event.inputs.version }}
+
+      - if: ${{ github.event.inputs.preid != '' }}
+        run: npm version ${{ github.event.inputs.version }} --preid ${{ github.event.inputs.preid }}
+
+      - name: git push
+        run: git push origin --tags ${{ github.ref }}:${{ github.ref }}

package/.prettierrc

@@ -0,0 +1,11 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "endOfLine": "lf",
+  "arrowParens": "always",
+  "bracketSpacing": true
+}

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) Meta Platforms, Inc. and affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,250 @@
+# duckscatter
+
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/UoA-CSS-Lab/duckscatter/blob/main/LICENSE)
+[![npm version](https://img.shields.io/npm/v/@uoa-css-lab/duckscatter.svg?style=flat)](https://www.npmjs.com/package/@uoa-css-lab/duckscatter)
+[![CI](https://github.com/UoA-CSS-Lab/duckscatter/actions/workflows/ci.yaml/badge.svg)](https://github.com/UoA-CSS-Lab/duckscatter/actions/workflows/ci.yaml)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/UoA-CSS-Lab/duckscatter)
+
+> duckscatterは大規模な散布図を描画するための、TypeScriptライブラリです。
+
+従来の散布図描画ライブラリでは、全文検索などの複雑なフィルタリングに時間がかかりました。duckscatterは、DuckDB-WASMによるSQL内での高速なデータ処理と、WebGPUによる大規模並列レンダリングを組み合わせることで、数十万点規模のデータでもスムーズな操作を実現します。
+
+* **WebGPUによるレンダリング:** GPUの能力を活用し、ブラウザ上で大規模な散布図を高速に描画します。CanvasやSVGでは扱えきれないような大量のデータポイントであっても、スムーズな操作を実現します。
+
+* **DuckDB-WASMによる高速なデータ分析:** DuckDB-WASMを内蔵しており、標準的なSQLを実行できます。SQLを使って動的に描画データをフィルタリングしたり、点の色やサイズを計算したりすることが可能です。
+
+* **ラベル表示:** データポイントにテキストラベルを表示できます。クラスタリングの結果を可視化する際に、各クラスタの中心や代表点にラベルを表示したり、特定のデータポイントに注釈を付けたりするのに最適です。
+
+## 画面イメージ
+
+<img src="./docs/image.png" alt="screen image" width="600">
+
+## データについて
+
+### Parquetファイル
+
+duckscatterは、Parquet形式のデータファイルを読み込みます。以下のカラムが必要です:
+
+| カラム | 型 | 説明 |
+|--------|------|------|
+| `x` | double | X座標 |
+| `y` | double | Y座標 |
+| IDカラム | 任意 | ポイントを識別するための一意キー（カラム名は`idColumn`オプションで指定） |
+
+その他のカラムはSQLで参照でき、色やサイズの計算に利用できます。
+
+### GeoJSONファイル（ラベル用）
+
+ラベルを表示するには、GeoJSON形式のファイルを指定します:
+
+```json
+{
+  "type": "FeatureCollection",
+  "features": [
+    {
+      "type": "Feature",
+      "geometry": {
+        "type": "Point",
+        "coordinates": [x, y]
+      },
+      "properties": {
+        "cluster_label": "ラベルテキスト"
+      }
+    }
+  ]
+}
+```
+
+## API
+
+```typescript
+const plot = new ScatterPlot({
+  canvas: HTMLCanvasElement,  // 描画先のcanvas要素
+  dataUrl: string,            // ParquetファイルのURL
+  data: {
+    idColumn: string,                         // IDカラム名（必須）
+    visiblePointLimit?: number,               // 描画最大ポイント数（デフォルト: 100,000）
+    sizeSql?: string,                         // サイズ計算SQL式（デフォルト: "3"）
+    colorSql?: string,                        // 色計算SQL式（ARGB 32bit整数、デフォルト: "0x4D4D4DCC"）
+    whereConditions?: WhereCondition[],       // フィルタ条件（CPU側）
+    gpuFilterColumns?: string[],              // GPUフィルタリング用カラム名（最大4つ）
+    gpuWhereConditions?: GpuWhereCondition[], // GPUフィルター条件
+  },
+  gpu?: {
+    backgroundColor?: ColorRGBA,  // 背景色
+    pointAlpha?: number,          // グローバル透明度（0.0-1.0、デフォルト: 1.0）
+    pointSizeScale?: number,      // グローバルサイズスケール（デフォルト: 1.0）
+  },
+  labels?: {
+    url?: string,                             // GeoJSONファイルのURL
+    fontSize?: number,                        // フォントサイズ（デフォルト: 12）
+    filterLambda?: LabelFilterLambda,         // ラベル表示フィルタ
+    onClick?: (label: Label) => void,         // クリックコールバック
+    hoverOutlineOptions?: HoverOutlineOptions, // ホバーアウトライン設定
+  },
+  interaction?: {
+    onPointHover?: PointHoverCallback,   // ポイントホバーコールバック
+    onLabelHover?: LabelHoverCallback,   // ラベルホバーコールバック
+  },
+});
+
+await plot.initialize();
+```
+
+主要メソッド:
+
+* `render()`: 描画
+* `resize(width, height)`: キャンバスリサイズ
+* `setZoom(zoom)` / `getZoom()` / `zoomIn()` / `zoomOut()`: ズーム操作
+* `zoomToPoint(newZoom, screenX, screenY)`: 指定座標を中心にズーム
+* `setPan(x, y)` / `getPan()` / `pan(dx, dy)`: パン操作
+* `resetView()`: ビューリセット
+* `update(options)`: オプション更新
+* `runQuery(sql)`: カスタムSQLクエリ実行
+* `getLabels()`: ラベル全件取得
+* `destroy()`: リソース解放
+
+**ポイント表示属性制御:**
+
+* `setPointAlpha(alpha)`: グローバル透明度を設定（0.0-1.0）
+* `getPointAlpha()`: 現在のグローバル透明度を取得
+* `setPointSizeScale(scale)`: グローバルサイズスケールを設定
+* `getPointSizeScale()`: 現在のグローバルサイズスケールを取得
+
+**ホバー制御API:**
+
+外部コンポーネントからプログラム的にホバー状態を制御できます。
+
+* `setPointHover(pointId)`: ポイントをホバー状態に（`Promise<boolean>`）
+* `clearPointHover()`: ポイントホバー解除
+* `getHoveredPoint()`: ホバー中のポイント取得
+* `setLabelHover(identifier)`: ラベルをホバー状態に（`boolean`を返す）
+* `clearLabelHover()`: ラベルホバー解除
+* `getHoveredLabel()`: ホバー中のラベル取得
+* `clearAllHover()`: 全ホバー解除
+
+```typescript
+// 使用例
+await plot.setPointHover(12345);           // IDでポイントをホバー
+plot.setLabelHover({ text: 'Cluster A' }); // テキストでラベルをホバー
+plot.setLabelHover({ cluster: 5 });        // クラスタ番号でラベルをホバー
+plot.clearAllHover();                      // 全ホバー解除
+```
+
+## GPUフィルタリング
+
+GPUフィルタリングを使用すると、数値カラムの範囲フィルタをGPU側で高速に実行できます。データの再フェッチなしにリアルタイムでフィルタリングが可能です。
+
+```typescript
+const plot = new ScatterPlot({
+  // ...
+  data: {
+    idColumn: 'word',
+    // GPUフィルタリング用のカラムを指定（最大4つ）
+    gpuFilterColumns: ['frequency', 'length'],
+    // フィルター条件を指定
+    gpuWhereConditions: [
+      { column: 'frequency', min: 100, max: 10000 },
+      { column: 'length', min: 3 },
+    ],
+  },
+});
+
+// 実行時にフィルター条件を更新
+await plot.update({
+  data: {
+    gpuWhereConditions: [
+      { column: 'frequency', min: 500 },
+    ],
+  },
+});
+```
+
+**CPUフィルタ（`whereConditions`）との違い:**
+
+| | CPUフィルタ | GPUフィルタ |
+|---|---|---|
+| **対応演算子** | 数値比較、文字列検索、生SQL | 範囲のみ（min/max） |
+| **更新速度** | SQLクエリ再実行が必要 | 即座に反映 |
+| **用途** | 複雑な条件、全文検索 | スライダーなどリアルタイム操作 |
+
+## 型定義
+
+主な型定義:
+
+```typescript
+// GPUフィルター条件
+interface GpuWhereCondition {
+  column: string;  // gpuFilterColumnsで指定したカラム名
+  min?: number;    // 最小値（省略時: -Infinity）
+  max?: number;    // 最大値（省略時: +Infinity）
+}
+
+// ホバーアウトラインオプション
+interface HoverOutlineOptions {
+  enabled?: boolean;           // 有効化（デフォルト: true）
+  color?: string;              // 線色（デフォルト: 白）
+  width?: number;              // 線幅（ピクセル、デフォルト: 2）
+  minimumHoverSize?: number;   // 最小ホバーサイズ
+  outlinedPointAddition?: number;
+}
+
+// WHERE条件フィルター
+type WhereCondition = NumericFilter | StringFilter | RawSqlFilter;
+
+interface NumericFilter {
+  type: 'numeric';
+  column: string;
+  operator: '>=' | '>' | '<=' | '<';
+  value: number;
+}
+
+interface StringFilter {
+  type: 'string';
+  column: string;
+  operator: 'contains' | 'equals' | 'startsWith' | 'endsWith';
+  value: string;
+}
+
+interface RawSqlFilter {
+  type: 'raw';
+  sql: string;
+}
+```
+
+## Examples
+
+### 実行方法
+
+```bash
+# ライブラリのビルド（ルートディレクトリで）
+npm install
+npm run build
+
+# サンプルアプリの実行
+cd examples/next
+npm install
+npm run dev
+```
+
+ブラウザで http://localhost:3000 を開きます。
+
+### サンプルデータ
+
+サンプルでは、GloVe 6B単語ベクトルをUMAPで2次元に投影したデータを使用しています（約40万単語）。
+
+* データセット: https://huggingface.co/datasets/mt0rm0/glove.6B.50d.umap.2d
+
+### ラベル生成
+
+ラベルはDBSCANクラスタリングとOpenAI APIを使って生成できます:
+
+```bash
+cd examples/next
+export OPENAI_API_KEY="your-api-key"
+python scripts/generate_labels.py
+```
+
+## ライセンス
+
+このライブラリは [MIT License](./LICENSE) の下でライセンスされています。

package/dist/data/data-layer.d.ts

@@ -0,0 +1,169 @@
+import type { ParquetData } from './repository.js';
+import type { WhereCondition, ScatterPlotError, PointId } from '../types.js';
+import type { AllPointsData } from '../renderer/gpu-layer.js';
+/**
+ * DataLayerの設定オプション
+ */
+export interface DataLayerOptions {
+    /** ポイントサイズを計算するSQL式 */
+    sizeSql?: string;
+    /** ポイント色を計算するSQL式（ARGB形式） */
+    colorSql?: string;
+    /** データフィルタリング用のWHERE条件 */
+    whereConditions?: WhereCondition[];
+    /** GPUでフィルタリングするカラム名（最大4つ） */
+    gpuFilterColumns?: string[];
+    /** ポイントを識別するためのカラム名 */
+    idColumn: string;
+    /** エラーをScatterPlotに通知するためのコールバック */
+    onError?: (error: ScatterPlotError) => void;
+    /** データ変更時に呼び出されるコールバック */
+    onDataChanged?: () => void;
+}
+/**
+ * データ取得とクエリ管理を担当するレイヤー
+ * 責務:
+ * - ParquetReaderを介したParquetデータの読み込みと管理
+ * - 全データをGPU用フォーマットに変換
+ * - データ変更の検知と通知
+ */
+export declare class DataLayer {
+    /** Parquetデータへのアクセスを提供するリポジトリ */
+    private repository;
+    /** ポイントサイズのSQL式 */
+    private sizeSql;
+    /** ポイント色のSQL式（ARGB形式: a=0.3, r=0.3, g=0.3, b=0.8） */
+    private colorSql;
+    /** フィルタリング用のWHERE条件 */
+    private whereConditions;
+    /** GPUでフィルタリングするカラム名 */
+    private gpuFilterColumns;
+    /** エラー通知用コールバック */
+    private onError?;
+    /** データ変更通知用コールバック */
+    private onDataChanged?;
+    /** 全ポイントデータのキャッシュ（ポイント検索用） */
+    private allPointsCache;
+    /** ポイント識別用のカラム名 */
+    private idColumn;
+    /**
+     * DataLayerインスタンスを作成する
+     * @param options 設定オプション
+     */
+    constructor(options: DataLayerOptions);
+    /**
+     * データレイヤーを初期化し、データを読み込む
+     * @param dataUrl Parquetファイルのurl
+     * @returns 処理済みの全データ
+     */
+    initialize(dataUrl: string): Promise<AllPointsData>;
+    /**
+     * GeoJSONラベルデータをDuckDBテーブルに読み込む
+     * @param geojson GeoJSON FeatureCollectionオブジェクト
+     */
+    loadLabelData(geojson: any): Promise<void>;
+    /**
+     * 単一の条件からWHERE句文字列を構築する
+     * @param condition WHERE条件
+     * @returns SQL WHERE句の文字列
+     */
+    private buildWhereClauseString;
+    /**
+     * 全データを読み込んでGPU用フォーマットに変換する
+     * @returns 処理済みの全データ
+     */
+    loadAllPoints(): Promise<AllPointsData>;
+    /**
+     * GPUフィルターカラムデータを読み込む
+     * @returns フィルターカラムデータとカラム数、カラムが指定されていない場合はnull
+     */
+    loadGpuFilterColumns(): Promise<{
+        data: Float32Array;
+        columnCount: number;
+        columnMapping: Map<string, number>;
+    } | null>;
+    /**
+     * カスタムSQLクエリを実行する
+     * @param query SQLクエリ
+     * @returns クエリ結果のParquetData
+     */
+    executeQuery(query: string | {
+        toString: () => string;
+    }): Promise<ParquetData | undefined>;
+    /**
+     * カラム形式のデータをGPU用インスタンスデータフォーマットに変換する
+     * フォーマット: ポイントごとに [x (f32), y (f32), color (u32), size (f32)]
+     * @param data ParquetData形式のデータ
+     * @returns 処理済みデータ
+     */
+    private processDataToGpuFormat;
+    /**
+     * 設定オプションを更新する
+     * @param options 更新する設定オプション
+     * @returns GPUフィルターカラムが変更された場合はtrue
+     */
+    updateOptions(options: Partial<DataLayerOptions>): {
+        gpuFilterColumnsChanged: boolean;
+    };
+    /**
+     * 行データからポイントの色を取得する
+     * @param row 行データ
+     * @param columns カラム名の配列
+     * @returns RGBAカラーオブジェクト
+     */
+    getPointColor(row: any[], columns: string[]): {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+    /**
+     * 行データからポイントのサイズを取得する
+     * @param row 行データ
+     * @param columns カラム名の配列
+     * @returns ポイントサイズ
+     */
+    getPointSize(row: any[], columns: string[]): number;
+    /**
+     * 画面座標に最も近いポイントを検索する
+     * @param screenX マウスのスクリーンX座標
+     * @param screenY マウスのスクリーンY座標
+     * @param canvasWidth キャンバスの幅（ピクセル）
+     * @param canvasHeight キャンバスの高さ（ピクセル）
+     * @param zoom 現在のズームレベル
+     * @param panX 現在のパンX
+     * @param panY 現在のパンY
+     * @param aspectRatio キャンバスのアスペクト比
+     * @param thresholdPixels ヒットと見なす最大距離（ピクセル、デフォルト: 10）
+     * @returns 見つかった場合はポイントデータ、そうでない場合はnull
+     */
+    findNearestPoint(screenX: number, screenY: number, canvasWidth: number, canvasHeight: number, zoom: number, panX: number, panY: number, aspectRatio: number, thresholdPixels?: number): Promise<{
+        row: any[];
+        columns: string[];
+    } | null>;
+    /**
+     * データレイヤーが初期化されているかチェックする
+     * @returns 初期化されていればtrue
+     */
+    isInitialized(): boolean;
+    /**
+     * IDでポイントを検索する
+     * @param pointId 検索するポイントのidColumn値
+     * @returns 見つかった場合はポイントデータ、そうでない場合はnull
+     */
+    findPointById(pointId: PointId): Promise<{
+        row: any[];
+        columns: string[];
+    } | null>;
+    /**
+     * ParquetDataから指定行のデータを配列として構築する
+     * @param data ParquetData
+     * @param rowIndex 行インデックス
+     * @returns 行データの配列
+     */
+    private buildRowFromData;
+    /**
+     * リソースをクリーンアップする
+     */
+    destroy(): Promise<void>;
+}