Skip to content

About

Contains the official code examples for the Cinema 4D Python API.

Topics

Resources

Stars

160 stars

Watchers

19 watching

Forks

Latest commit

 

History

56 Commits

Folders and files

Repository files navigation

Cinema 4D Python SDK

Describes the content of the Cinema 4D Python SDK.

Contents

SDK Layout

Path Description
examples Runnable Python examples demonstrating the Cinema 4D and Maxon APIs.
projects Complete Python SDK project templates for building Cinema 4D extensions.
AGENTS.md Agent instructions for the Cinema 4D Python SDK.
LICENSE.md License information for the Cinema 4D Python SDK.
sdk.code-workspace VS Code workspace configuration for the Python SDK.

Example Categories

Path Description
animation/ Animation, keyframes, motion, and tracks.
data/ Basic data types and containers.
gui/ User interface elements, dialogs, and user areas.
io/ Importing and exporting files, images, and assets.
math/ Vectors, random values, KD-trees, and related mathematical utilities.
misc/ Miscellaneous tooling commonly used in scripts.
modeling/ Modeling, meshes, splines, and UVs.
nodes/ Node-based workflows, node graphs, and node materials.
plugins/ Creating plugins, commands, tools, and extensions.
rendering/ Rendering, materials, shaders, textures, and render settings.
scene/ Scene files, documents, objects, tags, and takes.

Example Index

File Description

Plugins

Command

examples/plugins/py_cmd_gui_dynamic/ Demonstrates a dialog with dynamic content, where the content changes based on user input.
examples/plugins/py_cmd_gui_hello_world/ Demonstrates the most basic command/dialog plugin possible.
examples/plugins/py_cmd_gui_html/ Demonstrates how to implement a dialog that hosts an HTML viewer and can send and receive data to/from the displayed web page.
examples/plugins/py_cmd_gui_persistent/ Demonstrates how to store dialog layout data and values persistently over dialog open/close and Cinema 4D restart boundaries.
examples/plugins/py_cmd_gui_persistent_no_restart/ Demonstrates a simple way to store dialog layout data and values persistently over dialog open/close boundaries (but not over Cinema 4D restart boundaries).
examples/plugins/py_cmd_gui_resources/ Demonstrates a plugin that uses resources to define its dialog layout and string translations.
examples/plugins/py_cmd_gui_simple/ Demonstrates a simple dialog with two number input fields, a combo box and a button to carry out numeric operations on the two numbers.
examples/plugins/py_cmd_memory_viewer/ Demonstrates implementing a simple legacy memory viewer dialog.
examples/plugins/py_cmd_sculpt_save_mask/ Demonstrates the legacy Sculpting API; it is highly specialized and not that useful outside of sculpting.
examples/plugins/py_cmd_texture_baker/ Demonstrates implementing a simple legacy texture baking dialog.
examples/plugins/py_cmd_tool_finalization/ Demonstrates a tool finalization workflow at the example of editing SDS weights.

I/O

examples/plugins/py_io_ies_meta/ Demonstrates how to implement a scene saver plugin that exports all IES Meta information from the current document to a txt file, iterating through all objects in the scene.
examples/plugins/py_io_xample_loader/ Demonstrates how to implement a custom bitmap loader to import a custom picture format into Cinema 4D.
examples/plugins/py_io_xample_saver/ Demonstrates how to implement a custom bitmap saver to export a custom picture format into Cinema 4D.

Miscellaneous

examples/plugins/py_msc_licensing/ Demonstrates how to implement licensing checks in plugins.
examples/plugins/py_msc_menu/ Demonstrates how to build custom menus for your plugins.
examples/plugins/py_msc_noise_falloff/ Demonstrates legacy falloffs, a technology that has been replaced by fields in R20.
examples/plugins/py_msc_preference/ Demonstrates how to implement a preference category in the Cinema 4D preference dialog, exposing parameters as global preferences.
examples/plugins/py_msc_render_token/ Demonstrates how to register two Tokens, one visible in the render settings and the other not.

Objects

examples/plugins/py_obj_assetcontainer/ Demonstrates NodeData serialization and custom branching.
examples/plugins/py_obj_custom_icon/ Demonstrates how to implement a scene element that dynamically updates its icon.
examples/plugins/py_obj_double_circle/ Demonstrates how to implement a spline object generator with handles to drive parameters.
examples/plugins/py_obj_dynamic_parameters/ Demonstrates how to implement a node (at the example of an object) that dynamically updates its parameters.
examples/plugins/py_obj_gravitation/ Demonstrates how to implement a classic particle modifier object that applies a simple gravitation effect for each particle.
examples/plugins/py_obj_ocio_node/ Demonstrates how to implement a scene element respecting OpenColorIO color management.
examples/plugins/py_obj_offset_y_spline/ Demonstrates a spline offset generator (very questionable design, should not be followed).
examples/plugins/py_obj_rounded_tube/ Demonstrates how to implement a polygonal object generator with handles to drive parameters.
examples/plugins/py_obj_sculpt_modifier_deformer/ Demonstrates how to implement a modifier object that modifies a point object using the pull sculpting brush tool.
examples/plugins/py_obj_sphere_deformer/ Demonstrates how to implement a deformer object that pushes the points of a point object to a spherical shape, driven by radius and strength parameters.

Shaders

examples/plugins/py_sha_fresnel/ Demonstrates how to implement a shader that computes a fresnel effect.

Tags

examples/plugins/py_tag_look_at_camera/ Demonstrates how to implement a tag that forces the host object to look at the camera (like the Look At Camera Tag).

Tools

examples/plugins/py_tool_liquid_painter/ Demonstrates how to implement a simple tool.
examples/plugins/py_tool_sculpt_grab_brush/ Demonstrates how to implement a brush tool that modifies a BaseObject by grabbing all points under the brush.
examples/plugins/py_tool_sculpt_paint_brush/ Demonstrates how to implement a brush tool that rasterizes the stencil onto the polygons touched by the brush, accessing the stencil and BodyPaint layer.
examples/plugins/py_tool_sculpt_pull_brush/ Demonstrates how to implement a brush tool that modifies a BaseObject by pulling all points under the brush.
examples/plugins/py_tool_sculpt_twist_brush/ Demonstrates how to implement a brush tool that modifies a BaseObject by twisting all points under the brush.
examples/plugins/py_tool_ui/ Demonstrates how to implement a ToolData with a linkBox where it's possible to drag and drop an object, which is then cloned and added to the document in a random position.

Scripts

Animation

examples/animation/key_quaternion_interpolation.py Checks the interpolation of the first key for an object's rotation track. If the interpolation is linear (SLERP) it is changed to cubic.
examples/animation/motion_tracker_object_track.py Loops through all the tracks of the active Motion Tracker object.
examples/animation/object_find_best_euler_angle.py Checks the rotation tracks of the active object.
examples/animation/object_quaternion_rotation.py Checks if the active object uses quaternion interpolation.
examples/animation/object_sync_vector_keys.py Synchronizes the keys for the tracks of the active cube's "Size" parameter.
examples/animation/object_vector_curves.py Reads the vector components curves of the active object's rotation track curve.
examples/animation/object_vector_tracks.py Reads the vector components tracks of the active object's position track curve.
examples/animation/simulation/field_list_add_mask.py Creates a FieldList with a formula layer, a mask and another formula layer used as a mask of the first formula layer. Assigns this FieldList to the active object that have a c4d.FIELDS parameter e.g. all MoGraph effectors.
examples/animation/simulation/field_list_sampling.py Samples arbitrary points from multiple fields with c4d.FieldList and stores the result into a vertex color tag.
examples/animation/simulation/field_object_sampling.py Samples arbitrary points within a random field.
examples/animation/simulation/modata_get_selection.py Retrieves all selected clones of the active Cloner object.
examples/animation/simulation/modata_get_weights.py Retrieves the weights from all clones of the active Cloner object.
examples/animation/simulation/modata_read_color.py Retrieves the color or each clone using two ways. First one by accessing directly the Mograph Data. Second one by accessing the polygon cache representation of the Mograph Cloner.
examples/animation/simulation/modata_set_selection.py Generates and sets a MoGraph selection tag on a MoGraph cloner object. Effectively, this will create a selection tag for all uneven clones in the cloner object. This script has no runtime requirements, as it creates its inputs itself.
examples/animation/simulation/modata_set_weights.py Sets a weight of 1.0 for all clones of the active Cloner object.
examples/animation/simulation/particle_group_object.py Demonstrates how to read particle data from a ParticleGroupObject.
examples/animation/simulation/thinking_particles_creates.py Creates 90 Thinking Particles. Defines custom position and color for each particle.
examples/animation/simulation/voronoi_fracture.py Creates and define a noise shader as an input of a Voronoi Fracture object.
examples/animation/track_copy.py Copies the position, rotation and animation Tracks (so all Keyframes) from obj1 to obj2.
examples/animation/track_create_keys.py Creates position Y tracks. Adds two keyframes. Sets their value and interpolation.
examples/animation/track_synchronized.py Checks if the rotation track of an object is synchronized. If not, it will be synchronized.

Data

examples/data/_c4d_basebitmap.py Demonstrates the usage of the central bitmap type.
examples/data/_c4d_basecontainer.py Demonstrates the usage of the fundamental container type in the Cinema API.
examples/data/_c4d_descid.py Demonstrates important functions for the types c4d.DescID and c4d.DescLevel.
examples/data/_c4d_description.py Demonstrates important functions for the type c4d.Description.
examples/data/_maxon_basearray.py Demonstrates instantiation and usage of various Maxon data types.
examples/data/_maxon_datadictionary.py Demonstrates the key functionalities of maxon.DataDictionary.
examples/data/_maxon_tuple.py Creates a Maxon Tuple of 3 fields (any maxon type is working).

Gui

examples/gui/dialog_ask_number.py Creates a Modal Dialog asking for an integer or a float. Retrieves the entered value, once the user exit the Dialog.
examples/gui/dialog_menu_hide_content.py Creates an async Dialog with a top menu. Defines an icon in the menu to toggle group visibility.
examples/gui/dialog_modal.py Creates a basic Modal Dialog.
examples/gui/dialog_quick_tab.py Creates a Modal Dialog displaying a different SubDialog according to the selected entry of the QuickTab. Demonstrates how to add, flushes, remove tab interactively.
examples/gui/dialog_subdialog.py Creates and attaches a SubDialog to a Dialog. Switch the displayed SubDialog after a click on a button.
examples/gui/script_icon.py Example to customize the icon used for a script. The icon should be named like the .py file. Should be a TIF with a size of 32x32.
examples/gui/script_name_description.py Example to customize the name and the description in the script manager. Name-en-US defines the displayed name. Description-en-US defines the description of the script. As long as Name-en-US (Prior R20 it was Name-US) and Description-en-US (Prior R20 it was Description-US) are in the first comment bloc, c4d will extract them.
examples/gui/user_area_basic.py Creates and attaches a GeUserArea to a Dialog. Interacts from the GeDialog to the GeUserArea and vice-versa.
examples/gui/user_area_drag.py Creates and attaches a GeUserArea to a Dialog. Creates a series of aligned squares, that can be dragged and swapped together.

I/O

examples/io/asset_databases.py Provides examples for handling asset databases and repositories.
examples/io/asset_metadata.py Provides examples for reading and writing asset metadata.
examples/io/asset_types.py Provides examples for creating and loading different asset types.
examples/io/bitmap_fill_color.py Adds an overlay color to a Picture.
examples/io/bitmap_init_vector_file.py Initializes a bitmap from a vector image file.
examples/io/export_alembic.py Exports Alembic with custom settings.
examples/io/export_obj.py Exports Obj with custom settings.
examples/io/image_copy_32bit.py Copies the internal data of a 32 bit per-channel image to a new one.
examples/io/import_obj.py Imports Obj with custom settings.
examples/io/import_sketchup.py Imports Sketchup File with custom settings.
examples/io/import_step.py Imports STP/STEP with custom settings.
examples/io/memory_file_bitmap.py Writes/Reads a bitmap to/from memory.
examples/io/memory_file_data.py Writes/Reads simple data to/from memory.
examples/io/texture_paths.py Sets and gets global texture paths (Preferences->Files->Paths).

Math

examples/math/_c4d_geraycollider.py Demonstrates ray casting.
examples/math/_c4d_kdtree.py Demonstrates how to use KDTree to find neighboring points in a mesh.
examples/math/_c4d_matrix.py Demonstrates working with matrices.
examples/math/_c4d_noise.py Demonstrates working with noise functions.
examples/math/_c4d_quaternion.py Demonstrates working with quaternions.
examples/math/_c4d_vector.py Demonstrates working with vectors.
examples/math/_mxutils_random.py Demonstrates deterministic random values with mxutils.Random.

Misc

examples/misc/mxutils_checktype.py Demonstrates type and iterable validation with mxutils.
examples/misc/mxutils_debugprint.py Demonstrates mxutils helpers for diagnosing Cinema 4D scene data.
examples/misc/mxutils_decorators.py Demonstrates mxutils helpers for diagnosing Cinema 4D scene data.
examples/misc/mxutils_localimportpath.py Demonstrates importing a package relative to a saved Python script.
examples/misc/mxutils_symboltranslationcache.py Demonstrates translating Cinema 4D symbols with SymbolTranslationCache.
examples/misc/script_load.py Create a new temporary script. Load an existing Python file into the Script Manager. Retrieve the first script not active in the Script Manager and make it active.

Modeling

examples/modeling/geometry_cache.py Explains the geometry model of the Cinema API in Cinema 4D.
examples/modeling/geometry_edges.py Demonstrates handling edges in polygon objects at the example of splitting edges.
examples/modeling/geometry_extrude.py Demonstrates how to modify polygonal geometry at the example of extruding polygons.
examples/modeling/geometry_flatten.py Demonstrates how to deform points of a point object at the example of 'flattening' the selected polygons in a polygon object.
examples/modeling/geometry_polygon_object.py Explains the user-editable polygon object model of the Cinema API.
examples/modeling/geometry_sds_weights.py Demonstrates how to read and write data of an SDS weight tag.
examples/modeling/geometry_spline_object.py Explains the user-editable spline object model of the Cinema API.
examples/modeling/geometry_transfer_axis.py Demonstrates how to 'transfer' the axis of a point object to another object while keeping its vertices in place.
examples/modeling/lod.py Demonstrates creating and configuring LOD objects.
examples/modeling/modeling_command_bridge.py Demonstrates how to execute the 'Bridge' tool.
examples/modeling/modeling_command_current_state.py Demonstrates how to execute the 'Current State to Object' tool.
examples/modeling/modeling_command_edge_smooth.py Demonstrates how to execute the 'Edge Smooth' tool.
examples/modeling/modeling_command_extrude.py Demonstrates how to use the SendModelingCommand (SMC) function in general at the example of the 'Extrude' tool.
examples/modeling/modeling_command_flatten.py Demonstrates how to execute the 'Flatten' tool.
examples/modeling/modeling_command_join.py Demonstrates how to execute the 'Join' tool.
examples/modeling/normal_tag.py Script creates a NormalTag for a selected polygon object with a phong tag where the normals have been rotated by 45° around the world z-axis. Showcases read and write operations for the normals of a NormalTag. Normals are stored for each vertex of each polygon. Raw data normal structure for one polygon is 12 int16 value (4 vectors for each vertex of a Cpolygon * 3 components for each vector), even if the Cpolygon is a triangle.
examples/modeling/reduction_create.py Creates a new PolygonReduction object.
examples/modeling/reduction_edge_level.py Reduces the active PolygonObject to the given edge count.
examples/modeling/reduction_preprocess.py Configures the given PolygonReduction object. Reduces the given PolygonObject to 25%.
examples/modeling/reduction_triangle_level.py Copyright: MAXON Computer GmbH Author: Yannick Puech
examples/modeling/reduction_vertex_level.py Reduces the active PolygonObject to the given vertex count.
examples/modeling/snap_3d_point.py Enables the snap if it's not already the case. Sets it to 3D Type and also to Point mode.
examples/modeling/snap_quantize.py Enables the quantize if it's not already the case. Defines quantize Move and Scale step.
examples/modeling/snap_workplane.py Retrieves the current workplane position and object. Locks this workplane so it can't be edited.
examples/modeling/uv_command.py Calls BodyPaint 3D UV commands.
examples/modeling/uv_geometry.py Explains how to generate UVW data for polygon objects.
examples/modeling/uv_pin_deselect.py Removes the polygon point selection to the uv points pinned.
examples/modeling/uv_pin_points.py Sets the polygon point selection to the uv points pinned.
examples/modeling/uv_pin_select.py Adds the polygon point selection to the uv points pinned.
examples/modeling/uv_seams.py Copies the UV seams to the edge polygon selection.
examples/modeling/vertex_color_points.py Gets and Sets Vertex Colors in Point mode: Changes all black Vertex Colors to red.
examples/modeling/vertex_color_polygons.py Gets and Sets Vertex Colors in Polygon mode: Changes all vertex colors to red.
examples/modeling/volume_boolean_mesh.py Converts a Polygon Object to a Volume. Does a boolean operation over two Volume objects. Converts the resulting volume into a Polygon Object.
examples/modeling/volume_builder_access.py Retrieves a volume object from a volume builder.
examples/modeling/volume_builder_add_object.py Creates a volume builder and adds a cube object to it. Configures cube's object settings.
examples/modeling/volume_builder_create.py Creates a volume builder and inserts it into the active document.
examples/modeling/volume_builder_inputs.py Iterates over all input of a Volume Builder.
examples/modeling/volume_command_sphere.py Creates a sphere volume with the corresponding command.
examples/modeling/volume_command_spline.py Creates a volume from the selected spline object.
examples/modeling/volume_curl.py Creates a new vector volume object with a curl filter applied from an existing Volume Builder set as vector mode.
examples/modeling/volume_export_mesh.py Convert a Polygon Object to a Volume and save this volume to a VDB File Save a VDB file.
examples/modeling/volume_gradient_sphere.py Create a Spherical Volume filled with gradient data.
examples/modeling/volume_grid_read.py Reads the Float value of the first channel available from a Volume stored in a Volume Builder.
examples/modeling/volume_grid_write.py Create a volume from scratch and assign values to voxels.
examples/modeling/volume_import_vdb.py Loads a VDB file to a c4d.VolumeObject.
examples/modeling/volume_mesh_conversion.py Convert a Polygon Object to a Volume and convert it back to a Polygon Object
examples/modeling/volume_mix_meshes.py Converts a Polygon Object to a FOG Volume. Does a mix operation over two FOG Volume objects. Converts the resulting FOG volume into a Polygon Object.
examples/modeling/volume_mix_vectors.py Creates 2 vector volume from scratch. Mixes both vector volumes with a cross product to produce a third vector volume. Inserts all 3 volumes into the scene.
examples/modeling/volume_vdb_import.py Asks for a VDB file to load into a VolumeRef (a VolumeInterface Reference). Insert this VolumeRef into a VolumeObject. Inserts this VolumeObject into the current scene.
examples/modeling/volume_vector_to_fog.py Creates a vector volume from scratch. Converts this vector volume to a fog volume. Inserts this fog volume as a child of a volume mesher.

Nodes

examples/nodes/graph_descriptions_basics.py Demonstrates how graph descriptions create and modify node graphs.
examples/nodes/graph_descriptions_commands.py Demonstrates graph description commands.
examples/nodes/graph_descriptions_queries.py Demonstrates graph description queries, including lazy color and vector literals.
examples/nodes/graph_descriptions_references.py Demonstrates graph description references together with lazy color and URL literals.
examples/nodes/nodes_associate_nodes.py Demonstrates how to associate nodes in a Maxon API graph with their corresponding Cinema 4D API surrogate elements.
examples/nodes/nodes_create_or_get_graphs.py Demonstrates creating or getting node graphs in a scene.
examples/nodes/nodes_graph_entities.py Demonstrates the inner structure of node graphs and how to find entities in them.
examples/nodes/nodes_group.py Retrieve the selected node material and group the node that are selected.
examples/nodes/nodes_info.py Retrieve information about the selected port of a selected material.
examples/nodes/nodes_material_access.py Demonstrates accessing node materials and their graph contents in a scene.
examples/nodes/nodes_material_create_redshift.py Demonstrates setting up a Redshift node material composed out of multiple nodes.
examples/nodes/nodes_material_standard.py Demonstrates setting up a Standard renderer node material composed out of multiple nodes.
examples/nodes/nodes_modify_port.py Create a material for the standard node space and modify the value of the BDSF color port.
examples/nodes/nodes_selection.py This example shows how to select different elements on a node graph. It creates a node material, select ports, print connections and select wires.
examples/nodes/nodes_solo.py This example shows how to solo a node. It creates a material and solo's the end node in this material.
examples/nodes/nodes_wire_mute.py Retrieve the selected node material and toggle-mute the selected connection, i.e., if the connection is muted, it will be unmuted or vice-versa. A connection is composed out of eight wires, to mute the connection, one must set the INHIBIT wire to WIRE_MODE.NORMAL. To unmute the connection, one must set the INHIBIT wire to WIRE_MODE.REMOVE.
examples/nodes/xpresso_create_connect.py Creates a Constants and Results node in the Xpresso Tag of the selected object. Connects both Nodes together.
examples/nodes/xpresso_delete.py Deletes the first node created from the Xpresso Tag of the selected object.
examples/nodes/xpresso_from_tag.py Retrieves the Node Master (The BaseList2D object that holds all nodes) from an Xpresso Tag.
examples/nodes/xpresso_iterate.py Loops through all nodes from the Xpresso Tag of the selected object. Checks if it's a Constant Node.
examples/nodes/xpresso_move.py Moves the first node in the Graph View created from the Xpresso Tag of the selected object.

Plugins

examples/plugins/py_cmd_gui_resources/unicode_encode_strings.py Provides an example for how one could realize a string encoding pipeline for plugin resources.

Rendering

examples/rendering/_c4d_renderdata.py No short description provided.
examples/rendering/batch_render_postprocess.py Demonstrates to manipulate the file outputs of a batch render post process once the rendering has finished.
examples/rendering/batch_render_preprocess.py Demonstrates how to pre-process multiple documents before adding them to the batch renderer for rendering.
examples/rendering/ocio.py Demonstrates how to read, write, and convert colors in an OpenColorIO (OCIO) color-managed document in Cinema 4D.
examples/rendering/render_complex.py Demonstrates the details and manual handling of a programmatic rendering process.
examples/rendering/render_hardware.py Demonstrates how carry out a 'hardware preview' rendering, i.e., a rendering of what is shown in the viewport using the hardware renderer.
examples/rendering/render_openexr.py Configures OpenEXR output render format with SetImageSettingsDictionary() then reads these with GetImageSettingsDictionary().
examples/rendering/render_preroll.py Demonstrates how to render document from or at a given frame after prerolling it.
examples/rendering/render_set_engine.py Demonstrates how to manipulate the render settings of a rendering, specifically also the used render engine.
examples/rendering/render_simple.py Demonstrates a simple way to programmatically render a document to either memory or disk.
examples/rendering/render_tiles.py Demonstrates how to render a document split into tiles which can be composited back together to a full image.
examples/rendering/render_token.py Renders a BaseDocument and saves the resulting image using a filename handling tokens.

Scene

examples/scene/_c4d_atom.py Demonstrates important functions for the type c4d.C4DAtom.
examples/scene/_c4d_baselist2d.py Demonstrates important functions for the type c4d.BaseList2D.
examples/scene/_c4d_gelistnode.py Demonstrates important functions for the type c4d.GeListNode.
examples/scene/documents.py Demonstrates basic document operations.
examples/scene/layers.py Demonstrates how to assign a scene element to a layer.
examples/scene/objects.py Demonstrates basic operations on objects.
examples/scene/parameters.py Demonstrates different ways to access and modify parameters of Cinema 4D scene elements.
examples/scene/takes.py Demonstrates the fundamental operations of the Take System.
examples/scene/traversal.py Demonstrates scene traversal.
examples/scene/undos.py Demonstrates adding undo steps for document modifications.
examples/scene/userdata.py Demonstrates how to work with user data parameters.

About

Contains the official code examples for the Cinema 4D Python API.

Topics

Resources

Stars

160 stars

Watchers

19 watching

Forks

Releases

Contributors