API_intro (original) (raw)

Module API_intro

The Blender Python API Reference

An asterisk (*) means the module has been updated.

for a full list of changes since 2.42 see http://mediawiki.blender.org/index.php/Release_Notes/Notes243/Python_API

Top Module:

• Blender
• bpy (experimental)

Submodules:

• Armature (*)
  • NLA
  • Action
• BezTriple (*)
• BGL
• Camera (*)
• Curve (*)
• Draw (*)
• Effect
• Geometry (*)
• Group (*)
• Image (*)
• Ipo (*)
  • IpoCurve (*)
• Key (*)
• Lamp
• Lattice (*)
• Library (*)
• Material (*)
• Mathutils (*)
• Mesh (*)
  • MeshPrimitives (*)
• Metaball (*)
• NMesh (deprecated)
• Noise
• Object (*)
  • Modifier (*)
  • Pose (*)
  • Constraint (*)
  • ActionStrips (*)
• Registry
• Scene (*)
  • Radio
  • Render (*)
• Sound (*)
• Text
• Text3d
  • Font
• Texture (*)
• TimeLine
• Types
• Window
  • Theme (*)
• World
• sys

Additional information:

• Special features:
• scripts: registering in menus, documenting, configuring (new);
• command line examples (new);
• script links (*), space handler script links, Group module (new).

Introduction:

This reference documents the Blender Python API, a growing collection of Python modules (libraries) that give access to part of the program's internal data and functions.

Through scripting Blender can be extended in real-time via Python, an impressive high level, multi-paradigm, open source language. Newcomers are recommended to start with the tutorial that comes with it.

This opens many interesting possibilities, ranging from automating repetitive tasks to adding new functionality to the program: procedural models, importers and exporters, even complex applications and so on. Blender itself comes with some scripts, but many others can be found in the Scripts & Plugins sections and forum posts at the Blender-related sites listed below.

Scripting and Blender:

These are the basic ways to execute scripts in Blender:

1. They can be loaded or typed as text files in the Text Editor window, then executed with ALT+P.
2. Via command line: blender -P <scriptname> will start Blender and execute the given script. can be a filename in the user's file system or the name of a text saved in a .blend Blender file: 'blender myfile.blend -P textname'.
3. Via command line in background mode: use the '-b' flag (the order is important): blender -b <blendfile> -P <scriptname>. can be any .blend file, including the default .B.blend that is in Blender's home directory Blender.Get('homedir'). In this mode no window will be opened and the program will leave as soon as the script finishes execution.
4. Properly registered scripts can be selected directly from the program's menus.
5. Scriptlinks: these are also loaded or typed in the Text Editor window and can be linked to objects, materials or scenes using the Scriptlink buttons tab. Script links get executed automatically when their events (ONLOAD, REDRAW, FRAMECHANGED) are triggered. Normal scripts can create (Text) and link other scripts to objects and events, see Object.Object.addScriptLink, for example.
6. A script can call another script (that will run in its own context, with its own global dictionary) with the Blender.Run module function.

Interaction with users:

Scripts can:

• simply run and exit;
• pop messages, menus and small number and text input boxes;
• draw graphical user interfaces (GUIs) with OpenGL calls and native program buttons, which stay there accepting user input like any other Blender window until the user closes them;
• attach themselves to a space's event or drawing code (aka space handlers, check here);
• make changes to the 3D View (set visible layer(s), view point, etc);
• grab the main input event queue and process (or pass to Blender) selected keyboard, mouse, redraw events -- not considered good practice, but still available for private use;
• tell Blender to execute other scripts (see Blender.Run());
• use external Python libraries, if available. You can read the documentation for the Window, Draw and BGL modules for more information and also check the Python site for external modules that might be useful to you. Note though that any imported module will become a requirement of your script, since Blender itself does not bundle external modules.

Command line mode:

Python was embedded in Blender, so to access BPython modules you need to run scripts from the program itself: you can't import the Blender module into an external Python interpreter.

On the other hand, for many tasks it's possible to control Blender via some automated process using scripts. Interested readers should learn about features like "OnLoad" script links, the "-b " (background mode) and "-P