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：捕获场景快照（包括物体和预览图像）。

🔧 技术细节

兼容性计划与路线图

| Cinema 4D 版本 | Python 版本 | 兼容性状态 | 备注 | | -------------- | ------------ | ---------- | ------------------------------------------------- | | R21 / S22 | Python 2.7 | ❌ 不支持 | 遗留API和Python版本过旧 | | R23 | Python 3.7 | 🔍 计划中未测试 | 当前尚未进行测试 | | S24 / R25 / S26 | Python 3.9 | ⚠️ 可能（待定） | 需要测试和针对缺失API的Fallback支持 | | 2023.0 / 2023.1 | Python 3.9 | 🟢 支持 | 确保最佳兼容性请使用Cinema 4D 2024.0或更新版本 | | 2024.0及以上 | Python 3.10 | 🟢 完全支持 | 推荐用于所有新项目 |

最佳实践

日志记录与调试

# 记录关键操作日志
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