Python Script :
Modifying a Square Mesh ,
Part 1.
Version Française
  Main Index                                      Python Index
Previous Python: Introduction 
Python: Iterative loop (2) Next

Creating a square in Blender does not set any problem : Space Bar, then Mesh and finally Plane . The software automatically inserts the object at the exact location of the cursor.

Just try to imagine for a moment that, thanks to Python, it is possible to be released from the constraint of the cursor and for us to create this square anywhere in space by providing the appropriate co-ordinates. It is, perhaps, a little more complicated than some clicks of the mouse using the traditional method.

In this tutorial you will learn how  :

- to create a Python script file ""
- to import a module,
- to create an object "mesh",
- to access and modify the data corresponding to the nodes of this "mesh".

  To create the Python script file "":
1/  Switch to the text editor: Shift-F11.
2 / Click the button of the datablock browser  (the small square with a white dash "-")
3/ Select  ADD NEW, you now have an active page in which it is possible to add text, this text could be carried out by the combination of ALT-p keys
4/ Modify the file name to be saved later, click the button [ TX:Text ], and replace this text with " "
To import the modules:
5/   The cursor of the text window is red. At its current location, type the following, being sure not to enter any leading spaces : 
import Blender

Do not leave any space after the last letter either. Press the [ Enter ] key. This  line indicates to Python that it must load the Blender module which contains the various modules which, themselves, contain the methods and data fields which make it possible to interact with the objects and the software commands. 

It is necessary to imagine the Blender module like a set of Russian "nested" dolls. At the interior, different modules are locked up which contain methods and properties, which may also be referred to as data fields. The methods make it possible to access and modify the properties. 

6/    On the following line add:
from Blender import NMesh 

this line avoids burdening the text by having to continually type references to the principal module. Without it, you would be required to write repeatedly: " Blender.NMesh.references ". 

To create an object " Mesh "
7/   The NMesh module contains a method, GetRaw(), which we must use to create an object "mesh" in memory. This object is created in a buffer.

Note that this object can contain the copy of another mesh which is already in the scene if one passes the exact name. Example: me=GetRaw('mesh.001') , will place in memory a working copy  of   "mesh.001" which we will be able to access by using the name "me".

  On the third line add:
me = NMesh.GetRaw()

How to access the "mesh" and modify it
8/ "me" is a mesh object. This object contains methods and properties. For the moment the properties are empty. No data exists to work with. Before starting to operate at this level, it is wise to understand how information dealing with the shape of the mesh objects is managed in 3D software . 

At the base level, there are vertices. These vertices,  therefore, are grouped in an ordered unit, a list, a single-dimensional array. Its  starting index is zero, like the arrays in the C language. Thus, there is the vertices [ 0 ], then the vertices[ 1 ] and the vertices[ 2 ], etc. The index of the last vertex is [ the number of vertices - 1 ]. Each vertex, itself, consists of an array , another list ,   with three inputs containing the co-ordinates x, y, and z.
Point1:__verts[0]------>{x[-1.0], y[1.0],  z[0.0 ] }
Point2:__verts[1]------>{x[1.0],  y[1.0],  z[0.0 ] }
Point3:__verts[2]------>{x[-1.0], y[-1.0], z[0.0 ] }
Point4:__verts[3]------>{x[0.0],  y[-1.0], z[0.0 ] }
Point5:__verts[4]------>{x[1.0],  y[-1.0], z[0.0 ] }


Example of a series of vertices 

Geometrically, the faces are made up from the vertices.  Also, they have several properties. Most significantly: the vertices list, a array   which references   addresses of the coordinates of the vertices. In Blender, faces can have 3 or 4 vertices. In other software, the limit of the number of vertices per face can be: 65000, which leaves one to dream.
Example of a series of faces

Let us clarify our objective: create a mesh to form a face. We will not try to assign a color. In the current situation, we have started from scratch. The proper order of steps to perform are as follows : we should initially indicate that the material is not of type sticky and that the mesh does not have colored faces. Then it is necessary for us to build a list of vertices, and finally,  use these vertices to manufacture faces. 
The procedure for the creation of a vertex, which is very indirect, is performed in two phases.
Phase 1 / a vertext object  is created in memory using the method NMesh.Vert() . This method receives as arguments between its parentheses, the parameters which correspond to the 3D coordinates of the vertex. 

Phase 2 / the vertex is added to the vertices list of "me" which is named "verts" by using the standard  Python method for  adding an element to a list : "append()". In Python, the lists are objects which have methods and properties.

We repeat  this operation a sufficient number of times to create, at last, a face:



The creation of the face is almost identical. There is an additional phase because it is necessary to fill the list with vertices of the face before adding it to "me" .

Phase 1 / Creation of a face object "f" in memory with the method "NMesh.Face()"

Phase 2 / Filling of the face with the addresses of the vertices co-ordinates. These addresses are preserved in a list which is simply  called  "v" .
f.v.append(me.verts[0 ])
f.v.append(me.verts[1 ])
f.v.append(me.verts[2 ])
f.v.append(me.verts[3 ])

Phase 3 /   we add "f" to the faces list of "me "

The last step of our mesh creation procedure is to introduce this new object into the objects list of the current  Blender scene by using the method "PutRaw(mesh, [name, renormalise])" from  the NMesh module. The associated parameters are the mesh name, which we worked on, and  the "name" which it should have in the Blender object list. The last parameter forces Blender to recompute the normal vector on each node. 
NMesh.PutRaw(me, " plane", 1)

Finally, we ask Blender to update  the screen by redrawing it with the new object.

The magic combo: ALT-p and voila, miracle of miracles, a square has just emerged on  the screen!!
Another combo: ALT-s and the save file window appears. It is now possible to give a name to the text file by replacing the "current_file_name.blend"which was automatically displayed, with ""

See the complete

Before jumping to the explanation of the "" file,   I would suggest  that you manufacture some "potatoides"  by playing with the circular functions and the equation of the sphere. Which therefore follow, after a little more theory!!

previous Python: Introduction 
  Python: Iterative loop (2) next
 Top of Page


It is not necessary to indicate to Python what the type of variable is. Whereas, this would be a serious error in other languages. This small detail  reminds one of the good old days of gwbasic.

Blender associates other parameters with the vertices like the "normal" vector ,   UV coordinates for texture mapping  and the value of the index which is very practical with the Hash function in editing meshes.

Other properties of the face object:
  - the color value, which is coded in a array with 4 entries: Red, Green, Blue, and Alpha.
   - a array of indices, which references the materials which are used on this face. In Blender, the value which is located here  is sent to another material array, which is the one used by the mesh object. This is a small technicality with regards to materials management, upon which we shall not dwell.

To access a particular element of a list you need to give its number between brackets just after the name.
Example: list_name=[n1,n2,n3,n4] , to assign  the value of the third element to another variable you neeed to write: name_variable=list_name[2], the contents of name_variable will be n3 . Don't forget, the first element in a list is [0].