[MuziWong]

Description

Generate rigid scene variants through a shared CPU/CUDA core and apply them through Sim APIs, Scene Engine post-export jobs, or an ExpandSceneLayout reset event for handwritten expert and RL environments. Support group-root XY, selected member XY/yaw and subtree propagation while preserving assets, scales, explicit supports and fixed members. Geometry preparation is content-addressed; sampling remains batched and selected-row application does not step physics.

EpisodeContext attaches recording eligibility to the current row buffers. Synchronous component checks block publication until completion; rejection remains sticky until buffers are consumed or discarded and a new episode begins. Normal trajectories, datasets and independent row videos all intersect that eligibility with existing save/fragment/commit policies. Reset consumes old recordings before changing physical state, first-frame errors reject initialization, camera first frames are captured after final host preparation, and asynchronous writers own data/provenance snapshots. Diagnostic exports have a separate purpose and directory; close never implicitly commits live buffers.

• Replace RandomizeSceneLayout directly with ExpandSceneLayout in Python/YAML. Configured event names keep the same named random streams. Provenance is now episode_context.sources["events/<configured_name>"].metadata in both reset info and episode metadata. No old class alias or expansion-specific environment save flags remain.
• Keep v1–v4 layout reading, JSON/packed storage, saved variant identities and conversion without resampling. Previous support-hole, parent-transform and legacy-cache fixes remain included.
• Register TabletopFourBases as a downloadable asset. Ship only the portable scene_export; generated layouts, geometry caches and native PNG/GIF/MP4 previews belong to the output workspace.
• Document the public APIs, recording lifecycle and migration; refresh affected project context. Add focused lifecycle, row-isolation, writer-retry and synchronous/asynchronous provenance tests.

TaskSpec/Task Engine changes stay in codex/scene-randomization-task-spec, depending on unmerged #729. That integration uses independent frozen-layout and measured TaskSpec checks, restores frozen poses before the first frame and routes rejected/unverified evidence to diagnostics. This PR remains the independently mergeable shared layer.

Type of change

• New feature
• Bug fix
• Breaking change to the pre-merge functor name and event metadata path
• Documentation update

Reproduce and preview

python -m scripts.tutorials.scene.grouped_scene_randomization \
  --output-root outputs/tabletop_demo --render

Use an empty output directory and the installed project runtime. Assets are published in the Hugging Face demo directory. The command saves preview/contact_sheet.png, comparison.gif and comparison.mp4 alongside the 20-layout run.

Validation

• Reset row selection is normalized to torch.long; regression tests now cover full reset, non-contiguous list selections, int32/int64 tensor inputs and empty reset, including shared robot/sensor UIDs and untouched rows. These stub-only tests explicitly run in the fast CPU lane.

• GitHub PR merge snapshot 21a37523 (base f852b2af, PR head 35c9858b) passed 8,726 CPU tests, 1 skipped, and 4 native Default/Newton selective-reset tests with the pinned rc1 runtime. This independently validates the combined source tree in addition to the branch.

• Latest CI-fix commit validation with the pinned dexsim_engine==0.5.1rc1 wheel: 8,139 passed, 1 skipped in the full shared CPU lane; 50 passed, 2 skipped in focused reset/IK cases; 4 passed in native Default/Newton, Sim/Gym four-row reset tests. No production behavior or dependency change in this follow-up. Context reviewed; no edit needed because lifecycle semantics are unchanged.

• Full integrated CI CPU lane: 9,401 passed, 2 skipped. Focused recording, functor, host and Task Engine regression suite: 707 passed, 2 skipped; the broader shared CPU run passed 2,281 tests, 1 skipped before the final boundary additions.

• Native Default/Newton, Sim/Gym selective-reset tests: 4 passed, with four environments, non-contiguous reset IDs and rotated geometry. Gym probes also render 96×64 first frames, check selected-row camera buffers against current native frames, preserve unselected frames/counters, and forbid physics stepping during reset. CUDA geometry/replay suite: 19 passed.

• Downloaded-asset demo: 20/20 valid; saved replay IDs and poses are unchanged, fixed cup/saucer error is below 1e-12, and native PNG/GIF/MP4 previews regenerated.

• On the dependent integration branch: three different E1 frozen layouts succeeded with measured TaskSpec acceptance, normal trajectories and per-row videos; one geometrically valid but unreachable layout was rejected and produced only labelled diagnostics.

• Black 26.3.1, diff checks, context checks and public API coverage passed: 2,719/2,719 shared and 3,143/3,143 integrated. Shared HTML and shared/integrated Sphinx dummy builds passed; existing repository documentation warnings remain. Context/documentation regression tests: 139 passed.

Performance changes are limited to recording checks, snapshots and per-row metadata saving; the sampler is unchanged. On Ryzen 9 9950X / RTX 5090, Python 3.11, Torch 2.7.1, one CPU thread, 5 warmups/40 repetitions, the four-row/two-source CPU medians are 0.053 ms checks, 0.018 ms filtering, 0.043 ms snapshot. Publishing four JSON sidecars costs 0.223 ms with Context vs 0.078 ms baseline, using equal atomic-renaming writes without fsync or video encoding. CUDA-host measurements are synchronized and reported separately; this is not an end-to-end simulator speedup claim.

The existing 20/500/5,000-layout CPU/CUDA benchmark remains applicable because sampling is unchanged. At 5,000 layouts its previous three-seed medians were:

Backend	Generate	Save	Read	Consume	Apply
CPU	0.972 s	2.314 s	3.261 s	0.884 s	2.253 s
CUDA	0.349 s	2.332 s	3.345 s	0.888 s	2.117 s

These include validated package I/O and native application to four environments without physics stepping. Geometry acceptance does not certify physical settling or task success; hosts provide measured task validation.

Checklist

• Ran black . using Black 26.3.1.
• Reviewed and updated affected user/API documentation and project context.
• Public exports are documented.
• Added focused production-contract regression tests.
• No new runtime dependencies.

[greptile-apps]

Confidence Score: 4/5

[Medium impact] The changes reach scene-layout workflows and environment recording across simulator rows.

The PR still needs a limit on queued video jobs before merging.

Findings

1.  Queued videos exhaust RAM ▶

Fix with agent prompt

### Issue 1
embodichain/lab/gym/envs/managers/record.py:318-319
If simulation produces recordings faster than the single writer can encode them, `record_camera_data_async._flush_jobs` skips running jobs and keeps submitting new ones. Each queued episode holds a full copy of its frames, with no limit on pending work. Memory can keep growing until a long collection run crashes.

Add a pending-job or byte limit and wait for the writer when that limit is reached.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds shared CPU/CUDA scene layout generation and row-level recording eligibility through EpisodeContext.

• Scene layouts can be generated in batches and applied to selected simulator rows.
• Scene Engine exports can produce saved layouts for preview and replay.
• EpisodeContext tracks which environment rows can publish recordings.
• The scene-layout workflow now has runnable examples and updated public guidance.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Reset selected rows] --> B[Save eligible old recordings or discard]
  B --> C[Begin new episodes]
  C --> D[Reset physical state and run events]
  D --> E[Run optional host preparation]
  E --> F[Capture observations and first frames]
  F --> G[Complete initialization]
  G --> H[Component checks determine recording eligibility]

Loading

_{Reviews (5) · Last reviewed commit: "test(gym): align reset row IDs and run s..." · Reviewed by Greptile}

[greptile-apps]

Queued videos exhaust RAM

If simulation produces recordings faster than the single writer can encode them, record_camera_data_async._flush_jobs skips running jobs and keeps submitting new ones. Each queued episode holds a full copy of its frames, with no limit on pending work. Memory can keep growing until a long collection run crashes.

Add a pending-job or byte limit and wait for the writer when that limit is reached.

Prompt To Fix With AI

This is a comment left during a code review.
Path: embodichain/lab/gym/envs/managers/record.py
Line: 318-319

Comment:
**Queued videos exhaust RAM**

If simulation produces recordings faster than the single writer can encode them, `record_camera_data_async._flush_jobs` skips running jobs and keeps submitting new ones. Each queued episode holds a full copy of its frames, with no limit on pending work. Memory can keep growing until a long collection run crashes.

Add a pending-job or byte limit and wait for the writer when that limit is reached.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.