Python Character Tag¶
Introduction¶
Python code can be executed in various situations from a character tag.
Methods¶
-
BuildTemplate
() - Override - Called each time a character template is saved using the Save Character Template command.Good place to insert objects, to dynamically build a template or modify the template document.
Note
If any components are added, appropriate settings have to be added as well to the Character Component Tag.
The following variables are local to this function:
- type doc
c4d.documents.BaseDocument
- param doc
The template document.
- type op
c4d.BaseObject
- param op
The object with the Component tag.
-
GetComponents
() - Override - Called at every redraw to retrieve a list of available components.Good place to specify which component buttons are shown within the Character object.
Note
The standard inclusion rules specified in the Component tags will apply when None is returned.
The following variables are local to this function:
- type doc
c4d.documents.BaseDocument
- param doc
The document containing the Character object.
- type charop
c4d.modules.character.builder.CharacterObject
- param charop
The Character object present in the scene.
- type template
c4d.modules.character.builder.Template
- param template
The template.
- type op
c4d.BaseObject
- param op
The parent component’s main object.
- type pcomp
c4d.modules.character.builder.Component
- param pcomp
The parent component.
- type pcompop
c4d.modules.character.builder.ComponentObject
- param pcompop
The parent component object.
- rtype
c4d.BaseContainer
- return
Link of available components.
The next example from the Python tab of the Character object ensures an object with the name “Spine_null” to be present. Until a Spine is added, no other components can be added, regardless of the parent.
Note
The FindObject method searches for the object name, not the component name. A BaseContainer is returned in this example only when no Spine exists, so once a Spine is added the inclusion rules in the Component Tags will be used.
import c4d def GetComponents(): # Check if there is already no Spine object in the Character Object found in the scene. if charop.FindObject("Spine_null") is None: # Find the Spine object in the template spineObject = template.FindObject("Spine_null") if splineObject is None: return None # If there is a spineObject we store it into a BaseContainer bc = c4d.BaseContainer() bc.SetLink(1, spineObject) return bc
-
ModeChanged
() - Override - Called each time when the mode (Build, Adjust, Bind, Animate) is changed.Good place to change the visibility of objects or enable/disable functions like expressions according to a mode.
Note
Modification of the Character object should be done directly within the function.
The following variables are local to this function:
- type doc
c4d.documents.BaseDocument
- param doc
The document containing the Character object.
- type charop
c4d.modules.character.builder.CharacterObject
- param charop
The Character object present in the scene.
- type op
c4d.BaseObject
- param op
The object attached to the Component tag.
- type compop
c4d.modules.character.builder.ComponentObject
- param compop
The component object.
- type omode
int
- param omode
The old mode.
Note
These constants are defined in the c4d.modules.character.builder module so c4d.modules.character.builder.COMPONENT_OBJECT_GETOBJECTS_TYPE_ALL should be used and not c4d.COMPONENT_OBJECT_GETOBJECTS_TYPE_ALL.
Symbol ID
Description
ID_CA_CHARACTER_MODE_BUILD
Build Mode.
ID_CA_CHARACTER_MODE_ADJUST
Adjust Mode.
ID_CA_CHARACTER_MODE_BIND
Bind Mode.
ID_CA_CHARACTER_MODE_ANIMATE
Animate Mode.
- type nmode
int
- param nmode
The new mode.
Note
These constants are defined in the c4d.modules.character.builder module so c4d.modules.character.builder.COMPONENT_OBJECT_GETOBJECTS_TYPE_ALL should be used and not c4d.COMPONENT_OBJECT_GETOBJECTS_TYPE_ALL.
Symbol ID
Description
ID_CA_CHARACTER_MODE_BUILD
Build Mode.
ID_CA_CHARACTER_MODE_ADJUST
Adjust Mode.
ID_CA_CHARACTER_MODE_BIND
Bind Mode.
ID_CA_CHARACTER_MODE_ANIMATE
Animate Mode.
-
InsertComponent
() - Override - Used within the Component tag’s Python tab it’s called at each insertion action to override them.All objects should be inserted into the document used to create the component, and the main component object that was inserted into the document should be returned.Override - Used within an Insertion rule on the Insertion tab of the Component tag, it’s called at each insertion to change where and how the object will be inserted.The global variable itype should be defined to indicates the insertion type (like the Insert drop-down in the rule) and the c4d.BaseObject that corresponds to the Object attribute in the rules should be returned.The following variables are local to this function:
- type doc
c4d.documents.BaseDocument
- param doc
The document containing the Character object.
- type charop
c4d.modules.character.builder.CharacterObject
- param charop
The Character object present in the scene.
- type template
c4d.modules.character.builder.Template
- param template
The template.
- type pcompop
c4d.modules.character.builder.ComponentObject
- param pcompop
The parent component object.
- type pcomp
c4d.modules.character.builder.Component
- param pcomp
The parent component.
- type comp
c4d.modules.character.builder.Component
- param comp
The component to be inserted.
- type itype
int
- param itype
The insertion type for rule inserts. Need to be set before return.
Note
These constants are defined in the c4d.modules.character.builder module so c4d.modules.character.builder.COMPONENT_INSERT_TYPE_FIRST should be used and not c4d.COMPONENT_INSERT_TYPE_FIRST.
Symbol ID
Description
COMPONENT_INSERT_TYPE_FIRST
Insert as first Child of returned object.
COMPONENT_INSERT_TYPE_LAST
Insert as last Child of returned object.
COMPONENT_INSERT_TYPE_BEFORE
Insert before returned object.
COMPONENT_INSERT_TYPE_AFTER
Insert after returned object.
COMPONENT_INSERT_TYPE_ACTIVE
Insert From Parent, using the Default Insert object of the Parent component.
COMPONENT_INSERT_TYPE_END
Insert at the end of the returned object’s hierarchy.
- rtype
c4d.BaseObject
- return
The main component object if in the Python tab or the object, the component should be inserted under, if in the Insertion tab.
The next example from the Python Insertion rule of the Character tag defines under which object to insert the component, depending on the parent component already has a child or not.
import c4d def InsertComponent(): # Check if the parent component already has a child object. if pcompop.GetDown(): # If so, insert as child of Start Cap # Find the Start Cap object within the parent component iop = pcompop.FindObject("Start_Cap_con+") # Set itype to insert as First Child itype = c4d.moules.character.builder.COMPONENT_INSERT_TYPE_FIRST # Return the object to be inserted under return iop else: # Otherwise, insert as child of End Cap. # Find the End Cap object within the parent component iop = pcompop.FindObject("End_Cap_con+") # Set itype to insert as First Child itype = c4d.moules.character.builder.COMPONENT_INSERT_TYPE_FIRST # Return the object to be inserted under return iop
-
PostInsertComponent
() - Override - Called after a component has been inserted in the Character object and only if InsertComponent is not used.
Note
Change should be done directly to the inserted objects within the function.
The following variables are local to this function:
- type doc
c4d.documents.BaseDocument
- param doc
The document containing the Character object.
- type charop
c4d.modules.character.builder.CharacterObject
- param charop
The Character object present in the scene.
- type pcompop
c4d.modules.character.builder.ComponentObject
- param pcompop
The parent component object.
- type pcomp
c4d.modules.character.builder.Component
- param pcomp
The parent component.
- type comp
c4d.modules.character.builder.Component
- param comp
The component to be inserted.
- type op
c4d.BaseObject
- param op
The main component object that was inserted.
- type compop
c4d.modules.character.builder.ComponentObject
- param compop
The inserted component.
-
MirrorComponent
() - Override - Called when a mirrored component is added to the Character object. Mirrored components are automatically generated when multiple components of the same type are added with the same parent, based on the settings in the Component tag’s mirroring tab.
Note
MirrorComponent is called before PostInsertComponent and the mirrored component can be modified directly within this function.
The following variables are local to this function:
- type doc
c4d.documents.BaseDocument
- param doc
The document containing the Character object.
- type op
c4d.BaseObject
- param op
The main component object that was inserted.
- type charop
c4d.modules.character.builder.CharacterObject
- param charop
The Character object present in the scene.
- type comp
c4d.modules.character.builder.Component
- param comp
The component to be inserted.
- type compop
c4d.modules.character.builder.ComponentObject
- param compop
The inserted component.
- type pcomp
c4d.modules.character.builder.Component
- param pcomp
The parent component.
- type pcompop
c4d.modules.character.builder.ComponentObject
- param pcompop
The parent component object.
- rtype
bool
- return
True if mirroring was done by Python.
-
IncludeObjects
() - Override - Used to include additional objects with the component, similar to the Component tag’s Include tab.All objects that will be included should be defined in the global variable incdata as a BaseContainer
The following variables are local to this function:
- type doc
c4d.documents.BaseDocument
- param doc
The document containing the Character object.
- type iop
c4d.BaseObject
- param iop
The main component object that was inserted.
- type iparent
c4d.BaseObject
- param iparent
The parent component object of the inserted object.
- type icharop
c4d.modules.character.builder.CharacterObject
- param icharop
The Character object present in the scene.
- type iincdata
c4d.BaseContainer
- param iincdata
All objects that will be included where each entry is a BaseLink to the object and the index is an integer corresponding to the InExcludeData flags:
Value
Description
1
Hierarchy.
2
Sharing.
4
Self-Sharing.
- rtype
bool
- return
True if incdata was changed.
-
AdjustObject
() - Override - Used in the Adjustments tab in the Code field of a Python type Adjustment rule.Called continuously while the related handle is being adjusted.
Note
All matrices for this function are local to the Character object.This function is called after AdjustObject.The following variables are local to this function:
- type doc
c4d.documents.BaseDocument
- param doc
The document containing the Character object.
- type op
c4d.BaseObject
- param op
The object linked to the Adjustment rule.
- type targ
c4d.BaseObject
- param targ
The object linked in the field of the Adjustment rule.
- type cmg
c4d.Matrix
- param cmg
The matrix of the Character object.
- type m
c4d.Matrix
- param m
The object’s current matrix should not be modified.
- type om
c4d.Matrix
- param om
The object’s original matrix.
- type targm
c4d.Matrix
- param targm
The target’s current matrix
- type targom
c4d.Matrix
- param targom
The target’s original matrix.
- rtype
c4d.Matrix
- return
The matrix to set for the object.
-
GetDependency
() - Override - Used in the Adjustments tab in the Code field of a Python type Adjustment rule.It defines the objects upon which the rule depends (e.g. if an adjustment rule needs to set position based on 3 other objects - such as a pole vector - , it should be returned a c4d.BaseContainer with those 3 objects).This allows the Character object to create a dependency tree so that adjustments will be evaluated in the correct order, since one rule could change the object matrix used by another rule.
Note
This function is called prior to AdjustObject.
The following variables are local to this function:
- type doc
c4d.documents.BaseDocument
- param doc
The document containing the Character object.
- type op
c4d.BaseObject
- param op
The object linked to the Adjustment rule.
- type linkop
c4d.BaseObject
- param linkop
The object linked in the field of the Adjustment rule.
- rtype
c4d.BaseContainer
- return
Containing BaseLinks (ID isn’t evaluated) of the dependent objects.
-
TransformComponent
() - Override - Used in the Insertion tab in the Code field of a Python type Insertion rule.It defines the coordinates of the component.
Note
All matrices for this function are local to the Character object.The following variables are local to this function:
- type doc
c4d.documents.BaseDocument
- param doc
The document containing the Character object.
- type template
c4d.modules.character.builder.Template
- param template
The template.
- type charop
c4d.modules.character.builder.CharacterObject
- param charop
The Character object present in the scene.
- type pcompop
c4d.modules.character.builder.ComponentObject
- param pcompop
The parent component object.
- type pcomp
c4d.modules.character.builder.Component
- param pcomp
The parent component.
- type op
c4d.BaseObject
- param op
The main component object.
- rtype
c4d.Matrix
- return
The new global matrix to set for the main component object.
-
AllowComponent
() - Override - Used in the Insertion tab in the Code field of a Python type Insertion rule.It defines if the component is allowed.
The following variables are local to this function:
- type doc
c4d.documents.BaseDocument
- param doc
The document containing the Character object.
- type charop
c4d.modules.character.builder.CharacterObject
- param charop
The Character object present in the scene.
- type template
c4d.modules.character.builder.Template
- param template
The template.
- rtype
bool
- return
True if the component is allowed otherwise False.