Align2D#

Interactive image alignment widget with phase correlation and manual adjustment.

Usage#

import numpy as np
from quantem.widget import Align2D

img_a = np.random.rand(256, 256).astype(np.float32)
img_b = np.random.rand(256, 256).astype(np.float32)
Align2D(img_a, img_b, title="Alignment")

# With calibration
Align2D(img_a, img_b, pixel_size=2.4, cmap="viridis")

Features#

  • Auto-alignment – Phase correlation with Tukey windowing and DFT refinement

  • Manual mode – Drag or joystick to fine-tune translation

  • Overlay blend – Adjustable opacity for visual comparison

  • Side panels – Show both images side-by-side

  • FFT toggle – Compare Fourier transforms

  • Scale bar – Calibrated when pixel_size is set

Methods#

w = Align2D(img_a, img_b)

# Replace both images (re-runs auto-alignment)
w.set_images(new_a, new_b, auto_align=True)

# Access alignment result
dx, dy = w.offset
print(f"NCC: {w.ncc_aligned:.4f}")

# Reset alignment to zero offset
w.reset_alignment()

Control Groups#

# Lock groups (visible but non-interactive)
w = Align2D(
    img_a, img_b,
    disable_alignment=True,
    disable_display=True,
    disable_export=True,
)

# Hide groups entirely
w = Align2D(
    img_a, img_b,
    hide_stats=True,
    hidden_tools=["export"],
)

State Persistence#

w = Align2D(img_a, img_b, cmap="viridis", pixel_size=2.4)

w.summary()          # Print human-readable state
w.state_dict()       # Get all settings as a dict
w.save("state.json") # Save versioned envelope JSON file

# Restore from file or dict
w2 = Align2D(img_a, img_b, state="state.json")

Examples#

API Reference#

See quantem.widget.Align2D for full documentation.