@neoanaloglabkk/lensfun-wasm 0.1.1

package/README.zh-CN.md

@@ -0,0 +1,318 @@
+# lensfun-wasm
+
+语言： [English](./README.md) | **简体中文** | [日本語](./README.ja.md)
+
+将 [Lensfun](https://github.com/lensfun/lensfun) 编译为 WebAssembly，并提供适合前端直接调用的 JavaScript API。
+
+## 项目概览
+
+`lensfun-wasm` 包含：
+
+- 以固定 commit 方式接入的 `lensfun` 上游源码（git submodule）
+- 完整官方镜头数据库（`data/db`，打包进 `.data`）
+- 稳定的 C 层 wasm 导出接口
+- 高层 TypeScript API
+- 同时支持 npm（ESM）和 CDN（UMD）
+
+## 能做什么
+
+- 在浏览器内初始化 Lensfun 数据库
+- 搜索镜头与机身
+- 生成以下矫正映射（map）：
+  - 几何/畸变
+  - TCA（横向色差）
+  - 暗角（vignetting）
+
+输出数据可直接用于 WebGL/WebGPU/canvas 的重映射流程。
+
+## 目录结构
+
+- `third_party/lensfun`：上游源码子模块
+- `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` 可用）
+
+## 安装
+
+```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` 的备用方式。
+- `wasmUrl?: string`
+  - 显式指定 `lensfun-core.wasm` 地址。
+- `dataUrl?: string`
+  - 显式指定 `lensfun-core.data` 地址。
+- `locateFile?: (path, prefix) => string`
+  - 完整覆盖 Emscripten 资源定位逻辑。
+- `dbPath?: string`
+  - Emscripten 文件系统中的数据库路径，默认 `/lensfun-db`。
+- `autoInitDb?: boolean`
+  - 默认 `true`，设为 `false` 可跳过初始化。
+
+## `LensfunClient`
+
+### `searchLenses(input) => LensMatch[]`
+
+`SearchLensesInput`：
+
+- `lensModel`（必填）
+- `lensMaker?`
+- `cameraMaker?`
+- `cameraModel?`
+- `searchFlags?`（默认 `LF_SEARCH_SORT_AND_UNIQUIFY`）
+
+返回 `LensMatch[]`：
+
+- `handle`（后续生成 map 需要）
+- `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()`
+
+释放原生数据库内存。完成后建议调用。
+
+## 导出常量
+
+搜索相关：
+
+- `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*` tag 后由 GitHub Actions 自动发布到 npmjs.org。  
+对应工作流：`.github/workflows/release.yml`
+
+已启用的发布保护：
+
+1. tag 与版本一致性校验（`vX.Y.Z` 必须等于 `package.json` 的 `version`）
+2. 构建与测试
+3. `npm pack --dry-run` 打包校验
+4. 发布到 npmjs.org（带 provenance）
+
+一次性配置：
+
+1. 在 npm 创建可发布的 Automation Token
+2. 在 GitHub 仓库 Secrets 中添加 `NPM_TOKEN`
+
+发布命令：
+
+```bash
+git checkout main
+git pull --ff-only
+
+# package.json 版本需已设置（示例：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 固定 commit 管理。
+- 手动升级，不自动追踪。
+
+同步命令：
+
+```bash
+scripts/sync-upstream.sh origin/master
+```
+
+升级后请执行：
+
+1. 重新构建 wasm
+2. 跑测试
+3. 更新 `UPSTREAM.md`
+
+## 常见问题
+
+### `emcc not found`
+
+未安装或未激活 emsdk。请在当前 shell 中激活后再构建。
+
+### `module factory not found`
+
+没有提供 `moduleFactory`，也没有预加载 `dist/assets/lensfun-core.js`。
+
+### `lfw_init failed with code ...`
+
+数据库文件路径或 `.data` 加载不正确。
+
+- 检查 `dataUrl` 是否指向 `lensfun-core.data`
+- 检查 `dbPath` 是否与预加载路径一致（默认 `/lensfun-db`）
+
+### `native map builder failed with code ...`
+
+通常是输入参数问题或镜头标定数据不匹配。
+
+- `lensHandle` 必须来自当前实例的 `searchLenses`
+- `width/height/step` 需合法
+- 请求暗角 map 时必须提供 `aperture`
+
+## 许可证
+
+- Lensfun 核心库：LGPL-3.0-or-later
+- Lensfun 数据库：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/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,20 @@
+# Third-Party Licenses
+
+## Lensfun
+
+- Repository: https://github.com/lensfun/lensfun
+- Library license: GNU LGPL v3.0 or later
+- Database license: Creative Commons Attribution-ShareAlike 3.0
+- Copyright: Lensfun contributors
+
+## tinyxml2
+
+- Repository: https://github.com/leethomason/tinyxml2
+- License: zlib
+- Copyright: Lee Thomason
+
+## utf8proc
+
+- Repository: https://github.com/JuliaStrings/utf8proc
+- License: MIT
+- Copyright: utf8proc contributors

package/UPSTREAM.md

@@ -0,0 +1,23 @@
+# Upstream Tracking
+
+## Source of truth
+
+- Upstream repo: https://github.com/lensfun/lensfun.git
+- Integration mode: git submodule (`third_party/lensfun`)
+- Current pinned commit: `655a9c4e3e53c25bc04843c853e7e7a0121359e7`
+- Commit date: `2026-02-28`
+- Commit subject: `Add tca data for Meike SL 35mm F1.8 STM PRO`
+
+## Update policy
+
+- Pin exact commits.
+- Upgrade manually via PR.
+- Run full build/test after each bump.
+
+## Update steps
+
+1. `scripts/sync-upstream.sh origin/master`
+2. Review upstream diff impact (API, DB changes, compile behavior)
+3. Rebuild wasm assets
+4. Run tests
+5. Update this file with new commit metadata