Tython Documentation

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:


Introduction

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'. For example: 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 os and sys modules.

Scene

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.

Scene Workbench

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

Example

  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

The 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=scene.load('filename')

The handle is the geometric object which can be manipulated. For an already loaded object, the handle can be accessed by using the numerical id of the object by: handle=scene.object()[id].

Base3dObject

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

Example

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)

B3sphere

The 'B3sphere' object can be manipulated by:

  float     radius # radius of the sphere
  QVector3D center # center position of the sphere

Example

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)

B3Tspline

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.

Example

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])

Conclusion

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.

See Also

Möbius tutorial