Python quickstart

A labelled, validated dataset with an HTML report in about ten minutes, without Unreal, without a GPU and without any licensed assets. The commands you run here are exactly the ones you run against a real Unreal capture. Only the source of the dump changes.

1. Install#

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

Requires Python 3.11+. Full detail on Installation.

2. The whole thing in one command#

nameframe generate --demo --samples 16 --seed 7 --output _demo/headless --dataset-task box --dataset-format yolo,coco --inspect --fail-under 80

That single command generates a procedural dump, verifies it, derives labels, writes a report, exports YOLO and COCO, scores the result, and fails the process if the score drops below 80. Under _demo/headless you now have:

Folder	What is in it
`dump/`	The raw capture: `capture.json` and one folder per frame
`report/index.html`	Frame counts, quality gates and RGB overlays
`dataset/`	Images, labels, splits, `data.yaml`, COCO annotations
`validation/validation.html`	The 0 to 100 scorecard with every penalty explained
`inspector/`	A sample browser, because `--inspect` was set

About the demo dump

The people in --demo are procedural blobs, not rendered humans. Every transform, ID colour and bone in it is real and self-consistent though, so the pipeline exercises the same code paths as a real capture. Treat it as a mechanism test, not a visual one.

3. The same thing, one stage at a time#

When something goes wrong, run the stages separately so the failure lands in one place.

# 1. make a dump
nameframe demo-dump _demo/dump --frames 16 --seed 7

# 2. pre-flight gates
nameframe verify _demo/dump

# 3. derive labels
nameframe label _demo/dump _demo/labels

# 4. browsable report
nameframe report _demo/dump _demo/report

# 5. assemble and split
nameframe dataset _demo/dump _demo/dataset --task box --format yolo,coco

# 6. score it
nameframe validate _demo/dataset --out _demo/validation

4. Resumable runs#

run executes the offline chain over an existing dump and autosaves progress to job_state.json. If it gets interrupted, add --resume and it continues from exactly where it stopped.

nameframe run _demo/dump --verify --label-out _demo/labels --report-out _demo/report --dataset-out _demo/dataset --dataset-task pose --dataset-format yolo,coco --validate-out _demo/validation --fail-under 80 --resume

5. Moving to a real Unreal capture#

Everything after capture is identical. Only step 1 changes.

Write a recipe

Copy the closest file from examples/ and edit scene.map, the class selectors, the spawn zones and the camera. See the recipe reference.

Validate it before Unreal is involved

nameframe studio-validate examples/studio_generic_object_detection.yml

Compile it to a plugin job

nameframe studio-compile examples/studio_generic_object_detection.yml _local/jobs/generic.json

Check the randomisation plan without rendering

nameframe studio-dry-run examples/studio_generic_object_detection.yml _local/plans/generic --samples 20

Capture from an open Unreal editor

nameframe capture-unreal _local/jobs/generic.json --verify --report-out _local/reports/generic --dataset-out _local/datasets/generic --dataset-task box --dataset-format yolo,coco --validate-out _local/validation/generic --resume

Unreal has to already be open with your level loaded and the Remote Control API enabled. NameFrame does not launch the editor.

Prove the loop first

Before a long run, use nameframe live-smoke. It authors a tiny scene, captures it, labels it and scores it, end to end. If that passes, your Unreal connection and plugin are working, and any later failure is in your recipe.

Environment variables#

Variable	Effect
`NAMEFRAME_UE_REMOTE_URL`	Default Unreal Remote Control endpoint. Defaults to `http://127.0.0.1:30010`.

Where to go next#

Reference