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