ringgrid (Python)

Python bindings for the ringgrid detector (PyO3 + maturin).

Install

From PyPI:

pip install ringgrid

With plotting helpers:

pip install "ringgrid[viz]"

From source (repository checkout):

pip install maturin
maturin develop -m crates/ringgrid-py/Cargo.toml --release

Fast Start: Generate target_spec.json + Printable SVG/PNG/DXF

Installed-package target generation is available directly from import ringgrid via the typed TargetLayout API:

from pathlib import Path
import ringgrid

target = ringgrid.TargetLayout.coded_hex(
    pitch_mm=8.0,
    rows=15,
    long_row_cols=14,
    outer_radius_mm=4.8,
    inner_radius_mm=3.2,
    ring_width_mm=1.152,
)

Path("target_spec.json").write_text(target.to_spec_json())
target.write_svg(Path("target_print.svg"), margin_mm=5.0)
target.write_png(Path("target_print.png"), dpi=600.0, margin_mm=5.0)
target.write_dxf(Path("target_print.dxf"))

Key knobs:

Outputs:

• target_spec.json (schema v6)
• target_print.svg
• target_print.png
• target_print.dxf (2D CAD, millimeters — for laser/CNC fabrication)

Equivalent paths for the same geometry (identical SVG/PNG/DXF; all write a v6 target_spec.json):

• Rust CLI: ringgrid gen <recipe.toml> --out <dir> — a small TOML/JSON target recipe (start from ringgrid example --name hex_coded) renders the same target_spec.json + SVG/PNG/DXF
• Python script from the repo: tools/gen_target.py for the same geometry
• Rust API: TargetLayout::coded_hex(...) / TargetLayout::new(...) plus write_json_file, write_target_svg, write_target_png, and write_target_dxf

Legacy v4 board_spec.json files still load — ringgrid.TargetLayout.from_json(...) auto-migrates v4 and v5 to v6. (See migration notes.)

Load this target in Python:

from pathlib import Path
import ringgrid

target = ringgrid.TargetLayout.from_json(Path("tools/out/target_faststart/target_spec.json"))
cfg = ringgrid.DetectConfig(target)
detector = ringgrid.Detector(cfg)
# Convenience default (config-free): detector = ringgrid.Detector.from_target(target)

If you are working from a repository checkout and also need synthetic images or ground truth, the repo tools under tools/ still provide the combined generation/evaluation workflow. The installed package target-generation API is for target JSON + printable SVG/PNG/DXF only. The repo-level tools/gen_target.py is a thin wrapper over this same installed-package surface.

Complete target-generation tutorial and full flag reference:

• https://vitalyvorobyev.github.io/ringgrid/book/target-generation.html

Target layouts

TargetLayout is the typed, first-class target model — the Python mirror of the Rust ringgrid.target.v6 schema. It expresses hex and rectangular lattices, coded and plain (uncoded) markers, and optional origin fiducials.

import ringgrid

# Presets (geometry comes from the native library — no duplicated constants):
hex_target = ringgrid.TargetLayout.default_hex()        # 15-row coded hex, 203 markers
rect_target = ringgrid.TargetLayout.rect_24x24()   # 24x24 plain rect + origin dots

# One constructor per target-matrix row, all taking plain scalars:
coded_hex = ringgrid.TargetLayout.coded_hex(
    pitch_mm=8.0, rows=15, long_row_cols=14,
    outer_radius_mm=4.8, inner_radius_mm=3.2, ring_width_mm=1.152,
)
coded_rect = ringgrid.TargetLayout.coded_rect(14.0, 20, 20, 4.8, 3.2, 1.152)

# Plain targets take `dots=`: True auto-places a rotation-asymmetric origin-dot
# triad in the lattice gaps (absolute board frame); False omits it (the board is
# then labeled up to lattice symmetry and must be detected completely).
rect_plain = ringgrid.TargetLayout.plain_rect(14.0, 24, 24, 5.6, 2.8, dots=True)
hex_plain = ringgrid.TargetLayout.plain_hex(8.0, 15, 14, 4.8, 3.2, dots=False)

# Dot placement (lattice gaps + rotational-symmetry validation) is computed
# natively — you never hand-author dot coordinates. The full compositional
# constructor mirrors the v6 schema verbatim if you need it:
explicit = ringgrid.TargetLayout(
    name="my_rect",
    lattice=ringgrid.RectGeometry(rows=24, cols=24, pitch_mm=14.0),
    marker=ringgrid.RingGeometry(outer_radius_mm=5.6, inner_radius_mm=2.8),
    coding=ringgrid.Plain(),
)

# Detector / DetectConfig accept a TargetLayout directly:
detector = ringgrid.Detector.from_target(hex_target)
# ...or: ringgrid.Detector(ringgrid.DetectConfig(hex_target))

to_dict() / from_dict() round-trip the v6 schema verbatim; from_json(...) loads v6 (or legacy v5 / v4, auto-migrated) text or a file path; to_spec_json() returns canonical, validated v6 JSON. Invalid geometry raises ValueError with the native error message:

lattice: ringgrid.LatticeGeometry = ringgrid.HexGeometry(15, 14, 8.0)
coding: ringgrid.MarkerCoding = ringgrid.Coded16(ring_width_mm=1.152)

restored = ringgrid.TargetLayout.from_json("target.json")
assert ringgrid.TargetLayout.from_dict(restored.to_dict()) == restored

Features

• Typed TargetLayout (ringgrid.target.v6) — hex/rect lattices, coded/plain markers, origin fiducials
• Native TargetLayout target generation for canonical spec JSON + printable SVG/PNG/DXF
• Native Detector API with NumPy input support
• Slim DetectionResult model objects with JSON round-trips
• Opt-in DetectionDiagnostics channel (detector.detect_with_diagnostics(...)) for per-marker fit/decode internals, edge points, and homography RANSAC stats
• Optional plotting helpers in ringgrid.viz (pip install ringgrid[viz])

Input Rules

• Detector.detect(...) accepts:
  • np.ndarray with dtype=uint8 and shape (H, W) (grayscale)
  • np.ndarray with dtype=uint8 and shape (H, W, 3|4) (RGB/RGBA, auto-converted to grayscale)
  • image file path (str or pathlib.Path)
• Other dtypes/shapes raise TypeError.

Proposal-Only Diagnostics

You can run just the proposal stage and inspect the heatmap used for proposal localization:

import ringgrid
from ringgrid import viz

proposals = ringgrid.propose("photo.png")
diagnostics = ringgrid.propose_with_heatmap("photo.png")

print(len(proposals))
print(diagnostics.heatmap.shape)  # (H, W), float32

viz.plot_proposal_diagnostics(
    image="photo.png",
    diagnostics=diagnostics,
    out="proposal_diagnostics.png",
)

If you want proposal generation to follow the detector's existing scale tuning, use the detector-bound methods instead:

target = ringgrid.TargetLayout.default_hex()
cfg = ringgrid.DetectConfig(target)
detector = ringgrid.Detector(cfg)

diagnostics = detector.propose_with_heatmap("photo.png")

ProposalResult.heatmap is the post-Gaussian-smoothed vote accumulator that the proposal stage uses for thresholding and NMS.

Full tutorial and repo tool workflow:

• Book: Proposal Diagnostics
• python tools/plot_proposal.py --image ... --gt ... --out ...

DetectConfig Field Guide

DetectConfig is the full Python tuning surface for Detector.detect(...), detect_adaptive(...), and detect_multiscale(...).

import ringgrid

target = ringgrid.TargetLayout.default_hex()
cfg = ringgrid.DetectConfig(target)

# Section properties return copies: mutate, then reassign.
decode = cfg.decode
decode.codebook_profile = "extended"
decode.min_decode_margin = 2
cfg.decode = decode

# Or use convenience aliases for common one-field tweaks.
cfg.completion_enable = False
cfg.decode_min_confidence = 0.4

snapshot = cfg.to_dict()
# Stage tuning nests under "advanced" in the wire view.
print(snapshot["advanced"]["decode"]["codebook_profile"])  # "extended"

How Python DetectConfig behaves:

• cfg.target is the constructor input and stays read-only. It is not included in cfg.to_dict().
• cfg.to_dict() returns the resolved native wire view. That is the easiest way to inspect the exact config the Rust detector will use. Its top-level keys are marker_scale, circle_refinement, self_undistort, and advanced; every stage-tuning section (decode, inner_fit, outer_fit, completion, proposal, id_correction, …) lives under the advanced object.
• Section getters such as cfg.decode, cfg.inner_fit, and cfg.self_undistort stay flat on the Python DetectConfig object — they return copies. Reassign the section after editing it, or use a convenience alias such as cfg.decode_min_margin = 2. (The flat Python accessors map onto the nested advanced wire fields automatically.)
• cfg.marker_scale defaults to 14-66 px outer diameter and re-derives the scale-coupled search windows when you replace it.
• Target geometry derives cfg.marker_spec.r_inner_expected and cfg.decode.code_band_ratio. For TargetLayout.default_hex(), those resolve to 0.48809522 and 0.74404764.
• cfg.circle_refinement uses the Python enum ringgrid.CircleRefinementMethod, while cfg.to_dict()["circle_refinement"] stores the native wire strings "ProjectiveCenter" or "None".

Default marker_scale derivations for DetectConfig(TargetLayout.default_hex()) (stage sections shown as nested advanced wire keys):

• advanced.proposal.r_min — spacing-aware, max(0.15 * spacing_min_px, 2.0) -> 3.0310888
• advanced.proposal.r_max — spacing-aware, min(0.45 * spacing_max_px, 1.35 * radius_max_px) -> 42.86825
• advanced.proposal.min_distance — derived from marker spacing and diameter prior
• advanced.edge_sample.r_max = 2.0 * radius_max_px -> 66.0
• advanced.outer_estimation.search_halfwidth_px = max(max((radius_max_px - radius_min_px) * 0.5, 2.0), 13.0) -> 13.0
• advanced.completion.roi_radius_px = clamp(0.75 * nominal_diameter_px, 24.0, 80.0) -> 30.0
• advanced.projective_center.max_correction_shift_px — stays None ("auto"): the gate falls back to the nominal marker diameter (40.0 px here) at use time

Deeper theory and Rust-side derivation details:

• Book: DetectConfig
• Book: MarkerScalePrior

Surface Map

Top-Level Controls

Convenience Aliases

marker_scale

This is the highest-leverage tuning section. Replacing cfg.marker_scale recomputes the scale-coupled defaults in proposal, edge_sample, outer_estimation.search_halfwidth_px, and completion.roi_radius_px; the projective_center.max_correction_shift_px "auto" fallback also tracks it.

If markers span a very wide range, prefer detect_adaptive(...) or detect_multiscale(...) over one very wide marker_scale.

proposal

Controls the first Scharr-gradient voting stage that proposes candidate marker centers before local fitting.

edge_sample

Controls the radial rays used to collect inner and outer edge evidence around a proposal.

outer_estimation

Controls the radial profile stage that predicts an outer radius before the ellipse fit. This stage is cheaper than a full fit, so it is a good place to reject weak hypotheses early.

marker_spec

Describes the expected ring geometry. The target layout drives r_inner_expected, while the remaining fields control radial/theta sampling and coverage checks.

outer_fit

Controls the final outer-ellipse fit. Nested ransac is a ringgrid.RansacFitConfig.

inner_fit

Controls the inner-ellipse fit that refines geometry and influences final confidence. Nested ransac is a ringgrid.RansacFitConfig.

decode

Controls code-band sampling and codebook matching.

Typical decode tuning:

• Too many ambiguous IDs: raise cfg.decode_min_margin or lower cfg.decode_max_dist.
• Good geometry but noisy contrast: lower min_decode_contrast slightly before widening geometry gates.
• Need IDs beyond the stable shipped set: set codebook_profile to "extended" explicitly.

seed_proposals

Controls proposal injection from already-known seed centers during multi-pass or guided workflows.

projective_center

Controls the center-refinement stage used when cfg.circle_refinement == ringgrid.CircleRefinementMethod.PROJECTIVE_CENTER.

completion

Completion tries to recover missing IDs at homography-projected board locations. It only runs when a valid homography is available.

ransac_homography

Controls global homography fitting from decoded markers.

self_undistort

Controls the optional one-parameter division-model self-undistort flow. cfg.self_undistort_enable = True affects Detector.detect(...), but Detector.detect_with_mapper(...) always uses the mapper you pass in instead.

id_correction

Runs after local fit/decode to verify or recover IDs from the board's hex lattice structure.

inner_as_outer_recovery

Post-processing stage that tries to fix markers whose outer fit locked onto the inner ring.

Typical tuning sequence:

• Known scale: tighten cfg.marker_scale before touching low-level proposal thresholds.
• Too many weak IDs: raise cfg.decode_min_confidence or cfg.decode_min_margin.
• Good local fits but unstable global cleanup: tighten cfg.homography_inlier_threshold_px.
• Distorted scenes without calibration: try cfg.self_undistort_enable = True.
• Want direct detections only: set cfg.completion_enable = False.

Adaptive Detection

Use adaptive detection when marker diameter varies substantially across the image (near/far perspective, zoom changes, mixed target scales).

Which Method Should I Use?

Canonical adaptive entry point is:

• Detector.detect_adaptive(image, nominal_diameter_px: float | None = None)

Compatibility alias (deprecated, still supported):

• Detector.detect_adaptive_with_hint(image, nominal_diameter_px=...)

Tier objects:

• ScaleTier(diameter_min_px, diameter_max_px)
• ScaleTiers([...])
• Presets: ScaleTiers.four_tier_wide(), ScaleTiers.two_tier_standard()
• Single-pass equivalent: ScaleTiers.single(MarkerScalePrior(...))

Practical Recipes

Unknown scene scale:

from pathlib import Path
import ringgrid

target = ringgrid.TargetLayout.default_hex()
detector = ringgrid.Detector.from_target(target)
image = Path("testdata/target_3_split_00.png")

result = detector.detect_adaptive(image)

Known nominal diameter (for example, ~32 px):

result = detector.detect_adaptive(image, nominal_diameter_px=32.0)

Inspect tiers used by adaptive logic (debug/repro):

tiers = detector.adaptive_tiers(image, nominal_diameter_px=32.0)
for tier in tiers.tiers:
    print(tier.diameter_min_px, tier.diameter_max_px)

# Re-run exactly those tiers
result = detector.detect_multiscale(image, tiers)

Examples

Run from repository root:

python crates/ringgrid-py/examples/basic_detect.py \
  --image testdata/target_3_split_00.png \
  --out testdata/target_3_split_00_det_py.json

python crates/ringgrid-py/examples/detect_with_camera.py \
  --image testdata/target_3_split_00.png \
  --out testdata/target_3_split_00_det_cam_py.json

python crates/ringgrid-py/examples/detect_adaptive.py \
  --image testdata/target_3_split_00.png \
  --out testdata/target_3_split_00_det_adaptive_py.json

python crates/ringgrid-py/examples/detect_multiscale.py \
  --image testdata/target_3_split_00.png \
  --tiers four_tier_wide \
  --out testdata/target_3_split_00_det_multiscale_py.json

Plotting example:

python crates/ringgrid-py/examples/plot_detection.py \
  --image testdata/target_3_split_00.png \
  --out testdata/target_3_split_00_overlay_py.png