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