ComfyUI-3D-motion-reference

ComfyUI-3D-motion-reference

An interactive 3D motion reference custom node for ComfyUI. It provides a real-time Three.js interactive viewport containing customizable 3D box layouts, allowing users to translate, rotate, and scale them in all directions. It then captures the canvas animation as a video and uploads it directly to the ComfyUI inputs directory to be processed as a VIDEO type.

This custom node's canvas integration is based on ComfyUI-qwenmultiangle.

Features

• Interactive 3D Viewport - Inspect the scene from any angle using MapControls:
  • Drag to pan
  • Ctrl+Drag to rotate camera
  • Mouse wheel to zoom
• Interactive Object Editing - Select boxes directly with a click and manipulate them using standard 3D gizmos:
  • Move: Translate on X, Y, and Z axes.
  • Rotate: Rotate in all 3D orientations.
  • Scale: Scale width, height, and depth.
• Aspect Ratio Control - Change between standard aspect ratios (16:9, 9:16) with automatically adjusted viewport layouts.
• Media Capture - Capture the WebGL canvas as a high-fidelity video recording matching the selected length in seconds (4-15s).
• Targeted downstream execution - Mutes unconnected nodes in the graph when you start recording, so only connected workflows process the output video.
• Transform Persistence - All custom positions, rotations, and scales are saved in the node's properties, persisting when you save or reload your workflows.

Installation

1. Navigate to your ComfyUI custom nodes directory:

   cd ComfyUI/custom_nodes
   

2. Clone this repository:

   git clone https://github.com/arturitu/ComfyUI-3D-motion-reference.git
   

3. Restart ComfyUI.

Development

This project uses Vue 3, TypeScript, and Vite for compiling the frontend widgets. The backend is built using ComfyUI's V3 node API.

Prerequisites

• Node.js 18+
• npm

Build Commands

# Install dependencies
npm install

# Build for production
npm run build

# Build with watch mode (for development)
npm run dev

# Type check code
npm run typecheck

Project Structure

ComfyUI-3D-motion-reference/
├── src/
│   ├── main.ts                        # Extension registration and mounting
│   ├── App.vue                        # Viewport GUI and recording logic
│   ├── ThreeScene.ts                  # Three.js renderer and TransformControls engine
│   ├── types.ts                       # TypeScript type definitions
│   └── components/
│       └── SceneCanvas.vue            # WebGL Canvas container
├── nodes.py                           # Python ComfyUI Node definition & upload API
└── __init__.py                        # Node package entrypoint

License

This project is licensed under the MIT License.