This documentation is for the free plugin Py4D in CINEMA 4D R11.5 and not for the C4DSDK of Python in CINEMA 4D R12. For R12, please visit PluginCafe.com

Navigation

c4d.documents.BaseDocument – a document class

This object contains the complete description of a scene.

Note

Remember that you need to call StopAllThreads before making modifications to a user scene.

class c4d.documents.BaseDocument

SuperClass

BaseList2D

Methods

static BaseDocument.__init__()
Return type:BaseDocument
Returns:The new document.
BaseDocument.SetFps(fps)

Set the frames per second.

Parameter:fps (int) – The fps.
BaseDocument.GetFps()

Returns the fps of the document.

Return type:int
Returns:The fps
BaseDocument.SetLOD(lod)

Get the Level of Detail for this document.

Parameter:lod (float) –

The default level of detail values are:

Low = 0.25  
Medium = 0.5  
High = 1.0  
BaseDocument.GetLOD()

Get the Level of Detail for this document.

Return type:

float
Returns:

The default level of detail values are:

Low = 0.25

  

Medium = 0.5

  

High = 1.0

  
BaseDocument.GetRenderLod()

Get if the level of detail for rendering should be used in the editor.

Return type:bool
Returns:True if using the render lod.
BaseDocument.SetRenderLod(lod)

Set the level of detail for rendering.

Parameter:lod (bool) – True if using the render lod.
BaseDocument.GetDrawTime()

Get the editor redraw time.

Return type:int
Returns:The editor redraw time.
BaseDocument.GetSplinePlane()

Get the plane in which the splines are created, such as XY plane.

Return type:

int
Returns:

Values for this are:

0

XY plane.

1

ZY plane.

2

XZ plane.
BaseDocument.GetBaseDrawCount()

Get the BaseDraw count in the editor view.

Return type:int
Returns:The count.
BaseDocument.GetLOD()

Get the Level of Detail for this document.

Return type:

float
Returns:

The default level of detail values are:

Low = 0.25

  

Medium = 0.5

  

High = 1.0

  
BaseDocument.Flush()
Delete all ressources in the document. All references of internal objects will throw an exception on use.
BaseDocument.Settings(type)

Returns a reference to the original settings container of document’s type.

Parameter:type (int) –

The type flag:

SETTINGS_GENERAL General settings.
SETTINGS_MODELER Modeler settings
Return type:BaseContainer
Returns:The settings container
BaseDocument.SetDocumentName(name)

Set the filename of the document.

Note:fn must contain the name part only.
Parameter:type (str) – The filename.
BaseDocument.SetDocumentPath(path)

Set the path of the document.

Note:fn must contain the path part only.
Parameter:type (str) – The filename path.
BaseDocument.GetDocumentName()

Returns the filename.

Return type:str
Returns:If the document has not been saved then the path is empty.
BaseDocument.GetDocumentPath()

Returns the path of the document.

Return type:str
Returns:If the document has not been saved then the path is empty.
BaseDocument.GetParticleSystem()

Returns the ParticleSystem of the document.

Return type:ParticleSystem or one
Parameter:type – The ParticleSystem of the document. Is useless when the document was deleted. Is None if Thinking Particles is not installed.
BaseDocument.StartUndo()

Tell CINEMA 4D to start building a list of undos into a single undo action for the user, this must be paired with end_undo.

Return type:bool
Returns:Success of starting the undo list.

Here is a small example how you can write a redo support for new insert objects.:

import c4d
from c4d import documents

doc = documents.get_active_document()
doc.start_undo()                 #start undo support
cube = c4d.BaseObject(c4d.Ocube)

doc.insert_object(cube)          #insert the object
doc.add_undo(c4d.UNDO_NEW, cube) #support redo the insert operation
doc.end_undo()                   #dont forget to close the undo support
BaseDocument.AddUndo(type, data)

Tell CINEMA 4D to start building a list of undos into a single undo action for the user, this must be paired with an EndUndo().

Parameters:
  • type (int) –

    Value for this are:

       
    UNDO_CHANGE Any change to an object, including hierarchy modifications; modification in positioning (object has been moved from A to B), substructures etc. (Needs to be called BEFORE action.)
    UNDO_CHANGE_NOCHILDS Same as UNDO_CHANGE, but without child modifications. (Needs to be called BEFORE action.)
    UNDO_CHANGE_SMALL Change to local data only (e.g. data container), no substructures (e.g. no tags on an object). Also no childs. (Needs to be called BEFORE action.)
    UNDO_CHANGE_SELECTION Change to point/poly/edge selection only. (Needs to be called BEFORE action.)
    UNDO_NEW New object/node/tag etc. was created. (Needs to be called AFTER action.)
    UNDO_DELETE Object/node/tag etc. to be deleted. (Needs to be called BEFORE action.)
    UNDO_ACTIVATE Automatically managed by SetActive(Object/Tag/Material) No need to use manually.
    UNDO_DEACTIVATE Automatically managed by SetActive(Object/Tag/Material) No need to use manually.
    UNDO_TLACTIVATE Activation of an element in timeline. (Needs to be called BEFORE action.)
    UNDO_TLDEACTIVATE Deactivation of an element in timeline. (Needs to be called BEFORE action.)
    UNDO_BITS Change to object bits, e.g. selection status.
  • data (BaseList2D) – The object.
Return type:

bool
Returns:

Success of starting the undo list.
BaseDocument.GetUndoObject()

Returns the element of the last undo action. E.g. if you have added a BaseObject undo you can retrieve the object by calling this method.

Return type:BaseList2D
Returns:The last undo element.
BaseDocument.DoRedo()

Perform a redo on this document (undo the last undo).

Return type:bool
Returns:Success of the operation.
BaseDocument.DoUndo([multiple=False])

Perform an undo operation, same as the user selecting Undo from within CINEMA 4D.

Parameter:multiple (bool) – This parameter only matters if this method is called between AddUndo and EndUndo. If multiple is True then all the AddUndo steps will be undone. Otherwise only the last AddUndo step will be undone. If EndUndo has been called then all steps are always undone.
Return type:bool
Returns:True if successful, otherwise False.
BaseDocument.EndUndo()

End the building of multiple undo actions into a single user undo, this must be paired with StartUndo.

Return type:bool
Returns:Success of finishing the undo list.
BaseDocument.AnimateObject(op, time, flags)

Animate a node in this document at the given time.

Parameters:
  • op (BaseList2D) – This is the node to animate.
  • time (BaseTime) – The time at which it is being animated.
  • flags (int) –

    The flags are:

    ANIMATE_NO_PARTICLES Ignore particles.
    ANIMATE_QUICK Only fast tracks, e.g. not morphing. (Checks the ANIMINFO_QUICK bit of animation plugins.)
    ANIMATE_NO_CHILDS Don’t animate children.
    ANIMATE_INRENDER Prepare to render scene.
    ANIMATE_NO_MINMAX Private.
    ANIMATE_NO_NLA Private.
    ANIMATE_NLA_SUM Private.
BaseDocument.Polygonize(keepanimation)

Make a clone of the document and turn all objects into polygon based objects.

Parameter:keepanimation (bool) – Keep animation.
Return type:BaseDocument
Returns:The cloned polygon based document or None if this failed.
BaseDocument.SetMinTime(time)

Sets the min time of the document.

Parameter:type (BaseTime) – The time.
BaseDocument.SetMaxTime(time)

Sets the max time of the document.

Parameter:type (BaseTime) – The time.
BaseDocument.GetMinTime()

Returns the min time.

Return type:BaseTime
Returns:The time.
BaseDocument.GetMaxTime()

Returns the max time.

Return type:BaseTime
Returns:The time.
BaseDocument.GetTime()

Returns the min time.

Return type:BaseTime
Returns:The current time.
BaseDocument.SetTime(time)

Set the current time for this documents timeline.

..note:: This function only changes the document time, it does not start a redraw and/or animation/expressions.

Parameter:type (BaseTime) – The time.
BaseDocument.GetLoopMinTime()

Returns the time of the left boundary of the document’s preview range (loop range).

Return type:BaseTime
Returns:The time.
BaseDocument.SetLoopMinTime(time)

Sets the left boundary of the document’s preview range (loop range) to the given time.

Parameter:type (BaseTime) – The time.
BaseDocument.GetLoopMaxTime()

Returns the time of the right boundary of the document’s preview range (loop range).

Return type:BaseTime
Returns:The time.
BaseDocument.SetLoopMaxTime(time)

Sets the right boundary of the document’s preview range (loop range) to the given time.

Parameter:type (BaseTime) – The time.
BaseDocument.SetActiveObject(op[, mode=SELECTION_NEW])

Modifies the current multi selection with op, depending on mode.

Parameters:
  • op (BaseObject) – The object.
  • mode (int) –

    The selection flag.

    SELECTION_NEW Starts a new selection.
    SELECTION_ADD Adds to the current selection
    SELECTION_SUB Subtracts from the current selection.
BaseDocument.SetActiveTag(ta[, mode=SELECTION_NEW])

Sets a tag be the currently active one.

Parameters:
  • ta (BaseTag) – The tag to set active.
  • mode (int) –

    The selection flag.

    SELECTION_NEW Starts a new selection.
    SELECTION_ADD Adds to the current selection
    SELECTION_SUB Subtracts from the current selection.
BaseDocument.SetActiveMaterial(mp[, mode=SELECTION_NEW])

Modifies the current multi selection with op, depending on mode.

Parameters:
  • ta (BaseMaterial) – The material to set active.
  • mode (int) –

    The selection flag.

    SELECTION_NEW Starts a new selection.
    SELECTION_ADD Adds to the current selection
    SELECTION_SUB Subtracts from the current selection.
BaseDocument.SetActiveRenderData(rd)

Sets the active render settings for the document, these are the settings that are used for rendering.

Parameter:rd (BaseMaterial) – The render data that you want to make active.
BaseDocument.SoundCommand(command)

Issues a sound command to the document. This is a typical usage for scrubbing:

doc.SoundCommand(documents.)
Parameter:command (int) –

The command.

SOUNDCOMMAND_START Starts playing the sound.
SOUNDCOMMAND_DRAGSTART Prepares for scrubbing.
SOUNDCOMMAND_DRAGCONTINUE Updates the scrubbing sound.
BaseDocument.GetAllTextures()

Returns a collection of all used filename

Return type:BaseContainer
Returns:A container with all filenames used by textures in the document.
BaseDocument.SetAction(a)

Set the current tool in the editor.

Parameter:a (int) – The values are the IDM_MOVE, IDM_SCALE etc. All these IDs are listed in c4d_symbols.coh in the resource folder of the main application.
BaseDocument.GetAction()

Get the current tool in the editor.

Return type:int
Returns:The values are the IDM_MOVE, IDM_SCALE etc. All these IDs are listed in c4d_symbols.coh in the resource folder of the main application.
BaseDocument.GetActiveToolData()

Gets the original tool data container. The container is alive until the host object is freed.

Return type:BaseContainer
Returns:Tool data container.
BaseDocument.SetMode(m)

Set the main mode of the editor.

Parameter:m (int) –

The value:

Mcamera Camera mode.
Mobject Object mode.
Maxis Axis mode.
Mtexture Axis mode.
Mtextureaxis Texture axis mode.
Mpoints Point edit mode.
Medges Edge edit mode.
Mpolygons Polygon edit mode.
Manimation Animation mode.
Mkinematic IK mode.
Mmodel Model mode.
Mpaint Paint mode.
Muvpoints UV points.
Muvpolgons UV polygons.
Mdrag Drag mode.
Mpolyedgepoint Combined poly/edge/point mode. Must only be used in ViewportSelect.
BaseDocument.GetMode()

Get the main mode of the editor.

Return type:

int
Returns:

The value:

Mcamera

Camera mode.

Mobject

Object mode.

Maxis

Axis mode.

Mtexture

Axis mode.

Mtextureaxis

Texture axis mode.

Mpoints

Point edit mode.

Medges

Edge edit mode.

Mpolygons

Polygon edit mode.

Manimation

Animation mode.

Mkinematic

IK mode.

Mmodel

Model mode.

Mpaint

Paint mode.

Muvpoints

UV points.

Muvpolgons

UV polygons.

Mdrag

Drag mode.

Mpolyedgepoint

Combined poly/edge/point mode. Must only be used in ViewportSelect.
BaseDocument.IsEditMode()

Check if the editor is in an editable mode. This checks if GetMode is Mpoints, Medges or Mpolygons.

Return type:bool
Returns::keyword:`:keyword:`True* if the editor is in point/poly editing mode.
BaseDocument.GetBaseDraw(bd)

Returns the BaseDraw hook of the editor bd.

Parameter:bd (int) – If there are multiple views (multiple basedraws), this selects the view.
Return type:BaseDraw
Returns:The requested view in the editor, or None
BaseDocument.GetActiveBaseDraw()

Get the activate BaseDraw in the editor, this is where all drawing should be performed.

Return type:BaseDraw
Returns:The active view in the editor.
BaseDocument.GetRenderBaseDraw()

This is the BaseDraw belonging to the view that the user has chosen as ‘Render View’ (see View menu in CINEMA).

Return type:BaseDraw
Returns:The render view in the editor.
BaseDocument.GetActiveTag()

Returns the active selected tag.

Return type:BaseTag
Returns:The active tag, or None.
BaseDocument.GetMaterials()

Returns all materials in a list.

Return type:list of type BaseMaterial
Returns:The list of all materials.
BaseDocument.GetActiveObject()

Returns the active selected object.

Return type:BaseObject
Returns:The active object, or None.
BaseDocument.GetActiveRenderData()

Returns the active selected material.

Return type:

RenderData
Returns:

The active render data.

Note

Guaranteed to never be None.
BaseDocument.GetFirstRenderData()

Get the first render setting data RenderData for this document. The other render settings in the document can be accessed by using the base class list functions, :meth.`RenderData.GetNext`.

Return type:RenderData
Returns:The first render setting, or None if no render settings are associated with this document.
BaseDocument.InsertRenderData(rd[, pred=None])

Inserts the render setting data into the document’s render setting list. Optionally you can specify the insertion position with the pred parameter, giving the render setting before (right above) the wanted position. Otherwise the render setting is inserted at the first position in the list.

Parameters:
  • rd (RenderData) – Render setting data to insert.
  • pred (RenderData) – Optional point to insert the render settings data
BaseDocument.InsertRenderDataLast(rd)

Inserts the render data as last child into the document’s render data list.

Parameters:
  • rd (RenderData) – Render setting data to insert.
  • pred (RenderData) – Optional point to insert the render settings data
BaseDocument.GetActiveMaterial()

Returns the active selected material.

Return type:BaseMaterial
Returns:The active material, or None.
BaseDocument.GetFirstObject()

Returns the first object.

Return type:BaseObject
Returns:The first object, or None if no objects are contained in this document.
BaseDocument.GetFirstMaterial()

Returns the first material.

Return type:BaseMaterial
Returns:The active material, or None.
BaseDocument.GetActiveMaterials()

Returns the material selection.

Return type:list of type BaseMaterial
Returns:The selected materials in a list.
BaseDocument.GetActiveObjects()

Returns the object selection.

Return type:list of type BaseObject
Returns:The selected objects in a list.
BaseDocument.GetActiveTags()

Returns the tag selection.

Return type:list of type BaseTag
Returns:The selected tags in a list.
BaseDocument.GetSelection()

Returns the selection of materials, tags and objects in a list.

Return type:list of type BaseList2D
Returns:The selected objects in a list
BaseDocument.GetObjects()

Returns the highest objects without childs.

Return type:list of type BaseObject
Returns:The objects.
BaseDocument.SetSelection(sel[, mode=SELECTION_NEW])

Set the materials, tags and object selection with a list.

Parameters:
  • sel (BaseList2D) – The object you want to make active.
  • mode (int) –

    The mode

    SELECTION_NEW Starts a new selection.
    SELECTION_ADD Adds to the current selection
    SELECTION_SUB Subtracts from the current selection.
BaseDocument.SearchMaterial(name)

Search for a material with the same case sensitive name.

Parameter:name (str) – The name of the material to search for.
Return type:BaseMaterial
Returns:The material or None if nothing was found.
BaseDocument.SearchMaterialInc(name)

Search for a material with the closest matching name.

Parameter:name (str) – The name of the material to search for.
Return type:BaseMaterial
Returns:The material or None if nothing was found.
BaseDocument.SearchObject(name)

Search for an object with the same case sensitive name.

Parameter:name (str) – The name of the object to search for.
Return type:BaseObject
Returns:The object or None if nothing was found.
BaseDocument.SearchObjectInc(name)

Search for an object with the closest name.

Parameter:name (str) – The name of the object to search for.
Return type:BaseObject
Returns:The object or None if nothing was found.
BaseDocument.GetHighest(type, editor)

The first object in object manager hierarchy of type type. It searches objects that are not deactivated in the object manager (set to red).

Parameters:
  • type (int) – the object type
  • editor (bool) – True will search using the ‘editor dot’ in the Object Manager, False will use the ‘render dot’.
Return type:

BaseObject
Returns:

The first requested object or None if nothing was found.
BaseDocument.InsertObject(op[, parent=None, pred=None, checknames=False])

Note

If both pred and parent are provided then pred has precedence.

Inserts the object into the document’s object hierarchy. The insertion position can either be specified by the parent parameter, inserting the object as the first child of the specified parent, or by the pred parameter, inserting the object below the specified prev object. If neither is given, the object is inserted at the top of the hierarchy.

Raises ReferenceError:
 

Raise ReferenceError if the passed objects(parent, pred) are not in the same document.
Parameters:
  • op (BaseObject) – Object to insert into the document.
  • parent (BaseObject) – Optional parent to insert the object as a child of.
  • pred (BaseObject) – Optional insertion point.
  • checknames (bool) – Check for duplicate names and append .1, .2 etc.
BaseDocument.InsertMaterial(op[, pred=None, checknames=None])

Inserts the material into the document’s material list. Optionally you can specify the insertion position with the pred parameter, giving the material before (just to the left of) the wanted position. Otherwise the material is inserted at the first position in the list.

Parameters:
  • op (BaseMaterial) – Material to insert into the document.
  • pred (BaseObject) – Optional insertion point for the material. Require condition pred.get_document==op.get_document. That means, the object has to be in the same document.
  • checknames (bool) – Check for duplicate names and append .1, .2 etc.
BaseDocument.GetHelperAxis()

The helper axis for the current multi selection.

Return type:BaseObject
Returns:The axis object.
BaseDocument.GetChanged()

Returns True if the document been changed since it was last saved.

Return type:bool
Returns::keyword:`True if the document has been changed.
BaseDocument.SetChanged()
Set that changed state of the document to reflect it has been modified.
BaseDocument.GetRenderLOD()

Get if the level of detail for rendering should be used in the editor.

Return type:bool
Returns::keyword:`True if using the render lod.
BaseDocument.SetRenderLOD(lod)

Set the level of detail for rendering.

Parameter:lod (bool) – True if the render LOD should be used.

Document Caching

Sometimes you want to cache stuff and browse through the time of a document. The following code snippet shows you how to do it in the best way:

import c4d
from c4d import documents

def BrowseDoc(doc):
    """ Pass the document you want to run the time through"""

    ctime = doc.GetTime() #save current time

    fps = doc.GetFps()
    start = doc.GetMinTime().GetFrame(fps) #set min time
    until  = doc.GetMaxTime().GetFrame(fps)

    for f in xrange(start, until):
        c4d.StatusSetBar(100*(f-start) / (until-start) )
        doc.SetTime(c4d.BaseTime(f, fps))
        c4d.DrawViews( c4d.DA_ONLY_ACTIVE_VIEW|c4d.DA_NO_THREAD|c4d.DA_NO_REDUCTION|c4d.DA_STATICBREAK )

        # do your caching here. 'f' is the current frame

        c4d.GeSyncMessage(c4d.EVMSG_TIMECHANGED) #update timeline


    doc.SetTime(ctime) #set time back
    c4d.EventAdd(c4d.EVENT_ANIMATE)
    c4d.StatusClear()

Table Of Contents

This Page

Navigation

© Copyright 2010, MAXON Computer GmbH. Last updated on Apr 13, 2010. Created using Sphinx 0.6.5.