BLENDER PYTHON FOR AN IMPORTER/EXPORTER WRITER
This document is meant for Blender importer/exporter writers.
It explains all you need to know: how to create a mesh, add it to an object, add vertices, faces, vertex colors, UVs, normals, create and assign materials and textures to vertex groups, create bones, assign bones to vertices and add bone weights.
Blender is a powerful 3d modeller. Blender is a great choice if you want to write an importer/exporter as anyone can use your script because the program is completely free, unlike very expensive tools like Max and Maya. In fact users of these expensive tools shouldn't complain, because they can just reexport the data from Blender to a format their own program understands, something which Blender users can't do with Max/Maya scripts without paying. And doing that will require only basic understanding of the Blender GUI.
However Blender scripts are comparably more difficult to write than Max/Maya scripts, especially if you have no experience in programming. The main reason is Blender uses an actual general-purpose programming language called “Python”. What “general-purpose” means is that the language can be used to write any kind of program, from web applications to video games, unlike MaxScript and MEL, which are only used by and inside these 3d modellers. The good news is Python is a very simple language compared to other general-purpose programming languages like C++.
Frankly we don't even need to understand most of Python and most of Blender's Python library to be able to write an importer/exporter.
Firstly, you'll need to learn some Python. Make sure you understand “variables”, “functions”, “lists/tuples”, “dictionaries” and have at least some idea of “classes”.
This is a good tutorial:
http://www.swaroopch.com/notes/Python
Next all is left to do is to learn the needed functions and classes of Blender's Python library (“library” means collection of modules).
A full list is available here:
B2.4:
http://www.blender.org/documentation/249PythonDoc/
B2.5+:
http://www.blender.org/documentation/bl ... pi_2_61_2/
These are full lists of classes and functions you can use. You don't need to be a programmer to use a computer, the same way you don't need to know more than 5% of these to create an importer/exporter.
As you noticed there are two links, one for Blender 2.4, one for Blender 2.5 and above. The reason is everything was rewritten in Blender 2.5, including the Python library. 2.4 is quickly becoming deprecated, so you should go with Blender 2.5. This tutorial will list the commands for both of them, though.
Also note that Blender 2.4 uses Python 2, Blender 2.5 and above use Python 3. These languages are almost the same, but do some things differently. The main differences are:
“print” statement doesn't exist in Python 3, only print() function
“xrange()” doesn't exist in Python 3, “range()” does the same
strings are handled differently
For both you will need to import and use the module “struct”. “struct” is a module for converting data read from file to the needed type, like integer, short, long or float.
So let's begin. We will start with explaining the functions and classes of Blender 2.5+ which we need, then we will explain the equivalent Blender 2.4 functions and classes in a separate section.
Blender 2.5+
Creating vertices, edges, faces.
The usual way to create vertices, edges and faces is creating lists of vertex positions, list of edge indexes and list of face indexes and passing them as arguments to the function mesh.from_pydata() . Note that you can pass empty lists for edges and faces if you want.
As you see, from_pydata() is a method (method - function belonging to class) of the Mesh class. So you'll need to make a Mesh object (object - instance of Mesh class first). If these terms (“ method”. “class”, “object”, “instance”) confuse you, then you should probably learn some more on classes in Python.
Example:
vertices = [[x, y, z], [x, y, z], [x,y,z], [x,y,z]] # replace “x,y,z” with actual numbers
faces = [[0,1,2], [3,4,5], [6,7,8], [9,10,11]]
mesh = bpy.data.meshes.new('name')
mesh.from_pydata(vertices, [], faces) # [] is in place of edges, is an empty list
The first two lines create Python lists. vertices list contains sublists with 3 numbers, which will be used as x,y,z positions for the vertices. faces list is a collection of indexes, which tells how the vertices in the first list will connect and create triangles.
The 3rd line creates a Mesh and third adds vertices and faces to the Mesh from the data we have in our lists.
Like anything else in Blender (like Lights, Curves and Armatures), Meshes need to be assigned to “Objects”. Objects are like nodes. Everything in the 3d scene of Blender are Objects. However the Objects can contain different things, one can contain a Mesh, the other a Light. This allows everything in the 3d scene to the treated the same way, like a Light can be moved around the same way as a Mesh.
So to actually see your Mesh you'll need to create a new Object, assign the Mesh to it and add (“link”) the Object to the scene:
mesh = bpy.data.meshes.new('name') # again
object = bpy.data.objects.new('name', mesh)
bpy.context.scene.objects.link(object) # link object to scene
And you should be able to see your Mesh, unless you used some odd values for your vertices and faces lists (even then you should at least see a dot which is the pivot of the Object.
Vertex colors
To assign vertex colors, you will need to create a “VertexColor layer” for you mesh, then loop through your faces and add the colors to all vertices of each face, like this:
mesh.vertex_colors.new(name = 'VertexColor')
index = 0
for face in mesh.vertex_colors[0].data:
face.color1 = colors[index]
face.color2 = colors[index + 1]
face.color3 = colors[index + 2]
index += 3
Where colors is a list of sublists containing RGB colors, like so:
colors = [[R,B,G],[R,G,B],[R,G,B]]
Note that colors in Blender are float numbers in the range (0.0, 1.0). if you have an integer in the range (0, 255), just divide your number by 255.
TODO