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