8326ee72279bba3564c228206bb27e10ae4bc39d
[blender.git] / source / blender / python / api2_2x / doc / API_related.py
1 # This is not a real module, it's simply an introductory text.
2
3 """
4 Blender Python related features
5 ===============================
6
7  L{Back to Main Page<API_intro>}
8
9
10 Introduction:
11 =============
12
13  This page describes special features available to BPython scripts:
14
15    - Command line mode is accessible with the '-P' and '-b' Blender options.
16    - Registration allows scripts to become available from some pre-defined menus
17      in Blender, like Import, Export, Wizards and so on.
18    - Proper documentation data is used by the 'Scripts Help Browser' script to
19      show help information for any registered script.  Your own GUI can use
20      this facility with the L{Blender.ShowHelp} function.
21    - Configuration is for data in your script that can be tweaked according to
22      user taste or needs.  Like documentation, this is another helper
23      functionality -- you don't need to provide a GUI yourself to edit config
24      data.
25
26
27  Command line usage:
28  -------------------
29
30  B{Specifying scripts}:
31
32  The '-P' option followed either by:
33    - a script filename (full pathname if not in the same folder where you run
34      the command);
35    - the name of a Text in a .blend file (that must also be specified)
36  will open Blender and immediately run the given script.
37
38  Example::
39
40   # open Blender and execute the given script:
41   blender -P script.py
42
43  B{Passing parameters}:
44
45  To pass parameters to the script you can:
46         - write them to a file before running Blender, then make your script parse that file;
47         - set environment variables and access them with the 'os' module:
48
49  Examples with parameters being passed to the script via command line::
50
51   # execute a command like:
52
53   myvar=value blender -P script.py
54
55   # and in script.py access myvar with os.getenv
56   # (os.environ and os.setenv are also useful):
57
58   # script.py:
59   import os
60   val = os.getenv('myvar')
61
62   # To pass multiple parameters, simply write them in sequence,
63   # separated by spaces:
64
65   myvar1=value1 myvar2=value2 mystr="some string data" blender -P script.py
66
67  B{Background mode}:
68
69  In '-b' mode no windows will be opened: the program will run as a command
70  line tool able to render stills and animations and execute any working Python
71  script with complete access to loaded .blend's file contents.  Once the task
72  is completed, the program will exit.
73
74  Background mode examples::
75
76   # Open Blender in background mode with file 'myfile.blend'
77   # and run the script 'script.py':
78
79   blender -b myfile.blend -P script.py
80
81   # Note: a .blend file is always required.  'script.py' can be a file
82   # in the file system or a Blender Text stored in 'myfile.blend'.
83
84   # Let's assume 'script.py' has code to render the current frame;
85   # this line will set the [s]tart and [e]nd (and so the current) frame to
86   # frame 44 and call the script:
87
88   blender -b myfile.blend -s 44 -e 44 -P script.py
89
90   # Using now a script written to render animations, we set different
91   # start and end frames and then execute this line:
92
93   blender -b myfile.blend -s 1 -e 10 -P script.py
94
95   # Note: we can also set frames and define if we want a single image or
96   # an animation in the script body itself, naturally.
97
98  The rendered pictures will be written to the default render folder, that can
99  also be set via bpython (take a look at L{Render.RenderData}).  Their
100  names will be the equivalent frame number followed by the extension of the
101  chosen image type: 0001.png, for example.  To rename them to something else,
102  coders can use the C{rename} function in the standard 'os' Python module.
103
104  Reminder: if you just need to render, it's not necessary to have a script.
105  Blender can create stills and animations with its own command line arguments.
106  Example:
107   - a single image at frame 44: blender -b myfile.blend -f 44
108   - an animation from frame 1 to 10: blender -b myfile.blend -s 1 -e 10 -a
109
110
111  Registering scripts:
112  --------------------
113
114  To be registered a script needs two things:
115    - to be either in the default scripts dir or in the user defined scripts
116      path (see User Preferences window -> File Paths tab -> Python path);
117    - to have a proper header.
118
119  Try 'blender -d' to know where your default dir for scripts is, it will
120  inform either the dir or the file with that info already parsed, which is
121  in the same dir of the scripts folder.
122
123  The header should be like this one (all double and single apostrophes below
124  are required)::
125   #!BPY
126
127   # \"\"\"
128   # Name: 'Script Name'
129   # Blender: 233
130   # Group: 'Export'
131   # Submenu: 'All' all
132   # Submenu: 'Selected' sel
133   # Submenu: 'Configure (gui)' gui
134   # Tooltip: 'Export to some format.'
135   # \"\"\"
136
137  where:
138   - B{Name} is the string that will appear in the menu;
139   - B{Blender} is the minimum program version required to run the script;
140   - B{Group} defines where the script will be put, see all groups in the
141     Scripts Window's header, menu "Scripts";
142   - B{Submenu} adds optional submenus for further control;
143   - B{Tooltip} is the (short) tooltip string for the menu entry.
144
145  note:
146   - all double and single apostrophes above are required;
147   - you can "comment out" the header above, by starting lines with
148     '#', like we did.  This is not required (except for the first line, #!BPY,
149     of course), but this way the header won't conflict with Python tools that
150     you can use to generate documentation for your script code.  Just
151     remember to keep this header above any other line with triple
152     double-quotes (\"\"\") in your script.
153
154  Submenu lines are not required, use them if you want to provide extra
155  options.  To see which submenu the user chose, check the "__script__"
156  dictionary in your code: __script__['arg'] has the defined keyword (the word
157  after the submenu string name: all, sel or gui in the example above) of the
158  chosen submenu.  For example, if the user clicked on submenu 'Selected' above,
159  __script__['arg'] will be "sel".
160
161  If your script requires extra data or configuration files, there is a special
162  folder where they can be saved: see 'datadir' in L{Blender.Get}.
163
164
165  Documenting scripts:
166  --------------------
167
168  The "Scripts Help Browser" script in the Help menu can parse special variables
169  from registered scripts and display help information for users.  For that,
170  authors only need to add proper information to their scripts, after the
171  registration header.
172
173  The expected variables:
174
175   - __bpydoc__ (or __doc__) (type: string):
176     - The main help text.  Write a first short paragraph explaining what the
177       script does, then add the rest of the help text, leaving a blank line
178       between each new paragraph.  To force line breaks you can use <br> tags.
179
180   - __author__ (type: string or list of strings):
181     - Author name(s).
182
183   - __version__ (type: string):
184     - Script version.  A good recommendation is using a version number followed
185       by the date in the format YYYY/MM/DD: "1.0 2005/12/31".
186
187   - __url__ (type: string or list of strings):
188     - Internet links that are shown as buttons in the help screen.  Clicking
189       them opens the user's default browser at the specified location.  The
190       expected format for each url entry is e.g.
191       "Author's site, http://www.somewhere.com".  The first part, before the
192       comma (','), is used as the button's tooltip.  There are two preset
193       options: "blender" and "elysiun", which link to the Python forums at
194       blender.org and elysiun.com, respectively.
195
196   - __email__ (optional, type: string or list of strings):
197     - Equivalent to __url__, but opens the user's default email client.  You
198       can write the email as someone:somewhere*com and the help script will
199       substitute accordingly: someone@somewhere.com.  This is only a minor help
200       to hide emails from spammers, since your script may be available at some
201       site.  "scripts" is the available preset, with the email address of the
202       mailing list devoted to scripting in Blender, bf-scripts-dev@blender.org.
203       You should only use this one if you are subscribed to the list:
204       http://projects.blender.org/mailman/listinfo/bf-scripts-dev for more
205       information.
206
207  Example::
208    __author__ = 'Mr. Author'
209    __version__ = '1.0 2005/01/01'
210    __url__ = ["Author's site, http://somewhere.com",
211        "Support forum, http://somewhere.com/forum/", "blender", "elysiun"]
212    __email__ = ["Mr. Author, mrauthor:somewhere*com", "scripts"]
213    __bpydoc__ = \"\"\"\\
214    This script does this and that.
215
216    Explaining better, this script helps you create ...
217
218    You can write as many paragraphs as needed.
219
220    Shortcuts:<br>
221      Esc or Q: quit.<br>
222      etc.
223
224    Supported:<br>
225      Meshes, metaballs.
226
227    Known issues:<br>
228      This is just an example, there's no actual script.
229
230    Notes:<br>
231      You can check scripts bundled with Blender to see more examples of how to
232     add documentation to your own works.
233  \"\"\"
234
235  B{Note}: your own GUI or menu code can display documentation by calling the
236  help browser with the L{Blender.ShowHelp} function.
237
238  Configuring scripts:
239  --------------------
240
241  The L{Blender.Registry<Registry>} module provides a simplified way to keep
242  scripts configuration options in memory and also saved in config files.
243  And with the "Scripts Config Editor" script in the System menu users can later 
244  view and edit the options easily.
245
246  Let's first clarify what we mean by config options: they are simple data
247  (bools, ints, floats, strings) used by programs to conform to user
248  preferences.  The buttons in Blender's User Preferences window are a good
249  example.
250
251  For example, a particular exporter might include:
252    - SEPARATE_MATS = False: a bool variable (True / False) to determine if it
253      should write materials to a separate file;
254    - VERSION = 2: an int to define an specific version of the export format;
255    - TEX_DIR = "/path/to/textures": a default texture dir to prepend to all
256      exported texture filenames instead of their actual paths.
257
258  The script needs to provide users a GUI to configure these options -- or else
259  directly editing the source code would be the only way to change them.  And to
260  store changes made to the GUI so they can be reloaded any time the script is
261  executed, programmers have to write and load their own config files (ideally at
262  L{Blender.Get}('udatadir') or, if not available, L{Blender.Get}('datadir')).
263
264  This section describes BPython facilities (based on the L{Registry} module and
265  the config editor) that can take care of this in a simplified (and much
266  recommended) way.
267
268  Here's how it works::
269
270   # sample_exporter.py
271   import Blender
272   from Blender import Registry
273
274   # First define all config variables with their default values:
275   SEPARATE_MATERIALS = True
276   VERSION = True
277   TEX_DIR = ''
278   EXPORT_DIR = ''
279
280   # Then define a function to update the Registry:
281   def registry_update():
282     # populate a dict with current config values:
283     d = {
284       'SEPARATE_MATERIALS': SEPARATE_MATERIALS,
285       'VERSION': VERSION,
286       'TEX_DIR': TEX_DIR,
287       'EXPORT_DIR': EXPORT_DIR
288     }
289     # store the key (optional 3rd arg tells if
290     # the data should also be written to a file):
291     Registry.SetKey('sample_exporter', d, True)
292
293   # (A good convention is to use the script name as Registry key)
294
295   # Now we check if our key is available in the Registry or file system:
296   regdict = Registry.GetKey('sample_exporter', True)
297
298   # If this key already exists, update config variables with its values:
299   if regdict:
300     try:
301       SEPARATE_MATERIALS = regdict['SEPARATE_MATERIALS']
302       VERSION = regdict['VERSION']
303       TEX_DIR = regdict['TEX_DIR']
304       EXPORT_DIR = regdict['EXPORT_DIR']
305
306     # if data was corrupted (or a new version of the script changed
307     # (expanded, removed, renamed) the config vars and users may have
308     # the old config file around):
309     except: update_registry() # rewrite it
310
311   else: # if the key doesn't exist yet, use our function to create it:
312     update_registry()
313
314   # ...
315
316  Hint: nicer code than the simplistic example above can be written by keeping
317  config var names in a list of strings and using the exec function. 
318
319  B{Note}: if your script's GUI lets users change config vars, call the
320  registry_update() function in the button events callback to save the changes.
321  On the other hand, you don't need to handle configuration
322  in your own gui, it can be left for the 'Scripts Config Editor',
323  which should have access to your script's config key as soon as the
324  above code is executed once (as soon as SetKey is executed).
325
326  B{Note} (limits for config vars): strings longer than 300 characters are
327  clamped and the number of items in dictionaries, sequences and the config key
328  itself is limited to 60.
329
330
331  B{Scripts Configuration Editor}:
332
333  This script should be available from the System menu in the Scripts window.
334  It provides a GUI to view and edit saved configuration data, both from the
335  Registry dictionary in memory and the scripts config data dir.  This is
336  useful for all scripts with config vars, but specially for those without GUI's,
337  like most importers and exporters, since this editor will provide one for them.
338
339  The example above already gives a good idea of how the information can be
340  prepared to be accessible from this editor, but there is more worth knowing:
341
342   1. String vars that end with '_dir' or '_file' (can be upper case, too) are
343   recognized as input boxes for dirs or files and a 'browse' button is added to
344   their right side, to call the file selector.
345
346   2. Both key names and configuration variables names starting with an
347   underscore ('_') are ignored by the editor.  Programmers can use this feature
348   for any key or config var that is not meant to be configured by this editor.
349
350   3. The following information refers to extra config variables that may be
351   added specifically to aid the configuration editor script.  To clarify, in the
352   example code above these variables (the string 'script' and the dictionaries
353   'tooltips' and 'limits') would appear along with SEPARATE_MATERIALS, VERSION,
354   TEX_DIR and EXPORT_DIR, wherever they are written.
355
356   Minor note: these names are case insensitive: tooltips, TOOLTIPS, etc. are all
357   recognized.
358
359   3.1 The config editor will try to display a 'help' button for a key, to show
360   documentation for the script that owns it. To find this "owner script", it
361   will first look for a config variable called 'script', a string containing
362   the name of the owner Python file (with or without '.py' extension)::
363
364    script = 'sample_exporter.py'
365
366   If there is no such variable, the editor will check if the file formed by the
367   key name and the '.py' extension exists. If both alternatives fail, no help
368   button will be displayed.
369
370   3.2 You can define tooltips for the buttons that the editor creates for your
371   config data (string input, toggle, number sliders).  Simply create a dict
372   called 'tooltips', where config var names are keys and their tooltips,
373   values::
374
375    tooltips = {
376      'EXPORT_DIR': 'default folder where exported files should be saved',
377      'VERBOSE': 'print info and warning messages to the console',
378      'SEPARATE_MATERIALS': 'write materials to their own file'
379    }
380
381   3.3 Int and float button sliders need min and max limits.  This can be passed
382   to the editor via a dict called 'limits' (ivar1, ivar2 and fvar are meant as
383   extra config vars that might have been in the example code above)::
384
385    limits = {'ivar1': [-10, 10], 'ivar2': [0, 100], 'fvar1': [-12.3, 15.4]}
386
387   4. The Config Editor itself maintains a Registry key called "General", with
388   general options relevant to many scripts, like "verbose" to tell if the user
389   wants messages printed to the console and "confirm overwrite", to know if
390   a script should ask for confirmation before overwriting files (all exporters
391   are recommended to access the General key and check this var -- L{sys.exists
392   <Sys.exists>} tells if files or folders already exist).
393
394  Hint: for actual examples, try the ac3d importer and exporter (it's enough to
395  call them from the menus then cancel with ESC), as those have been updated to
396  use this config system.  After calling them their config data will be available
397  in the Config Editor.  We also recommend adding a section about config vars
398  in your script's help info, as done in the ac3d ones.
399
400  L{Back to Main Page<API_intro>}
401 """