API Overview¶

Provides an overview of the major API components.

The Cinema 4D Python API includes three complementary components: the Cinema API (c4d, see the reference), the Maxon API (maxon, see the reference), and Python-specific helpers in mxutils (see the reference). They can be used together in the same script or plugin. See Quickstart to run an introductory script.

Cinema API¶

The c4d module provides core Cinema 4D functionality. A BaseDocument contains a scene hierarchy, materials, animation, and render settings. Objects are BaseObject instances; tags are BaseTag instances attached to objects. These scene entities derive from BaseList2D, which provides names, descriptions, and parameter access. Traverse the object hierarchy through its first child and next sibling, rather than assuming that all objects are in one flat list, see Scene Structure.

Parameters have identifiers defined in Cinema 4D’s description resources. Access a value with object[c4d.PRIM_CUBE_LEN] or a DescID when addressing a nested parameter. These identifiers are not necessarily the interface labels shown in the Attribute Manager. Use the Resource Index and the type reference to look up the identifier rather than guessing it.

Maxon API¶

The maxon module exposes nodes, assets, volumes, and other modern parts of Cinema 4D. It is the API which Cinema 4D itself is built with, and it follows different conventions than the Cinema API: functionality is split into frameworks, types come as interfaces and references, and a failed operation raises an exception. Do not assume that a Maxon reference and a similarly named c4d object are interchangeable.

Node materials and scene nodes are a common reason to use maxon. A graph contains nodes and their input/output ports; editing it requires the proper graph context and transaction. The Graph Descriptions shows how to create and update node materials. The classes for graphs are in the nodes and graph frameworks. For node IDs and port definitions shipped with a given release, consult the Resource Index.

Frameworks¶

The API is organized in frameworks, each covering one area, such as volume for OpenVDB volumes or nodes for node graphs. The members of all frameworks are available directly in the maxon module. The Maxon API reference lists them by framework.

Interfaces and References¶

Most types of the Maxon API consist of two parts:

Part	Naming	Role
Interface	`maxon.VolumeInterface`	Declares the functions of a type. The implementation lives in Cinema 4D and is hidden. Python cannot define new implementations, only use the existing ones. Interfaces are not used directly.
Reference	`maxon.VolumeRef`	The object a script works with. It is a handle to an instance of an implementation, and calling one of its methods runs the function of the interface on that instance.

You get a reference by calling the reference type, for example maxon.VolumeRef(), or as the result of an API call. Assigning a reference in Python only adds another name for the same handle.

Some references have no Ref suffix, e.g., maxon.Url for maxon.UrlInterface. These are copy-on-write references: copies share their data until one of them is modified. Scripts do not have to handle this; it only explains why the suffix can be missing.

Data Types and Registries¶

The Maxon API has its own data types which match its C++ counterparts: for example maxon.Int32, maxon.Float64, maxon.BaseArray, maxon.Tuple, maxon.Url, and maxon.Id. Use maxon.MaxonConvert() to convert a Maxon value to a Python built-in type.

Registries store the components of the API, such as classes and implementations, by maxon.Id. They are how you discover what is available, for example maxon.Loggers, the registry of all loggers. Python can read registries, but only the C++ API can add new entries to them.

mxutils API¶

The mxutils module offers Python-specific convenience tools, mainly for working with the Cinema API. For example, mxutils.LocalImportPath temporarily adds a plugin-local module directory to the import path, and mxutils.CheckType() checks the result of an API call before you use it. These helpers complement rather than replace c4d and maxon. The mxutils reference lists all of them.

Category	Option	Description
Query	Words and phrases	Search is case-insensitive. Put a phrase in quotes for an exact match. Quoted phrases require every word and disable fuzzy matching.
Terms	OR / AND	Choose whether to match any term or require all terms.
Fuzzy	On / Off	Toggle approximate and prefix matches. Quoted phrases always use strict matching.
Results	Sparse / Dense	Sparse groups multiple hits for one entity and hides its owned API members when the class or module itself matches. Dense lists each match separately.
Sort by	Type / Relevance	Group results by entity type then rank within each group, or rank all results by relevance.
Content	All / API / Manuals / Examples / Resources	Search all documentation, API documentation, manuals, the examples index, or the resources index. Code examples embedded in other sections retain their own content area.
Entity	All / Page / Module / Class / Function / Attribute / Description / Node / Symbol / Icon	Page covers results without a specific entity type. Resource entity types are available with All or Resources; API entity types are available with All or API.
Location	All / Text / Code / Name / Signature	Text covers everything outside code, names, and signatures. Name and Signature are available with All or API.