c4d.plugins.ObjectData

An object plugin class to be registered with RegisterObjectPlugin().

Note

Before starting to develop an ObjectData plugin, read Optimize Cache and NodeData Management before.

See also

Py-DoubleCircle, Py-Gravitation, Py-RoundedTube and Py-SpherifyModifier plugin examples.

c4d.plugins.ObjectData

class c4d.plugins.ObjectData

An object plugin class to be registered with RegisterObjectPlugin().

Note

Before starting to develop an ObjectData plugin, read NodeData Management before.

See also

Py-DoubleCircle, Py-Gravitation, Py-RoundedTube and Py-SpherifyModifier plugin examples.

Methods Signatures

Generic Methods

ObjectData.AddToExecution(self, op, list)
Override - By default this function returns False.
ObjectData.Draw(self, op, drawpass, bd, bh) Override - Called when the display is updated for you to display some visual element of your op in the 3D view.
ObjectData.DrawShadow(self, op, bd, bh) Called during the shadow pass instead of the Draw() method.
ObjectData.Execute(self, op, doc, bt, ...) Override - Called at the point in the priority pipeline specified by AddToExecution(), or the lack thereof.
ObjectData.GetContour(self, op, doc, lod, bt) Override - Return a spline contour. For spline objects only.
ObjectData.GetDimension(self, op, mp, rad) Override - Return the boundaries of your object.
ObjectData.GetVirtualObjects(self, op, hh) Override - Return an object chain of a generator object (e.g. a polygonal object).

Handle Methods

ObjectData.DetectHandle(self, op, bd, x, y, ...) Override - Manually detect a click on a handle.
ObjectData.GetHandle(self, op, i, info) Called to get the information for handle at index i. Part of the automated handle interface.
ObjectData.GetHandleCount(self, op) Called to get the number of handles the object has. Part of the automated handle interface.
ObjectData.MoveHandle(self, op, undo, ...) Override - Move a handle manually.
ObjectData.SetHandle(self, op, i, p, info)
Called to set the information for handle at index i. Part of the automated handle interface.

Modifier Specific Methods

ObjectData.CheckDirty(self, op, doc)
Override - You can override this function to check for a change in the object manually.
ObjectData.ModifyObject(self, mod, doc, op, ...) Override - Called when an object plugin should modify the passed object.

Particle Specific Methods

ObjectData.ModifyParticles(self, op, pp, ss, pcnt, ...) Override - Called for modifying particles. This is for particle modifiers only.

Inheritance

Inheritance

Parent Class:

Methods Documentation

ObjectData.AddToExecution(self, op, list)
Override - By default this function returns False.
Then Cinema 4D will call Execute() at the priority specified by the user in the EXPRESSION_PRIORITY parameter of the container.

If you override this function and return True, then you can insert your own points of execution in the list by calling for example.

list.Add(op, c4d.EXECUTIONPRIORITY_ANIMATION, 0)
list.Add(op, c4d.EXECUTIONPRIORITY_GENERATOR, 0)
Parameters:
Return type:

bool
Returns:

True if you override this function and has added stuff to list.
ObjectData.Draw(self, op, drawpass, bd, bh)

Override - Called when the display is updated for you to display some visual element of your op in the 3D view.

Note

This function is called in a thread context.
Please see the important information about threading.
Parameters:
  • op (c4d.BaseObject) – The established base object.
  • drawpass (int) –

    One of the following flags:

    DRAWPASS_OBJECT Object pass.
    DRAWPASS_BOX Box pass.
    DRAWPASS_HANDLES Handle pass.
    DRAWPASS_HIGHLIGHTS Highlights pass.
    DRAWPASS_XRAY X-Ray pass.

    Warning

    Only draw in DRAWPASS_HIGHLIGHTS if you really know what you are doing.
    Otherwise always check the drawpass and then do not draw if it is DRAWPASS_HIGHLIGHTS.

    Here is an example.

    def Draw(self, op, drawpass, bd, bh):

    if drawpass==c4d.DRAWPASS_HIGHLIGHTS:
        return c4d.DRAWRESULT_SKIP

    # Put here your drawing operations

    return c4d.DRAWRESULT_OK

    Warning

    Only draw the object in one pass : DRAWPASS_OBJECT.
    The object’s appearance may change if you draw the same object in multiple passes.
  • bd (c4d.BaseDraw) – The editor’s view.
  • bh (c4d.plugins.BaseDrawHelp) – The BaseDrawHelp editor’s view.
Return type:

int
Returns:

Success of drawing into the editor view:

DRAWRESULT_ERROR There was an error while drawing.
DRAWRESULT_OK Something was drawn.
DRAWRESULT_SKIP There was nothing to draw in the pass.

ObjectData.DrawShadow(self, op, bd, bh)

Called during the shadow pass instead of the Draw() method.

New in version R14.014.

Parameters:
Return type:

int
Returns:

Success of drawing into the editor view:

DRAWRESULT_ERROR There was an error while drawing.
DRAWRESULT_OK Something was drawn.
DRAWRESULT_SKIP There was nothing to draw in the pass.

ObjectData.Execute(self, op, doc, bt, priority, flags)

Override - Called at the point in the priority pipeline specified by AddToExecution(), or the lack thereof.

Note

This function is called in a thread context.
Please see the important information about threading.
Parameters:
  • op (c4d.BaseObject) – The established base object.
  • doc (c4d.documents.BaseDocument) – The host document of the object.
  • bt (Optional[c4d.BaseThread]) – Currently not used.
  • priority (int) –

    The priority of this call to Execute() in the pipeline. Standard values are:

    EXECUTIONPRIORITY_INITIAL Initial.
    EXECUTIONPRIORITY_ANIMATION Animation.
    EXECUTIONPRIORITY_ANIMATION_NLA NLA.
    EXECUTIONPRIORITY_EXPRESSION Expression.
    EXECUTIONPRIORITY_DYNAMICS Dynamics.
    EXECUTIONPRIORITY_GENERATOR Generators.
    EXECUTIONPRIORITY_FORCE Highest priority that will ensure execution even if the execution pipeline is cancelled before. Only use this to e.g. release locks or do super-fast non-blocking operations.
  • flags (int) –

    A combination of the following flags:

    EXECUTIONFLAGS_NONE None.
    EXECUTIONFLAGS_ANIMATION Animation is calculated.
    EXECUTIONFLAGS_EXPRESSION Expressions are calculated.
    EXECUTIONFLAGS_CACHEBUILDING Cache building is done.
    EXECUTIONFLAGS_CAMERAONLY Only camera dependent expressions shall be executed.
    EXECUTIONFLAGS_INDRAG Pipeline is done within scrubbing.
    EXECUTIONFLAGS_INMOVE Pipeline is done within moving.
    EXECUTIONFLAGS_RENDER The external renderer (Picture Viewer) is running.
    EXECUTIONFLAGS_ALLOW_PRIORITYSHIFT

    New in version R18: Allow to shift the priority with the priority shift tag. Private.
Return type:

int
Returns:

The result:

EXECUTIONRESULT_OK OK.
EXECUTIONRESULT_USERBREAK User break.
EXECUTIONRESULT_MEMORYERROR Not enough memory.

ObjectData.GetContour(self, op, doc, lod, bt)

Override - Return a spline contour. For spline objects only.

Note

This function is called in a thread context.
Please see the important information about threading.

Note

Splines created through GetContour() are cached.
To make this frame dependent, CheckDirty() can be overloaded to set the object dirty if a certain condition has changed.

Warning

Must not be overridden for non-spline objects.

Parameters:
Return type:

c4d.SplineObject or None
Returns:

The newly allocated spline or None
ObjectData.GetDimension(self, op, mp, rad)

Override - Return the boundaries of your object.

def GetDimension(self, op, mp, rad):
    '''
    (i) When the method runs without a raised exception
    mp and rad will be internally copied, otherwise they
    are ignored.
    '''

    mp.x = self.x_size   # correct
    mp.y = self.y_size   # correct
    mp.z = self.z_size   # correct

    mp = c4d.Vector(x_size, y_size, z_size)    #!!! wrong !!! do not rebind mp!
    #this assign applies for 'rad' as well
    return
Parameters:
  • op (c4d.BaseObject) – The established base object.
  • mp (c4d.Vector) – Assign the center point of the bounding box to this vector.
  • rad (c4d.Vector) – Assign the XYZ bounding box radius to this vector.
ObjectData.GetVirtualObjects(self, op, hh)

Override - Return an object chain of a generator object (e.g. a polygonal object).

Note

This function is called in a thread context.
Please see the important information about threading.

Note

Please read the Optimize Cache section at the top of this page to get in touch with the caching options.

Warning

Must not be overridden for non-generator objects.

Parameters:
Return type:

c4d.BaseObject
Returns:

The newly allocated object chain, or None if a memory error occured.

Note

Only return None in the case of a memory error.
If the generator does not produce any output (e.g. when the user chooses wrong settings) it must at least return an (empty) Onull object, otherwise Cinema 4D will try to rebuild the cache again and again.
ObjectData.DetectHandle(self, op, bd, x, y, qualifier)

Override - Manually detect a click on a handle.

Parameters:
  • op (c4d.BaseObject) – The established base object.
  • bd (c4d.BaseDraw) – The editor’s view.
  • x (int) – The mouse X coordinate.
  • y (int) – The mouse Y coordinate.
  • qualifier (int) –

    Any qualifier keys that were pressed. These are defined in c4d.gui:

    QUALIFIER_SHIFT SHIFT key.
    QUALIFIER_CTRL CTRL key.
    QUALIFIER_MOUSEHIT Indication in ObjectData.DetectHandle() that the user pressed the mouse (ObjectData.DetectHandle() is also called for cursor information, when hovering over a handle). For instance if QUALIFIER_MOUSEHIT and QUALIFIER_CTRL are set, ObjectData.DetectHandle() could create a new element.
Return type:

int
Returns:

The handle ID that is to be passed to MoveHandle()
ObjectData.GetHandle(self, op, i, info)

Called to get the information for handle at index i. Part of the automated handle interface.

New in version R18.011.

Parameters:
  • op (c4d.BaseObject) – The established base object.
  • i (int) – The handle index.
  • info (c4d.HandleInfo) – Fill with the handle information.
ObjectData.GetHandleCount(self, op)

Called to get the number of handles the object has. Part of the automated handle interface.

New in version R18.011.

Parameters:op (c4d.BaseObject) – The established base object.
Return type:int
Returns:The number of handles for the object.
ObjectData.MoveHandle(self, op, undo, mouse_pos, hit_id, qualifier, bd)

Override - Move a handle manually.

Parameters:
  • op (c4d.BaseObject) – The established base object.
  • undo (c4d.BaseObject) – This is a copy of the object that must not be modified during the move handle.
  • mouse_pos (c4d.Vector) – The current mouse position.
  • hit_id (int) – The handle ID returned from DetectHandle()
  • qualifier (int) –

    Any qualifier keys that were pressed. These are defined in c4d.gui:

    QUALIFIER_SHIFT SHIFT key.
    QUALIFIER_CTRL CTRL key.
    QUALIFIER_MOUSEHIT Indication in ObjectData.DetectHandle() that the user pressed the mouse (ObjectData.DetectHandle() is also called for cursor information, when hovering over a handle). For instance if QUALIFIER_MOUSEHIT and QUALIFIER_CTRL are set, ObjectData.DetectHandle() could create a new element.
  • bd (c4d.BaseDraw) – The editor’s view.
Return type:

bool
Returns:

Success of modifying the handle.
ObjectData.SetHandle(self, op, i, p, info)
Called to set the information for handle at index i. Part of the automated handle interface.
Called when the user has moved handle i to position p. Update the object’s internal data accordingly (e.g. parameter values etc).

New in version R18.011.

Parameters:
ObjectData.CheckDirty(self, op, doc)
Override - You can override this function to check for a change in the object manually.
This example will make your object update every frame.
def CheckDirty(self, op, doc):

    frame = doc.GetTime().GetFrame(doc.GetFps())
    if frame != lastFrame:
        lastFrame = frame
        op.SetDirty(c4d.DIRTYFLAGS_DATA)

This method is useful to override in deformer and spline plugins.

Note

This function is called in a thread context.
Please see the important information about threading.
Parameters:
ObjectData.ModifyObject(self, mod, doc, op, op_mg, mod_mg, lod, flags, thread)

Override - Called when an object plugin should modify the passed object.

Note

This function is called in a thread context.
Please see the important information about threading.

Warning

Must not be overridden for non-modifier objects.

Parameters:
Return type:

bool
Returns:

Success of modifying the object.
ObjectData.ModifyParticles(self, op, pp, ss, pcnt, diff)

Override - Called for modifying particles. This is for particle modifiers only.

Note

This function is called in a thread context.
Please see the important information about threading.
Parameters:
  • op (c4d.BaseObject) – The established base object.
  • pp (list of Particle) –

    The initial element of the Particle list.

    Note

    This list is used to read the particles information only, the particles should not be modified.

  • ss (list of BaseParticle) – The initial element of the BaseParticle list. Modify the elements in this list to change the velocity of the particle.
  • pcnt (int) – The number of particles in the Particle and BaseParticle list.
  • diff (float) – The time delta for the particles movement in seconds. Usually the difference in time between two frames, but this can be different for such functions as motion blur.