Fix T71878: Cycles crash with adaptive subdivision and empty mesh
[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, key-maps 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 - Subscribe to changes to data and it's properties.
23 - Define new settings in existing Blender data.
24 - Draw in the 3D view using Python.
25
26
27 The Blender/Python API **can't** (yet)...
28
29 - Create new space types.
30 - Assign custom properties to every type.
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:`directory layout docs <blender_manual:blender-directory-layout>`.
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 Viewport,
321    open the :ref:`operator search menu <blender_manual:bpy.ops.wm.search_menu>`,
322    and type "Simple".
323 #. Click on the "Simple Operator" item found in search.
324
325
326 .. seealso:: The class members with the ``bl_`` prefix are documented in the API
327    reference :class:`bpy.types.Operator`
328
329 .. note::
330
331    The output from the ``main`` function is sent to the terminal;
332    in order to see this, be sure to :ref:`use the terminal <use_the_terminal>`.
333
334 Example Panel
335 -------------
336
337 Panels register themselves as a class, like an operator.
338 Notice the extra ``bl_`` variables used to set the context they display in.
339
340 .. literalinclude:: __/__/__/release/scripts/templates_py/ui_panel_simple.py
341
342 To run the script:
343
344 #. Highlight the above code then press :kbd:`Ctrl-C` to copy it.
345 #. Start Blender.
346 #. Click on the tab for the *Scripting* workspace.
347 #. Click the button labeled ``New`` to create a new text block.
348 #. Press :kbd:`Ctrl-V` to paste the code into the text panel (the upper left frame).
349 #. Click on the button **Run Script**.
350
351
352 To view the results:
353
354 #. Select the the default cube.
355 #. Click on the Object properties icon in the buttons panel (far right; appears as a tiny cube).
356 #. Scroll down to see a panel named **Hello World Panel**.
357 #. Changing the object name also updates **Hello World Panel's** Name: field.
358
359 Note the row distribution and the label and properties that are available through the code.
360
361 .. seealso:: :class:`bpy.types.Panel`
362
363
364 Types
365 =====
366
367 Blender defines a number of Python types but also uses Python native types.
368
369 Blender's Python API can be split up into 3 categories.
370
371
372 Native Types
373 ------------
374
375 In simple cases returning a number or a string as a custom type would be cumbersome,
376 so these are accessed as normal Python types.
377
378 - Blender float/int/boolean -> float/int/boolean
379 - Blender enumerator -> string
380
381      >>> C.object.rotation_mode = 'AXIS_ANGLE'
382
383 - Blender enumerator (multiple) -> set of strings
384
385   .. code-block:: python
386
387      # setting multiple camera overlay guides
388      bpy.context.scene.camera.data.show_guide = {'GOLDEN', 'CENTER'}
389
390      # passing as an operator argument for report types
391      self.report({'WARNING', 'INFO'}, "Some message!")
392
393
394 Internal Types
395 --------------
396
397 Used for Blender data-blocks and collections: :class:`bpy.types.bpy_struct`
398
399 For data that contains its own attributes collections/meshes/bones/scenes... etc.
400
401 There are 2 main types that wrap Blenders data, one for data-blocks
402 (known internally as ``bpy_struct``), another for properties.
403
404    >>> bpy.context.object
405    bpy.data.objects['Cube']
406
407    >>> C.scene.objects
408    bpy.data.scenes['Scene'].objects
409
410 Note that these types reference Blender's data so modifying them is immediately visible.
411
412
413 Mathutils Types
414 ---------------
415
416 Used for vectors, quaternion, eulers, matrix and color types, accessible from :mod:`mathutils`
417
418 Some attributes such as :class:`bpy.types.Object.location`,
419 :class:`bpy.types.PoseBone.rotation_euler` and :class:`bpy.types.Scene.cursor_location`
420 can be accessed as special math types which can be used together and manipulated in various useful ways.
421
422 Example of a matrix, vector multiplication:
423
424 .. code-block:: python
425
426    bpy.context.object.matrix_world * bpy.context.object.data.verts[0].co
427
428 .. note::
429
430    mathutils types keep a reference to Blender's internal data so changes can
431    be applied back.
432
433
434    Example:
435
436    .. code-block:: python
437
438       # modifies the Z axis in place.
439       bpy.context.object.location.z += 2.0
440
441       # location variable holds a reference to the object too.
442       location = bpy.context.object.location
443       location *= 2.0
444
445       # Copying the value drops the reference so the value can be passed to
446       # functions and modified without unwanted side effects.
447       location = bpy.context.object.location.copy()
448
449
450 Animation
451 =========
452
453 There are 2 ways to add keyframes through Python.
454
455 The first is through key properties directly, which is similar to inserting a keyframe from the button as a user.
456 You can also manually create the curves and keyframe data, then set the path to the property.
457 Here are examples of both methods.
458
459 Both examples insert a keyframe on the active object's Z axis.
460
461 Simple example:
462
463 .. code-block:: python
464
465    obj = bpy.context.object
466    obj.location[2] = 0.0
467    obj.keyframe_insert(data_path="location", frame=10.0, index=2)
468    obj.location[2] = 1.0
469    obj.keyframe_insert(data_path="location", frame=20.0, index=2)
470
471 Using Low-Level Functions:
472
473 .. code-block:: python
474
475    obj = bpy.context.object
476    obj.animation_data_create()
477    obj.animation_data.action = bpy.data.actions.new(name="MyAction")
478    fcu_z = obj.animation_data.action.fcurves.new(data_path="location", index=2)
479    fcu_z.keyframe_points.add(2)
480    fcu_z.keyframe_points[0].co = 10.0, 0.0
481    fcu_z.keyframe_points[1].co = 20.0, 1.0