1
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
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
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
270 """
271 This function removes a datablock.
272 applies to:
273 - L{scenes}
274 - L{groups}
275 - L{texts}
276 Other types will raise an error.
277 @rtype: None
278 """
279