Metadata v1

A structured, queryable record of what a run contained, separate from the dataset it exported. Schema version 1, metric registry version 1.

Why this exists#

A YOLO label file answers one question: what is in this image. It cannot answer how far that object was, how occluded, which rule placed it, how many attempts that took, or whether the same object appears in forty other frames.

Those questions are the ones you ask when a model is underperforming and you need to know what the data actually covered. Metadata v1 keeps the answers.

The four record types#

World instances versus camera observations#

This is the distinction the whole schema turns on, and it is worth slowing down for.

An instance is a thing that exists in the world: one crate, placed once, at one position. It has a nearest-neighbour distance and a placement attempt count, because those are facts about placing it.

An observation is one camera seeing one instance in one frame. It has a camera distance, a bounding box, an occlusion ratio and a truncation ratio, because those are facts about looking at it.

One instance produces many observations. A crate visible in twelve frames is one instance and twelve observations, and conflating them is how dataset statistics end up wrong: averaging occlusion "per object" when you mean per sighting gives a number that means nothing.

The metric registry#

15 metrics, each declaring its table, columns, aggregation and the SQL that computes it. A metric is a definition rather than a number, so two runs are compared by the same query rather than by two people's arithmetic.

run.frames.requested                         Requested frames
run.frames.generated                         Generated frames
run.frames.indexed                           Indexed frames
run.instances.total                          World instances
run.observations.total                       Camera observations
run.observations.visible                     Visible observations
run.visibility.visible_pixels                Visible instance pixels
run.observations.camera_distance.mean        Mean camera distance
run.observations.bbox_area_ratio.mean        Mean bounding-box area ratio
run.observations.occlusion.mean              Mean occlusion ratio
run.observations.truncation.mean             Mean truncation ratio
run.instances.placement_attempts.mean        Mean placement attempts
run.instances.nearest_neighbor.mean          Mean nearest-neighbor distance
run.samples.total                            Assembled samples
run.quality.minimum_score                    Minimum dataset quality score

Distribution dimensions#

10 dimensions available for distribution analysis:

observations.camera_distance_m         Camera distance (metre)
observations.bbox_width_px             Bounding-box width (pixel)
observations.bbox_height_px            Bounding-box height (pixel)
observations.bbox_area_ratio           Bounding-box area ratio (ratio)
observations.view_azimuth_deg          View azimuth (degree)
observations.view_elevation_deg        View elevation (degree)
observations.occlusion_ratio           Occlusion ratio (ratio)
observations.truncation_ratio          Truncation ratio (ratio)
instances.nearest_neighbor_m           Nearest-neighbor distance (metre)
instances.placement_attempt_count      Placement attempts (attempt)

These are the axes behind coverage questions. "Does this dataset cover close-range objects?" is observations.camera_distance_m. "Are the objects big enough to detect?" is observations.bbox_area_ratio. "Did we only ever look from one angle?" is observations.view_elevation_deg.

The local index#

Records are written as JSONL beside the run and can be indexed into a local SQLite database. That is what makes the metrics queryable and what the Studio's Results page reads.

Local, on your machine, no service required. Index schema version 2.

Coverage targets#

Once distributions are measurable, they can be compared against intent: a target distribution, the actual one, and the gap. A correction plan is a draft of what to generate to close it.

Treat the plan as a draft. It proposes; deciding whether the gap matters for your task is still yours.

Related#

Outputs and formats covers where these files sit in a run. Operations covers backup and restore of the index.