Marker Parquet Format

This document describes the expected structure for marker configuration files (e.g., standard_box_markers_600mm.parquet). These files define both the physical geometry of markers and their logical grouping into faces.

Schema

The parquet file must contain the following columns:

Column	Type	Description
`name`	`string`	Name of the face (e.g., "bottom", "front"). Used for logical grouping.
`ids`	`list<int64>`	List of ArUco marker IDs belonging to this face.
`corners`	`list<list<list<float64>>>`	3D coordinates of marker corners. Shape must be `(N, 4, 3)` where N is the number of markers.

Example Data

Based on standard_box_markers_600mm.parquet:

name	ids	corners (approximate structure)
"bottom"	`[21]`	`[[[-0.225, -0.3, 0.226], [0.225, -0.3, 0.226], [0.225, -0.3, -0.224], [-0.225, -0.3, -0.224]]]`

Loader Behavior

The system uses two different loading strategies based on this file:

1. Geometry Loader (`load_marker_geometry`)

Ignores: name column.
Uses: ids and corners.
Process:
- Flattens all ids and corners from all rows.
- Reshapes corners to (-1, 4, 3).
- Validates that each marker has exactly 4 corners with 3 coordinates (x, y, z).
- Validates coordinates are finite and within reasonable range (< 100m).
Output: dict[int, np.ndarray] mapping Marker ID → (4, 3) corner array.

2. Face Mapping Loader (`load_face_mapping`)

Uses: name and ids.
Process:
- Reads face names and associated marker IDs.
- Normalizes names to lowercase.
Output: dict[str, list[int]] mapping Face Name → List of Marker IDs.
Usage: Used for ground plane alignment (e.g., identifying the "bottom" face).

Validation Rules

Runtime validation in marker_geometry.py ensures:

corners shape is strictly (4, 3) per marker.
No NaN or Inf values.
Coordinates are absolute (meters) and must be < 100m.

2.0 KiB Raw Blame History