Monday, November 2, 2009

Blender Python 1: Setup

In addition to everything else, Blender is a programming environment, with Python its language of choice. Even if you don't plan on creating Python scripts in Blender, you should understand the Python environment. Python is how Blender talks to you. The purpose of this tutorial is to introduce you to Blender's Python environment. Understanding this environment should help you understand how Blender works as well. Of course, if you want to write Python scripts to make Blender behave exactly how you want, becoming familiar with the Blender Python environment is the first step. Even if you don't program, just understanding how to run a script will allow you to run Python programs, called scripts, written by others. For starters, go to the Blender Python Scripts Catalog.

Did you ever wonder what the purpose of the first window, and what the message:

Compiled with Python 2.6.2
Checking for installed Python... got it!

means? Does it have anything to do with big, poisonous snakes?

No. That first window is Blender's Python console. That message, which is what you should see as well, means that Blender found a good Python installation on your computer and that it could run Python programs. Blender also reports the Python version it found. You should, in general, go with the latest, most stable release of Python, which you can find at:

Python programs, incidentally, are called scripts and have the same meaning scripts have in the theatre. They're instructions for Blender. Blender uses Python scripts everywhere - to create objects, to move objects around in a scene, to animate objects, to add materials and textures, and so on.

Blender has two windows that were designed for interacting with Python. The Scripts window, the one with the snake icon, was designed to run Python scripts. The scripts are grouped into areas such as Mesh, Object, and UV. To run a script, select it from the menu. One commonly used script is to save the UV Face Layout to a file, for use with an image editor such as The Gimp or Photoshop. When you run the script, a screen with options for the UV image file displays. You can accept the defaults, or change them, and then press OK. The script will then run, asking you where you want to create the face layout file.

Blender has a built in Scripting setup, which works well if you want to create Python scripts in Blender. To access this window, go to the SR:5-Scripting view, which you can select from the dropdown menu. There are three windows: the 3D viewport, on the left; the Buttons Window, with the Scripts area highlighted, at the bottom; and the Text window at the right.

You have probably downloaded blend files with notes in the Text window. That's a great use for the text window. Another is to write Python scripts for Blender. Let's write our first Python script, a message to the Blender console announcing our presence. Type:

print "Ira was here."

in the Text window.

To run a script, you can either press Alt-P, or from the Text Menu, select Run Python Script. Press Alt-P. Seemingly, nothing happened. Blender is strangely silent if things go OK. Actually, the script run. To see the result, go to the Blender console, and the message "Ira was here." displays.

Blender will, however, tell you when you have made a programming error. Let's introduce an error. Text needs to be enclosed on each side by double quotes. Delete the last double quote. Press Alt-P. You get the following message:

Error: Python Script Error
Check console

Now that you have gotten this far, you know where to look. Click on the console window. You get the message:

SyntaxError: EOL while scanning string literal
File "Text" Line 1

and it shows you where it thought the error was. Actually, the error isn't quite where the message is pointing, but you have to give Blender a gold star for trying to be helpful.

Go back to the text window, add the double quote back, press alt-P, and check the console window. Everything is OK again.

Here are some formatting tips. Press the computer window icon. This makes the text window full screen. If your script is large, it's easier to have the window full screen so you won't have to scroll up and down as much. To return to the text window's original size, press the computer window icon (the screen is divided into 4 parts).

The next button displays line numbers along with the code. This can be very handy, especially considering that Blender's error messages give you the line number. Line numbers make it easier for you to get to a particular line.

The next window enables word wrap. Generally you don't want that button enabled when you are writing a script, although it is handy if you are writing notes or free form text in the window.

The "AB" button enables syntax highlighting. This is useful in coding to give you hints as to the proper syntax of a line of code.

The snake button enables Python text plugins. Text plugins can give the Text editor more power. You can find text plugins by going to the Text menu and selecting Text Plugins.

The Screen dropdown lets you change the font size. The code currently displays with a font size of 12. You can change it to 15 by selecting 15. Your choices depend on the fonts installed on your computer.

The Tab: selector lets you change the number of spaces that the editor inserts when you press the Tab key. Python syntax checks based on having the code properly tabbed. Making the indent larger helps the readability of the code as well. You can add a tab by placing the cursor at the beginning of the line and selecting Indent from the Format menu. You can also unindent.

Highlight the line "Ira was here". You can comment it out by selecting Comment from the Format menu. Commenting a line of code means that the code will not execute, i.e., run. To show this, press Alt-P to run the program. The message does not display on the console. You can uncomment by selecting Uncomment from the Format menu. Press Alt-P to run the program again. This time the message displays on the console.

You can create more than one script in a blend file. To do this, click the ADD NEW button. A new, blank text window, titled TEXT.001, displays. Enter a line of code

print "Message from Outer Space"

Press Alt-P and check the console. The message displays.

If you save the blend file (Control-W), all the text windows are saved. You can also save individual text windows by selecting the Save button from the Text window, or pressing Alt-S. Python files should be saved with an extension of .py.

I hope this gives you a good level of comfort with Blender's Python programming environment. I plan to do more tutorials on how to use Python in Blender. There is a lot to cover, much more than can be done in a 10 minute video. Happy Blending!