version 2, 17.11.2012
Tython is the python scripting interface of TLab. It gives an extensive access to the functionality of Tlab and its topology-spline library. This documentation focuses currently only on the most important features. It should be seen as a living document - therefore more can be expected in the near future. Like with TLab, we think that "Release early, release often" is the most effective way of any kind of development. Having said this, if you have any suggestion for the document or a question please write us an email.
But now let's start with the contents of the document:
Before starting to use the tython console it is maybe useful to get an overview on how powerful actual python is.
Here are two general tutorials which may help:
A more specific tutorial for tython can be found here:
About Python it is often said that it comes with loaded batteries. A nice thing is: all this 'power' can now be used in conjuction with TLab. By either using the console or executing scripts.
The console is one of the widgets of TLab and you can simply type commands in it and execute them by pressing 'RETURN'.
help()⏎ . For typing multi-line commands use ⇧⏎ (that is 'SHIFT-RETURN') to enter a new
line. When typing commands you will notice that the console has an autocompletion and gives you a set of possible
methods and variables which can be selected via the ARROW-keys. By default the autocompletion is filtered,
but the advanced user has the possibility to use an unfiltered autocompletion by setting
_autocomplete_full = True.
Like for the case of
_autocomplete_full a leading underscore of a variable or method indicates that it is belonging to
the low-level interface; they are powerful but can break also your models if not used correctly.
The following convenience functions:
help() # gives a small help text ls() # lists the directory content pwd() # prints the current working directory cd(path) # changes the directory, whereas path can be ".."
are available from the console, which wrap some python standard methods from the
scene is the entrance to most of the operations and to the geometric entities. Currently only the
scene.objects and the
scene.workbench are accessible from tython, but lights, camera and others will follow.
The workbench is the flexibile grid you should always see, at least if you start the program.
The grid can be modified by its public members:
bool active # not used yet bool visible # screen visibility QVector3D center # center of the workbench QVector3D uDir # u-direction uint uInc # increments in u-direction QVector3D vDir # v-direction uint vInc # increments in v-direction
py> scene.workbench.visible = 0 # switches the workbench off py> scene.workbench.visible = 1 # switches the workbench on py> scene.workbench.vInc = 2*scene.workbench.vInc # doubles the reference lines
scene.objects list is holding all geometric objects. The number of objects in the list can be retrieved by
scene.objectCount(). All geometric objects
are derived from
Base3dObject, which defines therefore the basic behaviour. To load a geometric object use:
handle is the geometric object which can be manipulated. For an already loaded object, the
handle can be accessed by using
id of the object by:
Every geometric object in Tlab is derived from the
Base3dObject. Hence every geometric object
has the same basic methods and variables.
The following variables can be directly accessed by every geometric object:
QString name # name of the object int layer # layer, try to avoid it int group # group, not in use bool visible # toggles visibilty of the object bool modelVisible # toggles the visibility of the actual geometry bool meshVisible # toggles the visibility of the control mesh QColor color # color of the object
The following methods can be used by every geometric object:
QString type() # gives the type (e.g. Sphere, T-Spline etc) void move(QVector3D vec) # moves the object in direction vec void move(double x, double y,double z) # moves the object in x,y and z
If you have an handle to your object you can for example change the name, the color and lift it.
py> handle.name = 'myComplexTopology' py> handle.color = QColor(255,0,0) py> handle.move(0,0,10)
The 'B3sphere' object can be manipulated by:
float radius # radius of the sphere QVector3D center # center position of the sphere
To create and manipulate some spheres the following example will help.
py> sun = B3sphere() py> earth = B3sphere() py> moon = B3sphere() py> scene.addObject(sun) py> scene.addObject(earth) py> scene.addObject(moon) py> sun.radius = 5.0 py> sun.color = QColor(255,255,0) py> sun.name = 'Sun' py> earth.radius = 2.0 py> earth.color = QColor(0,0,255) py> earth.name = 'Earth' py> earth.move(10,0,0) py> moon.radius = 0.2 py> moon.color = QColor(100,100,100) py> moon.name = 'Moon' py> moon.move(12,2,0)
The B3Tspline is the most complex object inside of TLab. It can be manipulated by the following methods:
bool valid() # checks if there's currently a TLIB::TSpline loaded and if it is ok int degree() # returns TLIB::TSpline's degree bool extraordinary() # returns true for T-NURCCs false otherwise int vertexCount() # returns number of vertices int edgeCount() # returns number of edges int faceCount() # returns number of faces int controlPointCount() # returns number of control points QString getObjectInfo() # returns object info string QString getFaceInfo(int fId) # returns face info string QString getEdgeInfo(int eId) # returns edge info string QString getVertexInfo(int vId) # returns vertex info string bool hasControlPoint(int id) QVector3D controlPoint(int id) # returns coordinates of control point of vertex/face with id "id" bool setControlPoint(int id, const QVector3D& vec) # set coordinates of control point of vertex/face with id "id" float controlPointWeight(int id) # returns weight of control point of vertex/face with id "id" bool setControlPointWeight(int id, float weight) # set weight of control point of vertex/face with id "id" bool isBoundaryEdge(int eId) # returns true if edge with id "eId" is a boundary edge bool writeSTL(QString filename) # writes a stl-file to disk bool writeTOPEN(QString filename) # writes a topen-file to disk int _addVertex(int id = -1) # add a new vertex with id "id" bool _removeVertex(int id) # remove the vertex with id "id" bool _addControlPoint(int id, const QVector3D& cp, float weight = 1.) # add a control point to vertex/face with id "id" bool _removeControlPoint(int id) # remove the control point of vertex/face with id "id" int _addEdge(int vId1, int vId2, float len = 1., int id = -1) # add an edge between vertices "vId1" and "vId2" with id "id" bool _removeEdge(int id) # remove edge with id "id" int _addFace(const QList<int>& vIds, const QList<int>& cornerVIds, int id = -1) # add a face with vertices "vIds" bool _removeFace(int id) # remove the face with id "id" bool _extraordinarySubdivide() # perform one global subdivision step bool _removeTjunctions() # try to remove all t-junctions, not always possible in T-NURCCs bool _appendOtherTSpline(const B3Tspline* other) # add the vertices/edges/faces/control-points of another T-spline
Important to remember is that all method starting with an underscore (like
_addVertex()) can destroy the T-Spline and they
should only be used with care.
A simple example how to create one valid face.
py> o = B3Tspline() py> scene.addObject(o) py> o._addVertex() py> o._addControlPoint(0,QVector3D(0.5,0.5,0.5)) py> o._addVertex() py> o._addControlPoint(1,QVector3D(1.5,0.5,0.5)) py> o._addVertex() py> o._addControlPoint(2,QVector3D(1.5,1.5,0.5)) py> o._addVertex() py> o._addControlPoint(3,QVector3D(0.5,1.5,0.5)) py> o._addEdge(0,1) py> o._addEdge(1,2) py> o._addEdge(2,3) py> o._addEdge(3,0) py> o._addFace([0,1,2,3],[0,1,2,3])
This first version of the of the tython documentation. As already mentioned it is a living document, the newest version
you can always find on the website or by simply using
DocTython() from the console.