simittag 0.1.0__py3-none-any.whl

marker/generate.py

@@ -0,0 +1,122 @@
+"""
+Render a Simittag marker to a numpy array / PNG.
+
+Geometry and cell ordering come from simittag.spec / simittag.codec, so the image
+is guaranteed consistent with what the detector expects.
+
+Convention (shared with detector): pixel (x=col, y=row); marker centered;
+dx=x-cx, dy=y-cy; theta = atan2(dy, dx) mod 2*pi; sector = floor(theta/step);
+radius normalized so the outer ring's outer edge = 1.0.
+"""
+from __future__ import annotations
+
+import argparse
+import numpy as np
+
+from simittag.spec import MarkerSpec, DEFAULT, VARIANTS
+from simittag import codec, payload as _payload
+
+
+def render(payload: bytes, spec: MarkerSpec = DEFAULT, size: int = 1024,
+           supersample: int = 4, margin: float = 0.12,
+           tile_rows: int = 64, inverted: bool = False) -> np.ndarray:
+    """
+    Return a (size, size) uint8 grayscale image (255=white, 0=black).
+    margin: white quiet-zone fraction added around the marker (radius 1.0).
+    inverted: white marker foreground on a black background.
+    """
+    if size <= 0:
+        raise ValueError("size must be positive")
+    if supersample <= 0:
+        raise ValueError("supersample must be positive")
+    if not (0.0 <= margin < 1.0):
+        raise ValueError("margin must be in [0, 1)")
+    if tile_rows <= 0:
+        raise ValueError("tile_rows must be positive")
+
+    grid = codec.encode(payload, spec)
+    S = size * supersample
+    # radius 1.0 maps to (1 - margin) of the half-extent, leaving a quiet border
+    cx = cy = (S - 1) / 2.0
+    R_px = (S / 2.0) * (1.0 - margin)
+
+    # Work in horizontal tiles. The original full-frame implementation kept
+    # several SxS float64 arrays alive together and peaked around 1.4 GB RSS at
+    # the default 1024x / 4x supersampling. A binary supersample is only SxS
+    # bytes; temporary coordinate arrays are bounded by tile_rows x S.
+    img = np.full((S, S), 255, dtype=np.uint8)
+    dx = (np.arange(S, dtype=np.float64)[None, :] - cx) / R_px
+    step = 2 * np.pi / spec.SECTOR_COUNT
+    ring_w = (spec.R_DATA_OUT - spec.R_DATA_IN) / spec.RING_COUNT
+
+    for y0 in range(0, S, tile_rows):
+        y1 = min(S, y0 + tile_rows)
+        dy = (np.arange(y0, y1, dtype=np.float64)[:, None] - cy) / R_px
+        r = np.sqrt(dx * dx + dy * dy)
+        theta = np.mod(np.arctan2(dy, dx), 2 * np.pi)
+        tile = img[y0:y1]
+
+        # outer ring and bullseye
+        tile[(r >= spec.R_RING_IN) & (r <= 1.0)] = 0
+        tile[r <= spec.R_BULLSEYE] = 0
+
+        # data cells
+        data_mask = (r >= spec.R_DATA_IN) & (r < spec.R_DATA_OUT)
+        ring_idx = np.clip(((r - spec.R_DATA_IN) / ring_w).astype(int),
+                           0, spec.RING_COUNT - 1)
+        sec_idx = np.clip((theta / step).astype(int), 0, spec.SECTOR_COUNT - 1)
+        cell_val = grid[ring_idx, sec_idx]  # 1 => black
+        tile[data_mask & (cell_val == 1)] = 0
+
+    # downsample (anti-alias)
+    result = img.reshape(size, supersample, size, supersample).mean(axis=(1, 3)).astype(np.uint8)
+    return 255 - result if inverted else result
+
+
+def save_png(arr: np.ndarray, path: str):
+    # OpenCV is already a detector dependency; using it here avoids making
+    # Pillow an undeclared generation-only dependency.
+    import cv2
+    if not cv2.imwrite(path, arr):
+        raise OSError(f"could not write PNG: {path}")
+
+
+def _parse_payload(s: str, n: int) -> bytes:
+    if s.startswith("0x"):
+        v = int(s, 16)
+        return v.to_bytes(n, "big")
+    b = s.encode()
+    if len(b) > n:
+        raise ValueError(f"payload string too long ({len(b)} > {n} bytes)")
+    return b.ljust(n, b"\x00")
+
+
+if __name__ == "__main__":
+    ap = argparse.ArgumentParser(description="Render a Simittag marker")
+    ap.add_argument("--variant", default="M", choices=list(VARIANTS),
+                    help="T=tracking 3x16, M=balanced 4x24, D=data 5x36")
+    ap.add_argument("--id", type=lambda s: int(s, 0), default=None,
+                    help="ID-mode integer (e.g. 0x1234); fills the payload")
+    ap.add_argument("--payload", default=None,
+                    help="raw payload: hex (0x...) or text (fills payload bytes)")
+    ap.add_argument("--out", default="marker.png")
+    ap.add_argument("--size", type=int, default=1024)
+    ap.add_argument("--inverted", action="store_true",
+                    help="render white foreground on a black background")
+    args = ap.parse_args()
+
+    sp = VARIANTS[args.variant]
+    if args.payload is not None:
+        payload = _parse_payload(args.payload, sp.payload_bytes)
+        desc = f"payload={payload.hex()}"
+    else:
+        # default to an ID so every variant has a sensible no-arg render
+        idval = args.id if args.id is not None else 0x1234
+        payload = _payload.encode_id(idval, sp)
+        desc = f"id=0x{idval:x}"
+    arr = render(payload, sp, size=args.size, inverted=args.inverted)
+    save_png(arr, args.out)
+    # confirm it decodes from its own grid (sanity, not validation)
+    back, _ = codec.decode(codec.encode(payload, sp), sp)
+    print(f"wrote {args.out} ({args.size}x{args.size}) variant={sp.NAME} {desc} "
+          f"self-decode={'OK' if back == payload else 'FAIL'}")

marker/svg.py

@@ -0,0 +1,159 @@
+"""
+Vector (SVG) renderer for Simittag markers, for clean printing at an exact physical
+size. Geometry matches marker/generate.py (the raster renderer) cell-for-cell, which
+in turn matches the detector's sampling convention (simittag.spec / simittag.codec):
+
+  angle:  theta = atan2(y, x) in screen coords (y DOWN), sector s spans [s*step,(s+1)*step)
+  radius: normalized so the outer ring's outer edge = 1.0
+  ring r spans [R_DATA_IN + r*ring_w, R_DATA_IN + (r+1)*ring_w), grid[r,s]==1 => black
+
+Painter's order (no even-odd needed): white bg -> black outer disk -> white disk at
+R_RING_IN (carves the ring) -> black bullseye -> black data cells.
+"""
+from __future__ import annotations
+import math
+
+from simittag.spec import MarkerSpec, DEFAULT
+from simittag import codec
+
+
+def _pt(cx, cy, rho, ang, R):
+    return (cx + R * rho * math.cos(ang), cy + R * rho * math.sin(ang))
+
+
+def _sector_path(cx, cy, ri, ro, a0, a1, R):
+    """Annular-sector path (one data cell), radii normalized, angles in radians."""
+    x0o, y0o = _pt(cx, cy, ro, a0, R)
+    x1o, y1o = _pt(cx, cy, ro, a1, R)
+    x1i, y1i = _pt(cx, cy, ri, a1, R)
+    x0i, y0i = _pt(cx, cy, ri, a0, R)
+    Ro, Ri = ro * R, ri * R
+    return (f"M{x0o:.3f},{y0o:.3f} A{Ro:.3f},{Ro:.3f} 0 0 1 {x1o:.3f},{y1o:.3f} "
+            f"L{x1i:.3f},{y1i:.3f} A{Ri:.3f},{Ri:.3f} 0 0 0 {x0i:.3f},{y0i:.3f} Z")
+
+
+def marker_svg_body(grid, spec: MarkerSpec, cx, cy, R):
+    """SVG element string for one marker centered at (cx,cy) with outer radius R (units)."""
+    step = 2 * math.pi / spec.SECTOR_COUNT
+    ring_w = (spec.R_DATA_OUT - spec.R_DATA_IN) / spec.RING_COUNT
+    out = []
+    # black outer disk, then white disk to leave the outer ring annulus
+    out.append(f'<circle cx="{cx}" cy="{cy}" r="{R:.3f}" fill="#000"/>')
+    out.append(f'<circle cx="{cx}" cy="{cy}" r="{R*spec.R_RING_IN:.3f}" fill="#fff"/>')
+    # bullseye
+    out.append(f'<circle cx="{cx}" cy="{cy}" r="{R*spec.R_BULLSEYE:.3f}" fill="#000"/>')
+    # data cells
+    paths = []
+    for ring in range(spec.RING_COUNT):
+        ri = spec.R_DATA_IN + ring * ring_w
+        ro = ri + ring_w
+        for s in range(spec.SECTOR_COUNT):
+            if grid[ring, s] == 1:
+                paths.append(_sector_path(cx, cy, ri, ro, s * step, (s + 1) * step, R))
+    if paths:
+        out.append(f'<path d="{" ".join(paths)}" fill="#000"/>')
+    return "\n".join(out)
+
+
+def marker_svg(payload: bytes, spec: MarkerSpec = DEFAULT, size_mm: float = 40.0,
+               margin: float = 0.12, label: str = None) -> str:
+    """
+    Standalone SVG (sized in mm) for one marker. `size_mm` is the marker diameter
+    (the outer ring's outer edge); a white quiet zone of `margin` is added around it.
+    Optional `label` text is drawn under the quiet zone.
+    """
+    grid = codec.encode(payload, spec)
+    R = size_mm / 2.0
+    pad = R * margin
+    W = size_mm + 2 * pad
+    cx = cy = W / 2.0
+    label_h = max(3.0, size_mm * 0.10) if label else 0.0
+    H = W + label_h
+    parts = [
+        f'<svg xmlns="http://www.w3.org/2000/svg" width="{W:.2f}mm" height="{H:.2f}mm" '
+        f'viewBox="0 0 {W:.3f} {H:.3f}">',
+        f'<rect x="0" y="0" width="{W:.3f}" height="{H:.3f}" fill="#fff"/>',
+        marker_svg_body(grid, spec, cx, cy, R),
+    ]
+    if label:
+        fs = label_h * 0.62
+        parts.append(
+            f'<text x="{cx:.3f}" y="{W + label_h*0.72:.3f}" font-family="monospace" '
+            f'font-size="{fs:.2f}" text-anchor="middle" fill="#000">{_esc(label)}</text>')
+    parts.append("</svg>")
+    return "\n".join(parts)
+
+
+def _esc(s):
+    return (str(s).replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;"))
+
+
+# ---- printable sheet ----
+PAGES_MM = {"A4": (210.0, 297.0), "Letter": (215.9, 279.4)}
+
+
+def sheet_svg(items, page="A4", size_mm=40.0, margin_mm=12.0, gap_mm=8.0,
+              cut_marks=True):
+    """
+    Lay markers out on a printable page (SVG sized in mm). `items` = list of
+    (payload_bytes, spec, label). Auto-flows into a grid; returns one SVG string.
+    Print at 100% scale (no fit-to-page) for the physical size to be exact.
+    """
+    pw, ph = PAGES_MM.get(page, PAGES_MM["A4"])
+    cell = size_mm * 1.12  # marker + its 12% quiet zone
+    label_h = max(3.0, size_mm * 0.10)
+    cell_h = cell + label_h + gap_mm
+    cell_w = cell + gap_mm
+    cols = max(1, int((pw - 2 * margin_mm + gap_mm) // cell_w))
+    rows = max(1, int((ph - 2 * margin_mm + gap_mm) // cell_h))
+    per_page = cols * rows
+
+    parts = [
+        f'<svg xmlns="http://www.w3.org/2000/svg" width="{pw}mm" height="{ph}mm" '
+        f'viewBox="0 0 {pw} {ph}">',
+        f'<rect x="0" y="0" width="{pw}" height="{ph}" fill="#fff"/>',
+    ]
+    # only the first page (browsers print one SVG page; multi-page is a future nicety)
+    for i, (payload, spec, label) in enumerate(items[:per_page]):
+        r, c = divmod(i, cols)
+        x0 = margin_mm + c * cell_w
+        y0 = margin_mm + r * cell_h
+        grid = codec.encode(payload, spec)
+        R = size_mm / 2.0
+        cx = x0 + cell / 2.0
+        cy = y0 + cell / 2.0
+        if cut_marks:
+            parts.append(_cut_marks(x0, y0, cell, cell))
+        parts.append(f'<g>{marker_svg_body(grid, spec, cx, cy, R)}</g>')
+        fs = label_h * 0.6
+        parts.append(
+            f'<text x="{cx:.3f}" y="{y0 + cell + label_h*0.7:.3f}" '
+            f'font-family="monospace" font-size="{fs:.2f}" text-anchor="middle" '
+            f'fill="#000">{_esc(label)}</text>')
+    extra = max(0, len(items) - per_page)
+    if extra:
+        parts.append(
+            f'<text x="{pw/2:.1f}" y="{ph-4:.1f}" font-family="monospace" '
+            f'font-size="3.5" text-anchor="middle" fill="#888">'
+            f'+{extra} more (reduce size or count to fit one page)</text>')
+    parts.append("</svg>")
+    return "\n".join(parts)
+
+
+def _cut_marks(x, y, w, h, m=2.0):
+    L = []
+    for (px, py, dx, dy) in [(x, y, 1, 0), (x, y, 0, 1),
+                             (x + w, y, -1, 0), (x + w, y, 0, 1),
+                             (x, y + h, 1, 0), (x, y + h, 0, -1),
+                             (x + w, y + h, -1, 0), (x + w, y + h, 0, -1)]:
+        L.append(f'<line x1="{px:.2f}" y1="{py:.2f}" x2="{px+dx*m:.2f}" '
+                 f'y2="{py+dy*m:.2f}" stroke="#bbb" stroke-width="0.2"/>')
+    return "".join(L)
+
+
+if __name__ == "__main__":
+    from simittag import payload as _p
+    svg = marker_svg(_p.encode_id(0x1234, DEFAULT), DEFAULT, size_mm=40,
+                     label="SIMITTAG-M 0x1234")
+    open("/tmp/marker.svg", "w").write(svg)
+    print("wrote /tmp/marker.svg", len(svg), "bytes")

simittag/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

simittag/board.py

@@ -0,0 +1,159 @@
+"""
+Calibration board definitions.
+
+A board is a set of markers at known planar positions (mm), used to solve for
+camera intrinsics (see simittag.calibrate). Board coordinates: origin at the
+center of tag 0 (top-left), x right, y down — matching image conventions.
+
+Boards are self-describing: each printed sheet carries one D-variant tag whose
+RAW payload encodes the board parameters, so the calibrator can configure
+itself from the sheet alone. The studio (web/) also writes a JSON sidecar with
+explicit per-tag positions; when available it is the preferred source of truth
+(it also locates the descriptor tag itself, adding one more point per view).
+
+Descriptor RAW payload (8 bytes, version 1):
+
+  [0] version (1)
+  [1] family  (1 = grid, 2 = multiscale)
+  [2:4] pitch  in 0.1 mm, big-endian   (grid: cell pitch; multiscale: frame step)
+  [4:6] tag diameter in 0.1 mm, big-endian
+  [6] rows    (grid: rows; multiscale: side tags per column)
+  [7] cols    (grid: cols; multiscale: tags per top/bottom row)
+
+Layout algorithms per family are frozen here and mirrored in web/js/calib.js;
+a descriptor fully determines every tag position.
+"""
+from __future__ import annotations
+import json
+from dataclasses import dataclass, field
+
+DESCRIPTOR_VERSION = 1
+FAMILY_GRID = 1
+FAMILY_MULTISCALE = 2
+FAMILY_NAMES = {FAMILY_GRID: "grid", FAMILY_MULTISCALE: "multiscale"}
+
+# multiscale layout constants (frozen, v1): the center anchor is an M tag with
+# this id, ANCHOR_RATIO times the perimeter tag diameter; side tags are spaced
+# SIDE_STEP_RATIO times the top/bottom step.
+MULTISCALE_ANCHOR_ID = 500
+ANCHOR_RATIO = 3.5
+SIDE_STEP_RATIO = 1.6
+
+
+@dataclass
+class BoardTag:
+    """One marker at a known board position (center, mm)."""
+    variant: str          # "T" | "M" | "D"
+    mode: str             # "ID" | "RAW"
+    value: object         # int for ID, bytes for RAW
+    x_mm: float
+    y_mm: float
+    diameter_mm: float
+
+
+@dataclass
+class Board:
+    family: int
+    pitch_mm: float
+    diameter_mm: float
+    rows: int
+    cols: int
+    tags: list = field(default_factory=list)   # [BoardTag]
+
+    def point_for(self, variant, mode, value):
+        """Board (x, y) for a detection, or None if it is not on this board."""
+        for t in self.tags:
+            if t.variant == variant and t.mode == mode and t.value == value:
+                return (t.x_mm, t.y_mm)
+        return None
+
+    @property
+    def descriptor_raw(self) -> bytes:
+        return pack_descriptor(self.family, self.pitch_mm, self.diameter_mm,
+                               self.rows, self.cols)
+
+
+def pack_descriptor(family, pitch_mm, diameter_mm, rows, cols) -> bytes:
+    p, d = round(pitch_mm * 10), round(diameter_mm * 10)
+    if not (0 < p < 65536 and 0 < d < 65536 and 0 < rows < 256 and 0 < cols < 256):
+        raise ValueError("board parameters out of descriptor range")
+    return bytes([DESCRIPTOR_VERSION, family, p >> 8, p & 0xFF,
+                  d >> 8, d & 0xFF, rows, cols])
+
+
+def unpack_descriptor(raw: bytes) -> dict:
+    if len(raw) < 8 or raw[0] != DESCRIPTOR_VERSION:
+        raise ValueError(f"not a v{DESCRIPTOR_VERSION} board descriptor")
+    family = raw[1]
+    if family not in FAMILY_NAMES:
+        raise ValueError(f"unknown board family {family}")
+    return {"family": family,
+            "pitch_mm": ((raw[2] << 8) | raw[3]) / 10.0,
+            "diameter_mm": ((raw[4] << 8) | raw[5]) / 10.0,
+            "rows": raw[6], "cols": raw[7]}
+
+
+def grid_board(pitch_mm, diameter_mm, rows, cols) -> Board:
+    """Uniform rows x cols grid of ID tags, row-major ids from 0.
+    Variant T while ids fit in one byte, M beyond."""
+    variant = "T" if rows * cols <= 256 else "M"
+    b = Board(FAMILY_GRID, pitch_mm, diameter_mm, rows, cols)
+    for i in range(rows * cols):
+        b.tags.append(BoardTag(variant, "ID", i,
+                               (i % cols) * pitch_mm, (i // cols) * pitch_mm,
+                               diameter_mm))
+    return b
+
+
+def multiscale_board(step_mm, diameter_mm, side_rows, top_cols) -> Board:
+    """Perimeter frame of small T tags + one large M anchor in the center.
+    Top and bottom rows have `top_cols` tags at `step_mm` pitch; each side has
+    `side_rows` tags between them at SIDE_STEP_RATIO * step_mm pitch."""
+    b = Board(FAMILY_MULTISCALE, step_mm, diameter_mm, side_rows, top_cols)
+    w = (top_cols - 1) * step_mm
+    sstep = step_mm * SIDE_STEP_RATIO
+    h = (side_rows + 1) * sstep
+    i = 0
+    for c in range(top_cols):                        # top + bottom rows
+        b.tags.append(BoardTag("T", "ID", i, c * step_mm, 0.0, diameter_mm)); i += 1
+        b.tags.append(BoardTag("T", "ID", i, c * step_mm, h, diameter_mm)); i += 1
+    for r in range(1, side_rows + 1):                # left + right columns
+        b.tags.append(BoardTag("T", "ID", i, 0.0, r * sstep, diameter_mm)); i += 1
+        b.tags.append(BoardTag("T", "ID", i, w, r * sstep, diameter_mm)); i += 1
+    b.tags.append(BoardTag("M", "ID", MULTISCALE_ANCHOR_ID,
+                           w / 2.0, h / 2.0, diameter_mm * ANCHOR_RATIO))
+    return b
+
+
+def board_from_descriptor(raw: bytes) -> Board:
+    d = unpack_descriptor(raw)
+    if d["family"] == FAMILY_GRID:
+        return grid_board(d["pitch_mm"], d["diameter_mm"], d["rows"], d["cols"])
+    return multiscale_board(d["pitch_mm"], d["diameter_mm"], d["rows"], d["cols"])
+
+
+def load_board(path) -> Board:
+    """Load a studio JSON sidecar (explicit tag positions, preferred)."""
+    j = json.load(open(path))
+    if j.get("simittag_board") != 1:
+        raise ValueError(f"{path} is not a simittag board file")
+    family = {v: k for k, v in FAMILY_NAMES.items()}[j["family"]]
+    b = Board(family, j["pitch_mm"], j["diameter_mm"], j["rows"], j["cols"])
+    for t in j["tags"]:
+        value = t["value"]
+        if t["mode"] == "RAW":
+            value = bytes.fromhex(value)
+        b.tags.append(BoardTag(t["variant"], t["mode"], value,
+                               t["x_mm"], t["y_mm"], t["diameter_mm"]))
+    return b
+
+
+def find_board(detections) -> Board | None:
+    """Reconstruct the board from a descriptor tag among detections, if any."""
+    for r in detections:
+        if r["variant"] == "D" and r["mode"] == "RAW":
+            try:
+                return board_from_descriptor(bytes(r["value"]))
+            except ValueError:
+                continue
+    return None

simittag/calibrate.py

@@ -0,0 +1,129 @@
+"""
+Camera calibration from simittag boards (see simittag.board).
+
+The intrinsics contract mirrors AprilTag's apriltag_detection_info_t: fx, fy,
+cx, cy in pixels (aprilrobotics/apriltag, apriltag_pose.h) — plus the OpenCV
+distortion vector, which AprilTag leaves to the caller. detect.detect() takes
+the same parameters as `K=` / `dist=`; feeding it a saved CameraIntrinsics
+replaces the default 60-degree-FOV guess with measured values, which is what
+turns the reported poses from approximate into metric.
+
+Usage:
+    intr = calibrate_images(["a.png", "b.png", ...])       # board from sheet
+    intr.save("intrinsics.json")
+    ...
+    intr = CameraIntrinsics.load("intrinsics.json")
+    detect.detect(gray, K=intr.K, dist=intr.dist_array)
+"""
+from __future__ import annotations
+import json
+from dataclasses import dataclass, field
+
+import numpy as np
+import cv2
+
+from . import detect as _detect
+from . import board as _board
+
+MIN_POINTS_PER_VIEW = 6
+MIN_VIEWS = 4
+
+
+@dataclass
+class CameraIntrinsics:
+    """Pinhole intrinsics, AprilTag field convention (pixels) + distortion."""
+    fx: float
+    fy: float
+    cx: float
+    cy: float
+    dist: list = field(default_factory=list)   # OpenCV k1 k2 p1 p2 k3
+    width: int = 0
+    height: int = 0
+    rms_px: float = 0.0                        # calibration reprojection RMS
+    views: int = 0
+
+    @property
+    def K(self) -> np.ndarray:
+        return np.array([[self.fx, 0, self.cx],
+                         [0, self.fy, self.cy],
+                         [0, 0, 1]], dtype=np.float64)
+
+    @property
+    def dist_array(self) -> np.ndarray:
+        return np.array(self.dist, dtype=np.float64)
+
+    def save(self, path):
+        json.dump({"simittag_intrinsics": 1, **self.__dict__},
+                  open(path, "w"), indent=2)
+
+    @classmethod
+    def load(cls, path) -> "CameraIntrinsics":
+        j = json.load(open(path))
+        if j.pop("simittag_intrinsics", None) != 1:
+            raise ValueError(f"{path} is not a simittag intrinsics file")
+        return cls(**j)
+
+
+def _view_points(detections, board):
+    """Match one image's detections against the board -> (obj Nx3, img Nx2)."""
+    obj, img = [], []
+    for r in detections:
+        value = r["value"]
+        if r["mode"] == "RAW":
+            value = bytes(value)
+        pt = board.point_for(r["variant"], r["mode"], value)
+        if pt is not None:
+            obj.append([pt[0], pt[1], 0.0])
+            img.append(r["center"])
+    return (np.array(obj, dtype=np.float32),
+            np.array(img, dtype=np.float32))
+
+
+def calibrate(images, board=None, versions=None) -> CameraIntrinsics:
+    """
+    Solve intrinsics (Zhang's method via cv2.calibrateCamera) from grayscale
+    images of a simittag calibration board. If `board` is None it is
+    reconstructed from the descriptor tag found on the sheet.
+    """
+    obj_pts, img_pts = [], []
+    size = None
+    for gray in images:
+        if size is None:
+            size = (gray.shape[1], gray.shape[0])
+        elif size != (gray.shape[1], gray.shape[0]):
+            raise ValueError("all calibration images must share one resolution")
+        dets = _detect.detect(gray, versions=versions)
+        if board is None:
+            board = _board.find_board(dets)
+        if board is None:
+            continue
+        obj, img = _view_points(dets, board)
+        if len(obj) >= MIN_POINTS_PER_VIEW:
+            obj_pts.append(obj)
+            img_pts.append(img)
+    if board is None:
+        raise ValueError("no board descriptor found — pass board= or use a "
+                         "sheet with a descriptor tag")
+    if len(obj_pts) < MIN_VIEWS:
+        raise ValueError(f"only {len(obj_pts)} usable view(s) "
+                         f"(>= {MIN_POINTS_PER_VIEW} board tags each); "
+                         f"need at least {MIN_VIEWS}")
+    rms, K, dist, _rvecs, _tvecs = cv2.calibrateCamera(
+        obj_pts, img_pts, size, None, None)
+    return CameraIntrinsics(
+        fx=float(K[0, 0]), fy=float(K[1, 1]),
+        cx=float(K[0, 2]), cy=float(K[1, 2]),
+        dist=[float(v) for v in dist.ravel()],
+        width=size[0], height=size[1],
+        rms_px=float(rms), views=len(obj_pts))
+
+
+def calibrate_images(paths, board=None, versions=None) -> CameraIntrinsics:
+    """calibrate() over image files."""
+    images = []
+    for p in paths:
+        gray = cv2.imread(str(p), cv2.IMREAD_GRAYSCALE)
+        if gray is None:
+            raise ValueError(f"cannot read {p}")
+        images.append(gray)
+    return calibrate(images, board=board, versions=versions)

simittag/cli.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""
+Simittag command line: encode a payload to a marker, decode an image,
+or solve camera intrinsics from calibration-sheet photos.
+
+  simittag encode --id 12345 --out marker.png
+  simittag encode --raw "hi" --out marker.png
+  simittag decode image.png
+  simittag calibrate img1.png img2.png ... --out intrinsics.json
+  simittag decode image.png --intrinsics intrinsics.json
+"""
+from __future__ import annotations
+import argparse
+import cv2
+
+from simittag.spec import VARIANTS
+from simittag import payload, detect
+from simittag import board as board_mod
+from simittag.calibrate import CameraIntrinsics, calibrate_images
+from marker.generate import render as render_marker, save_png
+
+
+def cmd_encode(a):
+    sp = VARIANTS[a.variant]
+    if a.id is not None:
+        pl = payload.encode_id(a.id, sp)
+    elif a.raw is not None:
+        data = bytes.fromhex(a.raw[2:]) if a.raw.startswith("0x") else a.raw.encode()
+        pl = payload.encode_raw(data, sp)
+    else:
+        raise SystemExit("give --id or --raw")
+    arr = render_marker(pl, sp, size=a.size, inverted=a.inverted)
+    save_png(arr, a.out)
+    print(f"wrote {a.out}  payload={pl.hex()}  decode={payload.decode(pl, sp)}")
+
+
+def cmd_decode(a):
+    gray = cv2.imread(a.image, cv2.IMREAD_GRAYSCALE)
+    if gray is None:
+        raise SystemExit(f"cannot read {a.image}")
+    versions = None if a.variant == "auto" else a.variant
+    K = dist = None
+    if a.intrinsics:
+        intr = CameraIntrinsics.load(a.intrinsics)
+        K, dist = intr.K, intr.dist_array
+    res = detect.detect(gray, versions=versions, K=K, dist=dist)
+    if not res:
+        print("no marker decoded")
+        return
+    for r in res:
+        polarity = "white-on-black" if r["inverted"] else "black-on-white"
+        print(f"  {r['variant']} {r['mode']}={r['value']}  "
+              f"center=({r['center'][0]:.0f},{r['center'][1]:.0f})  "
+              f"tilt={r['tilt_deg']:.1f}deg  {polarity}")
+
+
+def cmd_calibrate(a):
+    board = board_mod.load_board(a.board) if a.board else None
+    intr = calibrate_images(a.images, board=board)
+    intr.save(a.out)
+    print(f"wrote {a.out}")
+    print(f"  fx={intr.fx:.1f} fy={intr.fy:.1f} cx={intr.cx:.1f} cy={intr.cy:.1f}")
+    print(f"  dist={['%.4f' % v for v in intr.dist]}")
+    print(f"  {intr.views} views, reprojection rms {intr.rms_px:.3f} px")
+
+
+def main():
+    ap = argparse.ArgumentParser(prog="simittag")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    e = sub.add_parser("encode")
+    e.add_argument("--variant", choices=VARIANTS, default="M")
+    source = e.add_mutually_exclusive_group(required=True)
+    source.add_argument("--id", type=lambda s: int(s, 0))
+    source.add_argument("--raw")
+    e.add_argument("--out", default="marker.png")
+    e.add_argument("--size", type=int, default=1024)
+    e.add_argument("--inverted", action="store_true")
+    e.set_defaults(fn=cmd_encode)
+    d = sub.add_parser("decode")
+    d.add_argument("image")
+    d.add_argument("--variant", choices=("auto", *VARIANTS), default="auto")
+    d.add_argument("--intrinsics", help="intrinsics.json from `calibrate` "
+                   "(replaces the default 60-degree-FOV guess)")
+    d.set_defaults(fn=cmd_decode)
+    c = sub.add_parser("calibrate",
+                       help="solve camera intrinsics from calibration-sheet photos")
+    c.add_argument("images", nargs="+")
+    c.add_argument("--board", help="board JSON from the studio (default: "
+                   "reconstruct from the sheet's descriptor tag)")
+    c.add_argument("--out", default="intrinsics.json")
+    c.set_defaults(fn=cmd_calibrate)
+    args = ap.parse_args()
+    args.fn(args)
+
+
+if __name__ == "__main__":
+    main()