The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.
JavaScript
"""Auto-stitch: quad fitting math (pure) and the OpenCV layout solvers.
The solvers are exercised against synthetic scenes, so the right answer is known
up front. Planar gets a scene cut into overlapping crops: the crops' offset is
what we asked for, and the solved quads must reproduce it. The rotation model gets
views rendered through a camera turned by known angles — built by direct sampling
in `stitchscene.py`, so nothing under test is used to make its own input.
"""
import math
import pytest
from PIL import Image
from azimut.engine import stitch
from stitchscene import _pan, _scene
def _overlaid(images, box=(18, 18, 138, 88), seed=41) -> list[Image.Image]:
"""The same textured patch burnt into every image at the same pixel.
Stands in for what a video actually carries: a platform logo, a channel bug, a
timestamp. Textured rather than flat, because a flat patch has no keypoints and
would prove nothing.
"""
x0, y0, x1, y1 = box
logo = _scene(x1 - x0, y1 - y0, seed=seed, blobs=90)
out = []
for img in images:
copy = img.copy()
copy.paste(logo, (x0, y0))
out.append(copy)
return out
def _widths(quads):
return [max(p[0] for p in q) - min(p[0] for p in q) for q in quads]
def _centroid(quad):
return (sum(p[0] for p in quad) / 4, sum(p[1] for p in quad) / 4)
# --- pure math -------------------------------------------------------------
def test_fit_quads_to_canvas_centres_and_preserves_aspect():
# A 200x100 constellation into a 400x400 canvas: uniform scale, so it fills
# the width (minus margin) and stays centred vertically rather than stretching.
quads = [[[0, 0], [200, 0], [200, 100], [0, 100]]]
out = stitch.fit_quads_to_canvas(quads, 400, 400, margin=0.0)[0]
assert out[0] == pytest.approx([0, 100])
assert out[2] == pytest.approx([400, 300])
def test_fit_quads_to_canvas_keeps_relative_geometry():
quads = [
[[0, 0], [100, 0], [100, 100], [0, 100]],
[[100, 0], [200, 0], [200, 100], [100, 100]],
]
a, b = stitch.fit_quads_to_canvas(quads, 800, 400)
# Side-by-side before, side-by-side after: b's left edge meets a's right edge.
assert a[1][0] == pytest.approx(b[0][0])
assert a[1][1] == pytest.approx(b[0][1])
def test_fit_quads_to_canvas_handles_empty():
assert stitch.fit_quads_to_canvas([], 100, 100) == []
def test_canvas_for_layout_takes_the_layouts_own_extent():
quads = [[[0, 0], [1000, 0], [1000, 400], [0, 400]]]
assert stitch.canvas_for_layout(quads, margin=0.0) == (1000, 400)
def test_canvas_for_layout_leaves_room_for_the_fitting_margin():
# The point of the size: fitting the layout into it scales the geometry by
# exactly one, so the pieces land at the resolution they were solved at.
quads = [[[0, 0], [1000, 0], [1000, 400], [0, 400]]]
fitted = stitch.fit_quads_to_canvas(quads, *stitch.canvas_for_layout(quads))[0]
assert fitted[1][0] - fitted[0][0] == pytest.approx(1000, abs=2)
def test_canvas_for_layout_counts_source_pixels_per_solved_unit():
quads = [[[0, 0], [500, 0], [500, 200], [0, 200]]]
assert stitch.canvas_for_layout(quads, detail=3.0, margin=0.0) == (1500, 600)
def test_canvas_for_layout_never_shrinks_the_canvas_it_was_given():
quads = [[[0, 0], [100, 0], [100, 50], [0, 50]]]
assert stitch.canvas_for_layout(quads, minimum=(1600, 800), margin=0.0) == (1600, 800)
def test_canvas_for_layout_bounds_a_long_layout_by_its_side():
quads = [[[0, 0], [60000, 0], [60000, 20000], [0, 20000]]]
width, height = stitch.canvas_for_layout(quads, margin=0.0)
assert max(width, height) == stitch.MAX_CANVAS_DIM
# Both sides shrink together, so the clamped canvas still carries the shape.
assert width / height == pytest.approx(3.0, abs=0.01)
def test_canvas_for_layout_bounds_a_layout_by_its_area():
quads = [[[0, 0], [8000, 0], [8000, 6000], [0, 6000]]]
width, height = stitch.canvas_for_layout(quads, margin=0.0)
assert width * height <= stitch.MAX_CANVAS_PIXELS
assert width / height == pytest.approx(8000 / 6000, abs=0.01)
def test_canvas_for_layout_leaves_a_canvas_already_past_the_bounds_alone():
"""The bounds hold what the solver asks for, not what the analyst set. A
canvas already past them is a resolution they chose, and a function whose job
is to grow one must never be the thing that shrinks it — the pieces already
on it would be scaled down with it."""
quads = [[[0, 0], [8000, 0], [8000, 6000], [0, 6000]]]
big = (8192, 8192) # 67 MP: what the compose route accepts, past the area bound
assert stitch.canvas_for_layout(quads, minimum=big, margin=0.0) == big
def test_canvas_for_layout_handles_empty():
assert stitch.canvas_for_layout([], minimum=(320, 240)) == (320, 240)
def test_quad_ok_accepts_a_plain_rectangle():
assert stitch.quad_ok([[0, 0], [10, 0], [10, 10], [0, 10]])
def test_quad_ok_rejects_non_finite_and_collapsed_and_folded():
assert not stitch.quad_ok([[0, 0], [float("inf"), 0], [10, 10], [0, 10]])
assert not stitch.quad_ok([[0, 0], [0, 0], [0, 0], [0, 0]]) # collapsed
# Bow-tie: corners 2 and 3 swapped, so the quad folds over itself.
assert not stitch.quad_ok([[0, 0], [10, 0], [0, 10], [10, 10]])
# --- solver ----------------------------------------------------------------
def test_solve_layout_recovers_a_known_horizontal_offset():
scene = _scene()
left = scene.crop((0, 0, 500, 500))
right = scene.crop((300, 0, 800, 500)) # 200px of overlap, 300px offset
solved = stitch.solve_layout([left, right], width=1200, height=600)
assert solved["dropped"] == []
assert sorted(solved["quads"]) == [0, 1]
quad_a, quad_b = solved["quads"][0], solved["quads"][1]
# The solver works in its own fitted canvas scale, so check the ratio the
# crops actually encode: a 300px offset across a 500px-wide piece.
width_a = quad_a[1][0] - quad_a[0][0]
offset = _centroid(quad_b)[0] - _centroid(quad_a)[0]
assert offset / width_a == pytest.approx(300 / 500, abs=0.06)
def test_solve_layout_places_pieces_inside_the_canvas():
scene = _scene(seed=11)
pieces = [scene.crop((0, 0, 500, 500)), scene.crop((300, 0, 800, 500))]
solved = stitch.solve_layout(pieces, width=1000, height=800)
canvas = solved["canvas"]
for quad in solved["quads"].values():
for x, y in quad:
assert -1 <= x <= canvas["width"] + 1
assert -1 <= y <= canvas["height"] + 1
def test_solve_layout_grows_the_canvas_rather_than_shrinking_the_pieces():
# The canvas the caller has is smaller than one piece. Fitting the stitch into
# it would throw away most of the pixels it was solved from, so the answer
# comes back on a canvas that holds the layout at its own scale instead.
scene = _scene(seed=13)
pieces = [scene.crop((0, 0, 500, 500)), scene.crop((300, 0, 800, 500))]
solved = stitch.solve_layout(pieces, width=240, height=200)
canvas = solved["canvas"]
assert canvas["width"] > 240 and canvas["height"] > 200
widths = [quad[1][0] - quad[0][0] for quad in solved["quads"].values()]
assert max(widths) == pytest.approx(500, rel=0.05)
def test_solve_layout_drops_a_piece_that_matches_nothing():
scene = _scene(seed=3)
pieces = [
scene.crop((0, 0, 500, 500)),
scene.crop((300, 0, 800, 500)),
_scene(width=500, height=500, seed=999), # unrelated scene
]
solved = stitch.solve_layout(pieces, width=1000, height=600)
# The stranger is reported, never guessed at — the analyst hand-places it.
assert solved["dropped"] == [2]
assert sorted(solved["quads"]) == [0, 1]
def test_solve_layout_rejects_a_lone_piece():
with pytest.raises(ValueError, match="at least two"):
stitch.solve_layout([_scene(width=200, height=200)], width=400, height=400)
def test_solve_layout_raises_when_nothing_overlaps():
pieces = [_scene(width=400, height=400, seed=1), _scene(width=400, height=400, seed=2)]
with pytest.raises(RuntimeError, match="no overlap"):
stitch.solve_layout(pieces, width=800, height=600)
# --- rotation model --------------------------------------------------------
def test_rotation_layout_keeps_pieces_even_where_planar_blows_them_up():
"""The reason the panorama modes exist, stated as a test.
Seven views across a 90° pan. The planar model has to divide each piece by its
cosine from the anchor, so the end pieces balloon; the cylinder is the surface
the camera actually swept, so every piece keeps its size.
How badly planar blows up depends on which piece it anchors to (worst at an
end, mildest from the middle), so the bar here is only "visibly uneven" — the
claim under test is the cylinder's evenness, which holds either way.
"""
views = _pan([-45, -30, -15, 0, 15, 30, 45])
planar = stitch.solve_layout(views, width=1600, height=800)
cylindrical = stitch.solve_rotation_layout(views, width=1600, height=800, warp="cylindrical")
assert cylindrical["dropped"] == []
assert sorted(cylindrical["quads"]) == list(range(7))
flat = _widths(planar["quads"].values())
round_ = _widths(cylindrical["quads"].values())
assert max(flat) / min(flat) > 2 # the distortion we are fixing
assert max(round_) / min(round_) == pytest.approx(1.0, abs=0.1)
def test_rotation_layout_orders_pieces_along_the_pan():
views = _pan([-30, 0, 30])
solved = stitch.solve_rotation_layout(views, width=1600, height=800)
xs = [_centroid(solved["quads"][i])[0] for i in range(3)]
assert xs[0] < xs[1] < xs[2]
def test_rotation_layout_places_pieces_inside_the_canvas():
solved = stitch.solve_rotation_layout(_pan([-20, 0, 20]), width=1000, height=800)
canvas = solved["canvas"]
for quad in solved["quads"].values():
for x, y in quad:
assert -1 <= x <= canvas["width"] + 1
assert -1 <= y <= canvas["height"] + 1
def test_rotation_layout_sizes_the_canvas_in_source_pixels():
"""The rotation model solves on a 1000px work copy of every piece, so its
geometry has to be read back up to the source before the canvas is sized —
otherwise the same pan filmed in 4K would come back at the same detail as a
thumbnail of it. Three times the pixels in, three times the canvas out."""
small = _pan([-20, 0, 20])
big = [v.resize((v.width * 3, v.height * 3)) for v in small]
# A canvas at the floor, so the answer is the layout's own size and nothing else.
coarse = stitch.solve_rotation_layout(small, width=16, height=16)
fine = stitch.solve_rotation_layout(big, width=16, height=16)
assert fine["canvas"]["width"] == pytest.approx(3 * coarse["canvas"]["width"], rel=0.05)
assert fine["canvas"]["height"] == pytest.approx(3 * coarse["canvas"]["height"], rel=0.05)
# And the pan is worth more than the collage's default canvas, which is the
# size it used to be squeezed into.
assert fine["canvas"]["width"] > 1600
def test_rotation_layout_returns_a_remap_per_placed_piece():
solved = stitch.solve_rotation_layout(_pan([-20, 0, 20]), width=1200, height=600, warp="spherical")
assert sorted(solved["remaps"]) == sorted(solved["quads"])
for params in solved["remaps"].values():
assert params["warp"] == "spherical"
assert len(params["r"]) == 9
assert params["focal"] > 0 and params["scale"] > 0
def test_rotation_layout_drops_a_piece_that_matches_nothing():
views = _pan([-20, 0, 20])
views.append(_scene(width=520, height=420, seed=999)) # unrelated scene
solved = stitch.solve_rotation_layout(views, width=1200, height=600)
# Same promise as the planar solver: the stranger is reported, never guessed at.
assert solved["dropped"] == [3]
assert sorted(solved["quads"]) == [0, 1, 2]
assert 3 not in solved["remaps"]
def test_rotation_layout_rejects_a_lone_piece():
with pytest.raises(ValueError, match="at least two"):
stitch.solve_rotation_layout([_scene(width=200, height=200)], width=400, height=400)
def test_rotation_layout_raises_when_nothing_overlaps():
pieces = [_scene(width=400, height=400, seed=1), _scene(width=400, height=400, seed=2)]
with pytest.raises(RuntimeError, match="no overlap"):
stitch.solve_rotation_layout(pieces, width=800, height=600)
def test_rotation_layout_rejects_an_unknown_warp():
with pytest.raises(ValueError, match="unknown panorama warp"):
stitch.solve_rotation_layout(_pan([0, 20]), width=800, height=600, warp="planar")
class _FakeCv2:
"""Just enough of cv2 for `_solve_cameras`, with either solver set to blow up.
OpenCV reports a scene it cannot resolve two ways — `False`, or an assertion
thrown from inside the solver — and only the first was ever handled. Driven
through a stand-in rather than through real pictures, because the input that
makes the real adjuster assert is a property of the OpenCV build, not
something a fixture can promise across versions.
"""
error = type("error", (Exception,), {})
def __init__(self, raise_in: str):
self._raise_in = raise_in
class _Camera:
def __init__(self):
import numpy as np
self.R = np.eye(3, dtype="float64")
self.focal = 500.0
def _apply(self, which):
if self._raise_in == which:
raise self.error("(-215:Assertion failed) !err.empty() in function 'update'")
return True, [self._Camera(), self._Camera()]
def detail_HomographyBasedEstimator(self):
outer = self
class _Estimator:
def apply(self, feats, pairwise, _):
return outer._apply("estimator")
return _Estimator()
def detail_BundleAdjusterRay(self):
outer = self
class _Adjuster:
def setConfThresh(self, value): ...
def setRefinementMask(self, mask): ...
def apply(self, feats, pairwise, cameras):
return outer._apply("adjuster")
return _Adjuster()
@pytest.mark.parametrize(
("raise_in", "says"),
[("estimator", "estimate the camera rotations"), ("adjuster", "refine the camera rotations")],
)
def test_solve_cameras_answers_an_opencv_assertion_like_a_refusal(raise_in, says):
# Pieces that match just enough to be paired but not enough to be solved reach
# the ray adjuster and make it assert. Uncaught, that is a 500 and a traceback
# where the analyst should be reading that these pictures do not solve.
with pytest.raises(RuntimeError, match=says):
stitch._solve_cameras(_FakeCv2(raise_in), feats=[], pairwise=[])
# --- fixed overlays --------------------------------------------------------
def _points(*groups):
"""Keypoint arrays from ``(x, y)`` lists, as the solvers hand them over."""
import numpy as np
return [np.asarray(g, dtype=np.float32) for g in groups]
def test_static_points_flags_what_sits_in_the_same_place():
pinned = [(10.0, 10.0), (12.0, 40.0), (60.0, 15.0)]
moving = [[(100.0 + 30 * i, 20.0 * k) for k in range(12)] for i in range(4)]
points = _points(*[pinned + m for m in moving])
static = stitch._static_points(points, [(400, 300)] * 4)
assert [sorted(s) for s in static] == [[0, 1, 2]] * 4
def test_static_points_says_nothing_from_a_single_peer():
"""Two frames of a still camera and two frames sharing a logo are the same
picture — and there the identity the overlay pushes for is the right answer."""
points = _points([(10.0, 10.0), (12.0, 40.0)], [(10.0, 10.0), (12.0, 40.0)])
assert stitch._static_points(points, [(400, 300)] * 2) == [set(), set()]
def test_static_points_leaves_a_scene_that_simply_does_not_move():
"""Everything pinned means the camera is what stands still. Strip that and the
solver has nothing left to match with, so the piece keeps all of it."""
shared = [(10.0 * i, 20.0 + i) for i in range(30)]
points = _points(shared, shared, shared)
assert stitch._static_points(points, [(400, 300)] * 3) == [set()] * 3
def test_static_points_only_compares_pieces_of_the_same_geometry():
"""Same pixel on a different canvas is not the same place, so no overlay claim."""
shared = [(10.0, 10.0), (12.0, 40.0), (60.0, 15.0)]
noise = [[(100.0 + 30 * i, 20.0 * k) for k in range(12)] for i in range(3)]
points = _points(*[shared + n for n in noise])
static = stitch._static_points(points, [(400, 300), (400, 300), (640, 480)])
assert static == [set(), set(), set()]
def test_solve_layout_refuses_a_stitch_only_the_overlay_supports():
"""The regression this rejection exists for, and the reason it is worth having.
Three unrelated scenes wearing the same logo: the overlay matches itself
perfectly, so unfiltered it clears every guard here and glues the three into
one confident panorama — geometry invented out of nothing, which is exactly
what an analyst must never be handed.
"""
pieces = _overlaid([_scene(width=500, height=500, seed=s) for s in (1, 2, 3)])
with pytest.raises(RuntimeError, match="no overlap"):
stitch.solve_layout(pieces, width=900, height=900)
def test_rotation_layout_refuses_a_stitch_only_the_overlay_supports():
pieces = _overlaid([_scene(width=500, height=500, seed=s) for s in (4, 5, 6)])
with pytest.raises(RuntimeError, match="no overlap"):
stitch.solve_rotation_layout(pieces, width=900, height=900)
def test_solve_layout_still_stitches_pieces_that_wear_a_logo():
"""The other half of the bargain: dropping those keypoints must not cost the
real overlap. Same known offset as the plain planar test, logo and all."""
scene = _scene()
pieces = _overlaid([scene.crop((x, 0, x + 500, 500)) for x in (0, 130, 260, 390)])
solved = stitch.solve_layout(pieces, width=1600, height=800)
assert solved["dropped"] == []
width_a = solved["quads"][0][1][0] - solved["quads"][0][0][0]
xs = [_centroid(solved["quads"][i])[0] for i in range(4)]
for a, b in zip(xs, xs[1:]):
assert (b - a) / width_a == pytest.approx(130 / 500, abs=0.06)
def test_rotation_layout_still_stitches_pieces_that_wear_a_logo():
views = _overlaid(_pan([-30, -15, 0, 15, 30]))
solved = stitch.solve_rotation_layout(views, width=1600, height=800)
assert solved["dropped"] == []
xs = [_centroid(solved["quads"][i])[0] for i in range(5)]
assert xs == sorted(xs)
widths = _widths(solved["quads"].values())
assert max(widths) / min(widths) == pytest.approx(1.0, abs=0.1)
# --- the remap op ----------------------------------------------------------
def test_apply_warp_reproduces_the_solved_shape_and_marks_the_footprint():
views = _pan([-20, 0, 20])
solved = stitch.solve_rotation_layout(views, width=1200, height=600)
quad = solved["quads"][0]
out = stitch.apply_warp(views[0], solved["remaps"][0])
# The op must hand the compositor the very shape the solver measured, or the
# piece would not fill the quad it was placed in.
solved_aspect = (quad[1][0] - quad[0][0]) / (quad[3][1] - quad[0][1])
assert out.width / out.height == pytest.approx(solved_aspect, rel=0.01)
# Curved projection: the corners fall outside the piece and must stay clear,
# or they paint over whatever the piece overlaps.
assert out.mode == "RGBA"
alpha = out.getchannel("A")
assert alpha.getpixel((0, 0)) == 0
assert alpha.getpixel((out.width // 2, out.height // 2)) == 255
def test_apply_warp_is_resolution_independent():
"""The params are fractions, so a full-res re-derivation is the same shape."""
views = _pan([-20, 0, 20])
solved = stitch.solve_rotation_layout(views, width=1200, height=600)
params = solved["remaps"][1]
small = stitch.apply_warp(views[1], params)
large = stitch.apply_warp(views[1].resize((views[1].width * 3, views[1].height * 3)), params)
assert large.width / large.height == pytest.approx(small.width / small.height, rel=0.01)
assert large.width / small.width == pytest.approx(3.0, rel=0.02)
def test_apply_warp_applies_the_exposure_gain():
views = _pan([-20, 0, 20])
params = dict(stitch.solve_rotation_layout(views, width=1200, height=600)["remaps"][0])
params["gain"] = 0.5
plain = stitch.apply_warp(views[0], {**params, "gain": 1.0}).convert("RGB")
dim = stitch.apply_warp(views[0], params).convert("RGB")
assert _mean(dim) == pytest.approx(_mean(plain) * 0.5, rel=0.02)
def test_apply_warp_rejects_an_unknown_warp():
with pytest.raises(ValueError, match="unknown panorama warp"):
stitch.apply_warp(_scene(width=100, height=100), {"warp": "toroidal"})
def _mean(img):
import numpy as np
return float(np.asarray(img).mean())
def _stitched(heading, middle, warp="cylindrical", width=400):
"""A collage piece the rotation model placed: its camera turned `heading` degrees, centred at `middle`."""
h = math.radians(heading)
r = [math.cos(h), 0.0, math.sin(h), 0.0, 1.0, 0.0, -math.sin(h), 0.0, math.cos(h)]
remap = {"op": "remap", "params": {"warp": warp, "focal": 1.2, "aspect": 1, "ppx": 0.5, "ppy": 0.5, "r": r,
"scale": 1.2, "gain": 1}}
x0 = middle - width / 2
return {"save": {"path": "media/clip.mp4", "time": 1.0, "ops": [remap]},
"quad": [[x0, 10], [x0 + width, 10], [x0 + width, 300], [x0, 300]]}
def test_a_stitched_strip_says_how_many_pixels_a_degree_spans():
# 30 px a degree, the pieces 12° apart, one laid by hand beside them
nodes = [_stitched(h, 500 + 30 * h) for h in (-12, 0, 12, 24)]
nodes.append({"save": {"path": "media/clip.mp4", "ops": []}, "quad": [[0, 0], [100, 0], [100, 50], [0, 50]]})
scale = stitch.strip_scale(nodes)
assert scale["per_degree"] == pytest.approx(30.0)
assert (scale["stitched"], scale["by_hand"], scale["warp"]) == (4, 1, "cylindrical")
# a turn read the other way round is the same scale
assert stitch.strip_scale([_stitched(h, 500 - 30 * h) for h in (-12, 0, 12)])["per_degree"] == pytest.approx(30.0)
# across north, the headings are read as one turn
across = [_stitched(170, 30 * 170), _stitched(178, 30 * 178), _stitched(-174, 30 * 186)]
assert stitch.strip_scale(across)["per_degree"] == pytest.approx(30.0)
def test_a_strip_moved_by_hand_after_the_stitch_says_nothing():
nodes = [_stitched(h, 500 + 30 * h) for h in (-12, 0, 12, 24)]
nodes[2]["quad"] = [[x + 90, y] for x, y in nodes[2]["quad"]] # dragged 3° off where its turn puts it
assert stitch.strip_scale(nodes) is None
# one stitched piece, pieces that do not turn, or warps that differ say nothing either
assert stitch.strip_scale([_stitched(0, 500)]) is None
assert stitch.strip_scale([_stitched(5, 500), _stitched(5.2, 900)]) is None
assert stitch.strip_scale([_stitched(0, 500), _stitched(10, 800, warp="spherical")]) is None
assert stitch.strip_scale([]) is None
@pytest.mark.parametrize("focal", [520.0, 900.0])
def test_a_pans_lens_is_read_off_its_frames(focal):
views = _pan([-10, 0, 10], width=520, height=420, focal=focal)
found = stitch.lens_of_pan(views)
truth = 2 * math.degrees(math.atan(260 / focal))
assert len(found["fovs"]) == 3
for fov in found["fovs"].values():
assert fov == pytest.approx(truth, rel=0.05)
assert found["turn"] == pytest.approx(20.0, abs=1.5)
def test_a_pan_that_hardly_turns_or_frames_that_do_not_overlap_say_why():
with pytest.raises(RuntimeError, match="hardly turned"):
stitch.lens_of_pan(_pan([0, 1], width=520, height=420))
with pytest.raises(RuntimeError, match="do not overlap"):
stitch.lens_of_pan(_pan([0, 150], width=520, height=420))
with pytest.raises(RuntimeError, match="Two frames"):
stitch.lens_of_pan(_pan([0]))