@neoanaloglabkk/lensfun-wasm 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lex
+
+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/NOTICE.md

@@ -0,0 +1,10 @@
+# Notices
+
+This project bundles and/or links the following third-party components:
+
+1. Lensfun library source code (`third_party/lensfun/libs`) under LGPL-3.0-or-later.
+2. Lensfun camera/lens database (`third_party/lensfun/data/db`) under CC BY-SA 3.0.
+3. tinyxml2 (`third_party/tinyxml2`) under zlib license.
+4. utf8proc (`third_party/utf8proc`) under MIT license.
+
+Refer to `THIRD_PARTY_LICENSES.md` for license texts and links.

package/README.ja.md

@@ -0,0 +1,318 @@
+# lensfun-wasm
+
+言語: [English](./README.md) | [简体中文](./README.zh-CN.md) | **日本語**
+
+[Lensfun](https://github.com/lensfun/lensfun) を WebAssembly にコンパイルし、フロントエンドで使いやすい JavaScript API を提供します。
+
+## 概要
+
+`lensfun-wasm` には以下が含まれます。
+
+- 固定コミットで管理された `lensfun` 上流ソース（git submodule）
+- 公式の完全なレンズ DB（`data/db`、`.data` に同梱）
+- 安定した C ブリッジの wasm エクスポート
+- 高レベル TypeScript API
+- npm（ESM）と CDN（UMD）の両対応
+
+## できること
+
+- ブラウザ内で Lensfun DB を初期化
+- レンズ/カメラ検索
+- 以下の補正マップ生成
+  - 幾何/歪み
+  - TCA（倍率色収差）
+  - 周辺減光（vignetting）
+
+出力マップは WebGL/WebGPU/canvas のリマップ処理に利用できます。
+
+## ディレクトリ構成
+
+- `third_party/lensfun`: 上流ソース submodule
+- `native/`: wasm bridge、GLib 互換層、CMake ビルド
+- `src/`: 公開 TS API
+- `scripts/build-wasm.sh`: wasm ビルド入口
+- `dist/assets/`: 生成物 `lensfun-core.js/.wasm/.data`
+
+## 必要環境
+
+### 実行時（パッケージ利用のみ）
+
+- WebAssembly 対応のモダンブラウザ
+
+### ソースビルド
+
+- Node.js 22+
+- npm 10+
+- CMake 3.20+
+- Emscripten（`emcc`、`emcmake` が PATH にあること）
+
+## インストール
+
+```bash
+npm install @neoanaloglabkk/lensfun-wasm
+```
+
+## クイックスタート（バンドラ）
+
+```ts
+import { createLensfun } from '@neoanaloglabkk/lensfun-wasm';
+import createLensfunCoreModule from '@neoanaloglabkk/lensfun-wasm/core';
+import wasmUrl from '@neoanaloglabkk/lensfun-wasm/core-wasm?url';
+import dataUrl from '@neoanaloglabkk/lensfun-wasm/core-data?url';
+
+const client = await createLensfun({
+  moduleFactory: createLensfunCoreModule,
+  wasmUrl,
+  dataUrl
+});
+
+const lenses = client.searchLenses({
+  lensModel: 'pEntax 50-200 ED'
+});
+
+console.log(lenses[0]);
+```
+
+## クイックスタート（CDN）
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@neoanaloglabkk/lensfun-wasm@0.1.0/dist/assets/lensfun-core.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@neoanaloglabkk/lensfun-wasm@0.1.0/dist/umd/index.iife.js"></script>
+<script>
+(async () => {
+  const client = await LensfunWasm.createLensfun();
+  const lenses = client.searchLenses({ lensModel: 'pEntax 50-200 ED' });
+  console.log(lenses[0]);
+})();
+</script>
+```
+
+## API リファレンス
+
+## `createLensfun(options?) => Promise<LensfunClient>`
+
+`options`（`LensfunInitOptions`）:
+
+- `moduleFactory?: (opts) => Promise<LensfunModule>`
+  - バンドラ利用時の推奨。通常 `import createLensfunCoreModule from '@neoanaloglabkk/lensfun-wasm/core'`。
+- `moduleJsUrl?: string`
+  - `lensfun-core.js` の動的ロード URL。
+- `wasmUrl?: string`
+  - `lensfun-core.wasm` の明示 URL。
+- `dataUrl?: string`
+  - `lensfun-core.data` の明示 URL。
+- `locateFile?: (path, prefix) => string`
+  - Emscripten のファイル解決を完全上書き。
+- `dbPath?: string`
+  - Emscripten FS 上の DB パス。既定は `/lensfun-db`。
+- `autoInitDb?: boolean`
+  - 既定 `true`。`false` の場合は初期化をスキップ。
+
+## `LensfunClient`
+
+### `searchLenses(input) => LensMatch[]`
+
+`SearchLensesInput`:
+
+- `lensModel`（必須）
+- `lensMaker?`
+- `cameraMaker?`
+- `cameraModel?`
+- `searchFlags?`（既定 `LF_SEARCH_SORT_AND_UNIQUIFY`）
+
+戻り値 `LensMatch[]`:
+
+- `handle`（マップ生成で使用）
+- `maker`、`model`、`score`
+- `minFocal`、`maxFocal`、`minAperture`、`maxAperture`、`cropFactor`
+
+### `searchCameras(input) => CameraMatch[]`
+
+`SearchCamerasInput`:
+
+- `maker?`
+- `model?`
+- `searchFlags?`
+
+`CameraMatch[]` を返します（`maker/model/variant/mount/cropFactor/score`）。
+
+### `getAvailableModifications(lensHandle, crop) => number`
+
+Lensfun の `LF_MODIFY_*` ビットフラグを返します。
+
+### `buildCorrectionMaps(input) => CorrectionMaps`
+
+`CorrectionInput`:
+
+- `lensHandle`（必須）
+- `width`、`height`（必須、正整数）
+- `focal`、`crop`（必須）
+- `step?`（既定 `1`）
+- `reverse?`（既定 `false`）
+- `includeTca?`（既定 `false`）
+- `includeVignetting?`（既定 `false`）
+- `aperture?`（`includeVignetting = true` の場合必須）
+- `distance?`（既定 `1000`）
+
+`CorrectionMaps`:
+
+- `gridWidth`、`gridHeight`、`step`
+- `geometry: Float32Array` 長さ = `gridW * gridH * 2`
+  - 配列レイアウト: `[x0, y0, x1, y1, ...]`
+- `tca?: Float32Array` 長さ = `gridW * gridH * 6`
+  - 配列レイアウト: `[rx, ry, gx, gy, bx, by, ...]`
+- `vignetting?: Float32Array` 長さ = `gridW * gridH * 3`
+  - 配列レイアウト: `[rGain, gGain, bGain, ...]`
+
+### `dispose()`
+
+ネイティブ DB メモリを解放します。利用終了時に呼んでください。
+
+## 公開定数
+
+検索フラグ:
+
+- `LF_SEARCH_LOOSE = 1`
+- `LF_SEARCH_SORT_AND_UNIQUIFY = 2`
+
+補正フラグ:
+
+- `LF_MODIFY_TCA = 0x00000001`
+- `LF_MODIFY_VIGNETTING = 0x00000002`
+- `LF_MODIFY_DISTORTION = 0x00000008`
+- `LF_MODIFY_GEOMETRY = 0x00000010`
+- `LF_MODIFY_SCALE = 0x00000020`
+- `LF_MODIFY_PERSPECTIVE = 0x00000040`
+
+## ソースからビルド
+
+```bash
+# 1) 依存インストール
+npm install
+
+# 2) emcc/emcmake を有効化
+#    例: source /path/to/emsdk/emsdk_env.sh
+
+# 3) wasm + js + 型定義を生成
+npm run build
+```
+
+`npm run build` の実行内容:
+
+1. `npm run build:wasm`
+2. `npm run build:js`
+3. `npm run build:types`
+
+出力:
+
+- `dist/assets/lensfun-core.js`
+- `dist/assets/lensfun-core.wasm`
+- `dist/assets/lensfun-core.data`
+- `dist/esm/index.js`
+- `dist/umd/index.iife.js`
+- `dist/types/index.d.ts`
+
+## ローカル検証
+
+```bash
+npm run check
+```
+
+内容:
+
+- JS バンドル生成
+- 型定義生成
+- Vitest 単体テスト
+
+## 自動公開（npm + jsDelivr）
+
+このリポジトリは `v*` タグの push で GitHub Actions から npmjs.org に自動公開します。  
+対象ワークフロー: `.github/workflows/release.yml`
+
+公開前ガード:
+
+1. タグとバージョンの一致チェック（`vX.Y.Z` と `package.json` の `version`）
+2. ビルド + テスト
+3. `npm pack --dry-run` によるパッケージ検証
+4. npmjs.org へ provenance 付き公開
+
+初回設定:
+
+1. npm で publish 権限付き Automation Token を作成
+2. GitHub リポジトリ Secret に `NPM_TOKEN` を登録
+
+公開コマンド:
+
+```bash
+git checkout main
+git pull --ff-only
+
+# package.json の version は事前に設定（例: 0.1.0）
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+公開後確認:
+
+```bash
+npm view @neoanaloglabkk/lensfun-wasm version dist-tags --json
+```
+
+CDN 補足:
+
+- jsDelivr は npmjs.org の公開内容を自動反映します。
+
+## 上流同期ポリシー
+
+- Lensfun は submodule の固定コミットで管理
+- 自動追従せず手動更新
+
+同期コマンド:
+
+```bash
+scripts/sync-upstream.sh origin/master
+```
+
+更新後に行うこと:
+
+1. wasm 再ビルド
+2. テスト実行
+3. `UPSTREAM.md` 更新
+
+## トラブルシューティング
+
+### `emcc not found`
+
+emsdk が未インストール、または未アクティベートです。同じシェルで有効化後に再実行してください。
+
+### `module factory not found`
+
+`moduleFactory` 未指定、かつ `dist/assets/lensfun-core.js` が事前ロードされていません。
+
+### `lfw_init failed with code ...`
+
+DB パス、または `.data` 読み込みが不正です。
+
+- `dataUrl` が `lensfun-core.data` を指しているか確認
+- `dbPath` がプリロードパス（既定 `/lensfun-db`）と一致しているか確認
+
+### `native map builder failed with code ...`
+
+入力値不正、または補正データ不一致の可能性があります。
+
+- `lensHandle` は最新 `searchLenses` の結果を使う
+- `width/height/step` を見直す
+- vignetting 生成時は `aperture` を指定する
+
+## ライセンス
+
+- Lensfun コア: LGPL-3.0-or-later
+- Lensfun DB: CC BY-SA 3.0
+- tinyxml2: zlib
+- utf8proc: MIT
+
+詳細:
+
+- [NOTICE.md](./NOTICE.md)
+- [THIRD_PARTY_LICENSES.md](./THIRD_PARTY_LICENSES.md)
+- [UPSTREAM.md](./UPSTREAM.md)

package/README.md

@@ -0,0 +1,320 @@
+# lensfun-wasm
+
+Language: **English** | [简体中文](./README.zh-CN.md) | [日本語](./README.ja.md)
+
+Compile [Lensfun](https://github.com/lensfun/lensfun) into WebAssembly and expose a frontend-friendly JavaScript API.
+
+## Overview
+
+`lensfun-wasm` ships:
+
+- Upstream `lensfun` source as a pinned git submodule
+- Full official lens database (`data/db`) packaged into `.data`
+- A C bridge layer for stable wasm exports
+- A high-level TypeScript API for browser applications
+- ESM and UMD bundles for npm and CDN usage
+
+## What You Can Do
+
+- Initialize Lensfun database in browser
+- Search lenses and cameras
+- Build correction maps for:
+  - Geometry/distortion
+  - TCA (transverse chromatic aberration)
+  - Vignetting
+
+The output maps are designed for WebGL/WebGPU/canvas remap pipelines.
+
+## Project Layout
+
+- `third_party/lensfun`: upstream source (submodule)
+- `native/`: wasm bridge, GLib compatibility, native CMake build
+- `src/`: public TypeScript API
+- `scripts/build-wasm.sh`: wasm build entry
+- `dist/assets/`: generated `lensfun-core.js/.wasm/.data`
+
+## Requirements
+
+### Runtime (using package)
+
+- Modern browser with WebAssembly support
+
+### Build from source
+
+- Node.js 22+
+- npm 10+
+- CMake 3.20+
+- Emscripten (`emcc`, `emcmake` in PATH)
+
+## Installation
+
+```bash
+npm install @neoanaloglabkk/lensfun-wasm
+```
+
+## Quick Start (Bundler)
+
+```ts
+import { createLensfun } from '@neoanaloglabkk/lensfun-wasm';
+import createLensfunCoreModule from '@neoanaloglabkk/lensfun-wasm/core';
+import wasmUrl from '@neoanaloglabkk/lensfun-wasm/core-wasm?url';
+import dataUrl from '@neoanaloglabkk/lensfun-wasm/core-data?url';
+
+const client = await createLensfun({
+  moduleFactory: createLensfunCoreModule,
+  wasmUrl,
+  dataUrl
+});
+
+const lenses = client.searchLenses({
+  lensModel: 'pEntax 50-200 ED'
+});
+
+console.log(lenses[0]);
+```
+
+## Quick Start (CDN)
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@neoanaloglabkk/lensfun-wasm@0.1.0/dist/assets/lensfun-core.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@neoanaloglabkk/lensfun-wasm@0.1.0/dist/umd/index.iife.js"></script>
+<script>
+(async () => {
+  const client = await LensfunWasm.createLensfun();
+  const lenses = client.searchLenses({ lensModel: 'pEntax 50-200 ED' });
+  console.log(lenses[0]);
+})();
+</script>
+```
+
+## API Reference
+
+## `createLensfun(options?) => Promise<LensfunClient>`
+
+`options` (`LensfunInitOptions`):
+
+- `moduleFactory?: (opts) => Promise<LensfunModule>`
+  - Recommended in bundlers. Usually from `import createLensfunCoreModule from '@neoanaloglabkk/lensfun-wasm/core'`.
+- `moduleJsUrl?: string`
+  - Optional fallback URL for loading `lensfun-core.js` dynamically.
+- `wasmUrl?: string`
+  - Explicit URL for `lensfun-core.wasm`.
+- `dataUrl?: string`
+  - Explicit URL for `lensfun-core.data`.
+- `locateFile?: (path, prefix) => string`
+  - Full override for Emscripten file resolution.
+- `dbPath?: string`
+  - Database path in Emscripten FS. Default `/lensfun-db`.
+- `autoInitDb?: boolean`
+  - Default `true`. If false, db init is skipped.
+
+## `LensfunClient`
+
+### `searchLenses(input) => LensMatch[]`
+
+`SearchLensesInput`:
+
+- `lensModel` (required)
+- `lensMaker?`
+- `cameraMaker?`
+- `cameraModel?`
+- `searchFlags?` (default `LF_SEARCH_SORT_AND_UNIQUIFY`)
+
+Returns `LensMatch[]`:
+
+- `handle` (native lens handle for map generation)
+- `maker`, `model`, `score`
+- `minFocal`, `maxFocal`, `minAperture`, `maxAperture`, `cropFactor`
+
+### `searchCameras(input) => CameraMatch[]`
+
+`SearchCamerasInput`:
+
+- `maker?`
+- `model?`
+- `searchFlags?`
+
+Returns `CameraMatch[]` with `maker/model/variant/mount/cropFactor/score`.
+
+### `getAvailableModifications(lensHandle, crop) => number`
+
+Returns bit flags from Lensfun (`LF_MODIFY_*`).
+
+### `buildCorrectionMaps(input) => CorrectionMaps`
+
+`CorrectionInput`:
+
+- `lensHandle` (required)
+- `width`, `height` (required, positive integers)
+- `focal`, `crop` (required)
+- `step?` (default `1`)
+- `reverse?` (default `false`)
+- `includeTca?` (default `false`)
+- `includeVignetting?` (default `false`)
+- `aperture?` (required when `includeVignetting = true`)
+- `distance?` (default `1000`)
+
+`CorrectionMaps`:
+
+- `gridWidth`, `gridHeight`, `step`
+- `geometry: Float32Array` length = `gridW * gridH * 2`
+  - Layout: `[x0, y0, x1, y1, ...]`
+- `tca?: Float32Array` length = `gridW * gridH * 6`
+  - Layout: `[rx, ry, gx, gy, bx, by, ...]`
+- `vignetting?: Float32Array` length = `gridW * gridH * 3`
+  - Layout: `[rGain, gGain, bGain, ...]`
+
+### `dispose()`
+
+Releases native database memory. Call this when finished.
+
+## Exported Constants
+
+Search:
+
+- `LF_SEARCH_LOOSE = 1`
+- `LF_SEARCH_SORT_AND_UNIQUIFY = 2`
+
+Modification flags:
+
+- `LF_MODIFY_TCA = 0x00000001`
+- `LF_MODIFY_VIGNETTING = 0x00000002`
+- `LF_MODIFY_DISTORTION = 0x00000008`
+- `LF_MODIFY_GEOMETRY = 0x00000010`
+- `LF_MODIFY_SCALE = 0x00000020`
+- `LF_MODIFY_PERSPECTIVE = 0x00000040`
+
+## Build From Source
+
+```bash
+# 1) install dependencies
+npm install
+
+# 2) make sure emcc/emcmake are in PATH
+#    (example)
+#    source /path/to/emsdk/emsdk_env.sh
+
+# 3) build wasm + js + d.ts
+npm run build
+```
+
+`npm run build` steps:
+
+1. `npm run build:wasm`
+2. `npm run build:js`
+3. `npm run build:types`
+
+Output:
+
+- `dist/assets/lensfun-core.js`
+- `dist/assets/lensfun-core.wasm`
+- `dist/assets/lensfun-core.data`
+- `dist/esm/index.js`
+- `dist/umd/index.iife.js`
+- `dist/types/index.d.ts`
+
+## Local Validation
+
+```bash
+npm run check
+```
+
+Includes:
+
+- JS bundle build
+- Type declaration build
+- Vitest unit tests
+
+## Publish (npm + jsDelivr, Automated)
+
+This repository is configured to publish to npmjs.org from GitHub Actions when a `v*` tag is pushed.
+
+Workflow: `.github/workflows/release.yml`
+
+Release guardrails already enabled:
+
+1. Tag/version match check (`vX.Y.Z` must equal `package.json` version)
+2. Build + test
+3. `npm pack --dry-run` verification
+4. Publish to npmjs.org with provenance (`npm publish --provenance`)
+
+Setup once:
+
+1. Create an npm Automation Token with publish permission.
+2. Add it to repository secrets as `NPM_TOKEN`.
+
+Release commands:
+
+```bash
+git checkout main
+git pull --ff-only
+
+# package.json version must already be set (example: 0.1.0)
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+Post-release check:
+
+```bash
+npm view @neoanaloglabkk/lensfun-wasm version dist-tags --json
+```
+
+CDN note:
+
+- jsDelivr automatically reflects the npmjs.org package.
+
+## Upstream Sync Policy
+
+- Lensfun is tracked by pinned submodule commit.
+- Upgrade manually (no auto tracking).
+
+Sync helper:
+
+```bash
+scripts/sync-upstream.sh origin/master
+```
+
+After bumping upstream:
+
+1. Rebuild wasm
+2. Run tests
+3. Update `UPSTREAM.md`
+
+## Troubleshooting
+
+### `emcc not found`
+
+Install and activate emsdk, then re-run build in the same shell session.
+
+### `module factory not found`
+
+Provide `moduleFactory` or pre-load `dist/assets/lensfun-core.js` so `createLensfunCoreModule` exists.
+
+### `lfw_init failed with code ...`
+
+Database path or `.data` load is wrong.
+
+- Ensure `dataUrl` points to `lensfun-core.data`
+- Ensure `dbPath` matches preloaded path (`/lensfun-db` by default)
+
+### `native map builder failed with code ...`
+
+Input validation or Lensfun calibration mismatch.
+
+- Check `lensHandle` comes from latest `searchLenses`
+- Verify `width/height/step` are valid
+- Provide `aperture` when requesting vignetting
+
+## License
+
+- Lensfun core library: LGPL-3.0-or-later
+- Lensfun database: CC BY-SA 3.0
+- tinyxml2: zlib license
+- utf8proc: MIT license
+
+See:
+
+- [NOTICE.md](./NOTICE.md)
+- [THIRD_PARTY_LICENSES.md](./THIRD_PARTY_LICENSES.md)
+- [UPSTREAM.md](./UPSTREAM.md)