imgsym

Detect symmetry axes in images and score mirror symmetry along them. imgsym implements multiple algorithms from symmetry research — 4 detectors and 13 scorers — behind one small API, and benchmarks them head-to-head.

Installation

pip install imgsym

This covers the classical scoring methods and the nxc / xfeatures / r_lip detectors. Some methods pull optional extras:

pip install "imgsym[deep]"      # alexnet, deep_features
pip install "imgsym[wavelets]"  # wavelets detector
pip install "imgsym[all]"       # everything (+ numba speedups)

Quick start

import cv2
import imgsym

# find symmetry axes: (angles, midpoints, lengths, strengths), strongest first
img = cv2.imread("assets/butterfly.jpg")
bf_axes = imgsym.detect_axes(img, detector="nxc")
vis1 = imgsym.visualize(img, bf_axes)

# score mirror symmetry along an axis; higher = more symmetric
axis = imgsym.get_axis(bf_axes, 0)                # strongest detected axis
imgsym.score_along_axis(img, axis, method="hog")  # 0.89

# binary shape masks have their own detector
mask = cv2.imread("assets/synthetic_star.png", cv2.IMREAD_GRAYSCALE)
star_axes = imgsym.detect_axes_from_mask(mask, detector="r_lip", mode="multi", threshold=0.9)
vis2 = imgsym.visualize(cv2.cvtColor(mask, cv2.COLOR_GRAY2BGR), star_axes)

natural image — nxc	binary shape mask — r_lip

demo.ipynb reproduces every figure on this page and has more to play with.

Choosing a method

Detectors

Natural images — imgsym.detect_axes(image, detector=...)

Detection accuracy is competition-protocol max-F (a detected axis counts if its angle is within 10° of ground truth and its center lies on the true segment), measured on three annotated benchmarks with scripts/eval_detection_competition.py:

nxc leads on every benchmark — use it when accuracy matters; xfeatures is ~25× faster and the solid middle ground; wavelets trails clearly.

Binary shapes — imgsym.detect_axes_from_mask(mask, detector=...)

A different input domain, so not comparable above:

Scorers

Numbers, not guesswork: skill is single-axis discrimination skill (2·AUC−1; 1 = perfect, 0 = chance) averaged over the four datasets of our benchmark (see Benchmark); speed is the median scoring time per crop on CPU. Scores are comparable within a method, not across methods.

Three methods share the top and are statistically close — deep_features (0.83), alexnet (0.81), hog (0.80). hog runs at 0.45 ms, ~20× faster than alexnet and ~370× faster than deep_features, which makes it the default choice; reach for deep_features when accuracy matters more than speed. Below the top tier there is a clear gap to gabor and the remaining classical measures.

Full citations live in each method's docstring (imgsym/scoring/calculators.py).

Where is it symmetric? (PatchNN heatmap)

The local_global scoring method matches every patch to its best mirror-twin on the other side of the axis. calculate_heatmap returns the per-patch match quality as a map about the vertical center column (aligned below is the image rotated so the detected axis is that center column — see the notebook).

calc = imgsym.SymmetryCalculatorFactory.create("local_global")
score, heatmap = calc.calculate_heatmap(aligned)   # (H, W) map of mirror-match quality

Blue = high local symmetry, red = low: the mirrored wing bands read blue, while the gravel background is genuinely asymmetric and reads warm. (Butterfly photo from Wikimedia Commons.)

Benchmark

The skill numbers above come from the symmetry-scoring benchmark that ships in scripts/: every method ranks true symmetry axes against perturbed negatives on four annotated datasets (~3900 axis units), with derived results (leaderboards, ablations, timings) tracked under results/. The raw per-image score JSONs are not tracked — they regenerate deterministically (fixed seeds) from the datasets, whose sources and expected directory layout are documented in data/README.md:

python scripts/run_discrimination.py                    # single-axis protocol
python scripts/run_discrimination.py --protocol multi   # multi-axis protocol

The full protocol and analysis are described in the accompanying paper.

License

MIT — see LICENSE.