move wiki api intro and overview docs into the api reference docs.
[blender.git] / doc / python_api / rst / info_quickstart.rst
1 #######################
2 Quickstart Introduction
3 #######################
4
5 *****
6 Intro
7 *****
8
9 This API is generally stable but some areas are still being added and improved.
10
11 The Blender/Python API can do the following:
12
13 * Edit any data the user interface can (Scenes, Meshes, Particles etc.)
14
15 * Modify user preferences, keymaps and themes
16
17 * Run tools with own settings
18
19 * Create user interface elements such as menus, headers and panels
20
21 * Create new tools
22
23 * Create interactive tools
24
25 * Create new rendering engines that integrate with Blender
26
27 * Define new settings in existing Blender data
28
29 * Draw in the 3D view using OpenGL commands from Python
30
31
32 The Blender/Python API **can't** (yet)...
33
34 * Create new space types.
35
36 * Assign custom properties to every type.
37
38 * Define callbacks or listeners to be notified when data is changed.
39
40
41 ***************
42 Before Starting
43 ***************
44
45 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.
46
47
48 A quick list of helpful things to know before starting:
49
50 * Blender uses Python 3.x; some 3rd party extensions are not available yet.
51
52 * The interactive console in Blender 2.5 has been improved; testing one-liners in the console is a good way to learn.
53
54 * Button tool tips show Python attributes and operator names.
55
56 * Right clicking on buttons and menu items directly links to API documentation.
57
58 * For more examples, the text menu has a templates section where some example operators can be found.
59
60 * 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.
61
62
63 ************
64 Key Concepts
65 ************
66
67 ===========
68 Data Access
69 ===========
70
71 --------------------
72 Accessing datablocks
73 --------------------
74
75 Python accesses Blender's data in the same way as the animation system and user interface, which means any setting that is changed via a button can also be changed from Python.
76
77 Accessing data from the currently loaded blend file is done with the module :mod:`bpy.data`. This gives access to library data. For example:
78
79
80 .. code-block:: python
81
82    >>> bpy.data.objects
83    <bpy_collection[3], BlendDataObjects>
84
85    >>> bpy.data.scenes
86    <bpy_collection[1], BlendDataScenes>
87
88    >>> bpy.data.materials
89    <bpy_collection[1], BlendDataMaterials>
90
91
92 -----------------
93 About Collections
94 -----------------
95
96 You'll notice that an index as well as a string can be used to access members of the collection.
97
98 Unlike Python's dictionaries, both methods are acceptable; however, the index of a member may change while running Blender.
99
100
101 .. code-block:: python
102
103    >>> list(bpy.data.objects)
104    [bpy.data.objects["Cube"], bpy.data.objects["Plane"]]
105
106    >>> bpy.data.objects['Cube']
107    bpy.data.objects["Cube"]
108
109    >>> bpy.data.objects[0]
110    bpy.data.objects["Cube"]
111
112
113 --------------------
114 Accessing attributes
115 --------------------
116
117 Once you have a data block such as a material, object, groups etc. its attributes can be accessed just like changing a setting in the interface; in fact, the button tooltip also displays the Python attribute which can help in finding what settings to change in a script.
118
119 .. code-block:: python
120
121    >>> bpy.data.objects[0].name 
122    'Camera'
123
124    >>> bpy.data.scenes["Scene"]
125    bpy.data.scenes['Scene']
126
127    >>> bpy.data.materials.new("MyMaterial")
128    bpy.data.materials['MyMaterial']
129
130
131 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.
132
133 Example of a data path that can be quickly found via the console:
134
135 .. code-block:: python
136
137    >>> bpy.data.scenes[0].render.resolution_percentage
138    100
139    >>> bpy.data.scenes[0].objects["Torus"].data.vertices[0].co.x
140    1.0
141
142
143 -----------------
144 Custom Properties
145 -----------------
146
147 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.
148
149 This data is saved with the blend file and copied with objects.
150
151 Example:
152
153 .. code-block:: python
154
155    bpy.context.object["MyOwnProperty"] = 42
156
157    if "SomeProp" in bpy.context.object:
158        print("Property found")
159
160    # Use the get function like a python dictionary
161    # which can have a fallback value.
162    value = bpy.data.scenes["Scene"].get("test_prop", "fallback value")
163
164    # dictionaries can be assigned as long as they only use basic types.
165    group = bpy.data.groups.new("MyTestGroup")
166    group["GameSettings"] = {"foo": 10, "bar": "spam", "baz": {}}
167
168    del group["GameSettings"]
169
170
171 Note that these properties can only be assigned  basic Python types.
172
173 * int, float, string
174
175 * array of ints/floats
176
177 * dictionary (only string keys types on this list)
178
179 These properties are valid outside of Python. They can be animated by curves or used in driver paths.
180
181
182 =======
183 Context
184 =======
185
186 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.
187
188 Common-use cases:
189
190 .. code-block:: python
191
192    >>> bpy.context.object
193    >>> bpy.context.selected_objects
194    >>> bpy.context.visible_bones
195
196 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.
197
198 So ``bpy.context.object = obj`` will raise an error.
199
200 But ``bpy.context.scene.objects.active = obj`` will work as expected.
201
202
203 The context attributes change depending on where it is accessed. The 3D view has different context members to the Console, so take care when accessing context attributes that the user state is known.
204
205 See :mod:`bpy.context` API reference
206
207
208 =================
209 Operators (Tools)
210 =================
211
212 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.
213
214 Examples:
215
216 .. code-block:: python
217
218    >>> bpy.ops.mesh.flip_normals()
219    {'FINISHED'}
220    >>> bpy.ops.mesh.hide(unselected=False)
221    {'FINISHED'}
222    >>> bpy.ops.object.scale_apply()
223    {'FINISHED'}
224
225 .. note::
226
227    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.
228
229
230 ---------------
231 Operator Poll()
232 ---------------
233
234 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.
235
236 For example, calling bpy.ops.view3d.render_border() from the console raises the following error:
237
238 .. code-block:: python
239
240    RuntimeError: Operator bpy.ops.view3d.render_border.poll() failed, context is incorrect
241
242 In this case the context must be the 3d view with an active camera.
243
244 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.
245
246 .. code-block:: python
247
248    if bpy.ops.view3d.render_border.poll():
249        bpy.ops.view3d.render_border()
250
251
252 ***********
253 Integration
254 ***********
255
256 Python scripts can integrate with Blender in the following ways:
257
258 * By defining a rendering engine.
259
260 * By defining operators.
261
262 * By defining menus, headers and panels.
263
264 * By inserting new buttons into existing menus, headers and panels
265
266
267 In Python, this is done by defining a class, which is a subclass of an existing type.
268
269 ================
270 Example Operator
271 ================
272
273 .. literalinclude:: ../../../release/scripts/templates/operator_simple.py
274
275 Once this script runs, ``SimpleOperator`` is registered with Blender and can be called from the operator search popup or added to the toolbar.
276
277 To run the script:
278
279 #. Highlight the above code then press Ctrl+C to copy it.
280
281 #. Start Blender
282
283 #. Press Ctrl+Right twice to change to the Scripting layout.
284
285 #. Press Ctrl+V to paste the code into the text panel (the upper left frame).
286
287 #. Click on the button **Run Script**.
288
289 #. Move you're mouse into the 3D view, press spacebar for the operator search
290    menu, and type "Simple".
291
292 #. Click on the "Simple Operator" item found in search.
293
294
295 .. seealso:: The class members with the **bl_** prefix are documented in the API
296    reference :class:`bpy.types.Operator`
297
298
299 =============
300 Example Panel
301 =============
302
303 Panels register themselves as a class, like an operator. Notice the extra **bl_** variables used to set the context they display in.
304
305 .. literalinclude:: ../../../release/scripts/templates/ui_panel_simple.py
306
307 To run the script:
308
309 #. Highlight the above code then press Ctrl+C to copy it
310
311 #. Start Blender
312
313 #. Press Ctrl+Right twice to change to the Scripting layout
314
315 #. Press Ctrl+V to paste the code into the text panel (the upper left frame)
316
317 #. Click on the button **Run Script**.
318
319
320 To view the results:
321
322 #. Select the the default cube.
323
324 #. Click on the Object properties icon in the buttons panel (far right; appears as a tiny cube).
325
326 #. Scroll down to see a panel named **Hello World Panel**.
327
328 #. Changing the object name also updates **Hello World Panel's** Name: field.
329
330 Note the row distribution and the label and properties that are available through the code.
331
332 .. seealso:: :class:`bpy.types.Panel`
333
334
335 *****
336 Types
337 *****
338
339 Blender defines a number of Python types but also uses Python native types.
340
341 Blender's Python API can be split up into 3 categories. 
342
343 ============
344 Native Types
345 ============
346
347 In simple cases returning a number or a string as a custom type would be cumbersome, so these are accessed as normal python types.
348
349 * blender float/int/boolean -> float/int/boolean
350
351 * blender enumerator -> string
352
353   .. code-block:: python
354
355      >>> C.object.rotation_mode = 'AXIS_ANGLE'
356
357
358 * blender enumerator (multiple) -> set of strings
359
360   .. code-block:: python
361
362      # setting multiple camera overlay guides
363      bpy.context.scene.camera.data.show_guide = {'GOLDEN', 'CENTER'}
364
365      # passing as an operator argument for report types
366      self.report({'WARNING', 'INFO'}, "Some message!")
367
368
369 ==============
370 Internal Types
371 ==============
372
373 Used for Blender datablocks and collections: :class:`bpy.types.bpy_struct`
374
375 For data that contains its own attributes groups/meshes/bones/scenes... etc.
376
377 There are 2 main types that wrap Blenders data, one for datablocks (known internally as bpy_struct), another for properties.
378
379 .. code-block:: python
380
381    >>> bpy.context.object
382    bpy.data.objects['Cube']
383
384    >>> C.scene.objects
385    bpy.data.scenes['Scene'].objects
386
387 Note that these types reference Blender's data so modifying them is immediately visible.
388
389 ===============
390 Mathutils Types
391 ===============
392
393 Used for vectors, quaternion, eulers, matrix and color types, accessible from :mod:`mathutils`
394
395 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.
396
397 Example of a matrix, vector multiplication:
398
399 .. code-block:: python
400
401    bpy.context.object.matrix_world * bpy.context.object.data.verts[0].co
402
403 .. note::
404
405    mathutils types keep a reference to Blender's internal data so changes can
406    be applied back.
407
408
409    Example:
410
411    .. code-block:: python
412
413       # modifies the Z axis in place.
414       bpy.context.object.location.z += 2.0
415
416       # location variable holds a reference to the object too.
417       location = bpy.context.object.location
418       location *= 2.0
419
420       # Copying the value drops the reference so the value can be passed to
421       # functions and modified without unwanted side effects.
422       location = bpy.context.object.location.copy()
423
424
425 *********
426 Animation
427 *********
428
429 There are 2 ways to add keyframes through Python.
430
431 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.
432
433 Both examples insert a keyframe on the active object's Z axis.
434
435 Simple example:
436
437 .. code-block:: python
438
439    obj = bpy.context.object
440    obj.location[2] = 0.0
441    obj.keyframe_insert(data_path="location", frame=10.0, index=2)
442    obj.location[2] = 1.0
443    obj.keyframe_insert(data_path="location", frame=20.0, index=2)
444
445 Using Low-Level Functions:
446
447 .. code-block:: python
448
449    obj = bpy.context.object
450    obj.animation_data_create()
451    obj.animation_data.action = bpy.data.actions.new(name="MyAction")
452    fcu_z = obj.animation_data.action.fcurves.new(data_path="location", index=2)
453    fcu_z.keyframe_points.add(2)
454    fcu_z.keyframe_points[0].co = 10.0, 0.0
455    fcu_z.keyframe_points[1].co = 20.0, 1.0
456
457
458 *****************
459 Style Conventions
460 *****************
461
462 For Blender 2.5 we have chosen to follow python suggested style guide to avoid mixing styles amongst our own scripts and make it easier to use python scripts from other projects.
463
464 Using our style guide for your own scripts makes it easier if you eventually want to contribute them to blender.
465
466 This style guide is known as pep8 and can be found `here <http://www.python.org/dev/peps/pep-0008>`_
467
468 A brief listing of pep8 criteria.
469
470 * camel caps for class names: MyClass
471
472 * all lower case underscore separated module names: my_module
473
474 * indentation of 4 spaces (no tabs)
475
476 * spaces around operators. ``1 + 1``, not ``1+1``
477
478 * only use explicit imports, (no importing '*')
479
480 * don't use single line: ``if val: body``, separate onto 2 lines instead.
481
482
483 As well as pep8 we have other conventions used for blender python scripts.
484
485 * Use single quotes for enums, and double quotes for strings.
486
487   Both are of course strings but in our internal API enums are unique items from a limited set. eg.
488
489   .. code-block:: python
490
491      bpy.context.scene.render.file_format = 'PNG'
492      bpy.context.scene.render.filepath = "//render_out"
493
494 * pep8 also defines that lines should not exceed 79 characters, we felt this is too restrictive so this is optional per script.
495
496 Periodically we run checks for pep8 compliance on blender scripts, for scripts to be included in this check add this line as a comment at the top of the script.
497
498 ``# <pep8 compliant>``
499
500 To enable line length checks use this instead.
501
502 ``# <pep8-80 compliant>``
503