c4d.C4DAtom¶
-
class
c4d.C4DAtom¶ The base class of many other classes.
Child Class:
Overview¶
Copying And Cloning |
|
Copies all values from self to dst. The atoms must be of the same type! |
|
Clones the object and returns the reference. |
|
Description And Parameters |
|
Gets the description for this atom. |
|
Gets a description parameter of this atom. |
|
Sets a description parameter of this atom. |
|
Dirty State |
|
Returns the dirty counter for the passed dirty flags on this scene element. |
|
Returns the accumulated dirty counter for the passed dirty flags in this local hierarchy |
|
Marks the passed dirty flags on this scene element as changed. |
|
Reports the passed dirty flags to parent nodes and branch owners. |
|
Lifecycle And Type |
|
Checks if this atom is an instance of a base type. |
|
Returns the base type of the object, e.g. |
|
Checks if a description parameter should be disabled or enabled. |
|
Get the real type of the atom. |
|
Get the type of the atom. |
|
Even though a reference to an object still exists, the object might be freed by an user interaction. |
|
Checks if this atom is an instance of a base type. |
|
Magic Methods |
|
Returns the atom if it is alive or None if the atom is dead. |
|
Returns a hash of the Unique ID derived of the given C4DAtom. |
|
Check if two different objects point to the same object. |
|
Messaging |
|
Sends a message to the atom. |
|
Sends a message to the atom and to its children, parents or branches, depending on flags. |
|
Serialization |
|
Reads to this atom from a |
|
Reads to this atom from a |
|
Writes the atom to a |
|
Writes this atom to a |
|
Unique Identifiers |
|
Adds unique application ID to the object. |
|
Checks for a specific unique application ID. |
|
Retrieves the number of unique application IDs. |
|
Gets the idx-th unique application ID data. |
|
Members¶
Copying And Cloning¶
-
C4DAtom.CopyTo(self, dst, flags, trn=None)¶ Copies all values from self to dst. The atoms must be of the same type!
- Parameters
dst (c4d.C4DAtom) – The destination.
flags (int) –
Optional flags for the copy:
Key
Description
COPYFLAGS_NONE
None.
COPYFLAGS_NO_HIERARCHY
Copy without children.
COPYFLAGS_NO_ANIMATION
Copy without tracks, sequences or keys.
COPYFLAGS_NO_BITS
Do not copy
BaseList2Dbits.COPYFLAGS_NO_MATERIALPREVIEW
Do not create a new material preview.
COPYFLAGS_NO_BRANCHES
Do not copy branches, for example tags on an object. Automatically implies COPYFLAGS_NO_ANIMATION, as animation is a branch.
COPYFLAGS_DOCUMENT
Read-only flag set when a complete document is copied.
COPYFLAGS_NO_NGONS
Do not copy N-gons.
COPYFLAGS_CACHE_BUILD
Read-only flag set when cache is built.
COPYFLAGS_RECURSIONCHECK
Checks and avoids instances to cause recursions.
COPYFLAGS_PRIVATE_IDENTMARKER
Private.
COPYFLAGS_PRIVATE_NO_INTERNALS
Private.
COPYFLAGS_PRIVATE_NO_PLUGINLAYER
Private.
COPYFLAGS_PRIVATE_UNDO
Private.
COPYFLAGS_PRIVATE_NO_TAGS
Private.
COPYFLAGS_PRIVATE_DELETE
Private.
COPYFLAGS_PRIVATE_NO_ASSETS
Private.
COPYFLAGS_PRIVATE_NO_RESULTASSETS
Private.
COPYFLAGS_PRIVATE_NO_LOGS
Private.
COPYFLAGS_PRIVATE_BODYPAINT_NODATA
Private.
COPYFLAGS_PRIVATE_BODYPAINT_CONVERTLAYER
Private.
COPYFLAGS_PRIVATE_BODYPAINT_CONVERTLAYER
Private.
COPYFLAGS_PRIVATE_NO_DESCRIPTION
New in version 2024.5: Private
trn (Optional[c4d.AliasTrans]) –
New in version R17.032.
An optional alias translator for the operation.
- Return type
bool
- Returns
True if the atom was copied.
-
C4DAtom.GetClone(self, flags=0, trn=None)¶ Clones the object and returns the reference.
- Parameters
flags (int) –
Optional flags for the clone:
Key
Description
COPYFLAGS_NONE
None.
COPYFLAGS_NO_HIERARCHY
Copy without children.
COPYFLAGS_NO_ANIMATION
Copy without tracks, sequences or keys.
COPYFLAGS_NO_BITS
Do not copy
BaseList2Dbits.COPYFLAGS_NO_MATERIALPREVIEW
Do not create a new material preview.
COPYFLAGS_NO_BRANCHES
Do not copy branches, for example tags on an object. Automatically implies COPYFLAGS_NO_ANIMATION, as animation is a branch.
COPYFLAGS_DOCUMENT
Read-only flag set when a complete document is copied.
COPYFLAGS_NO_NGONS
Do not copy N-gons.
COPYFLAGS_CACHE_BUILD
Read-only flag set when cache is built.
COPYFLAGS_RECURSIONCHECK
Checks and avoids instances to cause recursions.
COPYFLAGS_PRIVATE_IDENTMARKER
Private.
COPYFLAGS_PRIVATE_NO_INTERNALS
Private.
COPYFLAGS_PRIVATE_NO_PLUGINLAYER
Private.
COPYFLAGS_PRIVATE_UNDO
Private.
COPYFLAGS_PRIVATE_NO_TAGS
Private.
COPYFLAGS_PRIVATE_DELETE
Private.
COPYFLAGS_PRIVATE_NO_ASSETS
Private.
COPYFLAGS_PRIVATE_NO_RESULTASSETS
Private.
COPYFLAGS_PRIVATE_NO_LOGS
Private.
COPYFLAGS_PRIVATE_BODYPAINT_NODATA
Private.
COPYFLAGS_PRIVATE_BODYPAINT_CONVERTLAYER
Private.
COPYFLAGS_PRIVATE_BODYPAINT_CONVERTLAYER
Private.
COPYFLAGS_PRIVATE_NO_DESCRIPTION
New in version 2024.5: Private
trn (Optional[c4d.AliasTrans]) –
New in version R17.032.
An optional alias translator for the operation.
- Return type
- Returns
Minimum of type atom.
Description And Parameters¶
-
C4DAtom.GetDescription(self, flags)¶ Gets the description for this atom.
New in version R15.037.
Warning
Every caller ofGetDescription()gets a copy of the object’s description, including the Attribute Manager.The only way to customize the description is to overrideNodeData.GetDDescription().- Parameters
flags (int) –
Flags:
DESCFLAGS_DESC_NONE
None.
DESCFLAGS_DESC_RESOLVEMULTIPLEDATA
Private and unused.
DESCFLAGS_DESC_LOADED
Set if elements have been added to the description, either by loading or manual addition.
DESCFLAGS_DESC_RECURSIONLOCK
Private.
DESCFLAGS_DESC_DONTLOADDEFAULT
If set, the object description will also contain the tag’s descriptions (as sub-containers).
DESCFLAGS_DESC_MAPTAGS
If specified, the object description will also contain the tag’s descriptions (as sub-containers).
DESCFLAGS_DESC_NEEDDEFAULTVALUE
Set if “Reset to Default” was called by the user.
- Return type
- Returns
The atom’s description.
-
C4DAtom.GetParameter(self, id, flags)¶ Gets a description parameter of this atom.
New in version R16.021.
- Parameters
id (c4d.DescID) – The ID of the parameter.
flags (int) –
Flags:
DESCFLAGS_GET_NONE
None.
DESCFLAGS_GET_PARAM_GET
Parameter retrieved.
DESCFLAGS_GET_NO_GEDATADEFAULTVALUE
If set, the C++ GeData default type will not be initialized for
C4DAtom.GetParameter().DESCFLAGS_GET_NO_GLOBALDATA
Private.
- Return type
Optional[Any]
- Returns
The parameter data, or None if an error occured.
-
C4DAtom.SetParameter(self, id, data, flags)¶ Sets a description parameter of this atom.
New in version R16.021.
- Parameters
id (c4d.DescID) – The ID of the parameter.
data (any) – The parameter data to set.
flags (int) –
Flags:
DESCFLAGS_SET_NONE
None.
DESCFLAGS_SET_PARAM_SET
Parameter set.
DESCFLAGS_SET_USERINTERACTION
Set when the GUI is calling
SetParameter(). This is the only time whenSetParameter()is allowed to use user interaction elements (e.g. open dialogs, display messages etc.).DESCFLAGS_SET_DONTCHECKMINMAX
No check is internally done if the parameter passed is within the [min/max] range of the description, to save some time.
DESCFLAGS_SET_DONTAFFECTINHERITANCE
No parameter inheritance, for render settings and post effects only.
DESCFLAGS_SET_FORCESET
Forces the set value without
GetParameter()/Compare. Use only for calls where for sure the value was changed!DESCFLAGS_SET_DONTFREESPLINECACHE
- Private.
New in version R16.038.
DESCFLAGS_SET_INDRAG
- Gadget (e.g. Slider) in dragging mode (not finished). Only used when DESCFLAGS_SET_USERINTERACTION is set.
New in version R17.053.
- Return type
bool
- Returns
True if the parameter was set, otherwise False.
Dirty State¶
-
C4DAtom.GetDirty(self, flags)¶ Returns the dirty counter for the passed dirty flags on this scene element.
Call this on the element being monitored. The counters for all passed flags are summed; compare the result with an earlier value to detect changes.
See also
GetHDirty()for the accumulated dirty counter in the local hierarchy.- Parameters
flags (int) –
The passed dirty flags:
Expresses dirty state categories for a single scene element. Unlike
HDIRTYFLAGS, these flags only track changes on the element itself.DIRTYFLAGS_NONE
Signals no state.
DIRTYFLAGS_MATRIX
Signals that the matrix of a
BaseObjecthas changed.DIRTYFLAGS_DATA
Signals that container or parameter data of a scene element has changed.
DIRTYFLAGS_SELECT
Signals that a point, edge, or polygon selection of a
BaseObjecthas changed.DIRTYFLAGS_CACHE
Signals that the cache of a
BaseObjecthas changed or been rebuilt.DIRTYFLAGS_CHILDREN
Signals that owned child data of a scene element, such as animation keys, has changed.
DIRTYFLAGS_DESCRIPTION
Signals that the description of a scene element has changed.
DIRTYFLAGS_VISIBILITY
Signals that the visibility state of a scene element has changed.
DIRTYFLAGS_SELECTION_OBJECTS
Signals that the object selection of a
BaseDocumenthas changed.DIRTYFLAGS_SELECTION_TAGS
Signals that the tag selection of a
BaseDocumenthas changed.DIRTYFLAGS_SELECTION_MATERIALS
Signals that the material selection of a
BaseDocumenthas changed.DIRTYFLAGS_ALL
Signals all states.
- Return type
int
- Returns
The dirty counter.
-
C4DAtom.GetHDirty(self, mask)¶ Returns the accumulated dirty counter for the passed dirty flags in this local hierarchy and its branches.
Call this on any element to collect its own dirty counters and those of its descendants. Counters for all passed flags are summed; compare the result with an earlier value to detect matching changes.
See also
GetDirty()for the dirty counter of this element only.New in version R19.
- Parameters
mask (int) –
The passed dirty flags:
Expresses hierarchical or branching dirty state categories for a scene element. These states propagate from the changed scene element to its parent elements and branch owners.
HDIRTYFLAGS_NONE
Signals no state.
HDIRTYFLAGS_ANIMATION
Signals that animation data in a hierarchy has changed.
HDIRTYFLAGS_OBJECT
Signals that object data in a hierarchy has changed.
HDIRTYFLAGS_OBJECT_MATRIX
Signals that an object matrix in a hierarchy has changed.
HDIRTYFLAGS_OBJECT_HIERARCHY
Signals that an object hierarchy in a hierarchy has changed.
HDIRTYFLAGS_TAG
Signals that tag data in a hierachy has changed.
HDIRTYFLAGS_MATERIAL
Signals that material data in a hierachy has changed.
HDIRTYFLAGS_SHADER
Signals that shader data in a hierachy has changed.
HDIRTYFLAGS_RENDERSETTINGS
Signals that render settings in a hierachy have changed.
HDIRTYFLAGS_VP
Signals that a video post effect in a hierachy has changed.
HDIRTYFLAGS_FILTER
Signals that a filter in a hierachy has changed.
HDIRTYFLAGS_NBITS
Signals that bit flags in a hierachy have changed.
HDIRTYFLAGS_ALL
Signals all states.
- Return type
int
- Returns
The accumulated dirty counter.
-
C4DAtom.SetDirty(self, flags)¶ Marks the passed dirty flags on this scene element as changed.
Call this on the element that changed. This updates the corresponding dirty counters returned by
GetDirty(); derived element types can also report the change to their parent nodes.See also
SetHDirty()for reporting dirty flags to parent nodes.- Parameters
flags (int) –
The passed dirty flags:
Expresses dirty state categories for a single scene element. Unlike
HDIRTYFLAGS, these flags only track changes on the element itself.DIRTYFLAGS_NONE
Signals no state.
DIRTYFLAGS_MATRIX
Signals that the matrix of a
BaseObjecthas changed.DIRTYFLAGS_DATA
Signals that container or parameter data of a scene element has changed.
DIRTYFLAGS_SELECT
Signals that a point, edge, or polygon selection of a
BaseObjecthas changed.DIRTYFLAGS_CACHE
Signals that the cache of a
BaseObjecthas changed or been rebuilt.DIRTYFLAGS_CHILDREN
Signals that owned child data of a scene element, such as animation keys, has changed.
DIRTYFLAGS_DESCRIPTION
Signals that the description of a scene element has changed.
DIRTYFLAGS_VISIBILITY
Signals that the visibility state of a scene element has changed.
DIRTYFLAGS_SELECTION_OBJECTS
Signals that the object selection of a
BaseDocumenthas changed.DIRTYFLAGS_SELECTION_TAGS
Signals that the tag selection of a
BaseDocumenthas changed.DIRTYFLAGS_SELECTION_MATERIALS
Signals that the material selection of a
BaseDocumenthas changed.DIRTYFLAGS_ALL
Signals all states.
-
C4DAtom.SetHDirty(self, mask)¶ Reports the passed dirty flags to parent nodes and branch owners.
Call this on the element that changed. This marks each passed flag and propagates newly marked flags to parent nodes and branch owners.
See also
SetDirty()for marking this element as dirty.New in version R19.
- Parameters
mask (int) –
The passed dirty flags:
Expresses hierarchical or branching dirty state categories for a scene element. These states propagate from the changed scene element to its parent elements and branch owners.
HDIRTYFLAGS_NONE
Signals no state.
HDIRTYFLAGS_ANIMATION
Signals that animation data in a hierarchy has changed.
HDIRTYFLAGS_OBJECT
Signals that object data in a hierarchy has changed.
HDIRTYFLAGS_OBJECT_MATRIX
Signals that an object matrix in a hierarchy has changed.
HDIRTYFLAGS_OBJECT_HIERARCHY
Signals that an object hierarchy in a hierarchy has changed.
HDIRTYFLAGS_TAG
Signals that tag data in a hierachy has changed.
HDIRTYFLAGS_MATERIAL
Signals that material data in a hierachy has changed.
HDIRTYFLAGS_SHADER
Signals that shader data in a hierachy has changed.
HDIRTYFLAGS_RENDERSETTINGS
Signals that render settings in a hierachy have changed.
HDIRTYFLAGS_VP
Signals that a video post effect in a hierachy has changed.
HDIRTYFLAGS_FILTER
Signals that a filter in a hierachy has changed.
HDIRTYFLAGS_NBITS
Signals that bit flags in a hierachy have changed.
HDIRTYFLAGS_ALL
Signals all states.
Lifecycle And Type¶
-
C4DAtom.CheckType(self, id)¶ Checks if this atom is an instance of a base type.
Note
This is only an alias to
C4DAtom.IsInstanceOf()- Parameters
id (int) – The base type ID, for example Ocube.
- Return type
int
- Returns
True if the atom is an instance of the type id, otherwise False.
-
C4DAtom.GetClassification(self)¶ Returns the base type of the object, e.g. for all objects Obase, for all materials Mmat, for all tags Tbase etc.
- Return type
int
- Returns
The base type.
-
C4DAtom.GetEnabling(self, DescID)¶ Checks if a description parameter should be disabled or enabled.
New in version 24.
- Parameters
DescID (c4d.DescID) – The ID of the parameter.
- Return type
bool
- Returns
True if the parameter is enabled, otherwise False
-
C4DAtom.GetRealType(self)¶ - Get the real type of the atom.This is similar to
GetType(), but for multinodes the ID of the last linked part is returned.E.g. XPresso nodes have the type ID_GV_GROUPDATA or ID_GV_NODEDATA. WithGetRealType()you will get the ID of the operator as a return value.New in version R15.037.
- Return type
int
- Returns
The real type, for example Ocube.
-
C4DAtom.GetType(self)¶ - Get the type of the atom.This must be used to make sure that the derived object really is of the right type before trying to access its members.
- Return type
int
- Returns
The type, for example Ocube.
-
C4DAtom.IsAlive(self)¶ - Even though a reference to an object still exists, the object might be freed by an user interaction. Normally not needed.E.g. the C++ Python Object representing a BaseList2D actually store a pointer to this BaseList2D.This pointed BaseList2D could be dead for some reason, but we still have a Python object. So in this case IsAlive will return False.
- Return type
bool
- Returns
True if the object is still alive, otherwise False
-
C4DAtom.IsInstanceOf(self, id)¶ Checks if this atom is an instance of a base type.
New in version R16.021.
- Parameters
id (int) – The base type ID, for example Ocube.
- Return type
int
- Returns
True if the atom is an instance of the type id, otherwise False.
Magic Methods¶
-
C4DAtom.__call__(self)¶ - Returns the atom if it is alive or None if the atom is dead.This is a convenient way to know if you can still use the object.
- Return type
Optional[c4d.C4DAtom]
- Returns
The atom if it is still alive, otherwise None.
-
C4DAtom.__eq__(self, other)¶
-
C4DAtom.__hash__(self)¶ Returns a hash of the Unique ID derived of the given C4DAtom.
print(hash(obj) #hash calls obj.__hash__())
- Return type
int
- Returns
Hash value
-
C4DAtom.__ne__(self, other)¶ Check if two different objects point to the same object.
Note
Does not compare if two different objects are equal.
- Return type
bool
- Returns
True if the objects point to the same object, otherwise False.
Messaging¶
-
C4DAtom.Message(self, type, data=None)¶ Sends a message to the atom.
See also
C4DAtom and Plugin Messages for information on the messages type, data and input/output.
Note
Some notification messages are automatically passed along to branches: MSG_POINTS_CHANGED, MSG_POLYGONS_CHANGED and MSG_SEGMENTS_CHANGED. This is for convenience and historical reasons.
- Parameters
type (int) – The message type.
data (Optional[any]) – The message data.
- Return type
bool
- Returns
Depends on the message type.
-
C4DAtom.MultiMessage(self, flags, type, data)¶ Sends a message to the atom and to its children, parents or branches, depending on flags.
See also
MSG for information on the messages type, data and input/output.
- Parameters
flags (int) –
A combination of the following flags:
MULTIMSG_ROUTE_NONE
None.
MULTIMSG_ROUTE_UP
Send to parents.
MULTIMSG_ROUTE_ROOT
Send to root object.
MULTIMSG_ROUTE_DOWN
Send to children.
MULTIMSG_ROUTE_BROADCAST
Broadcast the message, i.e. distribute it to all branches given by
GeListNode.GetBranchInfo().type (int) – The message type.
data (any) – The message data.
- Return type
bool
- Returns
Depends on the message type.
Serialization¶
-
C4DAtom.Read(self, hf, id, level)¶ Reads to this atom from a
HyperFile, manually specifying ID and level.Note
This is the function to use if you have opened the hyper file yourself and are reading the object separately.If reading within a plugin function where Cinema 4D has passed the hyper file you should useReadObject().Note
The methods
Read(),Write(),ReadObject()andWriteObject()are generally not recommended for plugins.- Parameters
hf (c4d.storage.HyperFile) – The hyperfile to read from.
id (int) – The ID of the atom to read.
level (int) – The disklevel of the atom to read.
- Return type
bool
- Returns
True if the atom was read, otherwise False.
-
C4DAtom.ReadObject(self, hf, readheader)¶ Reads to this atom from a
HyperFilewithin another read operation.Note
This is the function to use where Cinema 4D has passed the hyper file you should use, for example in a plugin hook.Otherwise you should useRead().Note
The methods
Read(),Write(),ReadObject()andWriteObject()are generally not recommended for plugins.- Parameters
hf (c4d.storage.HyperFile) – The hyperfile to read from.
readheader (bool) – Normally True. Should only be False if you have manually read the file header yourself.
- Return type
bool
- Returns
True if the atom was read, otherwise False.
-
C4DAtom.Write(self, hf)¶ Writes the atom to a
HyperFile.Note
This is the function to use if you have opened the hyper file yourself and are writing the object manually.If writing within a plugin function where Cinema 4D has passed the hyper file you should useWriteObject().Note
The methods
Read(),Write(),ReadObject()andWriteObject()are generally not recommended for plugins.- Parameters
hf (c4d.storage.HyperFile) – The hyperfile to write to.
- Return type
bool
- Returns
True if the atom was written, otherwise False.
-
C4DAtom.WriteObject(self, hf)¶ Writes this atom to a
HyperFile, within another write operation.Note
This is the function to use where Cinema 4D has passed the hyper file you should use, for example in a plugin hook.Otherwise you should useWrite().Note
The methods
Read(),Write(),ReadObject()andWriteObject()are generally not recommended for plugins.- Parameters
hf (c4d.storage.HyperFile) – The hyperfile to write to.
- Return type
bool
- Returns
True if the atom was written, otherwise False.
Unique Identifiers¶
-
C4DAtom.AddUniqueID(self, appid, mem)¶ Adds unique application ID to the object.
New in version R16.021.
- Parameters
appid (int) – A unique application ID, has to be registered at MAXON, at least it should be obtained from http://www.plugincafe.com
mem (bytes) – The unique application ID data. Used for instance to store the name of a software vendor.
- Return type
bool
- Returns
True if successful, otherwise False.
-
C4DAtom.FindUniqueID(self, appid)¶ Checks for a specific unique application ID.
New in version R16.021.
- Parameters
appid (int) – A unique application ID, has to be registered at MAXON, at least it should be obtained from http://www.plugincafe.com
- Return type
Optional[memoryview]
- Returns
The unique application ID data, or None if it could not be found.
-
C4DAtom.GetUniqueIDCount(self)¶ Retrieves the number of unique application IDs.
New in version R16.021.
- Return type
int
- Returns
The number of unique application IDs.
-
C4DAtom.GetUniqueIDIndex(self, idx)¶ Gets the idx-th unique application ID data.
New in version R16.050.
- Parameters
idx (int) – The unique ID index: 0<=idx<
GetUniqueIDCount()- Return type
Optional[Tuple[int, bytes]]
- Returns
The unique application ID and its data. Used for instance to read the name of a software vendor.
None if it could not be found.