Operations on triangulated surfaces.
A triangulated surface is a surface consisting solely of triangles. Any surface in space, no matter how complex, can be approximated with a triangulated surface.
A class for handling triangulated 3D surfaces.
Create a new surface.
The surface contains ntri triangles, each having 3 vertices with 3 coordinates. The surface can be initialized from one of the following:
Internally, the surface is stored in a (coords,edges,faces) tuple.
TriSurface objects have the following methods:
Make the internal information consistent and complete.
This function should be called after one of the data fields have been changed.
Remove all nodes which are not used.
Normally, the surface definition can hold nodes that are not used in the edge/facet tables. They do however influence the bounding box of the surface. This method will remove all the unconnected nodes.
Merge another surface with self.
This just merges the data sets, and does not check whether the surfaces intersect or are connected! This is intended mostly for use inside higher level functions.
Return a (deep) copy of the surface.
If an index is given, only the specified faces are retained.
Return a TriSurface which holds only elements with numbers in ids.
idx can be a single element number or a list of numbers or any other index mechanism accepted by numpy’s ndarray By default, the vertex list will be compressed to hold only those used in the selected elements. Setting compress==False will keep all original nodes in the surface.
Create or delete the property array for the TriSurface.
A property array is a rank-1 integer array with dimension equal to the number of elements in the TriSurface. You can specify a single value or a list/array of integer values. If the number of passed values is less than the number of elements, they wil be repeated. If you give more, they will be ignored.
If a value None is given, the properties are removed from the TriSurface.
Return the centroids of all elements of the Formex.
The centroid of an element is the point whose coordinates are the mean values of all points of the element. The return value is an (nfaces,3) shaped Coords array.
Flag elements having nodal coordinates between min and max.
This function is very convenient in clipping a TriSurface in a specified direction. It returns a 1D integer array flagging (with a value 1 or True) the elements having nodal coordinates in the required range. Use where(result) to get a list of element numbers passing the test. Or directly use clip() or cclip() to create the clipped TriSurface
The test plane can be defined in two ways, depending on the value of dir. If dir == 0, 1 or 2, it specifies a global axis and min and max are the minimum and maximum values for the coordinates along that axis. Default is the 0 (or x) direction.
Else, dir should be compaitble with a (3,) shaped array and specifies the direction of the normal on the planes. In this case, min and max are points and should also evaluate to (3,) shaped arrays.
nodes specifies which nodes are taken into account in the comparisons. It should be one of the following:
The default (‘all’) will flag all the elements that have all their nodes between the planes x=min and x=max, i.e. the elements that fall completely between these planes. One of the two clipping planes may be left unspecified.
Return a TriSurface with all the elements where t>0.
t should be a 1-D integer array with length equal to the number of elements of the TriSurface. The resulting TriSurface will contain all elements where t > 0.
Compute the normal vectors in each point of a collection of triangles.
The normal vector in a point is the average of the normal vectors of the neighbouring triangles. The normal vectors are normalized.
Offset a surface with a certain distance.
All the nodes of the surface are translated over a specified distance along their normal vector. This creates a new congruent surface.
Read a surface from file.
If no file type is specified, it is derived from the filename extension. Currently supported file types:
Write the surface to file.
If no filetype is given, it is deduced from the filename extension. If the filename has no extension, the ‘gts’ file type is used.
Return a copy scaled with scale[i] in direction i.
The scale should be a list of 3 scaling factors for the 3 axis directions, or a single scaling factor. In the latter case, dir (a single axis number or a list) may be given to specify the direction(s) to scale. The default is to produce a homothetic scaling.
Translate a Coords object.
The translation vector can be specified in one of the following ways:
If an axis number is given, a unit vector in the direction of the specified axis will be used. If an array of translation vectors is given, it should be broadcastable to the size of the Coords array. If a distance value is given, the translation vector is multiplied with this value before it is added to the coordinates.
Thus, the following lines are all equivalent:
F.translate(1)
F.translate(1,1)
F.translate([0,1,0])
F.translate([0,2,0],0.5)
Return a copy rotated over angle around axis.
The angle is specified in degrees. The axis is either one of (0,1,2) designating the global axes, or a vector specifying an axis through the origin. If no axis is specified, rotation is around the 2(z)-axis. This is convenient for working on 2D-structures.
As a convenience, the user may also specify a 3x3 rotation matrix, in which case the function rotate(mat) is equivalent to affine(mat).
All rotations are performed around the point [0,0,0], unless a rotation origin is specified in the argument ‘around’.
Return a copy skewed in the direction dir of plane (dir,dir1).
The coordinate dir is replaced with (dir + skew * dir1).
Reflect the coordinates in direction dir against plane at pos.
Default position of the plane is through the origin. Default mirror direction is the z-direction.
Returns a general affine transform of the Coords object.
mat: a 3x3 float matrix
vec: a length 3 list or array of floats
The returned object has coordinates given by self * mat + vec.
Compute the area and normal vectors of the surface triangles.
The normal vectors are normalized. The area is always positive.
The values are returned and saved in the object.
Return the enclosed volume of the surface.
This will only be correct if the surface is a closed manifold.
Return the curvature parameters at the nodes.
The n-ring neighbourhood of the nodes is used (n=neighbours). Eight values are returned: the Gaussian and mean curvature, the shape index, the curvedness, the principal curvatures and the principal directions.
Detect the border elements of TriSurface.
The border elements are the edges having less than 2 connected elements. Returns True where edge is on the border.
Detect the border nodes of TriSurface.
The border nodes are the vertices belonging to the border edges. Returns a list of vertex numbers.
If the surface has a single closed border, fill it.
Filling the border is done by adding a single point inside the border and connectin it with all border segments. This works well if the border is smooth and nearly planar.
Return the cos of the angles over all edges.
The surface should be a manifold (max. 2 elements per edge). Edges with only one element get angles = 1.0.
Generator function returning the frontal elements.
startat is an element number or list of numbers of the starting front. On first call, this function returns the starting front. Each next() call returns the next front. front_increment determines haw the property increases at each frontal step. There is an extra increment +1 at each start of a new part. Thus, the start of a new part can always be detected by a front not having the property of the previous plus front_increment.
Generator function returning the frontal elements.
startat is an element number or list of numbers of the starting front. On first call, this function returns the starting front. Each next() call returns the next front.
Grows a selection of a surface.
p is a single element number or a list of numbers. The return value is a list of element numbers obtained by growing the front nsteps times. The mode argument specifies how a single frontal step is done:
Detects different parts of the surface using a frontal method.
okedges flags the edges where the two adjacent triangles are to be in the same part of the surface. startat is a list of elements that are in the first part. The partitioning is returned as a property type array having a value corresponding to the part number. The lowest property number will be firstprop
Detects different parts of the surface using a frontal method.
okedges flags the edges where the two adjacent triangles are to be in the same part of the surface. startat is a list of elements that are in the first part. The partitioning is returned as a property type array having a value corresponding to the part number. The lowest property number will be firstprop
Functions defined in the module surface
- surface.areaNormals(x)¶
Compute the area and normal vectors of a collection of triangles.
x is an (ntri,3,3) array of coordinates.
Returns a tuple of areas,normals. The normal vectors are normalized. The area is always positive.
- surface.stlConvert(stlname, outname=None, options='-d')¶
Transform an .stl file to .off or .gts format.
If outname is given, it is either ‘.off’ or ‘.gts’ or a filename ending on one of these extensions. If it is only an extension, the stlname will be used with extension changed.
If the outname file exists and its mtime is more recent than the stlname, the outname file is considered uptodate and the conversion programwill not be run.
The conversion program will be choosen depending on the extension. This uses the external commands ‘admesh’ or ‘stl2gts’.
The return value is a tuple of the output file name, the conversion program exit code (0 if succesful) and the stdout of the conversion program (or a ‘file is already uptodate’ message).
- surface.read_gts(fn)¶
Read a GTS surface mesh.
Return a coords,edges,faces tuple.
- surface.read_off(fn)¶
Read an OFF surface mesh.
The mesh should consist of only triangles! Returns a nodes,elems tuple.
- surface.read_stl(fn, intermediate=None)¶
Read a surface from .stl file.
This is done by first coverting the .stl to .gts or .off format. The name of the intermediate file may be specified. If not, it will be generated by changing the extension of fn to ‘.gts’ or ‘.off’ depending on the setting of the ‘surface/stlread’ config setting.
Return a coords,edges,faces or a coords,elems tuple, depending on the intermediate format.
- surface.read_gambit_neutral(fn)¶
Read a triangular surface mesh in Gambit neutral format.
The .neu file nodes are numbered from 1! Returns a nodes,elems tuple.
- surface.write_gts(fn, nodes, edges, faces)¶
- surface.write_stla(f, x)¶
- Export an x[n,3,3] float array as an ascii .stl file.
- surface.write_stlb(f, x)¶
- Export an x[n,3,3] float array as an binary .stl file.
- surface.write_gambit_neutral(fn, nodes, elems)¶
- surface.write_off(fn, nodes, elems)¶
- surface.write_smesh(fn, nodes, elems)¶
- surface.surface_volume(x, pt=None)¶
Return the volume inside a 3-plex Formex.
For each element of Formex, return the volume of the tetrahedron formed by the point pt (default the center of x) and the 3 points of the element.
- surface.curvature(coords, elems, edges, neighbours=1)¶
Calculate curvature parameters
(according to Dong and Wang 2005; Koenderink and Van Doorn 1992). The n-ring neighbourhood of the nodes is used (n=neighbours). Eight values are returned: the Gaussian and mean curvature, the shape index, the curvedness, the principal curvatures and the principal directions.
- surface.surfaceInsideLoop(coords, elems)¶
Create a surface inside a closed curve defined by coords and elems.
coords is a set of coordinates. elems is an (nsegments,2) shaped connectivity array defining a set of line segments forming a closed loop.
The return value is coords,elems tuple where coords has one more point: the center of th original coords elems is (nsegment,3) and defines triangles describing a surface inside the original curve.
- surface.fillHole(coords, elems)¶
Fill a hole surrounded by the border defined by coords and elems.
Coords is a (npoints,3) shaped array of floats. Elems is a (nelems,2) shaped array of integers representing the border element numbers and must be ordered.
- surface.create_border_triangle(coords, elems)¶
Create a triangle within a border.
The triangle is created from the two border elements with the sharpest angle. Coords is a (npoints,3) shaped array of floats. Elems is a (nelems,2) shaped array of integers representing the border element numbers and must be ordered. A list of two objects is returned: the new border elements and the triangle.
- surface.read_error(cnt, line)¶
- Raise an error on reading the stl file.
- surface.degenerate(area, norm)¶
Return a list of the degenerate faces according to area and normals.
A face is degenerate if its surface is less or equal to zero or the normal has a nan.
- surface.read_stla(fn, dtype=Float, large=False, guess=True)¶
Read an ascii .stl file into an [n,3,3] float array.
If the .stl is large, read_ascii_large() is recommended, as it is a lot faster.
- surface.read_ascii_large(fn, dtype=Float)¶
Read an ascii .stl file into an [n,3,3] float array.
This is an alternative for read_ascii, which is a lot faster on large STL models. It requires the ‘awk’ command though, so is probably only useful on Linux/UNIX. It works by first transforming the input file to a .nodes file and then reading it through numpy’s fromfile() function.
- surface.off_to_tet(fn)¶
- Transform an .off model to tetgen (.node/.smesh) format.
- surface.find_row(mat, row, nmatch=None)¶
- Find all rows in matrix matching given row.
- surface.find_nodes(nodes, coords)¶
Find nodes with given coordinates in a node set.
nodes is a (nnodes,3) float array of coordinates. coords is a (npts,3) float array of coordinates.
Returns a (n,) integer array with ALL the node numbers matching EXACTLY ALL the coordinates of ANY of the given points.
- surface.find_first_nodes(nodes, coords)¶
Find nodes with given coordinates in a node set.
nodes is a (nnodes,3) float array of coordinates. coords is a (npts,3) float array of coordinates.
Returns a (n,) integer array with THE FIRST node number matching EXACTLY ALL the coordinates of EACH of the given points.
- surface.find_triangles(elems, triangles)¶
Find triangles with given node numbers in a surface mesh.
elems is a (nelems,3) integer array of triangles. triangles is a (ntri,3) integer array of triangles to find.
Returns a (ntri,) integer array with the triangles numbers.
- surface.remove_triangles(elems, remove)¶
Remove triangles from a surface mesh.
elems is a (nelems,3) integer array of triangles. remove is a (nremove,3) integer array of triangles to remove.
Returns a (nelems-nremove,3) integer array with the triangles of nelems where the triangles of remove have been removed.
- surface.Rectangle(nx, ny)¶
- Create a plane rectangular surface consisting of a nx,ny grid.
- surface.Cube()¶
- Create a surface in the form of a cube
- surface.Sphere(level=4, verbose=False, filename=None)¶
Create a spherical surface by caling the gtssphere command.
If a filename is given, it is stored under that name, else a temporary file is created. Beware: this may take a lot of time if level is 8 or higher.