Module Scene

Source Code for Module Scene

  1  # Blender.Scene module and the Scene PyType object 
  2   
  3  """ 
  4  The Blender.Scene submodule. 
  5   
  6  B{New}: 
  7          - L{Scene.clearScriptLinks<Scene.Scene.clearScriptLinks>} accepts a parameter now. 
  8          - acess methods L{Scene.getLayers<Scene.Scene.getLayers>}, L{Scene.setLayers<Scene.Scene.setLayers>} via lists to complement the layers and 
  9                  Layers Scene attributes which use bitmasks.  
 10   
 11  Scene 
 12  ===== 
 13   
 14  This module provides access to B{Scenes} in Blender. 
 15   
 16  Example:: 
 17          import Blender 
 18          from Blender import Scene, Object, Camera 
 19          # 
 20          camdata = Camera.New('persp')           # create new camera data 
 21          camdata.name = 'newCam' 
 22          camdata.lens = 16.0 
 23          scene = Scene.New('NewScene')           # create a new scene 
 24          scene.objects.new(camdata,'Camera')     # add a new object to the scene with newly-created data 
 25          scene.makeCurrent()                     # make this the current scene 
 26   
 27  @warn: B{scene.objects.new} is the preferred way to add new objects to a scene. 
 28          The older way is to create an object with B{Object.New()}, link the 
 29          data to the new object, then link the object to the scene.  This way is 
 30          not recommended since a forgotten step or run-time error in the script can  
 31          cause bad things to be done to Blender's database. 
 32   
 33          If you use this older method, it's recommended to always perform the 
 34          operations in this order.  This is because if 
 35          there is no object data linked to an object B{ob}, B{scene.link(ob)} will 
 36          automatically create the missing data.  This is OK on its own, but I{if 
 37          after that} object B{ob} is linked to obdata, the automatically created one 
 38          will be discarded -- as expected -- but will stay in Blender's memory 
 39          space until the program is exited, since Blender doesn't really get rid of 
 40          most kinds of data.  So first linking ObData to object, then object to 
 41          scene is a tiny tiny bit faster than the other way around and also saves 
 42          some realtime memory (if many objects are created from scripts, the 
 43          savings become important). 
 44  """ 
 45   
46 -def New (name = 'Scene'):
47 """ 48 Create a new Scene in Blender. 49 @type name: string 50 @param name: The Scene name. 51 @rtype: Blender Scene 52 @return: The created Scene. 53 """
54
55 -def Get (name = None):
56 """ 57 Get the Scene(s) from Blender. 58 @type name: string 59 @param name: The name of a Scene. 60 @rtype: Blender Scene or a list of Blender Scenes 61 @return: It depends on the I{name} parameter: 62 - (name): The Scene with the given I{name}; 63 - (): A list with all Scenes currently in Blender. 64 """
65
66 -def GetCurrent():
67 """ 68 Get the currently active Scene in Blender. 69 @rtype: Blender Scene 70 @return: The currently active Scene. 71 """
72 79 80 from IDProp import IDGroup, IDArray
81 -class Scene:
82 """ 83 The Scene object 84 ================ 85 This object gives access to Scene data in Blender. 86 @type Layers: integer (bitmask) 87 @ivar Layers: The Scene layers (check also the easier to use 88 L{layers}). This value is a bitmask with at least 89 one position set for the 20 possible layers starting from the low order 90 bit. The easiest way to deal with these values in in hexadecimal 91 notation. 92 Example:: 93 scene.Layers = 0x04 # sets layer 3 ( bit pattern 0100 ) 94 scene.Layers |= 0x01 95 print scene.Layers # will print: 5 ( meaning bit pattern 0101) 96 After setting the Layers value, the interface (at least the 3d View and 97 the Buttons window) needs to be redrawn to show the changes. 98 @type layers: list of integers 99 @ivar layers: The Scene layers (check also L{Layers}). 100 This attribute accepts and returns a list of integer values in the 101 range [1, 20]. 102 Example:: 103 scene.layers = [3] # set layer 3 104 scene.layers = scene.layers.append(1) 105 print scene.layers # will print: [1, 3] 106 @type objects: sequence of objects 107 @ivar objects: The scene's objects. The sequence supports the methods .link(ob), .unlink(ob), and .new(obdata), and can be iterated over. 108 @type cursor: Vector (wrapped) 109 @ivar cursor: the 3d cursor location for this scene. 110 @type camera: Camera or None 111 @ivar camera: The active camera for this scene (can be set) 112 @type world: World or None 113 @ivar world: The world that this scene uses (if any) 114 @type timeline: Timeline 115 @ivar timeline: The L{timeline<TimeLine.TimeLine>} for this scene, named markers are stored here. (read only) 116 @type render: RenderData 117 @ivar render: The scenes L{render<Render.RenderData>} settings. (read only) 118 @type radiosity: RenderData 119 @ivar radiosity: The scenes L{radiosity<Radio>} settings. (read only) 120 @type halfFloat: OpenEXR's half float option 121 @ivar halfFloat: boolean 122 @type zbuf: OpenEXR's save zbuf option 123 @ivar zbuf: boolean 124 @type preview: OpenEXR's save preview option 125 @ivar preview: boolean 126 @type touch: enable creating empty image files while they are rendered. 127 @ivar touch: boolean 128 @type noOverwrite: Skip rendering existing image files 129 @ivar noOverwrite: boolean 130 """ 131
132 - def getName():
133 """ 134 Get the name of this Scene. 135 @rtype: string 136 """
137
138 - def setName(name):
139 """ 140 Set the name of this Scene. 141 @type name: string 142 @param name: The new name. 143 """
144
145 - def getLayers():
146 """ 147 Get the layers set for this Scene. 148 @rtype: list of integers 149 @return: a list where each number means the layer with that number is set. 150 """
151
152 - def setLayers(layers):
153 """ 154 Set the visible layers for this scene. 155 @type layers: list of integers 156 @param layers: a list of integers in the range [1, 20], where each available 157 index makes the layer with that number visible. 158 @note: if this Scene is the current one, the 3D View layers are also 159 updated, but the screen needs to be redrawn (at least 3D Views and 160 Buttons windows) for the changes to be seen. 161 """
162
163 - def copy(duplicate_objects = 1):
164 """ 165 Make a copy of this Scene. 166 @type duplicate_objects: int 167 @param duplicate_objects: Defines how the Scene children are duplicated: 168 - 0: Link Objects; 169 - 1: Link Object Data; 170 - 2: Full copy. 171 @rtype: Scene 172 @return: The copied Blender Scene. 173 """
174
175 - def makeCurrent():
176 """ 177 Make this Scene the currently active one in Blender. 178 """
179
180 - def update(full = 0):
181 """ 182 Update this Scene in Blender. 183 @type full: int 184 @param full: A bool to control the level of updating: 185 - 0: sort the base list of objects. 186 - 1: sort and also regroup, do ipos, keys, script links, etc. 187 @warn: When in doubt, try with I{full = 0} first, since it is faster. 188 The "full" update is a recent addition to this method. 189 """
190
192 """ 193 Get the rendering context for this scene, see L{Render}. 194 @rtype: RenderData 195 @return: the render data object for this scene. 196 """
197
199 """ 200 Get the radiosity context for this scene, see L{Radio}. 201 @rtype: Blender Radiosity 202 @return: the radiosity object for this scene. 203 @note: only the current scene can return a radiosity context. 204 """
205
206 - def getChildren():
207 """ 208 Get all objects linked to this Scene. (B{deprecated}). B{Note}: new scripts 209 should use the L{objects} attribute instead. In cases where a list is 210 required use list(scn.objects). 211 @rtype: list of Blender Objects 212 @return: A list with all Blender Objects linked to this Scene. 213 @note: L{Object.Get} will return all objects currently in Blender, which 214 means all objects from all available scenes. In most cases (exporter 215 scripts, for example), it's probably better to use this 216 scene.GetChildren instead, since it will only access objects from this 217 particular scene. 218 @warn: Depricated! use scene.objects instead. 219 """
220
221 - def getActiveObject():
222 """ 223 Get this scene's active object. 224 @note: the active object, if selected, can also be retrieved with 225 L{Object.GetSelected} -- it is the first item in the returned 226 list. But even when no object is selected in Blender, there can be 227 an active one (if the user enters editmode, for example, this is the 228 object that should become available for edition). So what makes this 229 scene method different from C{Object.GetSelected()[0]} is that it can 230 return the active object even when no objects are selected. 231 @rtype: Blender Object or None 232 @return: the active object or None if not available. 233 @warn: Depricated! use scene.objects.active instead. 234 """
235
236 - def getCurrentCamera():
237 """ 238 Get the currently active Camera for this Scene. 239 @note: The active camera can be any object type, not just a camera object. 240 @rtype: Blender Object 241 @return: The currently active Camera object. 242 """
243
244 - def setCurrentCamera(camera):
245 """ 246 Set the currently active Camera in this Scene. 247 @type camera: Blender Camera 248 @param camera: The new active Camera. 249 """
250 257 266 276 284 311
312 - def play (mode = 0, win = '<VIEW3D>'):
313 """ 314 Play a realtime animation. This is the "Play Back Animation" function in 315 Blender, different from playing a sequence of rendered images (for that 316 check L{Render.RenderData.play}). 317 @type mode: int 318 @param mode: controls playing: 319 - 0: keep playing in the biggest 'win' window; 320 - 1: keep playing in all 'win', VIEW3D and SEQ windows; 321 - 2: play once in the biggest VIEW3D; 322 - 3: play once in all 'win', VIEW3D and SEQ windows. 323 @type win: int 324 @param win: window type, see L{Window.Types}. Only some of them are 325 meaningful here: VIEW3D, SEQ, IPO, ACTION, NLA, SOUND. But the others 326 are also accepted, since this function can be used simply as an 327 interruptible timer. If 'win' is not visible or invalid, VIEW3D is 328 tried, then any bigger visible window. 329 @rtype: bool 330 @return: 0 on normal exit or 1 when play back is canceled by user input. 331 """
332 333 import id_generics 334 Scene.__doc__ += id_generics.attributes 335 336
337 -class SceneObjects:
338 """ 339 The SceneObjects (Scene ObjectSeq) object 340 ========================================= 341 This object gives access to the Objects in a Scene in Blender. 342 343 Example:: 344 from Blender import Scene 345 scn = Scene.GetCurrent() 346 347 scn.objects.selected = [] # select none 348 scn.objects.selected = scn.objects # select all 349 scn.objects.context = scn.objects # select all and move into the scenes display layer 350 351 # get a list of mesh objects 352 obs = [ob for ob in scn.objects if ob.type == 'Mesh'] 353 354 # Select only these mesh objects 355 scn.objects.selected = obs 356 357 # print all object names 358 for ob in scn.objects: print ob.name 359 360 # make a list of objects that you can add and remove to 361 # will not affect the current scene 362 scene_obs = list(scn.objects) 363 364 @ivar selected: an iterator over all the selected objects in a scene. 365 @type selected: sequence of L{Object} 366 @ivar context: an iterator over all the visible selected objects in a scene. 367 @type context: sequence of L{Object} 368 @ivar active: the active object in the scene. 369 @type active: L{Object} 370 @ivar camera: the active camera in the scene. 371 @type camera: L{Object} 372 """ 373
374 - def new(data):
375 """ 376 Adds a new object to the scene. Data is either object data such as a 377 L{Mesh} or L{Curve}, or the string "Empty" for an Empty object. The 378 type of the object is determined by the type of the data. 379 @type data: string or object data 380 @param data: the object data for the new object 381 @return: the new object. 382 @rtype: L{Object} 383 """
384 393
402