whugin

Hugin's panorama stitcher, compiled to WebAssembly so it runs in a browser or under Node. It finds control points between overlapping photos, optimises the lens and camera geometry, remaps the images onto a canvas and blends them into one panorama. All thirteen of Hugin's headless tools (pto_gen, cpfind, cpclean, autooptimiser, pano_modify, nona, verdandi and six more) ship in one module.

The module is single-threaded with SIMD and needs no SharedArrayBuffer, so it runs on any site without COOP/COEP headers. Part of the wasmedia family.

Install

npm install @wasmedia/whugin

import { stitchInWorker } from "@wasmedia/whugin";

// files: File[] from an <input type="file" multiple>
const panorama = await stitchInWorker(
  files.map((file) => ({ name: file.name, data: file })),
  { onProgress: (e) => console.log(e.step, e.image ?? "") },
);

This returns a PNG Blob by default; JPEG and TIFF are also available. ESM only, for browsers (Chrome/Edge 95, Firefox 114, Safari 16.4 and later) and Node 20+. stitch() does the same on the current thread. Project exposes each step, and hugin.execute() runs any tool with its own command line. When bundling with Vite, pass workerUrl and set worker: { format: "es" }; see docs/project.md, "Stitching in a worker".

What it does

• Reproducible stitches. Pass seed and the same inputs give the same panorama, in Node and in Chromium, Firefox and WebKit. Without it, cpfind's random sampling makes runs differ slightly.
• Working files on disk. storage: "files" keeps the inputs, the remapped layers and the output in OPFS (in a worker) or host files (Node), through @wasmedia/wopfs. Five 12 MP JPEGs on a 39 MP canvas staged 335 MiB of JS memory by default and 66 MiB (the output itself) on files.
• Cancellation and progress. stitchInWorker() takes an AbortSignal, terminates its worker mid-step, and reports progress live.
• One instance, many runs. An instance from initWHugin() can run any number of tools, in any order, and each behaves as it would in a fresh process: the global state Hugin's tools leave behind is reset between runs (audited; docs/upstream.md, "Process-global state across tool runs"). Start a fresh instance only to give memory back: a WebAssembly heap never shrinks.
• A memory guard. A canvas too large for the 4 GiB wasm32 heap (near 398 megapixels) is refused with CanvasTooLargeError before any work starts. File storage lowers tab memory but does not raise this limit.

Playground

npm run playground serves a browser playground at http://localhost:8000/ (needs a built dist/). On main it deploys to GitLab Pages at whugin-889d3e.gitlab.io. You can stitch your own photos or a built-in sample in a worker, and nothing leaves the browser.

Scope

Hugin's pipeline spans three of this family's projects, which depend on each other at the JavaScript layer rather than by vendoring C:

• Blending: Hugin's default blender, enblend, is wenblend. whugin blends with Hugin's built-in verdandi, and its Blender interface is the seam for another blender.
• Lens correction: fulla and lensfun are wlensfun's job. fulla is not built here.
• Raw decoding: is not Hugin's job. Use wlibraw first.

The wxWidgets GUI, OpenMP and GPU remapping are compiled out. cpfind --celeste works if you provide the 8 MB celeste.model (it is not shipped; see CELESTE_DATA_DIR).

Artifacts

| File | What | Size | |---|---|---| | dist/whugin.{js,wasm} | the Emscripten module: 13 tools behind one dispatcher | 11.4 MiB wasm, uncompressed | | dist/index.js | the TypeScript API | | | dist/worker.js | the ./worker entry stitchInWorker() starts | | | dist/vendor/wopfs/ | a copy of @wasmedia/wopfs (MIT), loaded only for storage: "files" | 44 KB |

Serve the wasm with Content-Encoding on.

Build

The native build runs in Docker (emscripten/emsdk:5.0.6). The host needs Docker, Node 20+ and GNU make, and no local Emscripten.

npm run build          # native module (30-60 min cold) + TypeScript
npm test               # Node suite
npm run test:browser   # Chromium, Firefox and WebKit (npx playwright install chromium firefox webkit)

Documentation

• docs/project.md: the API, including stitch(), stitchInWorker(), Project, reproducibility, file storage, memory and limitations.
• docs/upstream.md: the native build's engineering record (dependencies, patches, flags, measured sizes, memory and timings). Read it before touching native/.
• docs/decisions.md: why each ruling was made, including the ones reversed.
• CHANGELOG.md: what changed, release by release.

Licensing

GPL-2.0-or-later. Hugin is GPL, and libpano13, linked into the module, is GPL-2.0, so the module, and anything that bundles it, carries GPL obligations. LICENSE is the GPLv2 text. The vendored wopfs copy keeps its MIT LICENSE beside it. This describes the licences in the source tree; it is not legal advice.

Third-party notices for everything statically linked into whugin.wasm (Hugin, libpano13, exiv2, VIGRA, the image codecs, Boost, FLANN, SQLite and Emscripten's runtime) ship in the package under dist/licenses/, indexed by dist/licenses/README.md. Serving whugin.wasm from a site distributes it, so keep that directory with it.

Source code. The source for any release is this repository at the tag matching its version (vX.Y.Z): the wrapper, the build scripts, the pinned upstream versions (native/settings/versions.sh) and every patch applied to upstream (native/patches/). The upstream sources are fetched from the URLs in native/scripts/deps/*.sh and native/scripts/build-hugin.sh, and npm run build rebuilds the module from them.