SAM3D Cam Shot Toolkit

SAM3D Body ComfyUI Cam Shot Toolkit

Minimal ComfyUI custom node package for:

• Cam Shot Toolkit: Load SAM3D Model
• Cam Shot Toolkit: Load SAM3 Person Detector
• Cam Shot Toolkit: Process Image
• Cam Shot Toolkit: Render Offset View

This repo is a focused extraction from a larger SAM3DBody node pack, trimmed for calibrated pose-to-camera-shot workflows.

Install

1. Clone or copy this repo into ComfyUI/custom_nodes/.
2. Install dependencies with ComfyUI-Manager or manually:

python -m pip install -r requirements.txt

3. Restart ComfyUI.

This package installs into ComfyUI's active Python environment. It does not attempt to replace ComfyUI's existing torch / torchvision install. A working ComfyUI CUDA environment is expected already.

Registry Publishing

This repository is prepared for Comfy Registry publishing.

Before publishing:

1. Set your real PublisherId in pyproject.toml.
2. Create a Registry publishing API key for that publisher.
3. Publish with:

comfy node publish

Included

• SAM3D model loader with Hugging Face auto-download
• SAM3 person detector loader with official gated repo support and ungated mirror fallback for prompt-based multi-person detection
• single-image SAM3D processing node
• person selection for SAM3D outputs: person_index=-1 uses all detected people, while 0..N selects a specific detected person. When no mask is connected, nonzero selection modes automatically run a torchvision person detector so multi-person inputs produce multiple SAM3D crops.
• calibrated offset renderer with pivot, background, and lighting controls
• interactive browser viewer for scouting the render camera with orbit, pan, roll, and dolly controls
• optional render auto mode that ignores saved viewer camera state and realigns from each SAM3D input for API workflows
• rigged GLB export (one named mesh + armature per person, matching capture camera)
• PoseRig node group for procedural pose-reference scenes (CamShotToolkit/posing):
  • Save Pose Rig — a reconstruction becomes a named rig asset: <set>/<label>.glb (rigged, feet on the floor, opens in Blender) plus a rig.json entry with actor count, footprint, capture camera and source hash.
  • Load Pose Rigs — reads a rig set back (numpy-only GLB reader).
  • Camera Spec — real-unit mount (height / tilt / hfov / standoff / lateral) plus additive position and rotation offsets and per-axis seeded jitter ranges (0 = locked). Also emits the interactive_state string the offset renderer honours.
  • Assemble Scene — rolls K actor groups (a weighted distribution) onto the floor with footprint clearance, in-frame and 2D occlusion checks; deterministic reroll-then-drop policy; pinned placements via JSON; per-actor mirror/yaw.
  • Render Clay Grid — clay render of the assembled scene, a proximity-faded 1 ft floor grid drawn last and z-tested against the bodies, union + per-actor MASKs with optional dilation, and a scene manifest JSON (labels, actors, effective camera).

Node Categories

• CamShotToolkit
• CamShotToolkit/processing
• CamShotToolkit/visualization
• CamShotToolkit/io
• CamShotToolkit/posing

Tests

tests/ covers the numpy core of the PoseRig group (no ComfyUI needed):

python -m pytest -c tests/pytest.ini --rootdir tests tests -q

Notes

• Model weights are downloaded automatically on first use into ComfyUI/models/sam3dbody.
• SAM3 detector weights are downloaded into ComfyUI/models/sam3_person_detector. The detector loader tries facebook/sam3 first in auto mode and falls back to an ungated mirror such as jetjodh/sam3 if official access is gated.
• The render node uses a self-contained NumPy mesh rasterizer. It does not use pyrender, PyOpenGL, pyglet, OSMesa, or EGL.
• The browser viewer remains a Three.js preview for camera scouting. The saved camera state is rendered by the backend rasterizer during workflow execution.
• install.py is intentionally a no-op for Registry compliance. Dependency installation should be handled by ComfyUI-Manager or an explicit pip install -r requirements.txt.

Donations & Support

If this saves you time, you can support the work here:

• Patreon
• GitHub Sponsors
• PayPal