Griptape Nodes Blender Integration

Camera capture nodes for Blender integration with Griptape workflows.

Overview

This package provides Griptape nodes for capturing camera views from Blender scenes. The integration works through a simple socket server that runs inside Blender, providing a reliable and efficient communication channel.

Architecture

┌─────────────────┐    Socket/TCP     ┌──────────────────┐    bpy Python API ┌─────────┐
│ Griptape Nodes  │ ←─────────────────→ │  Socket Server   │ ←───────────────→ │ Blender │
│   (Clients)     │     JSON/8765     │  (Inside Blender) │                   │ (3D App) │
└─────────────────┘                   └──────────────────┘                   └─────────┘

Features

• ✅ Simple socket communication - No complex async context issues
• ✅ Runs inside Blender - Direct access to bpy API and scene data
• ✅ Real-time camera capture - Render images from any camera in scene
• ✅ Comprehensive camera metadata - Focal length, sensor info, DOF, transforms
• ✅ Dynamic UI updates - Camera dropdowns and metadata labels update automatically
• ✅ Flow control support - Both nodes integrate seamlessly into control workflows
• ✅ Always fresh data - Camera List Node re-evaluates on every workflow run
• ✅ Automatic engine handling - Fixes Eevee Next and GPU issues automatically
• ✅ No external dependencies - Just Python standard library
• ✅ Easy setup - Copy/paste script into Blender

Files

• blender/blender_socket_server.py - Socket server that runs inside Blender
• blender/socket_client.py - Socket client utilities for Griptape nodes
• blender/camera_capture.py - Camera capture node for Griptape workflows
• blender/camera_list.py - Node to list available cameras in Blender scene

Quick Setup

1. Start Blender Socket Server

1. Open Blender
2. Go to Scripting workspace (tab at top)
3. Create new text file (click "New")
4. Copy the entire contents of blender/blender_socket_server.py
5. Paste into Blender's text editor
6. Click "Run Script" button

The server will auto-start and show:

✓ Blender Socket Server started on localhost:8765
Ready to receive commands from Griptape nodes

2. Use Griptape Nodes

The camera capture and camera list nodes will automatically connect to the socket server running in Blender.

Server Controls

In Blender Console:

start_server()    # Start the socket server
stop_server()     # Stop the socket server  
server_status()   # Check if running

In Blender UI:

• 3D Viewport → Press N → Griptape tab
• Start/Stop buttons with status indicator
• Port information display

Add your library to your installed Engine!

If you haven't already installed your Griptape Nodes engine, follow the installation steps HERE. After you've completed those and you have your engine up and running:

1. Copy the path to your griptape_nodes_library.json file within this blender directory. Right click on the file, and Copy Path (Not Copy Relative Path).
2. Start up the engine!
3. Navigate to settings.
4. Open your settings and go to the App Events tab. Add an item in Libraries to Register.
5. Paste your copied griptape_nodes_library.json path from earlier into the new item.
6. Exit out of Settings. It will save automatically!
7. Open up the Libraries dropdown on the left sidebar.
8. Your newly registered library should appear! Drag and drop nodes to use them!

Available Nodes

Camera Capture Node

Captures single frames from Blender cameras with detailed camera metadata display.

Flow Control:

• exec_in - Flow input for control sequencing
• exec_out - Flow output for control sequencing

Parameters:

• cameras_input - Connect to Camera List Node for dynamic camera data (optional)
• camera_name - Name of camera in Blender scene (dropdown updates automatically)
• resolution_x - Image width in pixels (64-4096, default: 1920)
• resolution_y - Image height in pixels (64-4096, default: 1080)
• output_format - PNG or JPEG (default: PNG)
• quality - JPEG quality 1-100 (default: 90)

Camera Metadata Labels (displayed under Camera dropdown):

• Status - Shows if camera is active scene camera
• Focal Length - Lens focal length in mm
• Sensor - Sensor dimensions, fit mode, and camera type
• Depth of Field - DOF settings including focus distance and f-stop
• Transform - Camera location and rotation coordinates

Outputs:

• image_output - Captured image as ImageUrlArtifact
• status_output - Render information and timing

Features:

• ✅ Dynamic camera dropdown - Updates automatically when connected to Camera List Node
• ✅ Rich metadata display - Shows detailed camera properties in real-time
• ✅ Enhanced camera data - Accesses comprehensive Blender camera properties
• ✅ Auto camera validation - Switches to available camera if selection invalid

Camera List Node

Lists all cameras in the current Blender scene with comprehensive metadata.

Flow Control:

• exec_in - Flow input for control sequencing
• exec_out - Flow output for control sequencing

Features:

• ✅ Always re-evaluates - Fetches fresh camera data on every workflow run
• ✅ Comprehensive camera data - Collects detailed camera properties via Blender API
• ✅ Automatic fallback - Falls back to basic data if enhanced collection fails

Outputs:

• cameras_output - Detailed camera info including metadata (ListArtifact)
• camera_count - Total number of cameras found
• status_output - Operation status and connection info

Enhanced Camera Data Collected:

• Basic Transform: Location, rotation, scale, active status
• Lens Properties: Focal length, sensor dimensions, sensor fit mode
• Camera Type: Perspective, orthographic, panoramic
• Field of View: Angular measurements for framing calculations
• Clipping Distances: Near and far render boundaries
• Depth of Field: Focus distance, aperture f-stop settings
• Composition: Camera shift for perspective correction
• Matrix Data: Full 4x4 transformation matrix for precise positioning

Workflow Integration

Connected Workflow (Recommended)

For the best experience, connect Camera List Node → Camera Capture Node:

┌─────────────────┐ cameras_output ┌──────────────────────┐
│ Camera List     │────────────────→│ Camera Capture      │
│                 │                 │                      │
│ • Always fresh  │                 │ • Dynamic dropdown  │
│ • Detailed data │                 │ • Metadata labels   │
│ • Flow control  │                 │ • Auto validation   │
└─────────────────┘                 └──────────────────────┘

Benefits:

• ✅ Camera dropdown updates automatically when scene changes
• ✅ Rich metadata display under camera selection
• ✅ Always current data - Camera List always re-evaluates
• ✅ Seamless flow control - Both nodes support exec in/out

Standalone Usage

Camera Capture Node works independently but with limited features:

• Static camera dropdown (populated at node creation)
• Basic status messages instead of detailed metadata
• Manual refresh required for scene changes

Socket Server Commands

The server responds to these JSON commands on port 8765:

Health Check

{"command": "health_check"}

Scene Information

{"command": "get_scene_info"}

List Cameras

{"command": "list_cameras"}

Render Camera

{
  "command": "render_camera",
  "params": {
    "camera_name": "Camera",
    "width": 1920,
    "height": 1080,
    "format_type": "PNG",
    "quality": 90
  }
}

Execute Code (Enhanced Camera Data)

{
  "command": "execute_code", 
  "params": {
    "code": "import bpy; cameras = [{'name': obj.name, 'focal_length': obj.data.lens} for obj in bpy.data.objects if obj.type == 'CAMERA']"
  }
}

Engine Handling

The server automatically handles render engine issues:

• Eevee Next → Switches to Cycles CPU (headless stability)
• Cycles → Forces CPU rendering (avoids GPU context issues)
• Other engines → CPU-only for maximum stability

Benefits vs MCP Approach

• ✅ No async context issues - Simple socket connections
• ✅ Persistent server - Runs inside Blender, stays responsive
• ✅ Easy debugging - Clear JSON communication
• ✅ No complex dependencies - Just Python sockets
• ✅ Better performance - Direct bpy access, no process spawning

Troubleshooting

"Could not connect to Blender server at localhost:8765"

1. Make sure Blender is running with the socket server script
2. Check server status in Blender console: server_status()
3. Restart server if needed: stop_server() then start_server()
4. Check port availability - make sure nothing else is using port 8765

"PIL not available for PNG encoding"

The server needs PIL for image encoding. Install in Blender's Python:

/Applications/Blender.app/Contents/Resources/4.4/python/bin/python3.11 -m pip install Pillow

Socket Server Not Starting

1. Check Blender console for error messages
2. Verify script is run inside Blender (not external Python)
3. Try different port by editing the script: BlenderSocketServer(port=8766)

Render Issues

• Server forces CPU rendering for stability
• Automatically switches problematic engines (Eevee Next)
• Check Blender console for render error messages

Requirements

• Blender 3.0+ (tested with 4.4.3)
• Python 3.8+ (included with Blender)
• Pillow (for image encoding, install in Blender's Python)

No External Dependencies

Unlike the previous MCP approach, this socket-based solution requires no external Python packages in your Griptape environment. All communication happens through standard Python sockets.