cinema4d-mcp

# Cinema 4D MCP ## Source of Truth This skill targets Vlad's fork of Cinema 4D MCP: [vladmdgolam/cinema4d-mcp](https://github.com/vladmdgolam/cinema4d-mcp). Relevant fork additions: - `inspect_redshift_materials` - read-only Redshift inspector for assignments, preview-derived colors, readable description/container fields, and best-effort graph probing. **Note:** this tool may skip RS materials as `not_redshift_like` (type 5703) — use `execute_python_script` with the `maxon` API for full RS node graph extraction instead (see Redshift Material Extraction section). - Duplicate-safe material targeting - the inspector accepts `material_index` and returns stable scene indices plus duplicate-name hints when names collide. - Redshift GraphView fallback - when node-space access fails but `import redshift` works, the inspector falls back to `redshift.GetRSMaterialNodeMaster(...)` and reports GraphView nodes plus resolved connections. - The loaded C4D plugin may lag behind the repo copy. After plugin edits, restart Cinema 4D before trusting new tool behavior. ## Tool Selection Use **structured MCP tools** (`get_scene_info`, `list_objects`, `add_primitive`, etc.) for simple operations. Use **`execute_python_script`** as the primary path for non-trivial extraction. It avoids wrapper/schema mismatches, gives full `c4d` + `maxon` API access, and allows proper frame stepping control. This is especially important for **Redshift material extraction** — the `maxon` node-space API gives full access to RS node graphs, which other tools may miss. Use **`inspect_redshift_materials`** as a quick overview of material assignments and preview colors, but be aware it may skip RS materials as `not_redshift_like` if they use type 5703 wrappers. For full RS node graph data, use `execute_python_script` with the `maxon` API pattern documented in the Redshift section. ## Health Check (Always First) 1. `get_scene_info` - verify connection 2. `execute_python_script` with `print("ok")` - verify Python works 3. If both work, extraction is possible even when other tools are broken ## Critical Rules ### 1. World vs Local Coordinates `GeGetMoData()` returns cloner-local positions. Always apply global matrix: ```python mg = cloner.GetMg() world_pos = mg * m.off # LOCAL -> WORLD ``` Missing this shifts everything by the cloner's global offset. ### 2. Visibility Constants Are Swapped - `MODE_OFF = 1` (not 0!) - `MODE_ON = 0` (not 1!) - `MODE_UNDEF = 2` (default/inherit) Always use `c4d.MODE_OFF` / `c4d.MODE_ON`, never raw integers. ### 3. Sequential Frame Stepping MoGraph effectors accumulate state. Iterate 0->N sequentially: ```python for frame in range(start, end + 1): doc.SetTime(c4d.BaseTime(frame, fps)) doc.ExecutePasses(None, True, True, True, c4d.BUILDFLAGS_NONE) # NOW read data ``` Never jump to arbitrary frames. Never skip `ExecutePasses`. ### 4. Split Heavy Bakes MCP scripts timeout on large frame ranges (~20-30s default, some forks 60s). Bake in chunks (e.g., frames 0-200, then 200-400), combine afterward. Log progress with `print()`. ### 5. Iterative Traversal Only Use stack-based traversal. Recursive traversal hits Python recursion limits: ```python def find_obj(name): stack = [doc.GetFirstObject()] while stack: obj = stack.pop() while obj: if obj.GetName() == name: return obj if obj.GetDown(): stack.append(obj.GetDown()) obj = obj.GetNext() return None ``` ### 6. API Version Compatibility Constants differ between C4D versions. Use defensive checks: ```python if hasattr(c4d, "SCENEFILTER_ANIMATION"): ... ``` ### 7. Check Render Visibility Objects can be disabled via traffic lights (`GetRenderMode()`), RS Object tags, parent hierarchy inheritance, or Takes system. ## Complete Animation Bake Workflow This is the authoritative end-to-end procedure. Follow it in order — each step gates the next. ### Step 1: Health Check ```python # Tool call: get_scene_info # Then: import c4d print(doc.GetDocumentName(), doc.GetFps(), doc.GetMaxTime().GetFrame(doc.GetFps())) ``` Confirm: scene name resolves, fps is correct (typically 24/25/30), max frame is the expected end frame. ### Step 2: Discover Animation Tracks Before baking, confirm the cloner actually has animated effectors: ```python import c4d def find_obj(name): stack = [doc.GetFirstObject()] while stack: obj = stack.pop() while obj: if obj.GetName() == name: return obj if obj.GetDown(): stack.append(obj.GetDown()) obj = obj.GetNext() return None fps = doc.GetFps() cloner = find_obj("MyClonerName") # replace with actual name # Check direct tracks on cloner for t in cloner.GetCTracks(): did = t.GetDescriptionID() ids = [int(did[i].id) for i in range(did.GetDepth())] curve = t.GetCurve() key_count = curve.GetKeyCount() if curve else 0 print(f"Track IDs: {ids}, keys: {key_count}") # Check effector children for their own tracks child = cloner.GetDown() while child: for t in child.GetCTracks(): did = t.GetDescriptionID() ids = [int(did[i].id) for i in range(did.GetDepth())] print(f" Effector '{child.GetName()}' track IDs: {ids}") child = child.GetNext() ``` If no tracks appear, the animation may be driven by fields or expressions — proceed to bake anyway; `ExecutePasses` will resolve those. ### Step 3: Bake MoGraph (Sequential Frame Stepping) ```python import c4d from c4d.modules import mograph as mo import json def find_obj(name): stack = [doc.GetFirstObject()] while stack: obj = stack.pop() while obj: if obj.GetName() == name: return obj if obj.GetDown(): stack.append(obj.GetDown()) obj = obj.GetNext() return None def vec(v): return [float(v.x), float(v.y), float(v.z)] fps = doc.GetFps() start = 0 end = int(doc.GetMaxTime().GetFrame(fps)) cloner = find_obj("MyClonerName") mg = cloner.GetMg() # global matrix for LOCAL->WORLD frames_data = {} for frame in range(start, end + 1): doc.SetTime(c4d.BaseTime(frame, fps)) doc.ExecutePasses(None, True, True, True, c4d.BUILDFLAGS_NONE) md = mo.GeGetMoData(cloner) if md is None: print(f"Frame {frame}: no MoData") continue matrices = md.GetArray(c4d.MODATA_MATRIX) clone_indices = md.GetArray(c4d.MODATA_CLONE) frame_clones = [] for i, m in enumerate(matrices): world_pos = mg * m.off scale = (m.v1.GetLength() + m.v2.GetLength() + m.v3.GetLength()) / 3.0 frame_clones.append({ "index": i, "position": vec(world_pos), "scale": float(scale), "clone_index": float(clone_indices[i]) if clone_indices else None }) frames_data[frame] = frame_clones if frame % 50 == 0: print(f"Baked frame {frame}/{end}") print(f"Done. Total frames baked: {len(frames_data)}") ``` ### Step 4: Extract Keyframes (Optional — for sparse data) If you need keyframe-only data rather than every-frame bake: ```python import c4d fps = doc.GetFps() obj = find_obj("MyObject") keyframe_data = {} for t in obj.GetCTracks(): did = t.GetDescriptionID() ids = [int(did[i].id) for i in range(did.GetDepth())] curve = t.GetCurve() if not curve: continue keys = [] for k in range(curve.GetKeyCount()): key = curve.GetKey(k) keys.append({ "frame": key.GetTime().GetFrame(fps), "value": float(key.GetValue()) }) keyframe_data[str(ids)] = keys print(json.dumps(keyframe_data)) ``` ### Step 5: Export JSON ```python import json output = { "scene": doc.GetDocumentName(), "fps": fps, "start_frame": start, "end_frame": end, "clone_count": len(frames_data.get(start, [])), "frames": frames_data } import tempfile, os export_path = os.path.join(tempfile.gettempdir(), "mograph_export.json") with open(export_path, "w") as f: json.dump(output, f) print(f"Exported {len(frames_data)} frames to {export_path}") ``` ### Step 6: Validate Run this after export to catch silent errors before handing data downstream: ```python import json, math with open(export_path) as f: data = json.load(f) fps = data["fps"] start = data["start_frame"] end = data["end_frame"] expected_frames = end - start + 1 actual_frames = len(data["frames"]) errors = [] if actual_frames != expected_frames: errors.append(f"Frame count mismatch: expected {expected_frames}, got {actual_frames}") nan_count = 0 for frame_key, clones in data["frames"].items(): for clone in clones: for coord in clone["position"]: if math.isnan(coord) or math.isinf(coord): nan_count += 1 if clone.get("clone_index") is not None: if not (0.0 <= clone["clone_index"] <= 1.0): errors.append(f"Frame {frame_key} clone {clone['index']}: clone_index out of range: {clone['clone_index']}") if nan_count > 0: errors.append(f"NaN/Inf found in {nan_count} position coordinates") if errors: for e in errors: print("ERROR:", e) else: print("Validation passed.") print(f" Frames: {actual_frames}, Clones per frame: {data['clone_count']}") ``` ## Validation Checklist ### Before Baking - [ ] Frame range set in scene (`doc.GetMaxTime()` returns expected end frame) - [ ] All effectors active (check visibility traffic lights and Tags) - [ ] No interfering Takes (`doc.GetTakeData().GetCurrentTake()` is the correct take) - [ ] Test on small range (frames 0-10) first — confirm clone count and positions look right before running full bake ### After Baking - [ ] Total frame count equals `end - start + 1` (no off-by-one, no gaps) - [ ] No NaN or Inf values in position coordinates - [ ] Clone indices are in range 0.0–1.0 (if using `MODATA_CLONE`) - [ ] World positions make sense — spot-check frame 0 and last frame against viewport ## MoGraph Extraction Pattern ```python import c4d from c4d.modules import mograph as mo def vec(v): return [float(v.x), float(v.y), float(v.z)] cloner = find_obj("ClonerName") mg = cloner.GetMg() for frame in range(start, end + 1, step): doc.SetTime(c4d.BaseTime(frame, fps)) doc.ExecutePasses(None, True, True, True, c4d.BUILDFLAGS_NONE) md = mo.GeGetMoData(cloner) matrices = md.GetArray(c4d.MODATA_MATRIX) for i, m in enumerate(matrices): world_pos = mg * m.off scale = (m.v1.GetLength() + m.v2.GetLength() + m.v3.GetLength()) / 3.0 ``` ## Animation Track Discovery ```python for t in obj.GetCTracks(): did = t.GetDescriptionID() ids = [int(did[i].id) for i in range(did.GetDepth())] curve = t.GetCurve() keys = [] if curve: for k in range(curve.GetKeyCount()): key = curve.GetKey(k) keys.append({"frame": key.GetTime().GetFrame(fps), "value": float(key.GetValue())}) ``` ## Cloner Mode Constants ``` c4d.ID_MG_MOTIONGENERATOR_MODE: 0=Grid, 1=Linear, 2=Radial, 3=Object, 4=Honeycomb c4d.MG_GRID_MODE: 0=Endpoint (total span), 1=Per Step (spacing) ``` ## Redshift Material Extraction **RS node graphs ARE accessible** via the `maxon` Python API when Redshift is installed. The `inspect_redshift_materials` MCP tool may report materials as `not_redshift_like` (type 5703), but the node graph is still readable through the maxon node-space API. ### Primary Path: maxon Node-Space API (Proven Working) RS materials use node space `com.redshift3d.redshift4c4d.class.nodespace`. Access via: ```python import c4d import maxon RS_NODESPACE = "com.redshift3d.redshift4c4d.class.nodespace" mat = doc.GetMaterials()[0] nm = mat.GetNodeMaterialReference() graph = nm.GetGraph(RS_NODESPACE) # returns NodesGraphModelRef # Traverse ALL nodes and ports: root = graph.GetRoot() inner = root.GetInnerNodes(maxon.NODE_KIND.ALL_MASK, False) for n in inner: kind = n.GetKind() nid = str(n.GetId()) if kind == 1: # NODE — e.g. standardmaterial, incandescent, texturesampler print(f"Node: {nid}") elif kind == 8: # INPORT — readable port with value short_name = nid.split('.')[-1] try: val = n.GetDefaultValue() if val is not None: print(f" {short_name} = {val}") except: pass ```