← Back to branch summary

~siretart/ubuntu/utopic/blender/libav10

« back to all changes in this revision

Viewing changes to source/blender/python/api2_2x/doc/Bpy_data.py

  • Committer: Bazaar Package Importer
  • Author(s): Kevin Roy
  • Date: 2011-02-08 22:20:54 UTC
  • mfrom: (1.4.2 upstream)
  • mto: (14.2.6 sid) (1.5.1)
  • mto: This revision was merged to the branch mainline in revision 27.
  • Revision ID: james.westby@ubuntu.com-20110208222054-kk0gwa4bu8h5lyq4
Tags: upstream-2.56.1-beta-svn34076
Import upstream version 2.56.1-beta-svn34076

Show diffs side-by-side

added added

removed removed

Lines of Context:
source/blender/python/api2_2x/doc/Bpy_data.py
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
 
        
269
 
        def unlink(datablock):
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
 
 
280
 
 
281
 
        
 
 
b'\\ No newline at end of file'