Metadata-Version: 2.5
Name: dcc-mcp-cinema4d
Version: 0.3.1
Summary: Production Cinema 4D adapter for typed headless modeling, interchange, inspection, and rendering
Project-URL: Homepage, https://github.com/dcc-mcp/dcc-mcp-cinema4d
Project-URL: Repository, https://github.com/dcc-mcp/dcc-mcp-cinema4d
Project-URL: Issues, https://github.com/dcc-mcp/dcc-mcp-cinema4d/issues
Author-email: loonghao <hal.long@outlook.com>
License: MIT
License-File: LICENSE
Keywords: 3d,automation,c4dpy,cinema4d,dcc,mcp
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Requires-Dist: dcc-mcp-core<1.0.0,>=0.20.36
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: jsonschema>=4.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: pyyaml>=6; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: twine>=6; extra == 'dev'
Provides-Extra: test
Requires-Dist: jsonschema>=4.23; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Requires-Dist: pyyaml>=6; extra == 'test'
Requires-Dist: ruff>=0.8; extra == 'test'
Description-Content-Type: text/markdown

# dcc-mcp-cinema4d

<p align="center">
  <img src="docs/assets/dcc-mcp-cinema4d.svg" alt="DCC-MCP · CINEMA 4D" width="600">
</p>

Typed Cinema 4D document automation for DCC-MCP, executed through Maxon's licensed
headless `c4dpy` runtime.

![Typed primitives assembled, validated, rendered, and prepared for interchange through Cinema 4D](docs/images/dcc-mcp-cinema4d-showcase.webp)

_Illustrative workflow limited to the adapter's implemented primitive, transform, validation, render, and interchange operations; generated source is retained in `docs/images/dcc-mcp-cinema4d-showcase-source.png`._

<!-- dcc-mcp-coverage-pointer:start -->
<!-- Generated from dcc-mcp-catalog.yml by scripts/generate_adapter_pointer.py in dcc-mcp/dcc-mcp-core. Do not edit by hand. -->
## Part of the DCC-MCP host matrix

**dcc-mcp-cinema4d** — Cinema 4D adapter for typed headless modeling, interchange,
inspection, and rendering.

It is one of **47 host adapters** in the DCC-MCP catalog. Every adapter speaks the same
MCP protocol and builds on the same core runtime contract; each one exposes the tools
its own host needs on top of that.

- [All host adapters and install metadata](https://dcc-mcp.github.io/ecosystem)
- [Host matrix on the core README](https://github.com/dcc-mcp/dcc-mcp-core#readme)
- [Showcase](https://dcc-mcp.github.io/showcase)

This block is generated from the catalog entry in
[`dcc-mcp-catalog.yml`](https://github.com/dcc-mcp/dcc-mcp-core/blob/main/dcc-mcp-catalog.yml).
Re-run the generator after changing the catalog.
<!-- dcc-mcp-coverage-pointer:end -->

## Capabilities

- Discover and report the real Cinema 4D, Python, and API versions.
- Create, inspect, validate, and atomically copy `.c4d` documents.
- Add typed cube, sphere, cylinder, cone, torus, and plane primitives.
- Set absolute translation, HPB rotation, and scale; remove named objects safely.
- Import C4D, OBJ, FBX, glTF/GLB, STL, Alembic, Collada, and 3DS geometry when
  the installed Cinema 4D runtime provides the corresponding importer.
- Export full documents to C4D, OBJ, FBX, glTF/GLB, STL, Alembic, or Collada
  when the installed runtime provides the corresponding exporter.
- Render bounded PNG and JPEG images without a GUI.

The adapter never accepts arbitrary Python source. Every host call executes a packaged,
allowlisted driver in a fresh `c4dpy` process with bounded paths, timeouts, output streams,
and response size. Document mutations use a staged file and atomically replace the durable
document only after a successful host operation.

OBJ import and export form the production-validated interchange baseline. Other formats
are runtime-dependent; `get_capabilities` reports this boundary and unavailable optional
importers or exporters fail with a format-specific error.

## Requirements

- Cinema 4D R21 or newer with a valid license.
- The matching `c4dpy` executable shipped with that Cinema 4D installation.
- Python 3.9 or newer for the DCC-MCP service.
- `dcc-mcp-core>=0.20.36,<1.0.0` in the same Python distribution.

Maxon documents that `c4dpy` is a headless Cinema 4D instance capable of loading,
constructing, saving, and rendering scenes, but it requires a real Cinema 4D installation
and license.

## Two interpreters

The adapter spans two Python runtimes. Most setup confusion comes from mixing them up:

| Side | Interpreter | Floor | Runs |
| --- | --- | --- | --- |
| Service | the Python the adapter is installed into | 3.9 | MCP server, `install`/`doctor`/`verify`, path and timeout policy, bridge |
| Host | the Python **inside `c4dpy`** | 3 | the packaged driver, which imports `c4d` and touches the scene |

The service floor is this package's `requires-python`. The host floor is decided by
whichever interpreter that Cinema 4D build ships, and releases whose `c4dpy` is
Python 2.7 (the R21 and R22 lines) cannot run the driver. That makes R23 the effective
floor in practice, even though the build floor is R21.

`doctor --json` reports both: `checks.runtime.python_version` is the host side, and
`plan.python.version` is the service side.

## Host versions and read-back

Declared support lives in `src/dcc_mcp_cinema4d/compat_matrix.json`, shipped in the wheel
and keyed on the integer from `c4d.GetC4DVersion()`. `doctor` and `verify` embed the
verdict as `host_matrix`; a build outside the matrix is rejected explicitly rather than
treated as "close enough".

Every mutating tool reads its change back before reporting success — document mutations
against the reopened document, exports against their format signature, renders against the
requested dimensions — and a mismatch raises an error naming the tool, the check, both
values, and the Cinema 4D build.

CI runs `pytest -m "not cinema4d"`, so its evidence is **contract level**: the read-back
logic is proven, Cinema 4D's behaviour is not. Host-level evidence comes only from the
opt-in real-host test on a licensed machine. See [`install.md`](install.md).

## Install

See [`install.md`](install.md) for the official Core Install SOP contract,
identity-bound planning, atomic receipt, verification, upgrade, uninstall, and troubleshooting.

```bash
python -m pip install dcc-mcp-cinema4d
dcc-mcp-cinema4d plan --target install --c4dpy <absolute-c4dpy-path> --json
dcc-mcp-cinema4d install --c4dpy <absolute-c4dpy-path> --json --yes
dcc-mcp-cinema4d doctor --c4dpy <absolute-c4dpy-path> --json
```

Set the licensed runtime and allowed workspace before starting the adapter:

```powershell
$env:DCC_MCP_CINEMA4D_C4DPY = "C:\Program Files\Maxon Cinema 4D 2026\c4dpy.exe"
$env:DCC_MCP_CINEMA4D_ALLOWED_ROOTS = "D:\projects;D:\exports"
dcc-mcp-cinema4d
```

For an explicit standalone readiness check:

```powershell
dcc-mcp-cinema4d verify --c4dpy "C:\Program Files\Maxon Cinema 4D 2026\c4dpy.exe" --json
```

Lifecycle execution binds the exact Maxon product/file identity, digest, selected Python
distribution, live PID/start token, and adapter-owned receipt. The default allowed root is
the adapter's current working directory.

## Agent workflow

```bash
dcc-mcp-cli list
dcc-mcp-cli search Cinema 4D status --dcc-type c4d
dcc-mcp-cli load-skill cinema4d-session --dcc-type c4d --instance-id <id>
dcc-mcp-cli describe c4d.<id>.get_status
dcc-mcp-cli call c4d.<id>.get_status --json '{}'
```

Load `cinema4d-modeling` only when modeling, interchange, or rendering tools are needed.
Use `--wait` for document operations because they run as bounded asynchronous jobs.

## Development

```bash
python -m pip install -e ".[dev]"
python -m ruff check src tests
python -m ruff format --check src tests
python -m pytest -m "not cinema4d"
python -m build
python -m twine check dist/*
```

Real-host acceptance requires a licensed `c4dpy`; CI intentionally does not mock a Maxon
license. On a licensed machine:

```bash
C4D_TEST_EXECUTABLE=/path/to/c4dpy python -m pytest -m cinema4d
```

That is the only host-level evidence this adapter produces, and it is opt-in precisely
because the license cannot be provisioned on a hosted runner.

Official references: [c4dpy manual](https://developers.maxon.net/docs/py/2025_1_0/manuals/manual_py_c4dpy.html),
[Cinema 4D Python SDK](https://developers.maxon.net/docs/py/index.html).
