Cinema4d MCP

🚀 電影院4D API 中文文檔

本API文檔為開發者提供了與Cinema 4D進行交互的詳細指南，藉助Python綁定插件，可實現場景操作、對象創建、動畫製作等功能，提升Cinema 4D的使用效率和創作靈活性。

🚀 快速開始

安裝與兼容性

📦 安裝步驟

1. 下載並安裝官方Python綁定插件。
2. 啟動Cinema 4D，進入菜單 > 插件 > Python > 管理器。
3. 添加新的Python解釋器，選擇已安裝的Python路徑。

⚙️ 兼容性說明

• 支持版本：Cinema 4D 2023.2及以上（R25、S26及更高）
• Python版本：3.10
• 最低要求：Cinema 4D 2024.0或更新版本確保最佳兼容性

核心概念

🌍 場景對象

使用server.py與Cinema 4D進行交互，所有操作均基於當前活動場景。

# 獲取當前活動場景指針
scene = c4d.GetActiveScene()

⚙️ 屬性設置

通過Python可以訪問並修改Cinema 4D的大多數屬性，具體方式視對象類型而定。

基本命令示例

# 添加一個立方體
cube = c4d.utils.create_object(c4d.OBJECT_TYPE_Cube)
c4d.EventAdd()

# 獲取當前活動物體
active_obj = doc.GetActiveObject()

✨ 主要特性

本API支持多種功能，涵蓋場景信息獲取、對象創建與修改、相機與動畫設置、燈光與材質處理等多個方面，為Cinema 4D的創作提供了豐富的可能性。

📦 安裝指南

安裝步驟

1. 下載並安裝官方Python綁定插件。
2. 啟動Cinema 4D，進入菜單 > 插件 > Python > 管理器。
3. 添加新的Python解釋器，選擇已安裝的Python路徑。

💻 使用示例

基礎用法

場景對象操作

# 獲取當前活動場景指針
scene = c4d.GetActiveScene()

基本對象創建

# 添加一個立方體
cube = c4d.utils.create_object(c4d.OBJECT_TYPE_Cube)
c4d.EventAdd()

# 獲取當前活動物體
active_obj = doc.GetActiveObject()

高級用法

場景信息獲取與操作

# 獲取當前場景的摘要信息
scene_info = get_scene_info()

# 列出場景中的所有對象（包括層級結構）
objects = list_objects()

# 將選定對象分組到一個新的空物體下
group_objects(selected_objects)

# 在Cinema 4D中執行自定義Python代碼
execute_python("print('Hello, Cinema 4D!')")

# 保存當前的Cinema 4D項目到磁盤
save_scene("path/to/save.c4d")

# 加載一個.c4d文件到場景中
load_scene("path/to/load.c4d")

# 為物體屬性（位置、旋轉等）設置關鍵幀
set_keyframe(object, attribute, value, time)

對象創建與修改

# 向場景中添加一個基本形狀（立方體、球體、圓錐體等）
add_primitive(shape_type)

# 修改選定對象的變換或屬性
modify_object(selected_object, transformation, attributes)

# 創建一個有機的、非標準的抽象形式
create_abstract_shape()

相機與動畫

# 在場景中添加一個新的相機
create_camera()

# 沿路徑（線性或樣條曲線）對相機進行動畫處理
animate_camera(camera, path)

燈光與材質

# 向場景中添加一盞燈（環境光、聚光燈等）
create_light(light_type)

# 創建一個標準的Cinema 4D材質
create_material()

# 將材質應用到目標物體上
apply_material(material, target_object)

# 生成並應用一種風格化或程序化的著色器
apply_shader(shader_type, target_object)

Redshift支持

# 檢查Redshift材質設置及其連接情況
validate_redshift_materials()

MoGraph與字段

# 添加一個MoGraph克隆器（線性、徑向、網格等）
create_mograph_cloner(cloner_type)

# 添加一個MoGraph影響器（隨機、平面等）
add_effector(effector_type)

# 添加並鏈接一個MoGraph字段到物體上
apply_mograph_fields(field_type, target_object)

動力學與物理

# 在選定對象上添加柔軟體標籤
create_soft_body(selected_object)

# 為物體應用剛性或柔軟體物理屬性
apply_dynamics(object, physics_type)

渲染與預覽

# 渲染當前幀並保存到磁盤（僅限文件輸出）
render_frame("path/to/output.png")

# 渲染一個快速預覽並返回Base64圖像（供AI使用）
preview_image = render_preview()

# 捕獲場景快照（包括物體和預覽圖像）
snapshot_scene("path/to/snapshot.c4d")

📚 詳細文檔

場景信息與執行

• get_scene_info：獲取當前場景的摘要信息。
• list_objects：列出場景中的所有對象（包括層級結構）。
• group_objects：將選定對象分組到一個新的空物體下。
• execute_python：在Cinema 4D中執行自定義Python代碼。
• save_scene：保存當前的Cinema 4D項目到磁盤。
• load_scene：加載一個.c4d文件到場景中。
• set_keyframe：為物體屬性（位置、旋轉等）設置關鍵幀。

對象創建與修改

• add_primitive：向場景中添加一個基本形狀（立方體、球體、圓錐體等）。
• modify_object：修改選定對象的變換或屬性。
• create_abstract_shape：創建一個有機的、非標準的抽象形式。

相機與動畫

• create_camera：在場景中添加一個新的相機。
• animate_camera：沿路徑（線性或樣條曲線）對相機進行動畫處理。

燈光與材質

• create_light：向場景中添加一盞燈（環境光、聚光燈等）。
• create_material：創建一個標準的Cinema 4D材質。
• apply_material：將材質應用到目標物體上。
• apply_shader：生成並應用一種風格化或程序化的著色器。

Redshift支持

• validate_redshift_materials：檢查Redshift材質設置及其連接情況。

MoGraph與字段

• create_mograph_cloner：添加一個MoGraph克隆器（線性、徑向、網格等）。
• add_effector：添加一個MoGraph影響器（隨機、平面等）。
• apply_mograph_fields：添加並鏈接一個MoGraph字段到物體上。

動力學與物理

• create_soft_body：在選定對象上添加柔軟體標籤。
• apply_dynamics：為物體應用剛性或柔軟體物理屬性。

渲染與預覽

• render_frame：渲染當前幀並保存到磁盤（僅限文件輸出）。
• render_preview：渲染一個快速預覽並返回Base64圖像（供AI使用）。
• snapshot_scene：捕獲場景快照（包括物體和預覽圖像）。

🔧 技術細節

兼容性計劃與路線圖

最佳實踐

日誌記錄與調試

# 記錄關鍵操作日誌
import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

錯誤處理

始終使用異常捕獲來確保代碼的健壯性：

try:
    # 操作代碼
except Exception as e:
    logger.error(f"發生錯誤: {str(e)}")

已解決問題

• 問題：插件首次安裝時未顯示在菜單中。
  • 解決方法：重啟Cinema 4D後查看。
• 問題：無法訪問某些對象屬性。
  • 解決方法：確保已正確導入所有必要的模塊，並檢查日誌以獲取更多信息。

🤝 貢獻指南

如何貢獻代碼

1. 叉本地倉庫到您自己的賬戶。
2. 創建新的功能分支。
3. 提交更改並創建拉取請求。

如何報告問題

• 使用GitHub Issues提交問題，附帶詳細的操作步驟和錯誤信息。

📄 許可證

本項目遵循MIT許可證，具體條款請參閱LICENSE文件。

📞 聯繫我們

如有任何疑問或建議，請通過以下方式聯繫：

• 郵件：support@cinema4dapi.com
• GitHub：https://github.com/cinema4d/cinema4d-api