Extensions, Tooling and Internals
The rest of the public surface: the functions the package extensions provide (plots, the Python interface, the Lux backend, training), the pipeline's configuration and stages, traces, and the training-data tooling. Each name is reached as BlobBoards.name unless it is exported.
BlobBoards.BlobBoards — Module
BlobBoardsGenerate calibration boards with blob patterns for computer vision applications.
Quick Start
using BlobBoards # units (mm, px, dpi, …) are re-exported# Generate a PDF board with standard paper sizebundle = blob_board("A4"; blob_sizes=(4.0mm, 0.2short_side), cutoff=2.0, seed=0x1234, dir="./output")# Generate a pattern with logical dimensionspattern, blobs, config = blob_pattern(800, 600; blob_sizes=(12px, nothing), cutoff=2.0, seed=0x1234)# Extract blobs from saved filesbundle, _ = BlobBoards.load(BlobBoards.BoardBundle, "blob_board.json")b = blobs(bundle, :pattern; units=mm) # Physical unitsb = blobs(bundle, :canvas; density = 300dpi) # Pixel units, at a densityKey Interface Notes
blob_board:blob_sizes = (min, max)are printed disc diameters in physical units, both required (e.g.,suggest_blob_sizes(600dpi, "A4"), or(6mm, 38mm)); stored as σ in pointsblob_pattern:blob_sizes = (min, max)are disc diameters in logical units (e.g.,(12px, nothing))blobs(bundle, reference_frame; units=px, density): Extract blobs with specified frame and units
Coordinate Specifications
BlobBoards uses three types of coordinate specifications:
- Image origins (
:colmap,:opencv,:julia): Pixel coordinate conventions - Reference frames (
:pattern,:board,:canvas): Spatial origins on boards - Coordinate systems (
:pixel,:physical,:world): Unit systems for transforms
Blobs are stored internally in :colmap convention. Use EuclideanMap(PixelFrame{:colmap}, PixelFrame{:julia}) to convert.
Features
- Deterministic patterns from seeded configurations
- Physical units via FlexUnits (mm, inch, dpi, etc.)
- Printable boards (PDF) or training images (PNG) with ruler or blank frames
- JSON serialization for exact reproduction
- Blob extraction with multiple coordinate conventions and reference frames
- World coordinates for 3D pose workflows
- Visualization helpers for Makie backends
- Bit-exact reproducibility across Julia and Python interfaces
Plots (BlobBoardsMakieExt)
Loaded by any Makie backend: pkg> add BlobBoards CairoMakie, then using BlobBoards, CairoMakie. Without one, each raises an error naming that line.
BlobBoards.board — Function
Non-mutating form of board!. Requires a Makie backend.
BlobBoards.board! — Function
board!(ax, proj, rect, blobs; cutoff)Project a board's world rect + blobs into an image axis. Requires a Makie backend (BlobBoardsMakieExt).
BlobBoards.plot_boards — Function
plot_boards(camera, results, board_bundles, img; n = min(10, length(results)), lens = true)Plot a grid of accepted find_boards results. Requires a Makie backend.
BlobBoards.plot_board_poses — Function
Overlay (uid, pose) pairs on one image axis — for poses reloaded from disk. Requires a Makie backend.
BlobBoards.board_overlay! — Function
Paint boards — accepted find_boards results or (uid, model) pairs — onto an existing axis. Requires a Makie backend.
BlobBoards.inliers! — Function
Paint a result set's inlier ellipses onto an existing axis, batched into one ellipses! call. Requires a Makie backend.
BlobBoards.board_panel! — Function
Paint one find_boards result into a figure position: image, title, board overlay. Requires a Makie backend.
BlobBoards.plot_comparison — Function
Compare labelled find_boards result sets side by side, one panel each, on ONE shared palette. Requires a Makie backend.
BlobBoards.replay — Function
Scrub through a TrackTrace interactively. Requires GLMakie.
BlobBoards.inspect_pipeline — Function
inspect_pipeline(trace::PipelineTrace; region=nothing) -> FigureLinked-axes inspection grid: column 1 = raw detections over the detector image; per adaptation arm, one column of fitted frames and one of the post-filter survivors. Pan/zoom is synchronized across every panel. region = (xrange, yrange) crops the initial view.
Implemented in BlobBoardsMakieExt (needs a Makie backend).
BlobBoards.plot_annotations — Function
plot_annotations(sets; max_blobs=20, max_obs=10) -> FigureVisualize CorrespondenceSets as a grid. Each row is one blob: first column is the reference patch (from board PDF), then a gap, then observation columns (from camera images). Rows sorted by number of observations (most first).
plot_annotations(sets) # top 20 blobsplot_annotations(sets; max_blobs=5, max_obs=20) # fewer blobs, more obsplot_annotations(load_correspondence_sets("annotations/")) # directory of per-image JLD2sRequires a Makie backend (BlobBoardsMakieExt).
BlobBoards.view_angle_figure — Function
view_angle_figure(stats; edges=VIEW_ANGLE_EDGES, title, size) -> Makie.FigureChart the average detections per board against viewing obliquity: mean matched blobs per board-frame, recall against the board's visible GT blobs, and the per-bin board-frame support. Requires a Makie backend (BlobBoardsMakieExt).
BlobBoards.save_view_angle_figure — Function
save_view_angle_figure(path, stats; kwargs...) -> pathRender view_angle_figure and write it to path; the extension picks the format (.png, .svg, .pdf). Requires a Makie backend that can save — using CairoMakie is the headless choice. Keyword arguments are forwarded to view_angle_figure.
BlobBoards.board_palette — Function
board_palette(uids) -> Dict{String, Color}One stable color per board id.
The colors are deterministic over the SORTED unique id list — the same board gets the same color in every image, every sweep, every call site (sweep overlays, plot_board_poses, training overlays; this replaced three palettes with three different stability conventions). Seeded against white AND black so nothing produced is invisible on a light or a dark image.
BlobBoards.board_quad — Function
board_quad(camera_or_nothing, model, bundle::BoardBundle) -> GeometryBasics.PolygonProject a board's world-coordinate bounding rectangle into the image.
The rectangle goes through the estimated model; this is the ONE place the model→image quad is built (spatial suppression, feature claiming, agenda claim masks all share it). Homography path (camera === nothing): model IS the world→image H. Pose path: the VGC PosedCamera composes pose + intrinsics. bundle is typed so a call in the retired (camera, bundle, model) order is a MethodError.
Python interface (BlobBoardsPythonExt)
The Julia side of the blobboards Python package, loaded with PythonCall.
BlobBoards.blob_pattern_python — Function
blob_pattern_python(width, height; blob_sizes, seed, cutoff, dir, …)The Julia side of the Python package's blobboards.blob_pattern.
It is blob_pattern for arguments as Python objects — Python numbers or pint lengths (bare numbers: pixels) — returning Python dicts and numpy arrays, with every pixel coordinate in the stated pixel_frame convention. Its method is defined by BlobBoardsPythonExt, which loads with PythonCall (the Python package's Julia side); call it from Python, see docs/src/guide/python.md. Without PythonCall the call raises an error naming the install line.
BlobBoards.blob_board_python — Function
blob_board_python(canvas_size; blob_sizes, seed, margin, board_size, …, dir, format, density, …)The Julia side of the Python package's blobboards.blob_board.
It is blob_board for arguments as Python objects — a paper name, or Python numbers / pint lengths (bare numbers: mm) — returning Python dicts and numpy arrays, with every pixel coordinate in the stated pixel_frame convention. Its method is defined by BlobBoardsPythonExt, which loads with PythonCall (the Python package's Julia side); call it from Python, see docs/src/guide/python.md. Without PythonCall the call raises an error naming the install line.
BlobBoards.blobs_python — Function
blobs_python(json_path; units = "px", reference_frame = "pattern", pixel_frame = "colmap", density = nothing)The Julia side of the Python package's blobboards.blobs.
It is blobs for arguments as Python objects — a pattern or board JSON path — returning Python dicts and numpy arrays, with every pixel coordinate in the stated pixel_frame convention. Its method is defined by BlobBoardsPythonExt, which loads with PythonCall (the Python package's Julia side); call it from Python, see docs/src/guide/python.md. Without PythonCall the call raises an error naming the install line.
BlobBoards.detect_blobs_python — Function
detect_blobs_python(img; peak_threshold = 0.01, edge_threshold = 5.0, polarity = "dark", pixel_frame = "opencv")The Julia side of the Python package's blobboards.detect_blobs.
It is detect_blobs for arguments as Python objects — a 2-D numpy image — returning Python dicts and numpy arrays, with every pixel coordinate in the stated pixel_frame convention. Its method is defined by BlobBoardsPythonExt, which loads with PythonCall (the Python package's Julia side); call it from Python, see docs/src/guide/python.md. Without PythonCall the call raises an error naming the install line.
BlobBoards.find_boards_python — Function
find_boards_python(board_paths, model_path, img; …)The Julia side of the Python package's blobboards.find_boards.
It is find_boards for arguments as Python objects — board JSON paths, the descriptor ONNX path and a numpy image — returning Python dicts and numpy arrays, with every pixel coordinate in the stated pixel_frame convention. Its method is defined by BlobBoardsPythonExt, which loads with PythonCall (the Python package's Julia side); call it from Python, see docs/src/guide/python.md. Without PythonCall the call raises an error naming the install line.
BlobBoards.load_board_python — Function
load_board_python(json_path; pixel_frame = "colmap", density = nothing)The Julia side of the Python package's blobboards.load_board.
It is load_board for arguments as Python objects — a board JSON path — returning Python dicts and numpy arrays, with every pixel coordinate in the stated pixel_frame convention. Its method is defined by BlobBoardsPythonExt, which loads with PythonCall (the Python package's Julia side); call it from Python, see docs/src/guide/python.md. Without PythonCall the call raises an error naming the install line.
BlobBoards.render_board_python — Function
render_board_python(json_path; dir, format, density, icc_profile, id_label, shading_function, pixel_frame)The Julia side of the Python package's blobboards.render_board.
It is render_board for arguments as Python objects — a board JSON path — returning Python dicts and numpy arrays, with every pixel coordinate in the stated pixel_frame convention. Its method is defined by BlobBoardsPythonExt, which loads with PythonCall (the Python package's Julia side); call it from Python, see docs/src/guide/python.md. Without PythonCall the call raises an error naming the install line.
BlobBoards.track_boards_python — Function
track_boards_python(board_paths, model_path, frames; gallery_path, camera_json, device, pixel_frame)The Julia side of the Python package's blobboards.track_boards.
It is track_boards for arguments as Python objects — board JSON paths, the descriptor ONNX path and numpy frames — returning Python dicts and numpy arrays, with every pixel coordinate in the stated pixel_frame convention. Its method is defined by BlobBoardsPythonExt, which loads with PythonCall (the Python package's Julia side); call it from Python, see docs/src/guide/python.md. Without PythonCall the call raises an error naming the install line.
Descriptor networks
BlobBoards.AbstractDescriptorNetwork — Type
AbstractDescriptorNetworkAbstract type for descriptor models. Subtypes must implement:
describe(model, patches) -> Matrix{Float32}(N×D, L2-normalized)network_hash(model) -> String(unique identifier for cache invalidation)patch_size(model) -> Int(the input resolution the network requires)
Batching is a property OF THE MODEL, not of the call (max_batch sizes its CUDA arena).
BlobBoards.LuxDescriptorNetwork — Function
LuxDescriptorNetwork(...)Lux-based descriptor model. Implementation provided by the BlobBoardsLuxExt extension; available when Lux + NNlib + cuDNN are loaded, and without them the call raises an error naming the install line. Auto-moves parameters to GPU when functional.
BlobBoards.network_hash — Function
network_hash(model::AbstractDescriptorNetwork) -> StringThe descriptor network's identity, a hash of its weights file: part of every gallery cache key, so features computed by one network are never served for another.
BlobBoards.patch_size — Function
patch_size(model::AbstractDescriptorNetwork) -> IntThe canonical patch resolution the network takes, as a property OF THE NETWORK rather than a configured number.
It used to be a [descriptor] patch_size key in the run config, which restated something the checkpoint already fixes. That was redundant rather than dangerous — a mismatch is refused by the backend — but it was refused late: patch_size is part of the gallery cache key, so a wrong value first missed the cache and re-extracted the whole board set, and only then failed at the first describe. Deriving it makes the disagreement impossible instead of merely detectable.
BlobBoards.descriptor_network_path — Function
descriptor_network_path(run_config) -> String
descriptor_network_path(path::AbstractString) -> String
descriptor_network_path() -> StringAbsolute path to the descriptor checkpoint named by a run config's [descriptor] model key, resolved against data_dir.
This is the ONLY way a run should name its network. It replaced a DEFAULT_DESCRIPTOR_MODEL constant in this package plus a LocalPreferences key plus ENV["BLOBBOARDS_DESCRIPTOR_MODEL"] plus per-driver BB_ONNX — four mechanisms, of which the library-level constant was the worst: a package asserting the filename of one lab's checkpoint, which meant anyone installing BlobBoards got a default pointing at a file they had never had, and two paper artifacts silently ran a different network from the paper's main sweep.
data_dir() stays in LocalPreferences because where the data lives is genuinely per-machine. Which network to use is a property of the experiment, not the machine — which is exactly why the preference mechanism was the wrong scope for it.
The key is required. There is no default: a run that does not say which network it used is a run whose results cannot be reproduced.
TWO source forms, selected by the TOML value's type:
model = "models/x.onnx" # STRING: data_dir-relative — the FROZEN form. Bytes come from the local primary copy or the DOI'd Zenodo assets tier; experiment configs use this so the paper's network is pinned to an immutable record.
model = { artifact = "x" } # TABLE: Pkg artifact — the DISTRIBUTION form. artifact names an entry in the package-root Artifacts.toml, a catalog of every published network (lazy entries, tarballs in a numbered version of the BlobBoards Zenodo record, sha256 + git-tree-sha1 verified). The first run fetches the tarball into Julia's shared content-addressed artifact store; every later run resolves locally. The catalog cannot float: an entry IS a pinned hash, so a config always means the same bytes — newer weights are published as a NEW catalog entry and adopted by editing the config's artifact name, a git-tracked one-line change on each side.
BlobBoards.DEFAULT_CUTOFF — Constant
DEFAULT_CUTOFFA blob's default truncation radius, in σ: its printed disc's radius is cutoff·σ, so a disc's diameter is 2·cutoff·σ. Read from cutoff under [blob_pattern] in configs/authoring.toml (2.0); a pattern or board records the value it was made with.
BlobBoards.DEFAULT_OUTER_EXTENT — Constant
DEFAULT_OUTER_EXTENTThe outer radius, in σ, of the log-polar canonical patch a descriptor is computed on (the radial range is inner_extent/outer_extent, see canonicalize). Gallery and query patches must use the same value or their descriptors are not comparable, so this constant is the one authority: BoardGallery records it, and describe_frames / extract_board_features default to it.
Pipeline configuration and stages
BlobBoards.GeometryConfig — Type
GeometryConfigAbstract type for per-estimator geometry knobs (RANSAC outlier half-width, minimum inlier count, and the local-optimization strategy). Concrete subtypes: HomographyGeometry, PoseGeometry, RadialHomographyGeometry. Held by FindBoardsConfig.geometry — the type chooses the homography-vs-P3P path inside find_boards.
BlobBoards.geometry_from_toml — Function
geometry_from_toml(::Val{tag}, table; camera, image_size) -> GeometryConfigBuild the geometry arm a [find_boards.geometry] table names by its type tag, for an arm defined OUTSIDE this package. FindBoardsConfig's loader dispatches every tag it does not own ("pose", "homography", "radial_homography") here, so a package that defines its own GeometryConfig subtype makes it loadable by adding a method for its tag, and writable by a geometry_tag method:
BlobBoards.geometry_from_toml(::Val{:my_arm}, d; camera, image_size) = MyArm(...)BlobBoards.geometry_tag(::MyArm) = "my_arm"camera and image_size are the loader's data keywords, handed on unchanged. An unknown tag throws ArgumentError.
BlobBoards.radial_geometry_from_toml — Function
radial_geometry_from_toml(G, tag::Symbol, d; camera = nothing, image_size) -> GA radial arm's geometry from its [find_boards.geometry] table d (type = "<tag>"): the table's keys checked against G's fields, the image size REQUIRED (data, like the pose arm's camera: the sensor extent that fixes the distortion centre, which differs per capture session — a value in the file would drift), a camera ignored with a warning, and G(image_size; outlier_halfwidth, min_inliers, local_optimization_strategy) built from the keys present (the strategy table read by geometry_local_optimization_strategy for tag). BlobBoards' RadialHomographyGeometry reads through it, and so does a radial arm another package registers (its geometry_from_toml method is one call).
BlobBoards.find_boards_table — Function
find_boards_table(path; tables = ()) -> AbstractDictThe [find_boards] table of the run config at path, read by read_run_config (tables: the further top-level tables a driver's configs carry beside BlobBoards' own), an ArgumentError when the file has none. The ONE door of every file loader of a [find_boards] config — FindBoardsConfig(path), and a driver's config built on it — so a typo'd table ([descripter]) or key ([descriptor] modle) fails exactly as it does for a run config.
BlobBoards.geometry_tag — Function
geometry_tag(geometry::GeometryConfig) -> StringThe type tag geometry is written under in [find_boards.geometry] — the inverse of geometry_from_toml for an arm defined outside this package.
BlobBoards.CONTRACT_GENERICS — Constant
CONTRACT_GENERICSBlobBoards' declared extension points: the functions another stack package may add methods to (VisualGeometryToolkitCore's contract_generic_violations checks it). CaliBlobs adds a GeometryConfig arm of its own and its run configuration through them:
geometry_tagandgeometry_from_toml: the TOML tag of aGeometryConfigdefined outside this package, and its reader;write_config: a run configuration's TOML writer, for a configuration type defined outside this package. (Its table,config_dict, is VisualGeometryToolkitEstimation's generic, one of its CONTRACT_GENERICS: BlobBoards and CaliBlobs add methods to it.)
(BlobBoards also adds methods of VisualGeometryToolkitIO's migrate_schema, the extension point IO declares for the owner of a schema: src/migrate_boards.jl.)
BlobBoards.TrackConfig — Type
TrackConfigThe tracker's knobs — [find_boards.track] in the config of record; every track_boards keyword defaults from here and overrides per call. Until 2026-09 these four sat as bare keyword literals on track_boards, so a tracking run's sidecar could not name them.
iou_threshold: per-blob predicted↔detected ellipse IoU gate for the warm association (ellipse overlap at the board's own cutoff).support_fraction: fraction of the predicted blobs that must associate for the warm bet to proceed to estimation.patience: consecutive failed frames before a track stops being re-targeted every frame (it stays eligible for discovery keyframes).keyframe_every: discovery cadence for boards not currently tracked;0disables periodic discovery after frame 1.
VisualGeometryToolkitEstimation.config_dict — Function
config_dict(config::FindBoardsConfig) -> DictThe [find_boards] table for config, as a plain Dict — the form write_config emits and provenance sidecars embed.
Derived from the structs by walking fieldnames, so it cannot fall out of sync with them: add a field to any config type and it appears here.
BlobBoards.write_config — Function
write_config(path, config; extra = Dict())Write config — a FindBoardsConfig, or any config with a config_dict method (a driver's config built on it) — as a TOML file with a [find_boards] table (config_dict(config)), merging any extra top-level tables (experiment, descriptor, …); the header names the config's type as its reloading constructor. A FindBoardsConfig round-trips through FindBoardsConfig(path) — which the test suite asserts — so a config recorded beside an artifact reproduces the run that made it.
max_detections = typemax(Int) is emitted as the string "unbounded", since TOML integers are 64-bit signed and the literal round-trips confusingly.
BlobBoards.read_run_config — Function
read_run_config(path; tables = ()) -> (; config_toml, find_boards, experiment, gallery, descriptor)Read the whole run config, not just the [find_boards] table: config_toml is the raw parsed file (for a provenance sidecar), and the named fields are its top-level tables, defaulting to empty. Drivers use this to get the dataset, subsets and descriptor model from the same file that configures find_boards, so there is one thing to supply and one thing to record.
OWNERSHIP AND VALIDATION: unknown TOP-LEVEL tables are refused (a typo'd [descripter] used to make every knob in it a silent no-op), and the package-owned [descriptor] table is key-checked (model only; the retired patch_size warns — the graph declares it). [experiment] and [gallery] are DRIVER-owned free-form tables: the research drivers define their keys, and the package deliberately has no opinion on them. So is [inputs], the paper projects' [inputs.<id>] statement of what a run reads (VisualGeometryToolkitEval's convention: tier, path, provenance, sha256). A driver that keeps further top-level tables of its own names them in tables; they are admitted, not checked, and read from config_toml. (The board and pattern authoring defaults are configs/authoring.toml's, never a run config's: [blob_board] there is refused.)
BlobBoards.default_config_path — Function
default_config_path() -> StringPath to configs/default.toml — the configuration of record for every entry point that is not handed an explicit config.
BlobBoards.data_dir — Function
data_dir() -> StringReturn the root data directory for BlobBoards test data and training videos.
Set in LocalPreferences.toml:
[BlobBoards]
data_dir = "/path/to/blobboards-data"Override with ENV["BLOBBOARDS_DATA"] if needed.
BlobBoards.BlobDetection — Type
BlobDetection{T}Type alias for a Detection with an EllipticFrame and metadata containing:
id::Int— index into the original detection vector- the blob's adaptation outcome (VisualGeometryToolkitCore's termination record):
retcode::ReturnCode.T—Success(converged atrtol: the blob's convergence issuccessful_retcode(det.retcode), §14, not a field of its own),MaxIters(capped atmax_irls_iter: unconverged),Failure(the shape gate refused a step: rejected),InitialFailure(it refused the first step from the seed);stop_rule::StopRule—IncrementSize(the IRLS step belowrtol, Estimation'sirls_termination),IterationCaporShapeGate;rejection::Symbol— why the shape gate refused::not_peak(the fitted paraboloid is not concave) or:aspect_ratio(beyondmax_aspect_ratio);:noneotherwise.
Capped and rejected blobs are returned, flagged; count_unconverged and count_rejected count them.
Access fields via property forwarding: det.center, det.id, det.retcode.
BlobBoards.BoardObservation — Type
BoardObservationOne board observed in one frame (a board associated with its detections and fitted: the observation; a board's Vector{BoardObservation} from track_boards is its track): its estimated model (Extrinsics3, HomographyMat or RadialHomography; every map is derived from it), its quality and inlier count, and how the frame was won (:detect, :init or :track).
BlobBoards.filter_blobs — Function
filter_blobs(frames, detections; kwargs...) -> Vector{BlobDetection{Float64}}Apply geometric quality filters to fitted blob detections.
Uses det.id to look up the original detection for scale/drift comparisons.
Arguments
frames: Fitted detections fromadaptdetections: Original detections (indexed byframe.id)
Keyword Arguments
cutoff: Sigma multiplier for boundary ellipseimage=nothing: Image for clipping check (skipped ifnothing)max_aspect_ratio=10.0: Maximum allowed aspect ratiomax_scale_ratio=4.0: Maximum σ ratio (fitted/initial)max_center_drift=10.0: Maximum center drift in units of initial σmax_clip_ratio=0.2: Maximum fraction of ellipse clipped by image boundary
Returns
Vector{BlobDetection{Float64}}— filtered subset
BlobBoards.find_board — Function
find_board(camera, board_features, image_features; kwargs...)Match image features against a single board's features and estimate geometry.
Returns (model, quality, scored) or nothing if fewer than 4 matches; the IRLS weights ride scored as its weights attribute column. model is a HomographyMat or Extrinsics3 depending on camera.
BlobBoards.board_fit_keywords — Function
board_fit_keywords(config::FindBoardsConfig, uid, bundle) -> NamedTupleOne board's fit keywords, as find_boards' engine builds them. They are (less its per-thread workspace) the arm's outlier_halfwidth and local_optimization_strategy, the RANSAC config, the board's world extent and its own seeded stream (rng = fit_rng(config.ransac_seed, uid)). The serial oracle builds them here, and so does a downstream arm (CaliBlobs'), so their fits stay comparable with the engine's by construction.
BlobBoards.board_endpoints — Function
board_endpoints(scored) -> correspondencesA scored board → image correspondence set as a 2D fit's endpoints. The board centroids are exact (board points are known, not measured: VisualGeometryToolkitCore conventions/observation-noise.md), the image centroids plain (unit isotropic pixel noise); the attribute columns ride along. The endpoints of the homography arms' fits, and of a downstream arm's (CaliBlobs' radial camera).
BlobBoards.distortion_center — Function
distortion_center(g) -> Point2{Float64}A radial arm's distortion centre: the middle of the sensor the pixels were measured in (g.image_size), in those pixels' COLMAP convention. g is a radial geometry config (RadialHomographyGeometry, or a downstream arm's with an image_size).
BlobBoards.geometry_local_optimization_strategy — Function
geometry_local_optimization_strategy(d, class::Symbol) -> AbstractOptimizationStrategyThe RANSAC local-optimization strategy a [find_boards.geometry] local_optimization_strategy table d names. It is read by VisualGeometryToolkitEstimation's loader over its strategies and LocalOptimizationDoneRight's (class is the arm's pipeline class: :homography, :absolute_pose, :radial_homography, …). The one reader for every geometry arm's TOML, downstream arms' included.
BlobBoards.load_descriptor_network — Function
load_descriptor_network(network_or_path) -> AbstractDescriptorNetworkThe descriptor network a pipeline runs. It is a network as given, or one read from a path — a .jld2 checkpoint as a LuxDescriptorNetwork (BlobBoardsLuxExt must be loaded), anything else as an ONNX DescriptorNetwork. The single switch point: every caller that has a path and wants a model funnels through here.
BlobBoards.match_boards — Function
match_boards(strategy, galleries, features; index, backend, min_similarity)
-> Dict{uid, Vector{NNMatch}}Descriptor matching of one image's features against a board gallery (uid => board features), keyed per board: one entry per gallery key, empty vectors included. index is a GalleryIndex built once over the board set and reused across images.
ONE path, every strategy: the board set is matched as ONE gallery and the rows are split back. There is no per-board matching mode, because the per-board question is the wrong one. nn_match_stacked's reverse test is BLOCK-LOCAL — documented as "per gallery the result is identical to matching that gallery alone" — which is the right contract for N INDEPENDENT galleries and not what this pipeline asks: a detection belongs to exactly one board, so mutuality has to hold over the whole board set. Asked per board it is N independent questions and one detection can win several — measured on one 12 MP fisheye frame, 629 detections were claimed by more than one board, 40% of all matches were duplicates (1685 of 4209), and they fabricated 33 boards sitting at the min_inliers floor with grossly wrong poses. Through the stack the same frame gives 2496 matches, 2496 unique, zero duplicates.
KnnMatch used to take a second, per-board staging on the grounds that it has no reverse test to correct. It does not need one: its reduction (_ka_top4_rows!) is per gallery ROW over all features, so it returns the same matches under either blocking, and the per-board staging was only a duplicate copy of the same descriptors (see GalleryIndex).
galleries selects which boards may be returned — the engine's pool SHRINKS as boards are accepted, while the index stays over the full board set. A detection whose global best belongs to an accepted board is therefore dropped rather than handed to its runner-up, which is the one-detection-one-board rule the claiming enforces anyway.
BlobBoards.guided_search — Function
guided_search(H, bundle, image_features;
min_iou, keep = Pair{Int,Int}[],
rtree, det_ells, wdiscs, wregions) -> StructArrayFinal-fit correspondence builder. Project every world blob of bundle's pattern into the image through H (build it with _world_to_image) and associate it by OVERLAP alone: its candidates are the detections whose ellipses' bounding boxes intersect the bounding box of the projected ellipse (an R-tree query; both ellipses at the blob's rendered boundary, region(·, cutoff(bundle)), the same convention annotate_blobs uses for GT labeling), and it is associated with the candidate of highest exact ellipse IoU when that IoU is ≥ min_iou. The IoU is the only acceptance criterion: there is no radius, the projected ellipse bounds the search.
The IoU gate is purely geometric — descriptors are not consulted. It is what rejects confuser boards: a wrong board can be smeared onto a detection cluster center-wise, but its blobs' projected scales and shapes won't agree with the adapted frames, so they fail the overlap check. Returns a world-disc ↔ detection ScoredCorrespondence set for a posterior-weighted refit via _find_model (one-to-one, best overlap first), recovering pattern blobs the descriptor matcher missed without admitting smears.
H is the guided TRANSFER: a HomographyMap on the projective arms, a RadialHomography on the radial one, where the conic goes through the homography exactly and only the undistortion is linearised (_guided_transfer), or a VisualGeometryToolkitCore PosedCamera (a camera model and a board pose), where the conic goes through the plane homography exactly and the lens's affinity is taken at the transferred centre.
keep (world blob => detection index pairs) are admitted first and unconditionally. The remaining keywords are hoistable context, each computed here when absent: det_ells the detections' ellipses at the board's rendered boundary, rtree an index over THOSE ellipses (detection_rtree(det_ells), whose skip keeps claimed detections out), and wdiscs/wregions the board's world blobs and their regions. It is not a bare point map because the work here is CONIC transfer, not point transfer — the IoU gate tests a blob's projected shape, so the map has to carry the conic, not just its centre.
The transfer is one of the three a model hands back (_world_to_image): a HomographyMap (the homography arm), a PosedCamera (the pose arms, any lens: Core's transfer_ellipse(::PosedCamera, _) — the plane homography of its pinhole twin exactly, then for a distorting lens its affinity at the transferred centre, behind a cheirality test), or a RadialHomography (the radial arm: the conic through H exactly, the undistortion linearised).
transfer_ellipse rather than the bare H(ellipse) callable, because a projective map does NOT always send an ellipse to an ellipse: when the conic crosses the line at infinity the image is a hyperbola or parabola. The callable returns a conic matrix; transfer_ellipse classifies it and returns nothing for the degenerate cases (and behind the camera), which _guided_candidates skips.
BlobBoards.detection_rtree — Function
detection_rtree(detections; skip = nothing) -> SpatialIndexing.RTreeAn R-tree over the detections, indexed by position j. It indexes their centroids (detections a vector of points: point rects, the warm track's radius queries) or over their ellipses (detections a vector of Ellipses at a board's rendered boundary: each ellipse's bounding box). The ellipse form is the rtree that guided_search queries: a projected blob's candidates are the detections whose boxes intersect its own.
skip (a BitVector over the detections) leaves the detections already claimed out of the index, so they can never be re-associated; the engine instead builds one index per phase and hands guided_search the claim mask as its skip, which gives the same candidates. The codebase's standard spatial index (pattern.jl collision detection, annotate.jl IoU matching).
BlobBoards.fit_rng — Function
fit_rng(seed, uid) -> XoshiroThe RANSAC stream of one board's fit: Xoshiro(seed ⊻ uid), the board's uid read as hexadecimal. find_boards, find_board's callers and track_boards all draw from it with seed = config.ransac_seed, so a fit's result depends only on its inputs; a caller that fits boards itself and wants its fits comparable with the engine's derives its streams here.
BlobBoards.extract_board_features — Function
extract_board_features(model::AbstractDescriptorNetwork, board;
patch_size=64,
inner_extent=cutoff(board.bundle),
outer_extent=DEFAULT_OUTER_EXTENT) -> StructArray{DescribedFeature}Extract features from a loaded board: rasterize PDF, canonicalize GT blobs to log-polar patches, and compute descriptors.
board is a NamedTuple from load_board.
Default method assumes a single-channel descriptor (DescriptorNetwork, ONNX): canonicalizes only the rendered PDF intensity and feeds a Vector{Matrix{Gray{Float32}}} to describe.
The masked Lux descriptor overrides this method in BlobBoardsLuxExt to additionally canonicalize the board-rect mask and stack into a (P, P, 2, N) array — see _board_mask_image / _stack_2ch in src/annotate.jl.
inner_extent defaults to the board's own Gaussian cutoff (from bundle metadata); outer_extent is the outer sampling radius for the log-polar patch (in σ units relative to each blob's scale). image is the board's raster when the caller already has it (load_board_gallery, the gallery's batch insert!); by default it is read through the raster cache (_board_raster), so the PDF is rasterized at most once per board.
Returns StructArray{DescribedFeature} pairing world-coordinate Disc detections with their descriptor vectors.
BlobBoards.extract_image_features — Function
extract_image_features(descriptor_network, img; kwargs...) -> StructArray{DescribedFeature}Full query-image feature extraction pipeline: detect blobs, adapt via posterior IRLS, filter, canonicalize to log-polar patches, and compute descriptors.
Backends and image storage
device: the KA device every stage runs on (KA.CPU()default,CUDABackend()for GPU).imgmust match (e.g.CuArray{Float32}on CUDA for the adapt/canonicalize stages).detect_img: the image supplied todetect_blobs. Defaults toimg. The detector consumesMatrix{UInt8}host data. Whendetect_imgdiffers fromimgsupply both: the detect path usesdetect_img, the adapt/canonicalize path usesimg.
BlobBoards.Telemetry — Type
Telemetry(; tag = "", branch_log, appearance_log, phase2_log, refit_skip_log)Experiment instrumentation for find_boards: four optional JSONL sinks (each nothing, i.e. off, by default) and the frame tag every row carries. Supplied as find_boards(...; telemetry) and threaded to the sites that log — until 2026-09 these were four global Refs (BRANCH_LOG[], APPEARANCE_LOG[], PHASE2_LOG[], REFIT_SKIP_LOG[]) that a driver set through BB_* environment variables, so a library call's side effects depended on process state nothing recorded. Immutable: stamp the frame with with_tag.
branch_log:_resolve_pose_ambiguityappends one row per board with both branches, the post-LO likelihood-ratio margin, the winner and the discriminabilityd(plus one row per early-return arm).appearance_log: one row per appearance-gated candidate (uid, inlier count, support, verdict, the guided-only similarities).phase2_log: one row perfind_boardscall with the phase-1 / phase-2 acceptance counts.refit_skip_log: per commit, the upper bound on what a fit cache could have skipped (see the note above).
BlobBoards.with_tag — Function
with_tag(t::Telemetry, tag) -> TelemetryThe same sinks with the frame tag replaced — the per-frame stamp a driver applies before each find_boards call.
Boards, bundles and the design resolver
BlobBoards.pattern_config — Function
pattern_config(bundle) -> PatternConfigThe PatternConfig a pattern or board bundle was made with: its blob sizes (σ, in the stored unit), seed, placement ladder, cutoff and polarity.
BlobBoards.board_config — Function
board_config(bundle::BoardBundle) -> BoardConfigThe BoardConfig of a board: canvas, margin and board size, the frame's marks and the layout grid.
BlobBoards.cutoff — Function
cutoff(bundle) -> Float64The bundle's blob truncation radius in σ (a disc's radius is cutoff·σ); see DEFAULT_CUTOFF.
BlobBoards.uid_from_hash — Function
uid_from_hash(hex_hash)First 3 hex characters of a SHA-256 config hash — matches the characters physically printed in the board corner squares.
BlobBoards.board_library — Function
board_library(boards_dir) -> Dict{Symbol, BoardBundle}Every board design in a directory of board JSON sidecars, keyed by its uid (uid_from_hash of its stored configuration hash); pattern bundles and other JSON files are skipped. Geometry only: no render is resolved or regenerated.
BlobBoards.board_points — Function
board_points(bundle::BoardBundle) -> Vector{SVector{2}} of length quantities
board_points(uid::Symbol, boards) -> Vector{SVector{2}} of length quantitiesA board design's nominal plane points.
They are its blob centres in the board's world frame (centred, y up — the plane z = 0 of TargetFrame{uid}), in the bundle's blob order, the order an observation's point index refers to. A printed board is physical, so each coordinate is a length quantity in the board's native unit, millimetres (ustrip(mm, p) for the plain numbers; blobs(bundle, :world) keeps the plain millimetres the pose solvers work in). boards is a directory of board JSON sidecars, or a uid → bundle dictionary; an unknown uid is an ArgumentError naming the uids present.
BlobBoards.board_resolver — Function
board_resolver(boards) -> (design::Symbol -> Vector{SVector{2}} of mm quantities | nothing)The resolver a stored target rig takes for its referenced board designs: VisualGeometryToolkitIO.load(Rig, path; resolve = board_resolver(boards_dir)). A design the library does not hold resolves to nothing (it stays an unresolved, pose-only target). boards is a directory or a uid → bundle dictionary; a directory is read once.
BlobBoards.board_target — Function
board_target(uid::Symbol, boards; texture = nothing) -> PlanarTargetThe board as a resolved VisualGeometryToolkitCore PlanarTarget — its whole design, as a stored rig (VisualGeometryToolkitIO's rig/v6) carries it:
- the design named by
uid, and its nominal pointsboard_points(lengths, in millimetres); theRigidcalibration; - the board it is printed on, a VisualGeometryToolkitCore
Board: the board proper — inside the sheet's margins, its frame included — as its size and its lower-left corner; - the page, a VisualGeometryToolkitCore
Canvas: the canvas's size and lower-left corner, withtexture, the printed image (save_canvas_texture'sCanvasTexture), when one is given.
All of them in the design chart, the board's world frame: canvas centre, y up, the plane z = 0 of TargetFrame{uid}. boards is a directory of board JSON sidecars, a uid → bundle dictionary, or the bundle itself (whose uid the caller names: a stored board's uid is the one its file records).
BlobBoards.hruler — Constant
A horizontal ruler band (along the board's top or bottom edge); see RulerOrientation.
BlobBoards.vruler — Constant
A vertical ruler band (along the board's left or right edge); see RulerOrientation.
BlobBoards.rasterize_pdf — Function
rasterize_pdf(pdf_path, render_dpi::Integer) -> Matrix{Gray{N0f8}}Render a PDF's first page to an 8-bit grayscale image at render_dpi dots per inch, with Poppler's pdftocairo (Poppler_jll). Cairo copies an embedded image 1:1 and evaluates a smooth shading at every pixel, so a board's pattern comes back as written: a raster pattern pixel for pixel, a vector one within one grey level at every σ. The pixel grid is Poppler's: the page rounded UP to whole pixels and anchored at its top-left corner. It goes through an uncompressed TIFF (pdftocairo cannot write one to stdout): ≈1 s for a 12000² board, 32 s as PNG.
Traces
BlobBoards.TrackTrace — Type
TrackTrace(; dir = nothing, source = nothing)Capture sink for track_boards: push the frames its on_frame callback receives, track_boards(…; on_frame = f -> push!(trace, f)). Records accumulate in memory; when dir is given each record is ALSO streamed to the trace bundle as it is produced (bounded memory on long videos, crash-tolerant).
source: the video path (ornothingfor in-memory frame sequences) — recorded in the manifest, from which a replay re-decodes each frame's pixels. No decoded frame is stored (the "RAW + results only" rule); an in-memory sequence replays on a blank canvas.
BlobBoards.TrackFrame — Type
TrackFrameOne frame of a track_boards run, as its on_frame sink receives it: the record (a TrackFrameRecord), the frame image it was measured on, and the run's configuration of record — config (config_dict output, AFTER the board-derived polarity is folded in, so it is what actually ran) and the descriptor network_hash. The last two are the same for every frame of a call. push!(trace::TrackTrace, frame) records it.
BlobBoards.save_trace — Function
save_trace(path, trace::PipelineTrace)Persist a trace for plotting in a separate, CUDA-free process. Device arrays are brought to the host first.
save_trace(dir, trace::TrackTrace)Write the trace bundle manifest (records already stream to dir when the trace was constructed with one; for in-memory traces this writes everything).
BlobBoards.load_trace — Function
load_trace(path) -> TrackTrace | PipelineTraceOne generic loader for both trace kinds: a DIRECTORY is a track_boards trace bundle (TrackTrace); a FILE is an inspect.jl pipeline trace (PipelineTrace, JLD2).
BlobBoards.trace_pipeline — Function
trace_pipeline(cam, img; detect_config, cutoff=DEFAULT_CUTOFF,
device=KA.CPU(),
adapt_arms=[:default => AdaptConfig(cutoff = cutoff)])
-> PipelineTraceRun detect → adapt → filter, capturing every intermediate. All adapt_arms consume the same detections. Supply cam = nothing to skip undistortion.
Registration (when a gallery + bundles + network are given) runs under ONE FindBoardsConfig — geometry from cam, detect = detect_config, adapt = the FIRST arm of adapt_arms — and that same config is what the trace records.
BlobBoards.PipelineTrace — Type
PipelineTraceA PipelineCapture with its optional provenance attached.
The provenance is carried as Attributed attributes, the idiom VisualGeometryToolkitCore uses to carry a record's optional payload, and for the same reason: what a trace carries beyond the capture genuinely varies, and absence should be a fact about the TYPE rather than a nothing every reader has to test.
Attributes, each present only when it was actually captured:
registration:(; accepted, bundles, cam)—acceptedisfind_boards' output, so the inspector can draw each verified board's reprojected model and its inlier correspondences next to the detections that produced them. Absent when the trace stopped at filtering, and always absent on a LOADED trace: the models and bundle references are cheap to recompute but awkward to persist.config,network_hash: the configuration of record, on the same terms asposes/_config.toml—config_dictoutput plus the descriptor checkpoint's SHA-256. Without them a trace told you WHAT happened but not UNDER WHAT SETTINGS. Absent on traces written before they were recorded.
Field access forwards, so trace.arms, trace.cutoff and trace.detections read exactly as before. Use _has_attr / _attr for the optional three.
NB no constructor is defined on this alias: it would be a method on VisualGeometryToolkitCore's Attributed, i.e. piracy. Build one with Attributed(PipelineCapture(...), attrs).
BlobBoards.PipelineCapture — Type
PipelineCaptureThe mandatory part of a trace_pipeline record: the original image (img), the undistorted 8-bit image the detector saw (detect_img), the raw ASIFT detections shared by every adaptation arm (detections), each arm's frames and filtered frames (arms, name => (frames, filtered)), and the blob cutoff. PipelineTrace attaches the optional provenance.
Training data and tracks
BlobBoards.train_descriptor — Function
train_descriptor(train_path, val_path = nothing; cfg, output_dir = "checkpoints", resume = nothing)Train the blob descriptor network on annotation files (HDF5, from annotate_blobs), with Lux and Zygote, on the GPU when one is available and on the CPU otherwise. The learning rate decays linearly from cfg.lr to 0 over the run; validation (FPR@95) runs every cfg.eval_interval iterations and at epoch boundaries. TensorBoard logs go to output_dir/tb.
train_path: the training annotations (HDF5).val_path: optional validation annotations (HDF5).cfg: the training extension'sTrainingConfig, every hyperparameter (TrainingConfig()when omitted).output_dir: the checkpoint directory, created if needed.resume: a checkpoint (JLD2) to resume from: its parameters, state, epoch and iteration count are restored; the optimizer restarts.
Checkpoints (JLD2) are written to output_dir: checkpoint_epoch_N.jld2 every epoch and best_model.jld2 at the lowest FPR@95 on validation, each with :ps, :st, :opt_state, :cfg, :epoch, :iteration and :fpr. Returns a TrainingResult with the final parameters.
The method lives in BlobBoardsTrainingExt, which loads with Lux, Optimisers, Enzyme, Reactant, NNlib, TensorBoardLogger and Zygote; without them the call raises an error naming the install line.
BlobBoards.annotate_frame! — Function
Run annotate_blobs on one image (or one video frame), insert any not-yet-written reference patches into refs/, and write the frame's detections + confusers + meta to its own per-frame JLD2 file.
Returns the meta NamedTuple. Skips writing the frame file when there are zero detections AND zero confusers.
BlobBoards.append_log — Function
Append one line of structured stats for a processed source to output_dir/_log.jsonl. Designed to be safe under multi-process append: each line is < PIPE_BUF, so concurrent writes interleave at line boundaries.
BlobBoards.check_annotation_hashes — Function
Verify the model + config hashes in output_dir/_config.jld2 match the current ones. If no _config.jld2 yet, write it. Mismatch → error.
BlobBoards.existing_ref_uids — Function
Set of board UIDs that already have a refs/<uid>.jld2 file.
BlobBoards.is_source_processed — Function
A source is "processed" if its primary output exists.
- Image:
<basename>.jld2 - Video:
<basename>.donemarker
BlobBoards.image_path — Function
image_path(output_dir, source_basename) -> StringThe annotation file annotate_blobs's driver writes for one source image: <output_dir>/<source_basename>.jld2.
BlobBoards.config_hash — Function
config_hash(; config::FindBoardsConfig, cutoff, patch_size, outer_extent, min_iou)Hash the annotation-pipeline extraction settings into a string stored in _config.jld2 so the build_annotations driver can detect config drift across runs.
config.geometry is intentionally EXCLUDED: it carries the per-source camera (PoseGeometry) and the homography-vs-P3P choice, both of which legitimately vary across sources written into the same output directory. EVERY other field participates: the hash is taken over config_dict(config) minus the geometry table — the same fieldnames-derived serializer the run sidecars use — so a field added to FindBoardsConfig is hashed without anyone remembering to list it. (Until 2026-09-07 this was a hand-written tuple that omitted verify_similarity, min_appearance_support, ransac_seed and refine: the board-acceptance gates decide which boards get annotated, so changing them changed the output while the directory still read as consistent.)
The encoding is the canonical config JSON (sorted keys, Ryu floats), so the hash is stable across Julia and JSON library versions — a string(::Tuple) was not.
Changing any hashed setting invalidates the existing per-frame JLD2 files in the output directory (they must be rebuilt). The 2026-09-07 change itself does that once for every existing annotation directory.
BlobBoards.build_annotations — Function
build_annotations(board_feature_dict, descriptor_network, sources;
board_bundles, board_paths, output_dir="truth/", kwargs...)Annotate images and/or videos into a directory of per-frame JLD2 files.
sources is a vector of input paths. Each element is either:
- A video file (
.mp4,.avi,.mov,.mkv) — frames extracted withstride - An image file — annotated as a single frame
Resumable: per-source output existence is the "processed" marker; previously processed sources are skipped. Per-source structured stats are appended to output_dir/_log.jsonl (use summarize_annotations(output_dir) to read back).
BlobBoards.load_annotations — Function
load_annotations(path) -> NamedTupleLoad annotated blob observations. path may be:
- A directory written by
annotate_blobs/build_annotations(per-frame JLD2 files +refs/<uid>.jld2), in which case files are concatenated. - A single JLD2 split file produced by
split_training_data.
Returns (; board_uids, blob_ids, patches, confusers) — flat shape:
patchesis a P×P×2×N array (refs + per-frame detections concatenated, when reading a dir). Channel 1 = intensity. Channel 2 = validity mask (real on the ref side, all-1s on the detection side — see_extract_reference_patches).confusersis a P×P×2×C array (detection patches, channel 2 = all-1s).
Group by (board_uid, blob_id) to reconstruct CorrespondenceSets — cs[1] for each key is the reference patch (always loaded first).
BlobBoards.load_correspondence_sets — Function
load_correspondence_sets(path) -> Dict{Tuple{String,Int}, CorrespondenceSet}Load annotations from a directory or split JLD2 file, then group into CorrespondenceSets keyed by (board_uid, blob_id). Each CorrespondenceSet contains all observed patches of the same physical blob. cs[1] is the reference patch (from board PDF), cs[2:end] are camera observations.
BlobBoards.split_training_data — Function
split_training_data(source_path; output_dir="data/",
validation_fraction, test_fraction, seed,
val_boards=nothing, test_boards=nothing) -> NamedTupleSplit an annotation HDF5 into train/val/test files by board identity. All observations of a given board go entirely to one split — no leakage.
Split strategy
Boards are assigned greedily (largest first, ties broken by a shuffle of the SORTED board UIDs with MersenneTwister(seed)) to test, then val, until each split reaches its target patch fraction (test_fraction, then validation_fraction). Remaining boards go to train. Confusers go to training data. The fractions and the seed are the caller's — there are no defaults: the split of a training corpus is recorded where it is chosen.
Explicit board lists (val_boards, test_boards) override the automatic split for that partition.
Returns
(; train_path, val_path, test_path, val_boards, test_boards, stats)
BlobBoards.summarize_annotations — Function
summarize_annotations(output_dir) -> Vector{NamedTuple}Read every per-source meta record from output_dir/_log.jsonl and return them as a vector of NamedTuples. Useful for after-run analysis (which sources detected no boards, slowest sources, board distribution, etc.).
Falls back to scanning per-file metas if the JSONL log is missing.
BlobBoards.collect_media — Function
collect_media(video_dir) -> Vector{String}Recursively collect every video and image file under video_dir.
A file is the unit of independent work for track building: walk_media — the ONE enumeration, in sorted, reproducible order — behind a loud empty-corpus guard. Shared by build_tracks_for_sequences and the multi-GPU driver.
BlobBoards.load_board_gallery — Function
load_board_gallery(descriptor_model_path, board_dir; device = default_device())
-> (; boards, board_by_uid, model, board_feature_dict, board_bundles)Load every board .json in board_dir (metadata + rendered image), the descriptor model, and per-board gallery features + bundles (all keyed by uid). Runs check_blob_id_collisions to fail fast on blob-id hash-field clashes. Shared by build_tracks_for_sequences and the multi-GPU driver (examples/training/slurm/driver_build_tracks.jl) so every worker builds an identical gallery.
device is the KA backend used for descriptor extraction — default_device() (CUDABackend() when CUDA is loaded, otherwise KA.CPU()).
BlobBoards.merge_track_files — Function
merge_track_files(dest_path, src_paths) -> dest_pathMerge multimodal .tracks files into dest_path by copying each /sequences/<name> group verbatim (HDF5.copy_object — layout + zlib compression preserved, no decode/re-encode). Sequence names are globally unique (<media>_<uid> tracked, <uid> anchor), so this is a plain concatenation; names already present in dest_path are skipped, so it is idempotent (safe to re-run) and duplicate anchor groups collapse to one.
This is the merge for the multimodal Dict format written by _save_track_dict (patches + masks + affineshapes + `isanchor). It copies groups as-is rather than decoding and re-encoding, which is what the retiredmergetracksdid — that round-tripped through theVector{Track}loader and would have dropped masks/affine/anchor flags. Used by the multi-GPU driver to combine per-worker outputs (examples/training/slurm/driverbuild_tracks.jl`).
BlobBoards.save_board_anchors — Function
save_board_anchors(output_path, board; inner_extent, patch_type = :logpolar, scale = 32,
patch_size = 64, backend = default_device(), sink = nothing)Write one anchor sequence for a board to the .tracks file at output_path.
The sequence is named by the board's uid: every ground-truth blob (canvas coordinates, sampled from the rendered board image) as one patch of patch_type at scale. Track ids match the video tracks' ids (blob_track_id), so a video track's anchor is found by id; the sequence is flagged is_anchor = true and its masks are in-frame only. sink replaces the synchronous writer (the .tracks builder supplies a channel-backed one).
BlobBoards.symmetric_iou_match — Function
symmetric_iou_match(H_ij, frames_i, frames_j;
cutoff=2.0, iou_threshold=0.3) -> Vector{TrainingPair}Symmetric matching of the detections of two frames related by the homography H_ij, scored by the IoU of their cutoff-scaled boundary ellipses.
SYMMETRIC: a pair is kept only when both directions succeed. Forward, the detection of frame i, transferred through H_ij, finds its best-IoU match among frame j's detections. Backward, that match, transferred through H_ij⁻¹, overlaps the original detection. Each IoU must reach iou_threshold.
For each detection in frame i:
- Transfer its boundary ellipse to frame j via H_ij
- Find best IoU match among frame j detections
- Transfer that match back to frame i via H_ij⁻¹
- Check IoU with original detection
- Accept if min(forwardiou, backwardiou) ≥ iou_threshold
One deterministic sweep: no sampling, no iteration (an algorithm name, not a find: CLAUDE.md's verb conventions).
BlobBoards.TrainingPair — Type
TrainingPairOne validated correspondence between two frames.
It is the element symmetric_iou_match returns: the frame indices (frame_i, frame_j), the blob indices in each (idx_i, idx_j), and the ellipse IoU of the match each way (iou_forward, iou_backward). A NamedTuple type.
BlobBoards.view_angle_profile — Function
view_angle_profile(tracks_path; sequence=nothing) -> Vector{ViewAngleStat}Rebuild the per-(board, frame) viewing-angle records from a finished .tracks file, so a profile can be re-charted (or re-binned) offline without re-running the build:
stats = view_angle_profile("tracks_logpolar_s32.tracks")save_view_angle_figure("profile.png", stats) # needs CairoMakiesave_view_angle_figure("fine.svg", stats; edges = 0:5:90)print_view_angle_profile(filter(s -> s.uid == uid, stats)) # one board, no backendReads each tracked sequence's per-frame view_angles / n_gt_in_image / n_sift_on_board / n_detections_on_board / n_detections_in_frame table and counts the observations sharing each frame_id to recover how many blobs that board matched in that frame. Anchor sequences (no frame geometry) are skipped; sequence restricts to one sequence name.
BlobBoards.print_view_angle_profile — Function
print_view_angle_profile([io], stats; edges=VIEW_ANGLE_EDGES, width=40, title=...)Text fallback for view_angle_figure — the same binning as a terminal bar chart, for runs with no Makie backend loaded. stats is a collection of ViewAngleStat records, one per (board, frame) detection.
Each row is one angle bin: the mean GT blobs matched per board-frame (the bar), the recall against the board's blobs visible in those frames, the mean total frame detections, and the bin's board-frame count. Empty bins are skipped.
BlobBoards.ViewAngleStat — Type
ViewAngleStatOne board in one frame of a track build.
It is the element view_angle_profile returns: the board's uid, the frame (frame_idx), its viewing obliquity (view_angle, radians), the ground-truth blobs matched and those in the image (n_matched_gt, n_gt_in_image), and the detection counts on the board and in the frame. A NamedTuple type.