电影院4D API 中文文档

安装与兼容性

安装步骤

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()

详细文档

场景信息与执行

• 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