2015-06-17 21:52:52 +00:00
|
|
|
|
2011-09-06 00:12:34 +00:00
|
|
|
***************
|
2011-09-01 07:07:18 +00:00
|
|
|
Tips and Tricks
|
2011-09-06 00:12:34 +00:00
|
|
|
***************
|
2011-09-01 07:07:18 +00:00
|
|
|
|
2011-09-08 01:26:23 +00:00
|
|
|
Here are various suggestions that you might find useful when writing scripts.
|
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
Some of these are just Python features that scripters may not have thought to use with Blender,
|
|
|
|
others are Blender specific.
|
2011-09-01 07:07:18 +00:00
|
|
|
|
|
|
|
|
2011-10-28 01:10:46 +00:00
|
|
|
.. _use_the_terminal:
|
|
|
|
|
2011-09-01 07:07:18 +00:00
|
|
|
Use The Terminal
|
2011-09-06 00:12:34 +00:00
|
|
|
================
|
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
When writing Python scripts, it's useful to have a terminal open,
|
|
|
|
this is not the built-in Python console but a terminal application which is used to start Blender.
|
2011-09-06 00:12:34 +00:00
|
|
|
|
|
|
|
There are 3 main uses for the terminal, these are:
|
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
- You can see the output of ``print()`` as your script runs, which is useful to view debug info.
|
|
|
|
- The error trace-back is printed in full to the terminal which won't always generate an error popup in
|
|
|
|
Blender's user interface (depending on how the script is executed).
|
|
|
|
- If the script runs for too long or you accidentally enter an infinite loop,
|
|
|
|
:kbd:`Ctrl-C` in the terminal (:kbd:`Ctrl-Break` on Windows) will quit the script early.
|
2011-09-06 00:12:34 +00:00
|
|
|
|
|
|
|
.. note::
|
2015-06-17 21:52:52 +00:00
|
|
|
|
|
|
|
For Linux and OSX users this means starting the terminal first, then running Blender from within it.
|
|
|
|
On Windows the terminal can be enabled from the help menu.
|
2011-09-01 07:07:18 +00:00
|
|
|
|
|
|
|
|
2012-01-13 06:59:16 +00:00
|
|
|
Interface Tricks
|
|
|
|
================
|
|
|
|
|
|
|
|
|
|
|
|
Access Operator Commands
|
|
|
|
------------------------
|
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
You may have noticed that the tooltip for menu items and buttons includes the ``bpy.ops.[...])`` command
|
|
|
|
to run that button, a handy (hidden) feature is that you can press :kbd:`Ctrl-C` over
|
|
|
|
any menu item/button to copy this command into the clipboard.
|
2012-01-13 06:59:16 +00:00
|
|
|
|
|
|
|
|
|
|
|
Access Data Path
|
|
|
|
----------------
|
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
To find the path from an :class:`ID` datablock to its setting isn't always so simple since it may be nested away.
|
|
|
|
To get this quickly you can right click on the setting and select select **Copy Data Path**,
|
2012-01-13 06:59:16 +00:00
|
|
|
if this can't be generated, only the property name is copied.
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
This uses the same method for creating the animation path used by
|
|
|
|
:class:`bpy.types.FCurve.data_path` and
|
|
|
|
:class:`bpy.types.DriverTarget.data_path` drivers.
|
2012-01-13 06:59:16 +00:00
|
|
|
|
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
.. _info_show_all_operators:
|
2012-12-07 05:27:09 +00:00
|
|
|
|
2011-09-15 08:07:42 +00:00
|
|
|
Show All Operators
|
|
|
|
==================
|
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
While Blender logs operators in the Info space,
|
|
|
|
this only reports operators with the ``REGISTER`` option enabeld so as not to flood the *Info* view
|
|
|
|
with calls to ``bpy.ops.view3d.smoothview`` and ``bpy.ops.view3d.zoom``.
|
2011-09-15 08:07:42 +00:00
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
However, for testing it can be useful to see **every** operator called in a terminal,
|
|
|
|
do this by enabling the debug option either by passing the ``--debug-wm`` argument when starting Blender
|
|
|
|
or by setting :mod:`bpy.app.debug_wm` to ``True`` while Blender is running.
|
2011-09-15 08:07:42 +00:00
|
|
|
|
|
|
|
|
2011-09-08 01:26:23 +00:00
|
|
|
Use an External Editor
|
|
|
|
======================
|
2011-09-06 00:12:34 +00:00
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
Blenders text editor is fine for small changes and writing tests but its not full featured,
|
|
|
|
for larger projects you'll probably want to use a standalone editor or Python IDE.
|
2011-09-06 00:12:34 +00:00
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
Editing a text file externally and having the same text open in Blender does work but isn't that optimal
|
|
|
|
so here are 2 ways you can easily use an external file from Blender.
|
|
|
|
|
|
|
|
Using the following examples you'll still need textblock in Blender to execute,
|
|
|
|
but reference an external file rather then including it directly.
|
2011-09-06 00:12:34 +00:00
|
|
|
|
|
|
|
|
|
|
|
Executing External Scripts
|
2011-09-08 01:26:23 +00:00
|
|
|
--------------------------
|
2011-09-06 00:12:34 +00:00
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
This is the equivalent to running the script directly, referencing a scripts path from a 2 line text-block.
|
2011-09-06 00:12:34 +00:00
|
|
|
|
2011-09-08 01:26:23 +00:00
|
|
|
.. code-block:: python
|
2011-09-06 00:12:34 +00:00
|
|
|
|
|
|
|
filename = "/full/path/to/myscript.py"
|
|
|
|
exec(compile(open(filename).read(), filename, 'exec'))
|
|
|
|
|
|
|
|
|
2011-09-08 01:26:23 +00:00
|
|
|
You might want to reference a script relative to the blend file.
|
2011-09-06 00:12:34 +00:00
|
|
|
|
2011-09-08 01:26:23 +00:00
|
|
|
.. code-block:: python
|
2011-09-06 00:12:34 +00:00
|
|
|
|
|
|
|
import bpy
|
|
|
|
import os
|
|
|
|
|
2012-03-09 21:23:15 +00:00
|
|
|
filename = os.path.join(os.path.dirname(bpy.data.filepath), "myscript.py")
|
2011-09-06 00:12:34 +00:00
|
|
|
exec(compile(open(filename).read(), filename, 'exec'))
|
|
|
|
|
|
|
|
|
|
|
|
Executing Modules
|
2011-09-08 01:26:23 +00:00
|
|
|
-----------------
|
2011-09-06 00:12:34 +00:00
|
|
|
|
|
|
|
This example shows loading a script in as a module and executing a module function.
|
|
|
|
|
2011-09-08 01:26:23 +00:00
|
|
|
.. code-block:: python
|
2011-09-06 00:12:34 +00:00
|
|
|
|
|
|
|
import myscript
|
|
|
|
import imp
|
|
|
|
|
|
|
|
imp.reload(myscript)
|
|
|
|
myscript.main()
|
|
|
|
|
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
Notice that the script is reloaded every time, this forces use of the modified version,
|
|
|
|
otherwise the cached one in ``sys.modules`` would be used until Blender was restarted.
|
2011-09-06 00:12:34 +00:00
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
The important difference between this and executing the script directly is it
|
|
|
|
has to call a function in the module, in this case ``main()`` but it can be any function,
|
|
|
|
an advantage with this is you can pass arguments to the function from this
|
|
|
|
small script which is often useful for testing different settings quickly.
|
2011-09-06 00:12:34 +00:00
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
The other issue with this is the script has to be in Pythons module search path.
|
|
|
|
While this is not best practice - for testing you can extend the search path,
|
|
|
|
this example adds the current blend files directory to the search path, then loads the script as a module.
|
2011-09-06 00:12:34 +00:00
|
|
|
|
2011-09-08 01:26:23 +00:00
|
|
|
.. code-block:: python
|
2011-09-06 00:12:34 +00:00
|
|
|
|
|
|
|
import sys
|
|
|
|
import os
|
2011-09-08 01:26:23 +00:00
|
|
|
import bpy
|
2011-09-06 00:12:34 +00:00
|
|
|
|
2014-01-03 01:28:21 +00:00
|
|
|
blend_dir = os.path.dirname(bpy.data.filepath)
|
2011-09-06 00:12:34 +00:00
|
|
|
if blend_dir not in sys.path:
|
|
|
|
sys.path.append(blend_dir)
|
|
|
|
|
|
|
|
import myscript
|
|
|
|
import imp
|
|
|
|
imp.reload(myscript)
|
|
|
|
myscript.main()
|
2011-09-01 07:07:18 +00:00
|
|
|
|
|
|
|
|
|
|
|
Don't Use Blender!
|
2011-09-06 00:12:34 +00:00
|
|
|
==================
|
2011-09-01 07:07:18 +00:00
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
While developing your own scripts Blenders interface can get in the way,
|
|
|
|
manually reloading, running the scripts, opening file import etc. adds overhead.
|
2011-09-08 01:26:23 +00:00
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
For scripts that are not interactive it can end up being more efficient not to use
|
|
|
|
Blenders interface at all and instead execute the script on the command line.
|
2011-09-08 01:26:23 +00:00
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
.. code-block:: sh
|
2011-09-08 01:26:23 +00:00
|
|
|
|
|
|
|
blender --background --python myscript.py
|
|
|
|
|
|
|
|
|
|
|
|
You might want to run this with a blend file so the script has some data to operate on.
|
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
.. code-block:: sh
|
2011-09-07 07:46:26 +00:00
|
|
|
|
2011-09-08 01:26:23 +00:00
|
|
|
blender myscene.blend --background --python myscript.py
|
2011-09-07 07:46:26 +00:00
|
|
|
|
|
|
|
|
2011-09-08 01:26:23 +00:00
|
|
|
.. note::
|
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
Depending on your setup you might have to enter the full path to the Blender executable.
|
2011-09-08 01:26:23 +00:00
|
|
|
|
2011-09-07 07:46:26 +00:00
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
Once the script is running properly in background mode, you'll want to check the output of the script,
|
|
|
|
this depends completely on the task at hand however here are some suggestions.
|
2011-09-07 07:46:26 +00:00
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
- render the output to an image, use an image viewer and keep writing over the same image each time.
|
|
|
|
- save a new blend file, or export the file using one of Blenders exporters.
|
|
|
|
- if the results can be displayed as text - print them or write them to a file.
|
2011-09-07 07:46:26 +00:00
|
|
|
|
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
While this can take a little time to setup, it can be well worth the effort
|
|
|
|
to reduce the time it takes to test changes - you can even have
|
|
|
|
Blender running the script every few seconds with a viewer updating the results,
|
|
|
|
so no need to leave your text editor to see changes.
|
2011-09-07 07:46:26 +00:00
|
|
|
|
2011-09-01 07:07:18 +00:00
|
|
|
|
|
|
|
Use External Tools
|
2011-09-06 00:12:34 +00:00
|
|
|
==================
|
2011-09-01 07:07:18 +00:00
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
When there are no readily available Python modules to perform specific tasks it's
|
|
|
|
worth keeping in mind you may be able to have Python execute an external command
|
|
|
|
on your data and read the result back in.
|
2011-09-08 01:26:23 +00:00
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
Using external programs adds an extra dependency and may limit who can use the script
|
|
|
|
but to quickly setup your own custom pipeline or writing one-off scripts this can be handy.
|
2011-09-08 01:26:23 +00:00
|
|
|
|
|
|
|
Examples include:
|
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
- Run The Gimp in batch mode to execute custom scripts for advanced image processing.
|
|
|
|
- Write out 3D models to use external mesh manipulation tools and read back in the results.
|
|
|
|
- Convert files into recognizable formats before reading.
|
2011-09-08 01:26:23 +00:00
|
|
|
|
|
|
|
|
|
|
|
Bundled Python & Extensions
|
|
|
|
===========================
|
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
The Blender releases distributed from blender.org include a complete Python installation on all platforms,
|
|
|
|
this has the disadvantage that any extensions you have installed in your systems Python wont be found by Blender.
|
2011-09-01 07:07:18 +00:00
|
|
|
|
|
|
|
There are 2 ways around this:
|
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
- remove Blender Python sub-directory, Blender will then fallback on the systems Python and use that instead
|
|
|
|
.. warning::
|
|
|
|
|
|
|
|
The Python version must match the one that Blender comes with.
|
2011-09-08 01:26:23 +00:00
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
- copy the extensions into Blender's Python sub-directory so Blender can access them,
|
|
|
|
you could also copy the entire Python installation into Blenders sub-directory,
|
|
|
|
replacing the one Blender comes with.
|
|
|
|
This works as long as the Python versions match and the paths are created in the same relative locations.
|
|
|
|
Doing this has the advantage that you can redistribute this bundle to others with Blender and/or the game player,
|
|
|
|
including any extensions you rely on.
|
2011-09-08 01:26:23 +00:00
|
|
|
|
|
|
|
|
2012-01-04 03:22:37 +00:00
|
|
|
Drop Into a Python Interpreter in Your Script
|
|
|
|
=============================================
|
2011-09-08 01:26:23 +00:00
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
In the middle of a script you may want to inspect some variables,
|
|
|
|
run some function and generally dig about to see whats going on.
|
2011-09-01 07:07:18 +00:00
|
|
|
|
2011-09-08 01:26:23 +00:00
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
import code
|
2011-09-08 10:15:27 +00:00
|
|
|
code.interact(local=locals())
|
2011-09-08 01:26:23 +00:00
|
|
|
|
|
|
|
|
|
|
|
If you want to access both global and local variables do this...
|
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
import code
|
|
|
|
namespace = globals().copy()
|
|
|
|
namespace.update(locals())
|
2011-09-08 10:15:27 +00:00
|
|
|
code.interact(local=namespace)
|
2011-09-08 01:26:23 +00:00
|
|
|
|
|
|
|
|
2012-01-04 03:22:37 +00:00
|
|
|
The next example is an equivalent single line version of the script above which is easier to paste into your code:
|
2011-09-08 01:26:23 +00:00
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
2013-12-27 03:20:08 +00:00
|
|
|
__import__('code').interact(local=dict(globals(), **locals()))
|
2011-09-08 01:26:23 +00:00
|
|
|
|
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
``code.interact`` can be added at any line in the script
|
|
|
|
and will pause the script an launch an interactive interpreter in the terminal,
|
|
|
|
when you're done you can quit the interpreter and the script will continue execution.
|
2011-09-08 01:26:23 +00:00
|
|
|
|
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
If you have **IPython** installed you can use its ``embed()`` function which uses the current namespace.
|
|
|
|
The IPython prompt has auto-complete and some useful features that the standard Python eval-loop doesn't have.
|
2012-12-02 04:51:15 +00:00
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
import IPython
|
|
|
|
IPython.embed()
|
|
|
|
|
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
Admittedly this highlights the lack of any Python debugging support built into Blender, but its still handy to know.
|
2011-09-08 01:26:23 +00:00
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
This works in the game engine as well, it can be handy to inspect the state of a running game.
|
2011-09-01 07:07:18 +00:00
|
|
|
|
2011-09-06 00:12:34 +00:00
|
|
|
|
2011-09-01 07:07:18 +00:00
|
|
|
Advanced
|
2011-09-06 00:12:34 +00:00
|
|
|
========
|
2011-09-01 07:07:18 +00:00
|
|
|
|
|
|
|
|
|
|
|
Blender as a module
|
2011-09-06 00:12:34 +00:00
|
|
|
-------------------
|
2011-09-01 07:07:18 +00:00
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
From a Python perspective it's nicer to have everything as an extension
|
|
|
|
which lets the Python script combine many components.
|
2011-09-08 01:26:23 +00:00
|
|
|
|
|
|
|
Advantages include:
|
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
- you can use external editors/IDE's with Blenders Python API and execute scripts within the IDE
|
|
|
|
(step over code, inspect variables as the script runs).
|
|
|
|
- editors/IDE's can auto complete Blender modules & variables.
|
|
|
|
- existing scripts can import Blender API's without having to run inside Blender.
|
2011-09-08 01:26:23 +00:00
|
|
|
|
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
This is marked advanced because to run Blender as a Python module requires a special build option.
|
2011-09-08 01:26:23 +00:00
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
For instructions on building see
|
|
|
|
`Building Blender as a Python module <http://wiki.blender.org/index.php/User:Ideasman42/BlenderAsPyModule>`_
|
2011-09-08 01:26:23 +00:00
|
|
|
|
2011-09-01 07:07:18 +00:00
|
|
|
|
|
|
|
Python Safety (Build Option)
|
2011-09-06 00:12:34 +00:00
|
|
|
----------------------------
|
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
Since it's possible to access data which has been removed (see Gotcha's),
|
|
|
|
this can be hard to track down the cause of crashes.
|
|
|
|
|
|
|
|
To raise Python exceptions on accessing freed data (rather then crashing),
|
|
|
|
enable the CMake build option WITH_PYTHON_SAFETY.
|
2011-09-08 01:26:23 +00:00
|
|
|
|
2015-06-17 21:52:52 +00:00
|
|
|
This enables data tracking which makes data access about 2x slower
|
|
|
|
which is why the option isn't enabled in release builds.
|
2011-09-08 01:26:23 +00:00
|
|
|
|