# 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.