@neoanaloglabkk/lensfun-wasm

v0.1.3

Published

22 days ago

Lensfun compiled to WebAssembly with a high-level JS API for browser frontends.

0High
0Medium
0Low

neoanaloglabkk

lensfun-wasm

语言： English | 简体中文 | 日本語

将 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 可用）

安装

npm install @neoanaloglabkk/lensfun-wasm

快速开始（打包器）

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）

<script src="https://cdn.jsdelivr.net/npm/@neoanaloglabkk/[email protected]/dist/assets/lensfun-core.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@neoanaloglabkk/[email protected]/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

从源码构建

# 1) 安装依赖
npm install

# 2) 确保 emcc/emcmake 可用
#    例如：source /path/to/emsdk/emsdk_env.sh

# 3) 构建 wasm + js + 类型声明
npm run build

npm run build 包含：

npm run build:wasm
npm run build:js
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

本地检查

npm run check

包含：

JS 打包
类型声明生成
Vitest 单测

上游同步策略

Lensfun 通过 submodule 固定 commit 管理。
手动升级，不自动追踪。

同步命令：

scripts/sync-upstream.sh origin/master

升级后请执行：

重新构建 wasm
跑测试
更新 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

详见：

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme