Module Bpy_data

Source Code for Module Bpy_data

  1  # bpy module and the bpy PyType object 
  2   
  3  """ 
  4  The bpy module. 
  5   
  6  bpy.data (Generic Data Access) 
  7  ============================== 
  8   
  9  Example:: 
 10   
 11          # apply the active image to the active mesh 
 12          # this script has no error checking to keep it small and readable. 
 13   
 14          sce= bpy.data.scenes.active 
 15          ob_act = sce.objects.active             # assuming we have an active, might be None 
 16          me = ob_act.getData(mesh=1)             # assuming a mesh type, could be any 
 17          img = bpy.data.images.active                    # assuming we have an active image 
 18           
 19          for f in me.faces: 
 20                  f.image = img 
 21   
 22          Window.RedrawAll() 
 23   
 24  Example:: 
 25   
 26          # make a new object from an existing mesh 
 27          # and make it active 
 28          scn= bpy.data.scenes.active 
 29          me = bpy.data.meshes['mymesh'] 
 30          ob = sce.objects.new(me) # new object from the mesh 
 31          sce.objects.active = ob 
 32   
 33  Example:: 
 34          # print the names of any non local objects 
 35          sce= bpy.data.scenes.active 
 36          for ob in sce.objects: 
 37                  if ob.lib: 
 38                          print 'external object:', ob.name, ob.lib 
 39   
 40  Example:: 
 41          # add an empty object at each vertex of the active mesh 
 42          scn= bpy.data.scenes.active 
 43          ob_act = sce.objects.active 
 44          matrix = ob_act.matrixWorld 
 45          me = ob_act.getData(mesh=1) 
 46           
 47          for v in me.verts: 
 48                  ob = sce.objects.new('Empty') 
 49                  ob.loc = v.co * matrix                  # transform the vertex location by the objects matrix. 
 50                   
 51   
 52  Example:: 
 53          # load all the wave sound files in a directory 
 54          import os 
 55          sound_dir = '/home/me/soundfiles/' 
 56          sounds_new = [] 
 57          for fname in os.listdir(sound_dir): 
 58                  if fname.lower().endswith('.wav'): 
 59                          try: 
 60                                  snd = bpy.data.sounds.new(filename = sound_dir + fname) 
 61                          except: 
 62                                  snd = None 
 63                           
 64                          if snd: 
 65                                  sounds_new.append(snd) 
 66           
 67          # Print the sounds 
 68          for snd in sounds_new: 
 69                  print snd 
 70           
 71  Example:: 
 72          # apply a new image to each selected mesh object as a texface. 
 73          width, height= 512, 512 
 74          scn= bpy.data.scenes.active 
 75           
 76          for ob in sce.objects.context: 
 77                  if not ob.lib and ob.type == 'Mesh':    # object isn't from a library and is a mesh 
 78                          me = ob.getData(mesh=1) 
 79                          me.faceUV = True                                        # add UV coords and textures if we don't have them. 
 80                           
 81                          # Make an image named after the mesh 
 82                          img = bpy.data.images.new(me.name, width, height) 
 83                           
 84                          for f in me.faces: 
 85                                  f.image = img 
 86           
 87          Window.RedrawAll() 
 88   
 89   
 90   
 91  @var scenes: sequence for L{scene<Scene.Scene>} data 
 92  @type scenes: L{libBlockSeq} 
 93  @var objects: sequence for L{object<Object.Object>} data 
 94  @type objects: L{libBlockSeq} 
 95  @var meshes: sequence for L{mesh<Mesh.Mesh>} data 
 96  @type meshes: L{libBlockSeq} 
 97  @var curves: sequence for L{curve<Curve.Curve>} data, used to store Curve, Surface and Text3d data. 
 98  @type curves: L{libBlockSeq} 
 99  @var metaballs: sequence for L{metaball<Metaball.Metaball>} data 
100  @type metaballs: L{libBlockSeq} 
101  @var materials: sequence for L{material<Material.Material>} data 
102  @type materials: L{libBlockSeq} 
103  @var textures: sequence for L{texture<Texture.Texture>} data 
104  @type textures: L{libBlockSeq} 
105  @var images: sequence for L{image<Image.Image>} data 
106  @type images: L{libBlockSeq} 
107  @var lattices: sequence for L{lattice<Lattice.Lattice>} data 
108  @type lattices: L{libBlockSeq} 
109  @var lamps: sequence for L{lamp<Lamp.Lamp>} data 
110  @type lamps: L{libBlockSeq} 
111  @var cameras: sequence for L{camera<Camera.Camera>} data 
112  @type cameras: L{libBlockSeq} 
113  @var ipos: sequence for L{ipo<Ipo.Ipo>} data 
114  @type ipos: L{libBlockSeq} 
115  @var worlds: sequence for L{world<World.World>} data 
116  @type worlds: L{libBlockSeq} 
117  @var fonts: sequence for L{font<Font.Font>} data 
118  @type fonts: L{libBlockSeq} 
119  @var texts: sequence for L{text<Text.Text>} data 
120  @type texts: L{libBlockSeq} 
121  @var sounds: sequence for L{sound<Sound.Sound>} data 
122  @type sounds: L{libBlockSeq} 
123  @var groups: sequence for L{group<Group.Group>} data 
124  @type groups: L{libBlockSeq} 
125  @var armatures: sequence for L{armature<Armature.Armature>} data 
126  @type armatures: L{libBlockSeq} 
127  @var actions: sequence for L{action<NLA.Action>} data 
128  @type actions: L{libBlockSeq} 
129  """ 
130   
131   
132 -class libBlockSeq:
133 """ 134 Generic Data Access 135 =================== 136 This provides a unified way to access and manipulate data types in Blender 137 (scene, object, mesh, curve, metaball, material, texture, image, lattice, 138 lamp, camera, ipo, world, font, text, sound, groups, armatures, actions). 139 140 Get Item 141 ======== 142 To get a datablock by name you can use dictionary-like syntax. 143 144 >>> ob = bpy.data.objects['myobject'] 145 146 Note that this can only be used for getting. 147 148 >>> bpy.data.objects['myobject'] = data # will raise an error 149 150 B{Library distinctions} 151 152 Blender doesn't allow naming collisions within its own data, but it's 153 possible to run into naming collisions when you have data linked from an external blend file. 154 155 You can specify where the data is from by using a (name, library) pair as the key. 156 157 >>> group = bpy.data.groups['mygroup', '//mylib.blend'] # only return data linked from mylib 158 159 If you want to get a group from the local data only you can use None 160 161 >>> group = bpy.data.groups['mygroup', None] # always returns local data 162 163 Sequence 164 ======== 165 These generic datablocks are sequence datatypes. They are not lists. They support the dictionary and iterator protocols. This implies the following 166 167 - A B{for} statement allows you to loop through data using the iterator protocol without wasting resources on creating a large list. 168 169 >>> for me in bpy.data.meshes: 170 ... print me.name 171 172 - You can also use len() to see how many datablocks exist. 173 174 >>> print len(bpy.data.scenes) 175 176 - Because the sequences are not lists and the [] operator is used to get items by name, you cannot use indexing to retrieve an item. 177 178 >>> ob = bpy.data.objects[-1] # will raise an error 179 180 - If you want to access the entire sequence as a list simply use the list() constructor. 181 182 >>> ipo_list = list(bpy.data.ipos) 183 184 @type tag: Bool 185 @ivar tag: A fast way to set the tag value of every member of the sequence to True or False 186 187 For example 188 189 >>> bpy.data.meshes.tag = True 190 191 Is the same as... 192 193 >>> for me in bpy.data.meshes: me.tag = True 194 195 @type active: Datablock or None 196 @ivar active: The active member of the datatype 197 198 Applies to: 199 - L{images} 200 - L{scenes} 201 - L{texts} 202 This can also be used to set the active data. 203 204 >>> bpy.data.images.active = bpy.data.images.new(filename = '/home/me/someimage.jpg') 205 206 """ 207
208 - def new(name):
209 """ 210 fixme: need description for parameters. 211 This function returns a new datablock containing no data or loaded from a file. 212 213 Most datatypes accept a name for their argument except for L{sounds}, L{fonts}, L{ipos} and L{curves} that need an additional argument. 214 215 The name argument is optional if not given a default name will be assigned. 216 217 The name given may be modified by blender to make it unique. 218 219 Loading From File 220 ================= 221 For L{images}, L{texts}, L{sounds}, L{fonts} types you can use the filename keyword to make a new datablock from a file. 222 223 New L{sounds}, L{fonts} can only be made with the a filename given. 224 225 The filename can a keyword or the second argument, use the keyword only for the datablocks new name to be set by the filename. 226 227 >>> sound = bpy.data.sounds.new('newsound', '~/mysound.wav') # uses the first string given for the name. 228 229 >>> sound = bpy.data.sounds.new(filename = '~/mysound.wav') # will use the filename to make the name. 230 231 Images 232 ====== 233 Images optionally accept extra 2 arguments for width and height, values between 4 and 5000 if no args are given they will be 256. 234 235 >>> img = bpy.data.images.new(name, 512, 512) 236 237 Curves 238 ====== 239 Curves need 2 arguments: bpy.data.curves.new(name, type) type must be one of the following... 240 - 'Curve' 241 - 'Text3d' 242 243 >>> text3d = bpy.data.curves.new('MyCurve', 'Text3d') 244 245 Ipos 246 ==== 247 Ipos need 2 arguments: bpy.data.ipos.new(name, type) type must be one of the following... 248 - 'Camera' 249 - 'World' 250 - 'Material' 251 - 'Texture' 252 - 'Lamp' 253 - 'Action' 254 - 'Constraint' 255 - 'Sequence' 256 - 'Curve' 257 - 'Key' 258 Objects cannot be created from bpy.data.objects; 259 objects must be created from the scene. Here are some examples. 260 261 >>> ob = bpy.data.scenes.active.objects.new('Empty') 262 263 >>> scn = bpy.data.scenes.active 264 ... ob = sce.objects.new(bpy.data.meshes.new('mymesh')) 265 266 @rtype: datablock 267 """
268
279