geofit

Rotation- and scale-invariant shape matching for machine vision — find a part at any angle, under changing illumination, with pieces of it missing.

Give it a picture of the part you are looking for. It tells you where that part is in the next image, how far it is rotated, and how sure it is — to a tenth of a pixel and a tenth of a degree, for every instance in the frame, in milliseconds.

It keeps working when the lighting drifts, when the part is darker or lighter than the one you taught it, and when something is sitting on top of it. Those are the conditions that break a plain correlation template match, and they are the everyday conditions on a line.

A C++ core behind a Python API that needs only numpy. No OpenCV, no PyTorch, no model to train, nothing to configure. A 2592x1944 image searched over the full 360 degrees takes about 20 ms.

pip install geofit
geofit demo --save result.png     # runs on a bundled sample, nothing else needed

What it looks like

Seven screwdriver bits on a dark background, every one at a different angle. The red outline is the model drawn back onto the pose that was found, the green box is the template footprint, and the blue line shows which way it is facing.

Four retaining clips, two of them overlapping and one lying on top of a gear. All four are found and told apart, in 4 ms:

The bundled sample — four rotated instances, an illumination gradient across the frame, noise, and one instance about 30% occluded (bottom left, still scoring 0.83):

Install

pip install geofit

Python 3.10 – 3.14 on Windows x86-64, Linux x86-64 / aarch64, macOS arm64 / x86-64. The only runtime dependency is numpy.

Reading and writing PNG and PGM needs nothing else. Other formats (JPEG, TIFF, …) go through Pillow if it is installed:

pip install "geofit[image]"

The wheel is tagged py3-none-<platform>: it does not link against the CPython ABI, so one file covers every supported Python and keeps working when a new one is released.

Quick start

import geofit as gf

template = gf.imread("template.png")      # uint8 grayscale numpy array
image    = gf.imread("scene.png")

model = gf.ShapeModel.create(template)
matches = model.find(image, min_score=0.6, num_matches=0)   # 0 = find them all

for m in matches:
    print(m.x, m.y, m.angle, m.scale, m.score)

gf.imwrite("result.png", gf.overlay(image, model, matches))

m.x, m.y is where the centre of the template landed, in image pixels. m.angle is degrees, positive counter-clockwise on screen. To map a template coordinate p into the image: R(angle) @ (scale * (p - center)) + (x, y) — or call model.transform(m).

Any uint8 grayscale numpy array works, so gf.imread is a convenience rather than a requirement: OpenCV, Pillow, scikit-image or a frame grabber SDK all feed it directly.

import cv2
image = cv2.imread("scene.png", cv2.IMREAD_GRAYSCALE)
matches = model.find(image, min_score=0.6)

Command line

geofit serve                           # dashboard: crop a template, try parameters
geofit demo                            # bundled sample, prints the matches
geofit demo --save result.png          # ... and writes an overlay image
geofit find -t tpl.png -i scene.png --min-score 0.6 --save out.png
geofit find -t tpl.png -i scene.png --json        # machine-readable
geofit info                            # version, SIMD path, threads, licence
geofit bench                           # quick timing on the bundled sample
geofit check                           # licence key and evaluation status

The dashboard

geofit serve                # opens http://localhost:8020
geofit serve --port 9000

Drag a rectangle over the part you want to find, press Build model, and the model points appear on top of your crop so you can see what it latched on to. Load a search image, press Search, and the matches are drawn over it with a table and timings.

min_score and the match count are sliders that filter instantly - the search is not re-run - and the score histogram shows where the gap between real matches and noise sits, which is a better way to pick a threshold than guessing. Copy as Python gives you the call with whatever parameters you have arrived at.

It binds to localhost and has no authentication; keep it that way unless you have a reason not to.

geofit demo needs no files of your own — a synthetic template and scene ship inside the package, and geofit.sample_paths() returns where they are.

$ geofit demo
template 100x84  image 720x480
model    3 levels, points [131, 126, 94], built in 5.9 ms
search   8.5 ms  (pyramid 5.2 / top level 2.9 / refine 0.4)
         early termination: 35.3% of the work done (2.8x saved)

4 matches
    #          x          y     angle   scale   score
    0     399.23     110.09    +37.19   1.000   0.998
    1     139.36     119.18     -0.06   1.000   0.998
    2     600.65     299.97   -118.09   1.000   0.993
    3     169.71     349.85   +164.57   1.000   0.832

--json prints the same thing as a JSON document on stdout and nothing else, so it drops straight into a pipeline.

Python API

ShapeModel.create(template, ...)

Choosing points

A megapixel template has far more edge pixels than max_points, so something has to choose between them. points="chain" groups the edges into connected contours and places points at even spacing along each one, so every contour gets a share of the budget in proportion to its length. points="magnitude" takes the strongest gradients first, which is what versions before 0.3.0 did - on a part with one dominant contour that spends the entire budget there and leaves the rest of the outline unrepresented.

chain is the default and is what you want unless you have a specific reason otherwise. It is also the only mode that drops short contours, which is how noise speckle is kept out; magnitude is the only mode that fills max_points exactly.

Leaving parts of the template out

A crop is a rectangle and a part usually is not, so background comes in with it. Model points on that background make the model specific to the bench it was taught on. The same goes for anything that changes between parts - a date stamp, a label, a reflection.

model = gf.ShapeModel.create(template, exclude=[(120, 40, 60, 25)])

Gradients and Canny run on the whole untouched template and the mask is applied afterwards, so a masked-out region grows no false edge along its own border and the pixels just outside it keep their true gradient. Cropping the region out or painting it flat does neither. The dashboard draws these as exclusion boxes.

model.find(image, ...)

Calls release the GIL, so several find() calls from Python threads genuinely run in parallel.

matches, t = model.find(image, min_score=0.6, num_matches=0, with_timing=True)
print(t.total_ms, t.toplevel_ms, t.early_termination_ratio)

Other functions

Getting good results

Four things account for most of the difference between a model that works and one that does not.

Crop the template tightly. Background that varies from one instance to the next costs more score than any parameter you can tune. On a board where the same component sits next to different neighbours, trimming 15% off the template border took detections from 14 to 36 — a bigger change than anything min_score could do.

Elongated, self-similar shapes give duplicate matches slid along their own axis. Raise min_score rather than max_overlap: a duplicate offset along the axis does not overlap enough for IoU to catch it, but its score is clearly lower.

A rotationally symmetric part returns its angle modulo the symmetry. A brake rotor with six arms whose shapes alternate has a period of 120°, not 60°, and the search will tell you so: at the 60° offsets the score drops to 0.31.

Narrow the angle range when you know it. angle_start / angle_extent cut the top-level search proportionally. If parts arrive within ±15°, say so and the search gets an order of magnitude cheaper.

Accuracy

Measured against exact ground truth by rotating a real 2592×1944 image by known angles:

position error   mean 0.13 px   max 0.28
angle error      mean 0.080°    max 0.218      θ = -150° … +150°, 9/9 found

Against a public benchmark set (DennisLiu1993/Fastest_Image_Pattern_Matching), on ten scenes covering scattered parts at arbitrary angles, repeated grids, overlapping parts and fine particles, the detection count matched the expected count in every case where an expected count is well defined.

Performance

AMD Zen 4, 16 cores, full 360° search:

The hot loop is compiled three ways — a portable baseline, AVX2+FMA on x86-64, and NEON on ARM64 — and the x86 path is chosen at runtime by CPUID. The same wheel therefore runs on CPUs without AVX2, falling back to the portable path instead of crashing. geofit info reports which one it picked.

The search spends its time only where a match is still possible, which on real images is a small fraction of the frame. geofit demo reports how much of the work that saved on the run you just did — typically three- to eightfold. greediness controls how aggressively it does this: leave it at the default, raise it when you need speed, drop it to 0 when you would rather not miss a weak match.

Licensing

pip install geofit gives you a 90-day evaluation, counted from the first run on each machine. No sign-up, no key, no network call — nothing is transmitted anywhere at any point, during the evaluation or afterwards.

geofit check      # days remaining, and where the settings live

When the 90 days are up geofit stops running: calls raise geofit.TrialExpired and the CLI exits with status 3.

After the evaluation

Write to pashidl.lab@gmail.com and we will send a licence key — one line of text. There is no account to create and no licence server to reach.

A key is a signed statement, verified offline against a public key inside the package. Install it either way:

# environment variable
setx GEOFIT_LICENSE "<key>"           # Windows
export GEOFIT_LICENSE='<key>'         # macOS / Linux

# or save the key to a file
~/.geofit/license

geofit check then shows the licensee name and the expiry date. Keys carry their own expiry, and geofit check starts warning 30 days ahead of it.

License

Proprietary. This package is distributed for evaluation; see the LICENSE file inside the wheel for the full terms. Commercial licensing: pashidl.lab@gmail.com

The source code is not distributed.

Documentation and screenshots: https://github.com/pashidl-lab/geofit