1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
|
# The Blender Module
# The module files in this folder are used to create the API documentation.
# Doc system used: epydoc - http://epydoc.sf.net
# pseudo command line (check the epy_docgen.sh file):
# epydoc -o BPY_API_23x --url "http://www.blender.org" -t Blender.py \
# -n "Blender" --no-private --no-frames Blender.py \
# Types.py Scene.py Object.py [ ... etc]
"""
The main Blender module.
B{New}: L{Run}, L{UpdateMenus}, new options to L{Get}, L{ShowHelp},
L{SpaceHandlers} dictionary.
L{UnpackModes} dictionary.
Blender
=======
@type bylink: bool
@var bylink: True if the current script is being executed as a script link.
@type link: Blender Object or None; integer (space handlers)
@var link: for normal script links, 'link' points to the linked Object (can be
a scene, object (mesh, camera, lamp), material or
world). For space handler script links, 'link' is an integer from the
Blender.L{SpaceHandlers} dictionary. For script not running as script
links, 'link' is None.
@type event: string or int
@var event: this has three possible uses: script link type or events callback
ascii value:
- for normal script links it is a string representing the link type
(OnLoad, FrameChanged, Redraw, etc.).
- for EVENT space handler script links it is the passed event.
- for normal L{GUI<Draw.Register>} scripts I{during the events callback},
it holds the ascii value of the current event, if it is a valid one.
Users interested in this should also check the builtin 'ord' and 'chr'
Python functions.
@type mode: string
@var mode: Blender's current mode:
- 'interactive': normal mode, with an open window answering to user input;
- 'background': Blender was started as 'C{blender -b <blender file>}' and
will exit as soon as it finishes rendering or executing a script
(ex: 'C{blender -b <blender file> -P <script>}'). Try 'C{blender -h}'
for more detailed informations.
@type UnpackModes: constant dictionary
@var UnpackModes: dictionary with available unpack modes.
- USE_LOCAL - use files in current directory (create when necessary)
- WRITE_LOCAL - write files in current directory (overwrite when necessary)
- USE_ORIGINAL - use files in original location (create when necessary)
- WRITE_ORIGINAL - write files in original location (overwrite when necessary)
@type SpaceHandlers: constant dictionary
@var SpaceHandlers: dictionary with space handler types.
- VIEW3D_EVENT;
- VIEW3D_DRAW.
"""
def Set (request, data):
"""
Update settings in Blender.
@type request: string
@param request: The setting to change:
- 'curframe': the current animation frame
- 'compressfile' : compress file writing a blend file (Use a boolean value True/False).
- 'uscriptsdir': user scripts dir
- 'yfexportdir': yafray temp xml storage dir
- 'fontsdir': font dir
- 'texturesdir': textures dir
- 'seqpluginsdir': sequencer plugin dir
- 'renderdir': default render output dir
- 'soundsdir': sound dir
- 'tempdir': temp file storage dir
- 'mipmap' : Use mipmapping in the 3d view (Use a boolean value True/False).
@type data: int or string
@param data: The new value.
"""
def Get (request):
"""
Retrieve settings from Blender.
@type request: string
@param request: The setting data to be returned:
- 'curframe': the current animation frame.
- 'curtime' : the current animation time.
- 'compressfile' : compress setting from the file menu, return 0 for false or 1 for true.
- 'staframe': the start frame of the animation.
- 'endframe': the end frame of the animation.
- 'rt': the value of the 'rt' button for general debugging
- 'filename': the name of the last file read or written.
- 'homedir': Blender's home directory.
- 'datadir' : the path to the dir where scripts should store and
retrieve their data files, including saved configuration (can
be None, if not found).
- 'udatadir': the path to the user defined data dir. This may not be
available (is None if not found), but users that define uscriptsdir
have a place for their own scripts and script data that won't be
erased when a new version of Blender is installed. For this reason
we recommend scripts check this dir first and use it, if available.
- 'scriptsdir': the path to the main dir where scripts are stored.
- 'uscriptsdir': the path to the user defined dir for scripts. (*)
- 'icondir': the path to blenders icon theme files.
- 'yfexportdir': the path to the user defined dir for yafray export. (*)
- 'fontsdir': the path to the user defined dir for fonts. (*)
- 'texturesdir': the path to the user defined dir for textures. (*)
- 'texpluginsdir': the path to the user defined dir for texture plugins. (*)
- 'seqpluginsdir': the path to the user defined dir for sequence plugins. (*)
- 'renderdir': the path to the user defined dir for render output. (*)
- 'soundsdir': the path to the user defined dir for sound files. (*)
- 'tempdir': the path to the user defined dir for storage of Blender
temporary files. (*)
- 'mipmap' : Use mipmapping in the 3d view. (*)
- 'version' : the Blender version number.
@note: (*) these can be set in Blender at the User Preferences window -> File
Paths tab.
@warn: this function returns None for requested dir paths that have not been
set or do not exist in the user's file system.
@return: The requested data or None if not found.
"""
def Redraw ():
"""
Redraw all 3D windows.
"""
def Load (filename = None):
"""
Load a Blender .blend file or any of the other supported file formats.
Supported formats:
- Blender's .blend;
- DXF;
- Open Inventor 1.0 ASCII;
- Radiogour;
- STL;
- Videoscape;
- VRML 1.0 asc.
@type filename: string
@param filename: the pathname to the desired file. If 'filename'
isn't given or if it contains the substring '.B.blend', the default
.B.blend file is loaded.
@warn: loading a new .blend file removes the current data in Blender. For
safety, this function saves the current data as an auto-save file in
the temporary dir used by Blender before loading a new Blender file.
@warn: after a call to Load(blendfile), current data in Blender is lost,
including the Python dictionaries. Any posterior references in the
script to previously defined data will generate a NameError. So it's
better to put Blender.Load as the last executed command in the script,
when this function is used to open .blend files.
@warn: if in edit mode, this function leaves it, since Blender itself
requires that.
@note: for all types except .blend files, this function only works in
interactive mode, not in background, following what Blender itself does.
"""
def Save (filename, overwrite = 0):
"""
Save a Blender .blend file with the current program data or export to
one of the builtin file formats.
Supported formats:
- Blender (.blend);
- DXF (.dxf);
- STL (.stl);
- Videoscape (.obj);
- VRML 1.0 (.wrl).
@type filename: string
@param filename: the filename for the file to be written. It must have one
of the supported extensions or an error will be returned.
@type overwrite: int (bool)
@param overwrite: if non-zero, file 'filename' will be overwritten if it
already exists (can be checked with L{Blender.sys.exists<Sys.exists>}.
By default existing files are not overwritten (an error is returned).
@note: The substring ".B.blend" is not accepted inside 'filename'.
@note: DXF, STL and Videoscape export only B{selected} meshes.
"""
def Run (script):
"""
Execute the given script.
@type script: string
@param script: the name of an available Blender Text (use L{Text.Get}() to
get a complete list) or the full pathname to a Python script file in the
system.
@note: the script is executed in its own context -- with its own global
dictionary -- as if it had been executed from the Text Editor or chosen
from a menu.
"""
def ShowHelp (script):
"""
Show help for the given script. This is a time-saver ("code-saver") for
scripts that need to feature a 'help' button in their GUIs or a 'help'
submenu option. With proper documentation strings, calling this function is
enough to present a screen with help information plus link and email buttons.
@type script: string
@param script: the filename of a registered Python script.
@note: this function uses L{Run} and the "Scripts Help Browser" script. This
means that it expects proper doc strings in the script to be able to show
help for it (otherwise it offers to load the script source code as text).
The necessary information about doc strings is L{given here<API_related>}.
@note: 'script' doesn't need to be a full path name: "filename.py" is enough.
Note, though, that this function only works for properly registered
scripts (those that appear in menus).
"""
def UpdateMenus ():
"""
Update the menus that list registered scripts. This will scan the default
and user defined (if available) folder(s) for scripts that have registration
data and will make them accessible via menus.
@note: only scripts that save other new scripts in the default or user
defined folders need to call this function.
"""
def UnpackAll (mode):
"""
Unpack all files with specified mode.
@param mode: The Mode for unpacking. Must be one of the modes in
Blender.UnpackModes dictionary.
@type mode: int
"""
def PackAll ():
"""
Pack all files.
"""
def CountPackedFiles():
"""
Returns the number of packed files.
"""
def Quit ():
"""
Exit from Blender immediately.
@warn: the use of this function should obviously be avoided, it is available
because there are some cases where it can be useful, like in automated
tests. For safety, a "quit.blend" file is saved (normal Blender behavior
upon exiting) when this function is called, so the data in Blender isn't
lost.
"""
def SaveUndoState (message):
"""
Sets an undo at the current state.
@param message: Message that appiers in the undo menu
@type message: string
"""
|
