c4d.C4DAtom

class c4d.C4DAtom

The base class of many other classes.

Methods Signatures

C4DAtom.__eq__(self, other)

C4DAtom.__ne__(self, other)

Check if two different objects point to the same object.

C4DAtom.__hash__(self)

Returns a hash of the Unique ID derived of the given C4DAtom.

C4DAtom.__call__(self)

Returns the atom if it is alive or None if the atom is dead.

C4DAtom.SetDirty(self, flags)

Sets the dirty checksum, the one returned by GetDirty().

C4DAtom.GetDirty(self, flags)

Gets the dirty checksum for the object.

C4DAtom.GetHDirty(self, mask)

Returns the dirty count for the specified mask.

C4DAtom.SetHDirty(self, mask)

Sets the dirty flags for the specified mask.

C4DAtom.IsAlive(self)

Even though a reference to an object still exists, the object might be freed by an user interaction. Normally not needed.

C4DAtom.CheckType(self, id)

Checks if this atom is an instance of a base type.

C4DAtom.IsInstanceOf(self, id)

Checks if this atom is an instance of a base type.

C4DAtom.GetType(self)

Get the type of the atom.

C4DAtom.GetRealType(self)

Get the real type of the atom.

C4DAtom.GetEnabling(self, DescID)

Checks if a description parameter should be disabled or enabled.

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.

C4DAtom.Message(self, type[, data])

Sends a message to the atom.

C4DAtom.MultiMessage(self, flags, type, data)

Sends a message to the atom and to its children, parents or branches, depending on flags.

C4DAtom.CopyTo(self, dst, flags[, trn])

Copies all values from self to dst. The atoms must be of the same type!

C4DAtom.GetClone(self[, flags, trn])

Clones the object and returns the reference.

C4DAtom.Write(self, hf)

Writes the atom to a HyperFile.

C4DAtom.Read(self, hf, id, level)

Reads to this atom from a HyperFile, manually specifying ID and level.

C4DAtom.WriteObject(self, hf)

Writes this atom to a HyperFile, within another write operation.

C4DAtom.ReadObject(self, hf, readheader)

Reads to this atom from a HyperFile within another read operation.

C4DAtom.GetDescription(self, flags)

Gets the description for this atom.

C4DAtom.GetParameter(self, id, flags)

Gets a description parameter of this atom.

C4DAtom.SetParameter(self, id, data, flags)

Sets a description parameter of this atom.

C4DAtom.FindUniqueID(self, appid)

Checks for a specific unique application ID.

C4DAtom.AddUniqueID(self, appid, mem)

Adds unique application ID to the object.

C4DAtom.GetUniqueIDCount(self)

Retrieves the number of unique application IDs.

C4DAtom.GetUniqueIDIndex(self, idx)

Gets the idx-th unique application ID data.

Inheritance

Child Class:

Methods Documentation

C4DAtom.__eq__(self, other)
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.

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.__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.SetDirty(self, flags)

Sets the dirty checksum, the one returned by GetDirty().

Parameters

flags (int) –

Flags:

DIRTYFLAGS_NONE

None.

DIRTYFLAGS_MATRIX

Matrix changed.

DIRTYFLAGS_DATA

Container changed.

DIRTYFLAGS_SELECT

Checks all valid selections of the object, e.g. points, edge, polys.

DIRTYFLAGS_CACHE

Checks if the cache of an object has been changed (rebuilt).

DIRTYFLAGS_CHILDREN

Checks if the children are dirty.

DIRTYFLAGS_DESCRIPTION

Description changed.

DIRTYFLAGS_SELECTION_OBJECTS

For BaseDocument, object selections have changed.

DIRTYFLAGS_SELECTION_TAGS

For BaseDocument, tag selections have changed.

DIRTYFLAGS_SELECTION_MATERIALS

For BaseDocument, material selections have changed.

DIRTYFLAGS_ALL

Check all dirty flags.

C4DAtom.GetDirty(self, flags)
Gets the dirty checksum for the object.
This can be used to check if the object has been changed.
Parameters

flags (int) –

Flags:

DIRTYFLAGS_NONE

None.

DIRTYFLAGS_MATRIX

Matrix changed.

DIRTYFLAGS_DATA

Container changed.

DIRTYFLAGS_SELECT

Checks all valid selections of the object, e.g. points, edge, polys.

DIRTYFLAGS_CACHE

Checks if the cache of an object has been changed (rebuilt).

DIRTYFLAGS_CHILDREN

Checks if the children are dirty.

DIRTYFLAGS_DESCRIPTION

Description changed.

DIRTYFLAGS_SELECTION_OBJECTS

For BaseDocument, object selections have changed.

DIRTYFLAGS_SELECTION_TAGS

For BaseDocument, tag selections have changed.

DIRTYFLAGS_SELECTION_MATERIALS

For BaseDocument, material selections have changed.

DIRTYFLAGS_ALL

Check all dirty flags.

Return type

int

Returns

The checksum.

C4DAtom.GetHDirty(self, mask)

Returns the dirty count for the specified mask.

New in version R19.

Parameters

mask (int) –

The dirty flags:

HDIRTYFLAGS_NONE

None.

HDIRTYFLAGS_ANIMATION

Animation mask.

HDIRTYFLAGS_OBJECT

Object data mask.

HDIRTYFLAGS_OBJECT_MATRIX

Object matrix mask.

HDIRTYFLAGS_OBJECT_HIERARCHY

Object hierarchy mask.

HDIRTYFLAGS_TAG

Tag data mask.

HDIRTYFLAGS_MATERIAL

Material data mask.

HDIRTYFLAGS_SHADER

Shader data mask.

HDIRTYFLAGS_RENDERSETTINGS

Render settings mask.

HDIRTYFLAGS_VP

Videopost mask.

HDIRTYFLAGS_FILTER

Filter data mask.

HDIRTYFLAGS_NBITS

N-bits data mask.

HDIRTYFLAGS_ALL

All.

Return type

int

Returns

The dirty count.

C4DAtom.SetHDirty(self, mask)

Sets the dirty flags for the specified mask.

New in version R19.

Parameters

mask (int) –

The dirty flags:

HDIRTYFLAGS_NONE

None.

HDIRTYFLAGS_ANIMATION

Animation mask.

HDIRTYFLAGS_OBJECT

Object data mask.

HDIRTYFLAGS_OBJECT_MATRIX

Object matrix mask.

HDIRTYFLAGS_OBJECT_HIERARCHY

Object hierarchy mask.

HDIRTYFLAGS_TAG

Tag data mask.

HDIRTYFLAGS_MATERIAL

Material data mask.

HDIRTYFLAGS_SHADER

Shader data mask.

HDIRTYFLAGS_RENDERSETTINGS

Render settings mask.

HDIRTYFLAGS_VP

Videopost mask.

HDIRTYFLAGS_FILTER

Filter data mask.

HDIRTYFLAGS_NBITS

N-bits data mask.

HDIRTYFLAGS_ALL

All.

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.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.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.

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.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. With GetRealType() 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.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.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.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.

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:

    COPYFLAGS_NONE

    None.

    COPYFLAGS_NO_HIERARCHY

    Copy without children.

    COPYFLAGS_NO_ANIMATION

    Copy without tracks, sequences or keys.

    COPYFLAGS_NO_BITS

    Do not copy BaseList2D bits.

    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.

  • 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=COPYFLAGS_NONE, trn=None)

Clones the object and returns the reference.

Parameters
  • flags (int) –

    Optional flags for the clone:

    COPYFLAGS_NONE

    None.

    COPYFLAGS_NO_HIERARCHY

    Copy without children.

    COPYFLAGS_NO_ANIMATION

    Copy without tracks, sequences or keys.

    COPYFLAGS_NO_BITS

    Do not copy BaseList2D bits.

    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.

  • trn (Optional[c4d.AliasTrans]) –

    New in version R17.032.

    An optional alias translator for the operation.

Return type

c4d.C4DAtom

Returns

Minimum of type atom.

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 use WriteObject().

Note

The methods Read(), Write(), ReadObject() and WriteObject() 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.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 use ReadObject().

Note

The methods Read(), Write(), ReadObject() and WriteObject() 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.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 use Write().

Note

The methods Read(), Write(), ReadObject() and WriteObject() 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.ReadObject(self, hf, readheader)

Reads to this atom from a HyperFile within 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 use Read().

Note

The methods Read(), Write(), ReadObject() and WriteObject() 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.GetDescription(self, flags)

Gets the description for this atom.

New in version R15.037.

Warning

Every caller of GetDescription() gets a copy of the object’s description, including the Attribute Manager.
The only way to customize the description is to override NodeData.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

c4d.Description

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 when SetParameter() 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.

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.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.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.