patch [#29049] Minor phrasing and grammar patch
[blender.git] / doc / python_api / rst / info_quickstart.rst
1 ***********************
2 Quickstart Introduction
3 ***********************
4
5 Intro
6 =====
7
8 This API is generally stable but some areas are still being added and improved.
9
10 The Blender/Python API can do the following:
11
12 * Edit any data the user interface can (Scenes, Meshes, Particles etc.)
13
14 * Modify user preferences, keymaps and themes
15
16 * Run tools with own settings
17
18 * Create user interface elements such as menus, headers and panels
19
20 * Create new tools
21
22 * Create interactive tools
23
24 * Create new rendering engines that integrate with Blender
25
26 * Define new settings in existing Blender data
27
28 * Draw in the 3D view using OpenGL commands from Python
29
30
31 The Blender/Python API **can't** (yet)...
32
33 * Create new space types.
34
35 * Assign custom properties to every type.
36
37 * Define callbacks or listeners to be notified when data is changed.
38
39
40 Before Starting
41 ===============
42
43 This document isn't intended to fully cover each topic. Rather, its purpose is to familiarize you with Blender 2.5's new Python API.
44
45
46 A quick list of helpful things to know before starting:
47
48 * Blender uses Python 3.x; some 3rd party extensions are not available yet.
49
50 * The interactive console in Blender 2.5 has been improved; testing one-liners in the console is a good way to learn.
51
52 * Button tool tips show Python attributes and operator names.
53
54 * Right clicking on buttons and menu items directly links to API documentation.
55
56 * For more examples, the text menu has a templates section where some example operators can be found.
57
58 * To examine further scripts distributed with Blender, see ``~/.blender/scripts/startup/bl_ui`` for the user interface and ``~/.blender/scripts/startup/bl_op`` for operators.
59
60
61 Key Concepts
62 ============
63
64 Data Access
65 -----------
66
67 Accessing datablocks
68 ^^^^^^^^^^^^^^^^^^^^
69
70 Python accesses Blender's data in the same way as the animation system and user interface; this implies that any setting that can be changed via a button can also be changed from Python.
71
72 Accessing data from the currently loaded blend file is done with the module :mod:`bpy.data`. This gives access to library data. For example:
73
74    >>> bpy.data.objects
75    <bpy_collection[3], BlendDataObjects>
76
77    >>> bpy.data.scenes
78    <bpy_collection[1], BlendDataScenes>
79
80    >>> bpy.data.materials
81    <bpy_collection[1], BlendDataMaterials>
82
83
84 About Collections
85 ^^^^^^^^^^^^^^^^^
86
87 You'll notice that an index as well as a string can be used to access members of the collection.
88
89 Unlike Python's dictionaries, both methods are acceptable; however, the index of a member may change while running Blender.
90
91    >>> list(bpy.data.objects)
92    [bpy.data.objects["Cube"], bpy.data.objects["Plane"]]
93
94    >>> bpy.data.objects['Cube']
95    bpy.data.objects["Cube"]
96
97    >>> bpy.data.objects[0]
98    bpy.data.objects["Cube"]
99
100
101 Accessing attributes
102 ^^^^^^^^^^^^^^^^^^^^
103
104 Once you have a data block, such as a material, object, groups etc., its attributes can be accessed much like you would change a setting using the graphical interface. In fact, the tooltip for each button also displays the Python attribute which can help in finding what settings to change in a script.
105
106    >>> bpy.data.objects[0].name 
107    'Camera'
108
109    >>> bpy.data.scenes["Scene"]
110    bpy.data.scenes['Scene']
111
112    >>> bpy.data.materials.new("MyMaterial")
113    bpy.data.materials['MyMaterial']
114
115
116 For testing what data to access it's useful to use the "Console", which is its own space type in Blender 2.5. This supports auto-complete, giving you a fast way to dig into different data in your file.
117
118 Example of a data path that can be quickly found via the console:
119
120    >>> bpy.data.scenes[0].render.resolution_percentage
121    100
122    >>> bpy.data.scenes[0].objects["Torus"].data.vertices[0].co.x
123    1.0
124
125
126 Custom Properties
127 ^^^^^^^^^^^^^^^^^
128
129 Python can access properties on any datablock that has an ID (data that can be linked in and accessed from :mod:`bpy.data`. When assigning a property, you can make up your own names, these will be created when needed or overwritten if they exist.
130
131 This data is saved with the blend file and copied with objects.
132
133 Example:
134
135 .. code-block:: python
136
137    bpy.context.object["MyOwnProperty"] = 42
138
139    if "SomeProp" in bpy.context.object:
140        print("Property found")
141
142    # Use the get function like a python dictionary
143    # which can have a fallback value.
144    value = bpy.data.scenes["Scene"].get("test_prop", "fallback value")
145
146    # dictionaries can be assigned as long as they only use basic types.
147    group = bpy.data.groups.new("MyTestGroup")
148    group["GameSettings"] = {"foo": 10, "bar": "spam", "baz": {}}
149
150    del group["GameSettings"]
151
152
153 Note that these properties can only be assigned  basic Python types.
154
155 * int, float, string
156
157 * array of ints/floats
158
159 * dictionary (only string keys are supported, values must be basic types too)
160
161 These properties are valid outside of Python. They can be animated by curves or used in driver paths.
162
163
164 Context
165 -------
166
167 While it's useful to be able to access data directly by name or as a list, it's more common to operate on the user's selection. The context is always available from '''bpy.context''' and can be used to get the active object, scene, tool settings along with many other attributes.
168
169 Common-use cases:
170
171    >>> bpy.context.object
172    >>> bpy.context.selected_objects
173    >>> bpy.context.visible_bones
174
175 Note that the context is read-only. These values cannot be modified directly, though they may be changed by running API functions or by using the data API.
176
177 So ``bpy.context.object = obj`` will raise an error.
178
179 But ``bpy.context.scene.objects.active = obj`` will work as expected.
180
181
182 The context attributes change depending on where they are accessed. The 3D view has different context members than the console, so take care when accessing context attributes that the user state is known.
183
184 See :mod:`bpy.context` API reference
185
186
187 Operators (Tools)
188 -----------------
189
190 Operators are tools generally accessed by the user from buttons, menu items or key shortcuts. From the user perspective they are a tool but Python can run these with its own settings through the :mod:`bpy.ops` module.
191
192 Examples:
193
194    >>> bpy.ops.mesh.flip_normals()
195    {'FINISHED'}
196    >>> bpy.ops.mesh.hide(unselected=False)
197    {'FINISHED'}
198    >>> bpy.ops.object.scale_apply()
199    {'FINISHED'}
200
201 .. note::
202
203    The menu item: Help -> Operator Cheat Sheet" gives a list of all operators and their default values in Python syntax, along with the generated docs. This is a good way to get an overview of all blender's operators.
204
205
206 Operator Poll()
207 ^^^^^^^^^^^^^^^
208
209 Many operators have a "poll" function which may check that the mouse is a valid area or that the object is in the correct mode (Edit Mode, Weight Paint etc). When an operator's poll function fails within python, an exception is raised.
210
211 For example, calling bpy.ops.view3d.render_border() from the console raises the following error:
212
213 .. code-block:: python
214
215    RuntimeError: Operator bpy.ops.view3d.render_border.poll() failed, context is incorrect
216
217 In this case the context must be the 3d view with an active camera.
218
219 To avoid using try/except clauses wherever operators are called you can call the operators own .poll() function to check if it can run in the current context.
220
221 .. code-block:: python
222
223    if bpy.ops.view3d.render_border.poll():
224        bpy.ops.view3d.render_border()
225
226
227 Integration
228 ===========
229
230 Python scripts can integrate with Blender in the following ways:
231
232 * By defining a rendering engine.
233
234 * By defining operators.
235
236 * By defining menus, headers and panels.
237
238 * By inserting new buttons into existing menus, headers and panels
239
240
241 In Python, this is done by defining a class, which is a subclass of an existing type.
242
243
244 Example Operator
245 ----------------
246
247 .. literalinclude:: ../../../release/scripts/templates/operator_simple.py
248
249 Once this script runs, ``SimpleOperator`` is registered with Blender and can be called from the operator search popup or added to the toolbar.
250
251 To run the script:
252
253 #. Highlight the above code then press Ctrl+C to copy it.
254
255 #. Start Blender
256
257 #. Press Ctrl+Right twice to change to the Scripting layout.
258
259 #. Click the button labeled ``New`` and the confirmation pop up in order to create a new text block.
260
261 #. Press Ctrl+V to paste the code into the text panel (the upper left frame).
262
263 #. Click on the button **Run Script**.
264
265 #. Move you're mouse into the 3D view, press spacebar for the operator search
266    menu, and type "Simple".
267
268 #. Click on the "Simple Operator" item found in search.
269
270
271 .. seealso:: The class members with the **bl_** prefix are documented in the API
272    reference :class:`bpy.types.Operator`
273
274 .. note:: The output from the ``main`` function is sent to the terminal; in order to see this, be sure to :ref:`use the terminal <use_the_terminal>`.
275
276 Example Panel
277 -------------
278
279 Panels register themselves as a class, like an operator. Notice the extra **bl_** variables used to set the context they display in.
280
281 .. literalinclude:: ../../../release/scripts/templates/ui_panel_simple.py
282
283 To run the script:
284
285 #. Highlight the above code then press Ctrl+C to copy it
286
287 #. Start Blender
288
289 #. Press Ctrl+Right twice to change to the Scripting layout
290
291 #. Click the button labeled ``New`` and the confirmation pop up in order to create a new text block.
292
293 #. Press Ctrl+V to paste the code into the text panel (the upper left frame)
294
295 #. Click on the button **Run Script**.
296
297
298 To view the results:
299
300 #. Select the the default cube.
301
302 #. Click on the Object properties icon in the buttons panel (far right; appears as a tiny cube).
303
304 #. Scroll down to see a panel named **Hello World Panel**.
305
306 #. Changing the object name also updates **Hello World Panel's** Name: field.
307
308 Note the row distribution and the label and properties that are available through the code.
309
310 .. seealso:: :class:`bpy.types.Panel`
311
312
313 Types
314 =====
315
316 Blender defines a number of Python types but also uses Python native types.
317
318 Blender's Python API can be split up into 3 categories.
319
320
321 Native Types
322 ------------
323
324 In simple cases returning a number or a string as a custom type would be cumbersome, so these are accessed as normal python types.
325
326 * blender float/int/boolean -> float/int/boolean
327
328 * blender enumerator -> string
329
330      >>> C.object.rotation_mode = 'AXIS_ANGLE'
331
332
333 * blender enumerator (multiple) -> set of strings
334
335   .. code-block:: python
336
337      # setting multiple camera overlay guides
338      bpy.context.scene.camera.data.show_guide = {'GOLDEN', 'CENTER'}
339
340      # passing as an operator argument for report types
341      self.report({'WARNING', 'INFO'}, "Some message!")
342
343
344 Internal Types
345 --------------
346
347 Used for Blender datablocks and collections: :class:`bpy.types.bpy_struct`
348
349 For data that contains its own attributes groups/meshes/bones/scenes... etc.
350
351 There are 2 main types that wrap Blenders data, one for datablocks (known internally as bpy_struct), another for properties.
352
353    >>> bpy.context.object
354    bpy.data.objects['Cube']
355
356    >>> C.scene.objects
357    bpy.data.scenes['Scene'].objects
358
359 Note that these types reference Blender's data so modifying them is immediately visible.
360
361
362 Mathutils Types
363 ---------------
364
365 Used for vectors, quaternion, eulers, matrix and color types, accessible from :mod:`mathutils`
366
367 Some attributes such as :class:`bpy.types.Object.location`, :class:`bpy.types.PoseBone.rotation_euler` and :class:`bpy.types.Scene.cursor_location` can be accessed as special math types which can be used together and manipulated in various useful ways.
368
369 Example of a matrix, vector multiplication:
370
371 .. code-block:: python
372
373    bpy.context.object.matrix_world * bpy.context.object.data.verts[0].co
374
375 .. note::
376
377    mathutils types keep a reference to Blender's internal data so changes can
378    be applied back.
379
380
381    Example:
382
383    .. code-block:: python
384
385       # modifies the Z axis in place.
386       bpy.context.object.location.z += 2.0
387
388       # location variable holds a reference to the object too.
389       location = bpy.context.object.location
390       location *= 2.0
391
392       # Copying the value drops the reference so the value can be passed to
393       # functions and modified without unwanted side effects.
394       location = bpy.context.object.location.copy()
395
396
397 Animation
398 =========
399
400 There are 2 ways to add keyframes through Python.
401
402 The first is through key properties directly, which is similar to inserting a keyframe from the button as a user. You can also manually create the curves and keyframe data, then set the path to the property. Here are examples of both methods.
403
404 Both examples insert a keyframe on the active object's Z axis.
405
406 Simple example:
407
408 .. code-block:: python
409
410    obj = bpy.context.object
411    obj.location[2] = 0.0
412    obj.keyframe_insert(data_path="location", frame=10.0, index=2)
413    obj.location[2] = 1.0
414    obj.keyframe_insert(data_path="location", frame=20.0, index=2)
415
416 Using Low-Level Functions:
417
418 .. code-block:: python
419
420    obj = bpy.context.object
421    obj.animation_data_create()
422    obj.animation_data.action = bpy.data.actions.new(name="MyAction")
423    fcu_z = obj.animation_data.action.fcurves.new(data_path="location", index=2)
424    fcu_z.keyframe_points.add(2)
425    fcu_z.keyframe_points[0].co = 10.0, 0.0
426    fcu_z.keyframe_points[1].co = 20.0, 1.0
427