Focus stacking via Laplacian pyramid fusion. Takes a set of images captured at different focus distances and combines them into a single image where the entire subject is sharp.
Pre-built archives for Windows, macOS and Linux are on the releases tab, alongside Python wheels. FocusWeave can also be installed via
pip install FocusWeave
Point focusweave at a folder of images and it will produce stacked.jpg inside
that folder:
focusweave path/to/images/
To output to a specific file, format it as so.
focusweave path/to/images/ --output result.tiff
Output options
--output PATH Output file path, supports JPG, PNG, TIFF, and WebP images.
--quality N JPEG output quality 1–95 (default: 95).
Alignment options
--no-align Skip alignment entirely. Use when images are already registered.
--reference N Index of the image to align all others to (default: middle image).
--global-align Align every image directly to the reference instead of
chaining through neighbours. More robust when images are not
ordered by similarity.
--full-res Run the fine alignment pass at full resolution instead of the
default 1024px cap. More accurate but significantly slower.
--min-shift PIXELS Minimum shift in pixels before alignment is applied (default: 5.0).
--no-rotation Suppress rotation correction during alignment.
--no-scale Suppress scale correction during alignment.
--no-shear Suppress shear correction during alignment.
--no-translation Suppress translation correction during alignment.
Canvas options
--keep-size Keep the output the same size as the inputs; warps are applied
in-place rather than expanding the canvas.
--crop Crop the output to the intersection of all image extents —
removes all border regions but produces a smaller result.
--no-fill Fill border regions with black instead of reflecting edge pixels.
Pairs naturally with --crop to trim the borders away.
Stacking options
--levels N Laplacian pyramid levels (default: auto from image size).
--sharpness EXPONENT Weight sharpness exponent (default: 4.0). Higher values favour
the sharpest image more aggressively at each pixel, approaching
a hard winner-take-all selection. Useful range is roughly
1.0 (soft blend) to 8.0 (near-hard selection).
--workers N Number of frames fused concurrently. The default is automatic:
one per core, capped so the workers' buffers fit in free
memory. Each worker costs roughly 110 MB per megapixel of
output (160 MB for 16-bit sources). Pass a number to
override it.
Culling options
--cull [THRESHOLD] Remove wholly out-of-focus images before stacking. Each frame
is scored by the high- to low-frequency energy ratio of its
Tenengrad response; frames scoring below THRESHOLD are dropped.
The threshold is absolute, not relative to the sharpest frame.
THRESHOLD defaults to 0.6 when --cull is given without a value.
At least the two sharpest frames are always retained.
Slabbing options
Slabbing splits a large image set into overlapping sub-stacks, stacks each one independently, then fuses the results. This can improve quality by reducing the number of images competing in each fusion pass.
--slab SIZE OVERLAP Enable slabbing. SIZE is images per sub-stack; OVERLAP is how
many images adjacent slabs share. Example: --slab 20 5
--output-steps Save each intermediate slab result to a focusweave_slabs/
folder inside the output directory. Requires --slab.
--only-slab Stop after producing slabs; skip the final fusion. Implies
--output-steps. Requires --slab.
--recursive-slab If the layer-1 slab results still outnumber SIZE, apply
slabbing again as layer 2, and so on, until the count fits in
a single stack pass.
--slab-format EXT File format for slab output images (e.g. tiff, png, jpg).
Defaults to tiff. Requires --output-steps or --only-slab.
Batch options
Batch mode stacks a folder of folders, treating each subfolder as its own set:
focusweave --batch path/to/shoot/
focusweave --batch path/to/shoot/ --output path/to/results/
--batch FOLDER Stack each subfolder of FOLDER separately. Results are
named after their subfolder and written into FOLDER,
or into --output, which is then a folder rather than a
file. Every other option applies to each set. A set that
fails is reported and the rest carry on.
--batch-format EXT Format for batch results: inherit (the default), or an
extension such as tiff, png or jpg. inherit uses the
most common extension among each set's images, so a set
of 16-bit TIFFs comes out as a 16-bit TIFF.
Other
--timings Print how long each stage took.
--version, -V Show the version number and exit.
--opencv-version Show the version of the OpenCV library in use and exit.
--formats List the supported image extensions and exit.
--help Displays the list of commands
Peak memory is roughly 110 MB per megapixel of output per worker, or 160 MB for 16-bit sources. The worker count defaults to one per core, capped so those buffers fit in free memory. To cut memory to the minimum at the cost of processing time, set workers to 1:
focusweave path/to/images/ --workers 1
focusweave can be installed into your environment directly via pip:
pip install focusweave
Installing from git builds from source, so it needs the prerequisites listed under Building from source.
All public symbols are importable from the top-level focusweave package.
Only numpy is required at runtime. The main entry point is FocusStackConfig
and run:
from pathlib import Path
from focusweave import FocusStackConfig, run
cfg = FocusStackConfig(images=Path("path/to/images/"))
result = run(cfg)
# result.image is a uint8 (or uint16) RGB numpy arrayImages can be supplied as a folder path, a list of Path objects, or a list of
pre-loaded numpy arrays:
import numpy as np
from focusweave import FocusStackConfig, run
images: list[np.ndarray] = [...] # pre-loaded uint8 RGB arrays
cfg = FocusStackConfig(images=images, workers=4)
result = run(cfg)A progress callback can be passed to run to receive stage-by-stage updates:
from pathlib import Path
from focusweave import FocusStackConfig, run
def on_progress(fraction: float, stage: str, message: str) -> None:
print(f"[{stage}] {fraction * 100:.1f}% {message}")
cfg = FocusStackConfig(images=Path("path/to/images/"))
result = run(cfg, progress=on_progress)Long-running stacks can be cancelled by supplying an interrupt callback in the
config. If it returns True at any checkpoint, Interrupted is raised:
from pathlib import Path
from focusweave import FocusStackConfig, Interrupted, run
cancelled = False
cfg = FocusStackConfig(
images=Path("path/to/images/"),
interrupt=lambda: cancelled,
)
try:
result = run(cfg)
except Interrupted:
print("Stack cancelled.")Images can be read and written without pulling in another imaging library:
from pathlib import Path
from focusweave import load_image, save_image
frame = load_image(Path("frame_00.tiff")) # uint8 or uint16 RGB
save_image(result.image, Path("stacked.tiff"))See python/focusweave/api_example.py for a more complete example, or run it:
python -m focusweave.api_example path/to/images/ --streaming
A Rust toolchain (1.82 or newer) is required, plus OpenCV 4 development files
and libclang, which the opencv crate compiles and links against. Python 3.10
or newer if you want the bindings.
sudo apt-get install libopencv-dev libclang-dev # Debian, Ubuntu
brew install opencv llvm # macOS
choco install llvm opencv # Windows, plus the
# environment variables in
# RUNNING.md
Command line binary:
cargo build --release -p focusweave-cli
./target/release/focusweave --help
Python package, via maturin:
pip install maturin
maturin develop --release
Once installed, the focusweave command is available on your PATH and is the
same CLI as the native binary.
RUNNING.md walks through building, running and troubleshooting in more detail. docs/PORTING-NOTES.md records how the Rust implementation relates to the original Python one, including where the two deliberately differ.
cargo test --workspace
covers the parts that stand alone from image data. The port was validated
against the original Python implementation until the two were meant to
diverge; the last commit with that comparison is 638c5f0.
The focus stacking algorithm is based on Laplacian pyramid fusion as described in:
Wang, W., & Chang, F. (2011). A Multi-focus Image Fusion Method Based on Laplacian Pyramid. Journal of Computers.
Image alignment uses a custom coarse-to-fine pipeline built on an enhanced correlation coefficient solver (Evangelidis & Psarakis, 2008), implemented here. It seeds ECC with a phase-correlation translation estimate, applies CLAHE normalisation and a focus-aware pixel mask to concentrate the optimisation on sharp, informative regions, then validates the result against the seed to reject false minima. Warps are composed mathematically through a neighbour chain so interpolation error does not accumulate across the stack.