CAD 작업대에서 센서 데이터까지

CAD 작업대를 열고 Replicator에서 카메라 장면을 바꿉니다. RGB·깊이·라벨과 복원한 점군을 확인할 수 있습니다.

  • CadQuery
  • OpenUSD
  • Isaac Sim
  • PhysX
  • Replicator
작업대에서 센서 데이터까지
실행 영상실행 영상과 기록

동작 원리

데이터는 어떻게 흐를까요?
  1. 입력카메라 정보와 센서 데이터USD 카메라 + 깊이 배열 + 분할 마스크

    마스크는 큐브에 해당하는 픽셀을, USD는 렌즈와 카메라 위치를 알려줍니다.

  2. 처리픽셀을 3D 점으로 바꾸기픽셀 (u, v) + 깊이 → 좌표 (x, y, z)

    카메라 위치와 깊이를 이용해 큐브가 보이는 픽셀을 장면 속 좌표로 옮깁니다.

  3. 출력큐브가 얼마나 움직였나surface-00.npy · result.json

    보이는 점들의 중앙값을 첫 프레임과 비교해 상대 이동량을 구합니다.

픽셀 하나를 장면 속 점으로 옮기기

첫 단계는 깊이 배열에서 쓸 픽셀을 고르는 것입니다. 라벨 JSON에서 part 번호를 찾고 같은 위치의 깊이가 유한한 양수일 때만 남깁니다. 각 픽셀은 카메라에서 뻗어 나가는 한 방향을 나타냅니다. USD 카메라의 초점거리와 센서 폭으로 그 방향을 구하고, 깊이를 더하면 해당 표면의 3D 위치를 계산할 수 있습니다. 코드에서는 이미지 중심이 광축과 일치하고 픽셀이 정사각형이라고 가정합니다.

텍스트
마스크에서 part 선택 → (열 u, 행 v)와 깊이 읽기
                                  ↓
                     카메라 기준 3D 점
                                  ↓ USD의 카메라 위치·회전
                         월드 좌표 (x, y, z)

예를 들어 저장된 첫 프레임에서 (u=613, v=231)을 읽으면 깊이는 약 3.164 m, 라벨 번호는 2입니다. 같은 프레임의 JSON에서 2가 part이므로 이 픽셀을 점군에 포함합니다. 배경 또는 작업대 라벨이면 같은 깊이가 있어도 큐브 점군에는 넣지 않습니다. 역투영 코드 · 원본 RGB-D 기록

왜 첫 프레임과 뺄까요?

각 점군은 카메라에서 보인 표면만 담습니다. 큐브 중심을 바로 읽으려 하면 카메라 방향이나 가려진 면 때문에 오차가 납니다. 그 대신 보이는 점들의 X 중앙값을 구하고 프레임 0의 값과 차이를 냅니다. 프레임 1의 저장된 결과는 estimated_relative_x_m ≈ -0.300, authored_relative_x_m = -0.305입니다. 음수는 시뮬레이터 월드의 X가 줄었다는 뜻이며, 약 5.27mm는 두 이동량의 차이입니다.

픽셀 하나로 읽는 RGB·깊이·라벨

저장된 작업대의 첫 프레임에서 큐브와 상판 경계의 3 × 3 픽셀을 확대했습니다. RGB 칸을 눌러 같은 좌표를 비교하세요.

RGB

깊이 (m)

의미 분할 ID

u=613, v=231 · RGB [155, 63, 14] · 3.164 m · 2 (part)

이 영역에서는 가까운 픽셀일수록 깊이 칸이 밝습니다. 라벨 ID는 이 프레임의 JSON에서 읽었습니다.원본 데이터

처음이면 실습 파일부터 받기

GPU 실습은 Isaac Sim을 실행할 머신에서 터미널을 엽니다. CPU 실습은 지금 쓰는 컴퓨터에서 해도 됩니다. 아래 명령은 한 줄씩 입력하고 Enter를 누르세요. 여러 줄짜리 명령 블록은 통째로 복사해도 됩니다.

Shell
cd "$HOME"
git clone https://github.com/james-joobs/awesome-nvidia-physical-ai.git
cd awesome-nvidia-physical-ai
pwd

홈 폴더에 받는 예입니다. 이미 내려받았다면 git clone은 건너뛰고 내 실습 폴더로 이동합니다. 새 터미널을 열 때마다 pwd의 출력 끝이 awesome-nvidia-physical-ai인지 확인하세요. 그래야 labs/로 시작하는 파일을 찾을 수 있습니다.

따라 하기

준비물 · 일반 컴퓨터에서 Python 3.12와 터미널을 엽니다. 이 단계는 저장된 카메라 데이터로 계산하므로 GPU 없이 할 수 있습니다.

1. 점군을 계산할 Python 준비하기

이 레포의 폴더에서 아래를 실행합니다. 가상환경을 따로 만들면 다른 Python 프로젝트의 패키지와 섞이지 않습니다.

Shell
python3.12 -m venv .venv-workbench
source .venv-workbench/bin/activate
python -m pip install -r labs/scene-to-data/requirements-check.txt

2. 카메라 데이터 네 세트를 읽기

같은 터미널에서 아래 명령을 실행합니다. --recorded는 동봉한 USD와 카메라 데이터를 읽으라는 뜻입니다. runs/workbench-replay에 파일과 결과를 저장합니다.

Shell
python labs/scene-to-data/check_workbench.py runs/workbench-replay --recorded

check/frame-00.png에서 사진과 깊이, 큐브 마스크를 나란히 봅니다. 이동량은 check/point-cloud/result.json의 estimated_relative_x_m에 미터 단위로 나옵니다. 새 카메라 데이터를 만들고 싶다면 작업대 완주 과제로 이어가세요. 작업대 USD · 점군 재생 장면 · 12프레임 Replicator 실습

테스트 결과

STEP을 다시 읽어 상판의 가로·세로·두께가 1,200 × 600 × 40mm인지 검사했습니다. 큐브 중심은 0.8615m에서 멈췄습니다. 네 장의 점군에서 계산한 X축 이동량의 최대 오차는 약 5.3mm였습니다. 첫 프레임에서 보이는 표면을 기준으로 이동량을 비교한 값입니다. 촬영 당시 측정값

실행 영상과 기록

실습 소스 코드

make_step.pyGitHub에서 파일 보기
Python
"""Create the pilot's STEP file and tessellate the re-imported solids."""
import argparse
import json
from pathlib import Path

import cadquery as cq
from cadquery import exporters, importers

parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("output", type=Path)
folder = parser.parse_args().output
folder.mkdir(parents=True, exist_ok=True)
def box(w, d, h, x, y, z, bevel=0):
    part = cq.Workplane("XY").box(w, d, h)
    if bevel:
        part = part.edges("|Z").fillet(bevel)
    return part.val().translate((x, y, z))

parts = [
    box(1200, 600, 40, 0, 0, 780, 9),
    box(1000, 510, 22, 0, 0, 124, 6),
]
parts.extend(box(48, 48, 758, x, y, 379, 4) for x in (-516,516) for y in (-224,224))
parts.extend(box(1032, 29, 41, 0, y, 721, 4) for y in (-224,224))
parts.extend(box(29, 448, 41, x, 0, 721, 4) for x in (-516,516))
step = folder / "workbench.step"
exporters.export(cq.Compound.makeCompound(parts), str(step))

solids = importers.importStep(str(step)).solids().vals()
assert len(solids) == len(parts)
top = max(solids, key=lambda solid: solid.Center().z)
size = top.BoundingBox()
assert abs(size.xlen-1200) < 0.01 and abs(size.ylen-600) < 0.01 and abs(size.zlen-40) < 0.01
result = []
for number, solid in enumerate(solids):
    name = "Tabletop" if solid is top else "Shelf" if abs(solid.Center().z-124)<1 else f"Frame_{number:02d}"
    vertices, triangles = solid.tessellate(0.7)
    result.append({"name":name, "points":[[u/1000 for u in v.toTuple()] for v in vertices],
                   "indices":[index for face in triangles for index in face]})
(folder/"cad_meshes.json").write_text(json.dumps(result))
print(f"STEP round trip: {len(solids)} solids")
print(f"Measured tabletop (mm): {size.xlen:.2f} x {size.ylen:.2f} x {size.zlen:.2f}")
print(f"STEP: {step.name} | tessellated points: {sum(len(m['points']) for m in result)}")
workbench_final_take.pyGitHub에서 파일 보기
Python
"""Render the actual CAD-derived scene and Replicator outputs on RTX."""
import argparse
import json
import time
from pathlib import Path

from isaacsim import SimulationApp

parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("mesh", type=Path)
parser.add_argument("output", type=Path)
parser.add_argument("--headless", action="store_true", help="Capture without opening a viewport")
args = parser.parse_args()
cap = args.output.resolve()
cap.mkdir(parents=True, exist_ok=True)
app = SimulationApp({
    "headless": args.headless, "width": 1440, "height": 900, "window_width": 1440, "window_height": 900,
    "renderer": "RaytracedLighting", "anti_aliasing": 2, "fast_shutdown": True,
})

import carb
import numpy as np
from PIL import Image
import omni.physx
import omni.replicator.core as rep
import omni.timeline
import omni.usd
from isaacsim.core.utils.semantics import add_labels
from omni.kit.viewport.utility import get_active_viewport
from pxr import Gf, Sdf, Usd, UsdGeom, UsdLux, UsdPhysics, UsdShade

settings = carb.settings.get_settings()
settings.set_bool("/physics/updateToUsd", True)
settings.set_bool("/omni/replicator/captureOnPlay", False)
omni.usd.get_context().new_stage()
stage = omni.usd.get_context().get_stage()
UsdGeom.SetStageUpAxis(stage, UsdGeom.Tokens.z)
UsdGeom.SetStageMetersPerUnit(stage, 1.0)
world = UsdGeom.Xform.Define(stage,"/World")
stage.SetDefaultPrim(world.GetPrim())
scene = UsdPhysics.Scene.Define(stage,"/World/Physics")
scene.CreateGravityDirectionAttr(Gf.Vec3f(0,0,-1))
scene.CreateGravityMagnitudeAttr(9.81)

def material(name, rgb, roughness, metallic=0.0):
    target = UsdShade.Material.Define(stage, "/World/Looks/"+name)
    shader = UsdShade.Shader.Define(stage,target.GetPath().AppendChild("Shader"))
    shader.CreateIdAttr("UsdPreviewSurface")
    shader.CreateInput("diffuseColor",Sdf.ValueTypeNames.Color3f).Set(Gf.Vec3f(*rgb))
    shader.CreateInput("roughness",Sdf.ValueTypeNames.Float).Set(roughness)
    shader.CreateInput("metallic",Sdf.ValueTypeNames.Float).Set(metallic)
    target.CreateSurfaceOutput().ConnectToSource(shader.ConnectableAPI(),"surface")
    return target

def bind(prim, look):
    UsdShade.MaterialBindingAPI.Apply(prim).Bind(look)

def block(name, location, dimensions, look):
    obj=UsdGeom.Cube.Define(stage, "/World/"+name)
    obj.CreateSizeAttr(1.0)
    obj.AddTranslateOp().Set(Gf.Vec3d(*location))
    obj.AddScaleOp().Set(Gf.Vec3d(*dimensions))
    bind(obj.GetPrim(),look)
    return obj

top_look=material("Top",(.48,.30,.15),.34)
metal=material("Metal",(.039,.16,.19),.31,.54)
shelf=material("Shelf",(.075,.19,.20),.43,.35)
floor=material("Floor",(.072,.099,.12),.56)
orange=material("Orange",(.90,.22,.031),.33,.05)
mint=material("Mark",(.06,.42,.38),.45)
light_label=material("White",(.72,.78,.79),.55)
root=UsdGeom.Xform.Define(stage,"/World/Workbench")
for part in json.loads(args.mesh.read_text()):
    m=UsdGeom.Mesh.Define(stage,root.GetPath().AppendChild(part["name"]))
    m.CreatePointsAttr([Gf.Vec3f(*p) for p in part["points"]])
    m.CreateFaceVertexCountsAttr([3]*(len(part["indices"])//3))
    m.CreateFaceVertexIndicesAttr(part["indices"])
    m.CreateSubdivisionSchemeAttr("none")
    m.CreateDoubleSidedAttr(True)
    bind(m.GetPrim(),top_look if part["name"]=="Tabletop" else shelf if part["name"]=="Shelf" else metal)
    if part["name"]=="Tabletop":
        UsdPhysics.CollisionAPI.Apply(m.GetPrim())
        UsdPhysics.MeshCollisionAPI.Apply(m.GetPrim()).CreateApproximationAttr("convexHull")
add_labels(root.GetPrim(), ["workbench"], instance_name="class")
ground=block("Floor",(0,0,-.037),(40,40,.07),floor)
UsdPhysics.CollisionAPI.Apply(ground.GetPrim())
for i,x in enumerate((-0.83,0.83)):
    block(f"FloorMark{i}",(x,0,.001),(.021,1.65,.002),mint)
for i,y in enumerate((-.82,.82)):
    block(f"CrossMark{i}",(0,y,.001),(1.66,.021,.002),mint)
for i,x in enumerate((-.30,.30)):
    block(f"TopMark{i}",(x,.07,.801),(.007,.27,.002),light_label)
body = UsdGeom.Xform.Define(stage, "/World/TestPart")
cube_location = body.AddTranslateOp()
cube_location.Set(Gf.Vec3d(.125, -.075, 1.23))
cube = UsdGeom.Cube.Define(stage, body.GetPath().AppendChild("Geometry"))
cube.CreateSizeAttr(.123)
bind(cube.GetPrim(), orange)
UsdPhysics.CollisionAPI.Apply(cube.GetPrim())
UsdPhysics.RigidBodyAPI.Apply(body.GetPrim()).CreateRigidBodyEnabledAttr(True)
UsdPhysics.MassAPI.Apply(body.GetPrim()).CreateMassAttr(.21)
add_labels(cube.GetPrim(), ["part"], instance_name="class")

def aim(prim, pos, target):
    xf=Gf.Matrix4d(1).SetLookAt(Gf.Vec3d(*pos),Gf.Vec3d(*target),Gf.Vec3d(0,0,1)).GetInverse()
    UsdGeom.Xformable(prim).AddTransformOp().Set(xf)

camera=UsdGeom.Camera.Define(stage,"/World/InspectionCamera")
aim(camera.GetPrim(), (2.04,-2.42,1.83), (0,0,.61))
camera.CreateFocalLengthAttr(36)
camera.CreateClippingRangeAttr(Gf.Vec2f(.05,35))
ambient=UsdLux.DomeLight.Define(stage,"/World/Ambient")
ambient.CreateIntensityAttr(380)
key=UsdLux.RectLight.Define(stage,"/World/Key")
aim(key.GetPrim(),(-1.35,-1.19,2.82),(0,0,.5))
key.CreateWidthAttr(2.15)
key.CreateHeightAttr(1.65)
key.CreateIntensityAttr(1250)
rim=UsdLux.RectLight.Define(stage,"/World/Rim")
aim(rim.GetPrim(),(1.8,1.4,2.1),(0,0,.67))
rim.CreateWidthAttr(1.9)
rim.CreateHeightAttr(1.6)
rim.CreateIntensityAttr(710)
rim.CreateColorAttr(Gf.Vec3f(.55,.81,1.0))

cap.mkdir(exist_ok=True)
stage.Export(str(cap/"workbench_scene.usda"))
for _ in range(12):
    app.update()
viewport = None if args.headless else get_active_viewport()
if viewport:
    viewport.camera_path = camera.GetPath()
for _ in range(10):
    app.update()
rp=rep.create.render_product(camera.GetPath(),(1280,720))
timeline = omni.timeline.get_timeline_interface()
annotators = {
    "rgb": rep.AnnotatorRegistry.get_annotator("rgb"),
    "distance_to_image_plane": rep.AnnotatorRegistry.get_annotator("distance_to_image_plane"),
    "semantic_segmentation": rep.AnnotatorRegistry.get_annotator("semantic_segmentation",
                                                                 init_params={"colorize": False}),
}
for annotator in annotators.values():
    annotator.attach([rp])
for _ in range(12):
    rep.orchestrator.step(rt_subframes=8, pause_timeline=True)
    sample = np.asarray(annotators["rgb"].get_data())
    if sample.ndim == 3 and sample[:,:,:3].mean() > 5:
        break
else:
    raise RuntimeError("RTX camera did not produce an initialized RGB frame")
print("STAGE_READY: CAD-derived OpenUSD scene, Replicator camera 1280x720", flush=True)
if viewport:
    (cap/"viewport-ready").touch()
    until = time.monotonic() + 4
    while time.monotonic() < until:
        app.update()

def cube_position():
    value = omni.physx.get_physx_interface().get_rigidbody_transformation(str(body.GetPath()))
    return tuple(float(x) for x in value["position"]) if value.get("ret_val",False) else None

timeline.play()
positions = []
for index in range(48):
    rep.orchestrator.step(delta_time=1/30, rt_subframes=2, pause_timeline=False)
    positions.append(cube_position())
    if index in (0, 20, 47):
        print(f"PHYSICS_FRAME {index:02d} | part {positions[-1]}", flush=True)
timeline.stop()
for _ in range(3):
    app.update()

out = cap/"replicator"
out.mkdir(exist_ok=True)
focus_values = []
for frame, x in enumerate((.125, -.18, .23, .03)):
    cube_location.Set(Gf.Vec3d(x, -.075, .8615))
    key.GetIntensityAttr().Set(1100 + 170 * frame)
    for _ in range(3):
        app.update()
    rep.orchestrator.step(delta_time=0, rt_subframes=10, pause_timeline=True)
    rgb = np.asarray(annotators["rgb"].get_data(), np.uint8)
    depth = np.asarray(annotators["distance_to_image_plane"].get_data(), np.float32)
    value = annotators["semantic_segmentation"].get_data()
    ids = np.asarray(value["data"], np.uint32)
    labels = value["info"]["idToLabels"]
    part_labels = [int(i) for i,label in labels.items() if
                   (label.get("class") if isinstance(label,dict) else label) == "part"]
    part = np.isin(ids, part_labels)
    assert rgb.shape[0:2] == depth.shape == ids.shape == (720, 1280)
    assert part.any() and np.isfinite(depth[part]).all(), (frame, labels)
    Image.fromarray(rgb[:,:,:3]).save(out/f"rgb_{frame:04d}.png")
    np.save(out/f"distance_to_image_plane_{frame:04d}.npy",depth)
    np.save(out/f"semantic_segmentation_{frame:04d}.npy",ids)
    (out/f"semantic_segmentation_labels_{frame:04d}.json").write_text(json.dumps(labels))
    approx_part_depth = float(np.median(depth[part]))
    focus_values.append({"frame":frame, "part_pixels":int(part.sum()), "part_depth_m":approx_part_depth})
    print(f"CAPTURE_FRAME {frame:02d} | part pixels {part.sum()} | median depth {approx_part_depth:.3f} m",flush=True)
    if viewport:
        until=time.monotonic()+1.1
        while time.monotonic()<until:
            app.update()

valid = [point[2] for point in positions if point is not None]
expected = .8 + .123/2
summary = {"physics_frames":len(positions),"tabletop_top_m":.8,"expected_rest_center_m":expected,
           "first_cube_z_m":valid[0] if valid else None,"final_cube_z_m":valid[-1] if valid else None,
           "rest_within_2cm":bool(valid and abs(valid[-1]-expected)<.02),
           "replicator_frames":focus_values}
(cap/"workbench-result.json").write_text(json.dumps(summary,indent=2))
print("RESULT",json.dumps(summary),flush=True)
if viewport:
    (cap/"viewport-result").touch()
    until = time.monotonic() + 10
    while time.monotonic() < until:
        app.update()
app.close()
backproject.pyGitHub에서 파일 보기
Python
"""Lift Isaac Sim camera depth into world coordinates and test relative displacement."""

import argparse
import json
from pathlib import Path

import numpy as np
from pxr import Usd, UsdGeom

TRUE_CUBE_X = [.125, -.18, .23, .03]


def reconstruct(capture, output):
    output.mkdir(parents=True, exist_ok=True)
    stage = Usd.Stage.Open(str(capture / "workbench_scene.usda"))
    camera = UsdGeom.Camera.Get(stage, "/World/InspectionCamera")
    assert camera
    view = np.array(UsdGeom.XformCache().GetLocalToWorldTransform(camera.GetPrim()), dtype=np.float64)
    focal = camera.GetFocalLengthAttr().Get()
    aperture = camera.GetHorizontalApertureAttr().Get()
    assert focal > 0 and aperture > 0
    rows = []
    depths = capture / "replicator"
    for i, x_ref in enumerate(TRUE_CUBE_X):
        d = np.load(depths / f"distance_to_image_plane_{i:04}.npy", allow_pickle=False)
        seg = np.load(depths / f"semantic_segmentation_{i:04}.npy", allow_pickle=False)
        labels = json.loads((depths / f"semantic_segmentation_labels_{i:04}.json").read_text())
        part_ids = [int(key) for key, value in labels.items()
                    if (value.get("class") if isinstance(value, dict) else value) == "part"]
        y, x = np.nonzero(np.isin(seg, part_ids) & np.isfinite(d) & (d > 0))
        height, width = d.shape
        fx = focal / aperture * width
        z = d[y, x]
        local = np.column_stack(((x + .5 - width / 2) * z / fx, (height / 2 - y - .5) * z / fx, -z, np.ones_like(z)))
        world = (local @ view)[:, :3]
        assert world.shape[0] >= 1000 and np.isfinite(world).all()
        midpoint = np.median(world, axis=0)
        np.save(output / f"surface-{i:02}.npy", world[::8].astype(np.float32))
        rows.append({"frame": i, "authored_center_x_m": x_ref, "visible_surface_median_xyz_m": midpoint.tolist(),
                     "valid_surface_pixels": len(world)})
    initial = rows[0]["visible_surface_median_xyz_m"][0]
    for row in rows:
        estimate = row["visible_surface_median_xyz_m"][0] - initial
        reference = row["authored_center_x_m"] - TRUE_CUBE_X[0]
        row.update({"estimated_relative_x_m": estimate, "authored_relative_x_m": reference,
                    "absolute_displacement_error_mm": abs(estimate-reference)*1000})
        print(f"frame {row['frame']} | measured dx {estimate:+.3f} m | authored {reference:+.3f} m", flush=True)
    result = {
        "camera": "/World/InspectionCamera", "depth_channel": "distance_to_image_plane",
        "projection_assumption": "centered camera with horizontal aperture preserved and square pixels",
        "baseline": "frame 0 surface median; used only for displacement, not absolute center estimation",
        "authored_cube_x_source": "workbench_final_take.py",
        "frames": rows,
    }
    (output / "result.json").write_text(json.dumps(result, indent=2) + "\n")
    return result


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("capture", type=Path)
    parser.add_argument("output", type=Path)
    args = parser.parse_args()
    reconstruct(args.capture, args.output)


if __name__ == "__main__":
    main()
check_workbench.pyGitHub에서 파일 보기
Python
"""Check the CAD workbench capture on a CPU, from an archive or a fresh run."""

import argparse
import json
import shutil
from math import isfinite
from pathlib import Path
from zipfile import ZipFile

import numpy as np
from PIL import Image
from pxr import Usd, UsdGeom, UsdPhysics

from backproject import TRUE_CUBE_X, reconstruct

LAB = Path(__file__).resolve().parent
SIZE = (1280, 720)
CHANNELS = ("rgb_{:04}.png", "distance_to_image_plane_{:04}.npy",
            "semantic_segmentation_{:04}.npy", "semantic_segmentation_labels_{:04}.json")
FRAME_FILES = [tuple(pattern.format(i) for pattern in CHANNELS) for i in range(len(TRUE_CUBE_X))]


def require(condition, message):
    if not condition:
        raise ValueError(message)


def unpack_recording(capture):
    target = capture / "replicator"
    target.mkdir(parents=True, exist_ok=True)
    shutil.copyfile(LAB / "workbench_scene.usda", capture / "workbench_scene.usda")
    with ZipFile(LAB / "replicator-data.zip") as archive:
        for names in FRAME_FILES:
            for name in names:
                (target / name).write_bytes(archive.read(f"replicator/{name}"))


def check_scene(capture):
    stage = Usd.Stage.Open(str(capture / "workbench_scene.usda"))
    require(UsdGeom.GetStageMetersPerUnit(stage) == 1, "Expected USD scene units in meters")
    require(UsdGeom.GetStageUpAxis(stage) == UsdGeom.Tokens.z, "Expected a Z-up USD stage")
    tabletop = stage.GetPrimAtPath("/World/Workbench/Tabletop")
    require(tabletop and tabletop.HasAPI(UsdPhysics.CollisionAPI), "Missing tabletop collision geometry")
    bounds = UsdGeom.BBoxCache(Usd.TimeCode.Default(), [UsdGeom.Tokens.default_])
    box = bounds.ComputeWorldBound(tabletop).ComputeAlignedBox()
    dimensions = np.array(box.GetSize()) * 1000
    require(np.allclose(dimensions, (1200, 600, 40), rtol=0, atol=.5),
            f"Unexpected tabletop dimensions (mm): {dimensions}")
    cube = UsdGeom.Cube.Get(stage, "/World/TestPart/Geometry")
    require(cube and cube.GetSizeAttr().HasAuthoredValue(), "Missing test cube size")
    expected_z = float(box.GetMax()[2] + cube.GetSizeAttr().Get() / 2)
    return dimensions.tolist(), expected_z


def check_frames(capture, output):
    folder = capture / "replicator"
    expected_rgb = {files[0] for files in FRAME_FILES}
    require({file.name for file in folder.glob("rgb_*.png")} == expected_rgb,
            f"Expected {len(expected_rgb)} numbered RGB frames in {folder}")
    stats = []
    for index, (rgb_file, depth_file, ids_file, labels_file) in enumerate(FRAME_FILES):
        with Image.open(folder / rgb_file) as png:
            rgb = png.convert("RGB")
        depth = np.load(folder / depth_file, allow_pickle=False)
        ids = np.load(folder / ids_file, allow_pickle=False)
        labels = json.loads((folder / labels_file).read_text())
        require(rgb.size == SIZE and depth.shape == ids.shape == SIZE[::-1], f"Frame {index}: mismatched shapes")
        require(depth.dtype.kind == "f" and ids.dtype.kind in "iu", f"Frame {index}: wrong depth or mask dtype")
        part_ids = [int(key) for key, label in labels.items()
                    if (label.get("class") if isinstance(label, dict) else label) == "part"]
        mask = np.isin(ids, part_ids)
        part_depth = depth[mask]
        require(part_depth.size >= 1000, f"Frame {index}: fewer than 1,000 labeled cube pixels")
        require(np.isfinite(part_depth).all() and (part_depth > 0).all(),
                f"Frame {index}: cube depth must be finite and positive")
        stats.append({"frame": index, "part_pixels": int(part_depth.size),
                      "median_camera_depth_m": float(np.median(part_depth))})
        if index == 0:
            valid = np.isfinite(depth) & (depth > 0)
            depth_gray = np.zeros(depth.shape, dtype=np.uint8)
            depth_gray[valid] = (255 * (1 - np.clip(depth[valid] / 6, 0, 1))).astype(np.uint8)
            images = (rgb, Image.fromarray(depth_gray), Image.fromarray(mask.astype(np.uint8) * 255))
            preview = Image.new("RGB", (1280, 240))
            for panel, image in enumerate(images):
                preview.paste(image.resize((426, 240)), (panel * 427, 0))
            preview.save(output / "frame-00.png")
    return stats


def check(capture, recorded):
    if recorded:
        require(not (capture / "workbench-result.json").exists(),
                "Use a separate directory for archived frames to preserve the fresh capture")
    output = capture / "check"
    output.mkdir(parents=True, exist_ok=True)
    report_file = output / "report.json"
    report_file.unlink(missing_ok=True)
    if recorded:
        unpack_recording(capture)

    dimensions, expected_z = check_scene(capture)
    final_z = None
    if not recorded:
        summary = json.loads((capture / "workbench-result.json").read_text())
        initial_z, final_z = summary["first_cube_z_m"], summary["final_cube_z_m"]
        require(initial_z is not None and final_z is not None and isfinite(initial_z) and isfinite(final_z)
                and initial_z > expected_z + .05 and abs(final_z - expected_z) <= .02,
                f"Cube did not settle on the tabletop at {expected_z:.4f} m (final: {final_z})")

    frames = check_frames(capture, output)
    points = reconstruct(capture, output / "point-cloud")
    max_error = max(frame["absolute_displacement_error_mm"] for frame in points["frames"])
    require(isfinite(max_error) and max_error <= 10, f"X displacement error {max_error:.2f} mm exceeds 10 mm")
    report = {
        "input": "recorded" if recorded else "fresh",
        "tabletop_mm": dimensions,
        "resolution_px": SIZE,
        "frames": frames,
        "max_displacement_error_mm": max_error,
        "expected_rest_center_m": expected_z,
        "checked_physics_log": not recorded,
        "final_cube_center_m": final_z,
    }
    report_file.write_text(json.dumps(report, indent=2) + "\n")
    print(f"PASS: {len(frames)} RGB/depth/mask sets at {SIZE[0]}x{SIZE[1]}")
    print(f"PASS: maximum X displacement error {max_error:.2f} mm (limit: 10 mm)")
    if not recorded:
        print(f"PASS: captured cube center {final_z:.4f} m (expected {expected_z:.4f} m)")
    print(f"Report: {report_file}")


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("capture", type=Path, help="Run directory for inputs and generated results")
    parser.add_argument("--recorded", action="store_true", help="Unpack and check the bundled camera frames")
    args = parser.parse_args()
    try:
        check(args.capture, args.recorded)
    except (OSError, ValueError, KeyError) as error:
        parser.exit(1, f"Check failed: {error}\n")