lensfun-wasm

Language: English | 简体中文 | 日本語

Compile 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

npm install @neoanaloglabkk/lensfun-wasm

Quick Start (Bundler)

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)

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

# 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

npm run check

Includes:

• JS bundle build
• Type declaration build
• Vitest unit tests

Upstream Sync Policy

• Lensfun is tracked by pinned submodule commit.
• Upgrade manually (no auto tracking).

Sync helper:

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
• THIRD_PARTY_LICENSES.md
• UPSTREAM.md