Outputs and formats

Every artifact NameFrame produces, what is inside it, and which ones you should keep. Short version: keep the raw dump, keep the dataset, regenerate everything else.

The raw dump#

The raw dump is the source of truth. It contains what Unreal actually rendered and what was actually true in the scene, before any label was derived. Because it exists, you can produce a different annotation format months later without opening the editor.

dump/
  capture.json          # run-level contract
  verify.json           # pre-flight check results
  job_state.json        # resume state
  frames/
    demo_0000/
      rgb.png           # the rendered image
      seg.png           # per-instance ID buffer
      depth.npy         # optional, when write_depth is on
      frame.json        # camera, actors, environment, file map
    demo_0001/
      ...

capture.json

Key	Contents
`format_version`	Raw capture contract version
`generator`	What produced the dump
`source`	Where it came from, the Unreal job or the demo generator
`camera`	Camera model and parameters for the run
`labeling`	The labelling policy in force
`classes`	The class registry, label to index
`identity`	Run identity and seed material
`notes`	Free-form annotations, including studio warnings

frame.json

Key	Contents
`id`	Frame identifier, matching the folder name
`camera`	Pose and intrinsics for this exact frame
`actors`	Every actor: transform, ID colour, and world-space bones where applicable
`env`	The environment state actually applied: weather, sun, fog
`files`	Which files exist for this frame

Why seg.png matters

It is not a semantic mask. It is a per-instance ID buffer with one distinct colour per actor, which is what makes exact occlusion-aware boxes and per-instance polygons possible instead of approximations from bounding volumes.

The dataset#

dataset/
  images/{train,val,test}/          # shared across formats
  labels/{train,val,test}/*.txt     # YOLO
  data.yaml                         # YOLO config
  annotations/*.json                # COCO
  dataset.json                      # manifest: sources, splits, formats

Images are written once and shared by both formats, so exporting YOLO and COCO together does not double your disk usage.

YOLO

One .txt per image, one line per instance. For --task box that is the class and the normalised box. For --task pose the keypoints follow on the same line.

data.yaml carries the split paths, the class names, and for pose it also carries kpt_shape and flip_idx:

kpt_shape: [13, 3]
flip_idx: [0, 2, 1, 4, 3, 6, 5, 8, 7, 10, 9, 12, 11]

flip_idx is not optional

Training augmentation mirrors images. Without the swap map, a mirrored left shoulder keeps the left-shoulder index and the model learns contradictory data. NameFrame writes it automatically, so do not strip it when editing data.yaml.

The 13-joint order is: head, left/right shoulder, left/right elbow, left/right wrist, left/right hip, left/right knee, left/right ankle.

COCO

Standard COCO JSON under annotations/. Choose what gets written with --coco-exports: instances, person_keypoints, or all.

dataset.json

The manifest that makes a dataset traceable: format_version, generator, task, formats, sources (which dumps it came from), names, splits, fractions, empty_skipped, and pointers to the YOLO and COCO outputs.

Splitting#

Strategy	Behaviour	Use when
`hash`	Per-frame hash. Deterministic and well mixed.	Default. One scene, many frames.
`by_dump`	Holds out whole dumps.	Several scenes, and you want val/test to be scenes the model never saw.
`sequential`	Ordered contiguous blocks.	Temporal data where neighbouring frames are near-duplicates.

Leakage

With hash on a video-like capture, frame 100 and frame 101 are nearly identical and can land on opposite sides of the split, which turns your validation score into fiction. The validator flags near-duplicate leakage. If you see it, switch to sequential or by_dump.

Optional image layers#

Flag	Writes	Why
`--include-clean-images`	`clean_images/{train,val,test}`	Keep the un-degraded RGB next to lens-processed images
`--include-segmentation`	`segmentation/{train,val,test}`	Masks for segmentation training or debugging
`--precipitation`	rain/snow composited into images	UDS/UDW GPU particles do not render in editor scene captures

Frame filters#

Applied at dataset assembly, after labelling, so you can shape the dataset without re-rendering:

--filter-min-instances, --filter-max-instances, --filter-include-classes, --filter-require-classes, --filter-exclude-classes

The report#

report/index.html holds frame and instance counts, quality gates, and RGB overlays with boxes drawn on. It is disposable, and you can regenerate it any time from the dump with nameframe report. --report-preview-limit controls how many overlay images get produced.

The validation scorecard#

validation/validation.html holds a 0 to 100 score, a letter grade, and every penalty itemised with the reason. See Quality, checks and scoring.

The dataset inspector#

nameframe dataset-inspect, or --inspect on generate, writes a sample browser for flipping through assembled samples with their labels rendered. Use it when a score is lower than you expected and you want to see which samples are responsible.

Metadata v1#

A deterministic sidecar derived from a dump, holding the queryable record of the run: run metadata, frame records, instance records, observations, scene and spawn manifests, and the configuration snapshot. Indexed into local SQLite, it is what makes cross-run queries and comparisons possible.

nameframe metadata-build <dump> <metadata-out>
nameframe metadata-index _local/metadata.sqlite <metadata-out>

JSON Schemas for every contract live in docs/schemas/.

What to keep#

Artifact	Keep?	Why
Raw dump	Yes	Everything else is derivable from it. It is not derivable from anything.
Dataset	Yes	What you trained on. Needed to reproduce a result.
Metadata sidecar and index	Yes	Cheap, and it makes runs findable.
Validation	Yes	Small, and it is the evidence for a quality claim.
Report	No	Regenerate on demand.
Inspector	No	Regenerate on demand.

PreviousVerified UE 5.8 visual QA NextQuality, checks and scoring