1
2
3 """
4 The Blender Python API Reference
5 ================================
6
7 for a full list of changes since 2.45 see U{http://wiki.blender.org/index.php/Release_Notes/Notes246/Python_API}
8
9 Top Module:
10 -----------
11
12 - L{Blender}
13 - L{bpy<Bpy>} (experimental)
14
15 Submodules:
16 -----------
17 - L{Armature}
18 - L{NLA}
19 - L{Action<NLA.Action>}
20 - L{BezTriple}
21 - L{BGL}
22 - L{Camera}
23 - L{Curve}
24 - L{Draw}
25 - L{Effect}
26 - L{Geometry}
27 - L{Group}
28 - L{Image}
29 - L{Ipo}
30 - L{IpoCurve}
31 - L{Key}
32 - L{Lamp}
33 - L{Lattice}
34 - L{Library}
35 - L{Material}
36 - L{Mathutils}
37 - L{Mesh}
38 - L{MeshPrimitives}
39 - L{Metaball}
40 - L{NMesh} (deprecated)
41 - L{Noise}
42 - L{Object}
43 - L{Modifier}
44 - L{Pose}
45 - L{Constraint}
46 - L{ActionStrips<NLA>}
47 - L{Particle}
48 - L{Registry}
49 - L{Scene}
50 - L{Radio}
51 - L{Render}
52 - L{Sound}
53 - L{Text}
54 - L{Text3d}
55 - L{Font}
56 - L{Texture}
57 - L{TimeLine}
58 - L{Types}
59 - L{Window}
60 - L{Theme}
61 - L{World}
62 - L{sys<Sys>}
63
64 Introduction:
65 =============
66
67 This reference documents the Blender Python API, a growing collection of
68 Python modules (libraries) that give access to part of the program's internal
69 data and functions.
70
71 Through scripting Blender can be extended in real-time via
72 U{Python <www.python.org>}, an impressive high level, multi-paradigm, open
73 source language. Newcomers are recommended to start with the tutorial that
74 comes with it.
75
76 This opens many interesting possibilities, ranging from automating repetitive
77 tasks to adding new functionality to the program: procedural models,
78 importers and exporters, even complex applications and so on. Blender itself
79 comes with some scripts, but many others can be found in the Scripts & Plugins
80 sections and forum posts at the Blender-related sites listed below.
81
82 Scripting and Blender:
83 ======================
84
85 These are the basic ways to execute scripts in Blender:
86
87 1. They can be loaded or typed as text files in the Text Editor window, then
88 executed with ALT+P.
89 2. Via command line: C{blender -P <scriptname>} will start Blender and execute
90 the given script. <scriptname> can be a filename in the user's file system or
91 the name of a text saved in a .blend Blender file:
92 'blender myfile.blend -P textname'.
93 3. Via command line in I{background mode}: use the '-b' flag (the order is
94 important): C{blender -b <blendfile> -P <scriptname>}. <blendfile> can be any
95 .blend file, including the default .B.blend that is in Blender's home directory
96 L{Blender.Get}('homedir'). In this mode no window will be opened and the
97 program will leave as soon as the script finishes execution.
98 4. Properly registered scripts can be selected directly from the program's
99 menus.
100 5. Scriptlinks: these are also loaded or typed in the Text Editor window and
101 can be linked to objects, materials or scenes using the Scriptlink buttons
102 tab. Script links get executed automatically when their events (ONLOAD,
103 REDRAW, FRAMECHANGED) are triggered. Normal scripts can create (L{Text}) and
104 link other scripts to objects and events, see L{Object.Object.addScriptLink},
105 for example.
106 6. A script can call another script (that will run in its own context, with
107 its own global dictionary) with the L{Blender.Run} module function.
108
109
110 Interaction with users:
111 -----------------------
112
113 Scripts can:
114 - simply run and exit;
115 - pop messages, menus and small number and text input boxes;
116 - draw graphical user interfaces (GUIs) with OpenGL calls and native
117 program buttons, which stay there accepting user input like any other
118 Blender window until the user closes them;
119 - attach themselves to a space's event or drawing code (aka space handlers,
120 L{check here<API_related>});
121 - make changes to the 3D View (set visible layer(s), view point, etc);
122 - grab the main input event queue and process (or pass to Blender) selected
123 keyboard, mouse, redraw events -- not considered good practice, but still
124 available for private use;
125 - tell Blender to execute other scripts (see L{Blender.Run}());
126 - use external Python libraries, if available.
127
128 You can read the documentation for the L{Window}, L{Draw} and L{BGL} modules
129 for more information and also check the Python site for external modules that
130 might be useful to you. Note though that any imported module will become a
131 requirement of your script, since Blender itself does not bundle external
132 modules.
133
134 Command line mode:
135 ------------------
136
137 Python was embedded in Blender, so to access BPython modules you need to
138 run scripts from the program itself: you can't import the Blender module
139 into an external Python interpreter.
140
141 On the other hand, for many tasks it's possible to control Blender via
142 some automated process using scripts. Interested readers should learn about
143 features like "OnLoad" script links, the "-b <blendfile>" (background mode)
144 and "-P <script>" (run script) command line options and API calls like
145 L{Blender.Save}, L{Blender.Load}, L{Blender.Quit} and the L{Library} and
146 L{Render} modules.
147
148 Note that command line scripts are run before Blender initializes its windows
149 (and in '-b' mode no window will be initialized), so many functions that get
150 or set window related attributes (like most in L{Window}) don't work here. If
151 you need those, use an ONLOAD script link (see L{Scene.Scene.addScriptLink})
152 instead -- it's also possible to use a command line script to write or set an
153 ONLOAD script link. Check the L{Blender.mode} module var to know if Blender
154 is being executed in "background" or "interactive" mode.
155
156 L{Click here for command line and background mode examples<API_related>}.
157
158
159 Demo mode:
160 ----------
161
162 Blender has a demo mode, where once started it can work without user
163 intervention, "showing itself off". Demos can render stills and animations,
164 play rendered or real-time animations, calculate radiosity simulations and
165 do many other nifty things. If you want to turn a .blend file into a demo,
166 write a script to run the show and link it as a scene "OnLoad" scriptlink.
167 The demo will then be played automatically whenever this .blend file is
168 opened, B{unless Blender was started with the "-y" parameter}.
169
170 The Game Engine API:
171 --------------------
172
173 Blender has a game engine for users to create and play 3d games. This
174 engine lets programmers add scripts to improve game AI, control, etc, making
175 more complex interaction and tricks possible. The game engine API is
176 separate from the Blender Python API this document references and you can
177 find its own ref doc in the doc section of the main sites below.
178
179 Blender Data Structures:
180 ------------------------
181
182 Programs manipulate data structures. Blender python scripts are no exception.
183 Blender uses an Object Oriented architecture. The BPython interface tries to
184 present Blender objects and their attributes in the same way you see them
185 through the User Interface (the GUI). One key to BPython programming is
186 understanding the information presented in Blender's OOPS window where Blender
187 objects and their relationships are displayed.
188
189 Each Blender graphic element (Mesh, Lamp, Curve, etc.) is composed from two
190 parts: an Object and ObData. The Object holds information about the position,
191 rotation and size of the element. This is information that all elements have
192 in common. The ObData holds information specific to that particular type of
193 element.
194
195 Each Object has a link to its associated ObData. A single ObData may be
196 shared by many Objects. A graphic element also has a link to a list of
197 Materials. By default, this list is associated with the ObData.
198
199 All Blender objects have a unique name. However, the name is qualified by the
200 type of the object. This means you can have a Lamp Object called Lamp.001
201 (OB:Lamp.001) and a Lamp ObData called Lamp.001 (LA:Lamp.001).
202
203 For a more in-depth look at Blender internals, and some understanding of why
204 Blender works the way it does, see the U{Blender Architecture document
205 <http://www.blender3d.org/cms/Blender_Architecture.336.0.html>}.
206
207
208 A note to newbie script writers:
209 --------------------------------
210
211 Interpreted languages are known to be much slower than compiled code, but for
212 many applications the difference is negligible or acceptable. Also, with
213 profiling (or even simple direct timing with L{Blender.sys.time<Sys.time>}) to
214 identify slow areas and well thought optimizations, the speed can be
215 I{considerably} improved in many cases. Try some of the best BPython scripts
216 to get an idea of what can be done, you may be surprised.
217
218 @author: The Blender Python Team
219 @requires: Blender 2.46 or newer.
220 @version: 2.46
221 @see: U{www.blender.org<http://www.blender.org>}: documentation and forum
222 @see: U{blenderartists.org<http://blenderartists.org>}: user forum
223 @see: U{projects.blender.org<http://projects.blender.org>}
224 @see: U{blender architecture<http://www.blender3d.org/cms/Blender_Architecture.336.0.html>}: blender architecture document
225 @see: U{www.python.org<http://www.python.org>}
226 @see: U{www.python.org/doc<http://www.python.org/doc>}
227 @see: U{Blending into Python<en.wikibooks.org/wiki/Blender_3D:_Blending_Into_Python>}: User contributed documentation, featuring a blender/python cookbook with many examples.
228
229 @note: the official version of this reference guide is only updated for each
230 new Blender release. But you can build the current SVN
231 version yourself: install epydoc, grab all files in the
232 source/blender/python/api2_2x/doc/ folder of Blender's SVN and use the
233 epy_docgen.sh script also found there to generate the html docs.
234 Naturally you will also need a recent Blender binary to try the new
235 features. If you prefer not to compile it yourself, there is a testing
236 builds forum at U{blender.org<http://www.blender.org>}.
237 """
238