40. trisurface
— 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.
40.1. Classes defined in module trisurface¶
-
class
trisurface.
TriSurface
(*args, **kargs)[source]¶ A class representing a triangulated 3D surface.
A triangulated surface is a surface consisting of a collection of triangles. The TriSurface is subclassed from
Mesh
with a fixed plexitude 3. The surface contains ntri triangles and nedg edges. Each triangle has 3 vertices with 3 coordinates. The total number of vertices is ncoords. The TriSurface can be initialized from one of the following sets of data:- an (ntri,3,3) shaped array of floats
- a Formex with plexitude 3
- a Mesh with plexitude 3
- an (ncoords,3) float array of vertex coordinates and an (ntri,3) integer array of vertex numbers
- an (ncoords,3) float array of vertex coordinates, an (nedg,2) integer array of vertex numbers, an (ntri,3) integer array of edges numbers.
Additionally, a keyword argument
prop
may be provided to specify property values, as inMesh
.-
append
(S)[source]¶ 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.
-
classmethod
read
(fn, ftype=None)[source]¶ Read a surface from file.
If no file type is specified, it is derived from the filename extension. Currently supported file types:
- .off
- .gts
- .stl (ASCII or BINARY)
- .neu (Gambit Neutral)
- .smesh (Tetgen)
Compressed (gzip or bzip2) files are also supported. Their names should be the normal filename with ‘.gz’ or ‘.bz2’ appended. These files are uncompressed on the fly during the reading and the uncompressed versions are deleted after reading.
The file type can be specified explicitely to handle file names where the extension does not directly specify the file type.
-
write
(fn, ftype=None, *, color=None, name=None)[source]¶ Write the surface to file.
Parameters: - fn (path_like) – The output file name.
- ftype (str) – The output file format.
If not provided, it is determined from the suffix of the output
file name. If
fn
does not have a suffix, ‘off’ format is used. Available formats are: ‘pgf’, ‘gts’, ‘off’, ‘stl’, ‘stla’, ‘stlb’, ‘obj’, ‘smesh’, ‘vtp’, ‘vtk’. For a ‘stl’ types, the ftype may be set to ‘stla’ or ‘stlb’ to force ascii or binary STL format. Most formats accept transparent compression if a filename ending in ‘gz’ or ‘bz2’ is specified. - color – The color to be written in the output file (only used with ‘stlb’ format).
- name (str) – A name for the model to be written into the output file (currently only used with ‘obj’ format).
-
areaNormals
()[source]¶ 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.
-
volume
()[source]¶ Return the enclosed volume of the surface.
This will only be correct if the surface is a closed manifold.
-
volumeInertia
(density=1.0)[source]¶ Return the inertia properties of the enclosed volume of the surface.
The surface should be a closed manifold and is supposed to be the border of a volume of constant density 1.
Returns an
inertia.Inertia
instance with attributes- mass: the total mass (float)
- ctr: the center of mass: float (3,)
- tensor: the inertia tensor in the central axes: shape (3,3)
This will only be correct if the surface is a closed manifold.
See
inertia()
for the inertia of the surface.Example:
>>> from pyformex.simple import sphere >>> S = sphere(8) >>> I = S.volumeInertia() >>> print(I.mass) 4.1526... >>> print(I.ctr) [ 0. 0. 0.] >>> print(I.tensor) [[ 1.65 0. -0. ] [ 0. 1.65 -0. ] [-0. -0. 1.65]]
-
inertia
(volume=False, density=1.0)[source]¶ Return inertia related quantities of the surface.
This computes the inertia properties of the centroids of the triangles, using the triangle area as a weight. The result is therefore different from self.coords.inertia() and usually better suited for the surface, especially if the triangle areas differ a lot.
Returns a tuple with the center of gravity, the principal axes of inertia, the principal moments of inertia and the inertia tensor.
See also
volumeInertia()
.
-
curvature
(neighbours=1)[source]¶ Calculate curvature parameters at the nodes.
Algorithms based on Dong and Wang 2005; Koenderink and Van Doorn 1992. This uses the nodes that are connected to the node via a shortest path of ‘neighbours’ edges. Eight values are returned: the Gaussian and mean curvature, the shape index, the curvedness, the principal curvatures and the principal directions.
-
surfaceType
()[source]¶ Check whether the TriSurface is a manifold, orientable and closed.
Returns: - manifold (bool) – True if the surface is a manifold
- orientable (bool) – True if the surface is an orientable manifold
- closed (bool) – True if the surface is a closed manifold
- mincon (int) – The minimum number of triangles at any edge
- maxcon (int) – The maximum number of triangles at any edge
See also
isManifold()
- check if a surface is a manifold
isOrientable()
- check if a surface is an orientable manifold
isClosedManifold()
- check if a surface is a closed manifold
Notes
A Möbius ring is an open non-orientable manifold. A Klein bottle is a closed non-orientable (self-intersecting) manifold.
-
borderEdges
()[source]¶ 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.
-
borderNodeNrs
()[source]¶ Detect the border nodes of TriSurface.
The border nodes are the vertices belonging to the border edges. Returns a list of vertex numbers.
-
isManifold
()[source]¶ Check whether the TriSurface is a manifold.
A surface is a manifold if for every point of the surface a small sphere exists that cuts the surface to a part that can continuously be deformed to an open disk.
-
isOrientable
()[source]¶ Check whether the TriSurface is an orientable manifold.
A surface is an orientable manifold if it is a manifold and if for all edges where two triangles meet, the triangles have the two nodes in opposite order in their element definition. This also means that if the two triangles are rotated around the edge to fall in the same plane, with their third vertex at opposite sides of the edge, the triangles have the same positive normal.
See also
amborientedEdges()
- list the edges where the normals are opposite
-
nonManifoldEdges
()[source]¶ Return the non-manifold edges.
Non-manifold edges are edges having more than two triangles connected to them.
Returns the indices of the non-manifold edges in a TriSurface.
-
nonManifoldEdgesFaces
()[source]¶ Return the non-manifold edges and faces.
Non-manifold edges are edges that are connected to more than two faces.
Returns: - edges (list of int) – The list of non-manifold edges.
- faces (list of int) – The list of faces connected to any of the non-manifold edges.
-
removeNonManifold
()[source]¶ Remove the non-manifold edges.
Removes the non-manifold edges by iteratively applying
removeDuplicate()
andcollapseEdge()
until no edge has more than two connected triangles.Returns the reduced surface.
-
amborientedEdges
()[source]¶ Return the amboriented edges.
Amboriented edges are edges where two triangles are connected with different orientation, making the surface non-orientable.
Returns: int array – The indices of the amboriented edges in a TriSurface. Notes
This requires that the surface is a manifold. Non-manifold edges are also amboriented, but are not included in this list. An error is raised if there are non-manifold edges.
In a manifold surface there are only two triangles possible at an edge,and they should have the edge nodes numbered in different order for the surface to be orientable. Thus all the edges should come out as unique when permutations=’none’ is used in
arraytools.uniqueRowsIndex()
. The non-unique edges are the amboriented edges.
-
checkBorder
()[source]¶ Return the border of TriSurface.
Returns a list of connectivity tables. Each table holds the subsequent line segments of one continuous contour of the border of the surface.
-
border
(compact=True)[source]¶ Return the border(s) of TriSurface.
The complete border of the surface is returned as a list of plex-2 Meshes. Each Mesh constitutes a continuous part of the border. By default, the Meshes are compacted. Setting compact=False will return all Meshes with the full surface coordinate sets. This is usefull for filling the border and adding to the surface.
-
fillBorder
(method='radial', dir=None, compact=True)[source]¶ Fill the border areas of a surface to make it closed.
Returns a list of surfaces, each of which fills a singly connected part of the border of the input surface. Adding these surfaces to the original will create a closed surface. The surfaces will have property values set above those used in the parent surface. If the surface is already closed, an empty list is returned.
There are three methods: ‘radial’, ‘planar’ and ‘border’, corresponding to the methods of the
fillBorder()
function.
-
edgeCosAngles
(return_mask=False)[source]¶ Return the cos of the angles over all edges.
The surface should be a manifold (max. 2 elements per edge). Edges adjacent to only one element get cosangles = 1.0. If return_mask == True, a second return value is a boolean array with the edges that connect two faces.
As a side effect, this method also sets the area, normals, elem_edges and edges attributes.
-
edgeAngles
()[source]¶ Return the angles over all edges (in degrees).
It is the angle (0 to 180) between 2 face normals.
-
edgeSignedAngles
(return_mask=False)[source]¶ Return the signed angles over all edges (in degrees).
It is the angle (-180 to 180) between 2 face normals.
Positive/negative angles are associated to convexity/concavity at that edge. The border edges attached to one triangle have angle 0. NB: The sign of the angle is relevant if the surface has fixed normals. Should this check be done?
-
edgeLengths
()[source]¶ Returns the lengths of all edges
Returns an array with the length of all the edges in the surface. As a side effect, this stores the connectivities of the edges to nodes and the elements to edges in the attributes edges, resp. elem_edges.
-
quality
()[source]¶ Compute a quality measure for the triangle schapes.
The quality of a triangle is defined as the ratio of the square root of its surface area to its perimeter relative to this same ratio for an equilateral triangle with the same area. The quality is then one for an equilateral triangle and tends to zero for a very stretched triangle.
-
aspectRatio
()[source]¶ Return the apect ratio of the triangles of the surface.
The aspect ratio of a triangle is the ratio of the longest edge over the smallest altitude of the triangle.
Equilateral triangles have the smallest edge ratio (2 over square root 3).
-
distanceOfPoints
(X, return_points=False)[source]¶ Find the distances of points X to the TriSurface.
The distance of a point is either: - the closest perpendicular distance to the facets; - the closest perpendicular distance to the edges; - the closest distance to the vertices.
X is a (nX,3) shaped array of points. If return_points = True, a second value is returned: an array with the closest (foot)points matching X.
-
degenerate
()[source]¶ 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.
Returns the list of degenerate element numbers in a sorted array.
-
removeDegenerate
(compact=False)[source]¶ Remove the degenerate elements from a TriSurface.
Returns a TriSurface with all degenerate elements removed. By default, the coords set is unaltered and will still contain all points, even ones that are no longer connected to any element. To reduce the coordinate set, set the compact argument to True or use the
compact()
method afterwards.
-
collapseEdge
(edg)[source]¶ Collapse an edge in a TriSurface.
Collapsing an edge removes the triangles connected to the edge and replaces the two vertices of the edge with a single one, placed at the center of the edge. Triangles connected to one of the edge vertices, will become connected to the new vertex.
Parameters: edg (int) – The index of the edg to be removed. This is an index in the array of edges as returned by getElemEdges()
.Returns: TriSurface – An almost equivalent surface with the specified edge removed.
-
offset
(distance=1.0)[source]¶ Offset a surface with a certain distance.
All the nodes of the surface are translated over a specified distance along their normal vector.
-
dualMesh
(method='median')[source]¶ Return the dual mesh of a compacted triangulated surface.
Creates a new triangular mesh where all triangles with prop p represent the dual mesh region around the original surface node p.
Parameters: method ('median' | 'voronoi') – Returns: - Mesh – The dual Mesh. The elements have property numbers equal to the node number around which they are based.
- .. Note (This needs more explanation.)
-
featureEdges
(angle=60.0)[source]¶ Return the feature edges of the surface.
Feature edges are edges that are prominent features of the geometry. They are either border edges or edges where the normals on the two adjacent triangles differ more than a given angle. The non feature edges then represent edges on a rather smooth surface.
Parameters: angle (float) – The minimum value of the angle (in degrees) between the normals on two adjacent triangles in order for the edge to be considered a feature edge. Returns: bool array – An array with shape (nedg,) where the feature angles are marked True. Notes
As a side effect, this also sets the elem_edges and edges attributes, which can be used to get the edge data with the same numbering as used in the returned mask. Thus, the following constructs a Mesh with the feature edges of a surface S:
p = S.featureEdges() Mesh(S.coords,S.edges[p])
-
partitionByAngle
(angle=60.0, sort='number')[source]¶ Partition the surface by splitting it at sharp edges.
The surface is partitioned in parts in which all elements can be reached without ever crossing a sharp edge angle. More precisely, any two triangles will belong to the same part if the can be connected by a line in the surface that does not cross an edge between two elements having their normals differ more than the specified angle.
Parameters: - angle (float) – The minimum value of the angle (in degrees) between the normals on two adjacent triangles in order for the edge to be considered a sharp edge.
- sort (str) –
Defines how the resulting parts are sorted (by assigning them increasing part numbers). The following sort criteria are currently defined (any other value will return the parts unsorted):
- ’number’: sort in decreasing order of the number of triangles in the part. This is the default.
- ’area’: sort according to decreasing surface area of the part.
Returns: int array – An int array specifying for each triangle to which part it belongs. Values are in the range 0..nparts.
Notes
In order for the operation to be non-trivial, the specified edges, possibly together with (parts of) the border, should form one or more closed loops.
Beware that the existence of degenerate elements may cause unexpected results. If unsure, use the
removeDegenerate()
method first to remove those elements.
-
cutWithPlane1
(p, n, side='', return_intersection=False, atol=0.0)[source]¶ Cut a surface with a plane.
Cut the surface with a plane defined by a point p and normal n.
Warning
This is experimental and may not work correctly.
Parameters: - p (float array_like (3,)) – A point in the cutting plane.
- n (float array_like (3,)) – The normal vector to the cutting plane.
- side ('' | '+' | '-') – Selects the returned parts. Default (‘’) is to return a tuple of two surfaces, with the parts at the positive, resp. negative side of the plane, as defined by the normal vector. If a ‘+’ or ‘-‘ is specified, only the corresponding part is returned.
Returns: - Spos (TriSurface, optional) – The part of the surfacec at the positive side of thr plane (p,n). Only returned if side is ‘’ or ‘+’.
- Sneg (TriSurface, optional) – The part of the surfacec at the negative side of thr plane (p,n). Only returned if side is ‘’ or ‘-‘.
- The returned surfaces have their normals fixed wherever possible.
- Prop values are set containing the triangle number in the
- original surface from which the elements resulted.
-
cutWithPlane
(*args, **kargs)[source]¶ Cut a surface with a plane or a set of planes.
Cut the surface with one or more planes and return either one side or both. This uses a conversion to a 3-plex Formex to do the cutting, and then converts the results back to TriSurface(s). The parameters are the same as in
Formex.CutWithPlane()
. The returned surface(s) will have the normals fixed wherever possible.
-
intersectionWithPlane
(p, n, atol=1e-05, sort='number')[source]¶ Return the intersection lines with plane (p,n).
Parameters: - p (coords_like (3,)) – A point in the cutting plane.
- n (coords_like (3,)) – The positive normal on the plane
- atol (float) – Tolerance value to consider points lying in the plane. A small positive value is recommended in order to include triangle edges that happen to fall exactly in the cutting plane.
- sort ('number' | 'distance') – The sorting method for the connected components in the output Mesh. The default ‘number’ sorts in decreasing number of elements in the component. Setting to ‘distance’ will sort the parts according to increasing distance from the point p.
Returns: Mesh – The intersection of the TriSurface with the plane. This is a Mesh of eltype ‘line’. The line segments in the Mesh are ordered in a way to form continuous lines. The Mesh has property numbers such that all segments forming a single continuous part have the same property value. The parts are assigned property numbers according to their sort order.
Notes
The splitProp() method can be used to get a list of separate Meshes.
-
slice
(dir=0, nplanes=20)[source]¶ Intersect a surface with a series of parallel planes.
Parameters: - dir (int | array_like (3,)) – The direction of the normal on the planes. A single int (0..2) may be used to specify one of the global axes.
- nplanes (int) – The number of planes to be used. The planes are spread at equal distances over the bbox of the surface.
Returns: list of
Mesh
– A list of nplanes Meshes of type ‘line2’, being the intersections of the surface with each of the planes.Notes
The intersections are obtained with
intersectionWithPlane()
. See there for more dretails on the returned Meshes.
-
refine
(max_edges=None, min_cost=None, method='gts', log=False)[source]¶ Refine a TriSurface.
Refining a TriSurface means increasing the number of triangles and reducing their size, while keeping the changes to the modeled surface minimal. Construct a refined version of the surface. This uses the external program gtsrefine. The surface should be a closed orientable non-intersecting manifold. Use the
check()
method to find out.Parameters:
- max_edges: int: stop the refining process if the number of edges exceeds this value
- min_cost: float: stop the refining process if the cost of refining an edge is smaller
- log: boolean: log the evolution of the cost
- verbose: boolean: print statistics about the surface
-
similarity
(S)[source]¶ Compute the similarity with another TriSurface.
Compute a quantitative measure of the similarity of the volumes enclosed by two TriSurfaces. Both the calling and the passed TriSurface should be closed manifolds (see
isClosedManifold()
).Returns a tuple (jaccard, dice, overlap). If A and B are two closed manifolds, VA and VB are their respective volumes, VC is the volume of the intersection of A and B, and VD is the volume of the union of A and B, then the following similarity measures are defined:
- jaccard coefficient: VC / VD
- dice: 2 * VC / (VA + VB)
- overlap: VC / min(VA,VB)
Both jaccard and dice range from 0 when the surfaces are completely disjoint to 1 when the surfaces are identical. The overlap coefficient becomes 1 when one of the surfaces is completely inside the other.
This method uses gts library to compute the intersection or union. If that fails, nan values are returned.
-
fixNormals
(method=None, *, outwards=True, return_parts=False, inplace=True)[source]¶ Fix the orientation of the normals.
Some surface operations may result in improperly oriented normals, switching directions from one triangle to the adjacent one. This method tries to reverse triangles with improperly oriented normals so that a singly oriented surface may be achieved.
Parameters: - method ('admesh' | 'internal') – The method to be used. If not specified, the default ‘internal’ is used and a warning is shown about the changed default. The ‘internal’ method does not rely on external software, and is relatively fast. As it does not fuse the nodes nor compacts the node array, it guarantees that the numbering of nodes and elements is retained. The ‘admesh’ uses an external program and needs to write the surface to a file and read it back. This method will always do a fuse and compaction, so if the surface was not fused and compacted before the call, the result may have different node and/or element numberings.
- outwards (bool) – If True (default), a test is done whether the surface is a closed manifold, or a set of closed manifolds, and if so, the normals are oriented outwards. Setting this value to False may result in a closed surfaces with all normals pointing inside.
- return_parts (bool) – If True, also returns an index identifying to which connected part each of the triangles belong. Part numbers are in order of decreasing number of triangles.
Raises: ValueError: if the surface is not a manifold. Such a surface is not – orientable.
-
fixNormals_internal
()[source]¶ Fix normals using an internal algorithm.
This is normally invoked as
fixNormals('internal')
. SeefixNormals()
.
-
fixNormals_admesh
()[source]¶ Fix normals using admesh.
This is normally invoked as
fixNormals('admesh')
. SeefixNormals()
.
-
check
(matched=True, verbose=False)[source]¶ Check the surface using gtscheck.
Uses the external program gtscheck to check whether the surface is an orientable, non self-intersecting manifold. This is a necessary condition for using the gts methods: split, coarsen, refine, boolean. Additionally, the surface should be closed: this can be checked with
isClosedManifold()
.Parameters: Returns: - status (int) – Return code from the checking program. One of the following:
- 0: the surface is an orientable, non self-intersecting manifold.
- 1: the created GTS file is invalid: this should normally not occur.
- 2: the surface is not an orientable manifold. This may be due to
misoriented normals. The
fixNormals()
andreverse()
methods may be used to help fixing the problem in such case. - 3: the surface is an orientable manifold but is self-intersecting. The self intersecting triangles are returned as the second return value.
- intersect (None | list of ints | TriSurface) – None in case of a
status
0, 1 or 2. Forstatus
value 3, returns the self intersecting triangles as a list of element numbers (ifmatched
is True) or as a TriSurface (ifmatched
is False).
- status (int) – Return code from the checking program. One of the following:
-
split
(base, verbose=False)[source]¶ Split the surface using gtssplit.
Splits the surface into connected and manifold components. This uses the external program gtssplit. The surface should be a closed orientable non-intersecting manifold. Use the
check()
method to find out.This method creates a series of files with given base name, each file contains a single connected manifold.
-
coarsen
(min_edges=None, max_cost=None, mid_vertex=False, length_cost=False, max_fold=1.0, volume_weight=0.5, boundary_weight=0.5, shape_weight=0.0, progressive=False, log=False, verbose=False)[source]¶ Coarsen a surface using gtscoarsen.
Construct a coarsened version of the surface. This uses the external program gtscoarsen. The surface should be a closed orientable non-intersecting manifold. Use the
check()
method to find out.Parameters: - min_edges (int) – Stop the coarsening process if the number of edges was to fall below it.
- max_cost (float) – Stop the coarsening process if the cost of collapsing an edge is larger than the specified value.
- mid_vertex (bool) – Use midvertex as replacement vertex instead of the default, which is a volume optimized point.
- length_cost (bool) – Use length^2 as cost function instead of the default optimized point cost.
- max_fold (float) – Maximum fold angle in degrees.
- volume_weight (float) – Weight used for volume optimization.
- boundary_weight (float) – Weight used for boundary optimization.
- shape_weight (float) – Weight used for shape optimization.
- progressive (bool) – If True, write progressive surface file.
- log (bool) – If Trye, log the evolution of the cost.
- verbose (bool) – If True, print statistics about the surface.
-
gts_refine
(max_edges=None, min_cost=None, log=False, verbose=False)[source]¶ Refine the TriSurface.
Refining a TriSurface means increasing the number of triangles and reducing their size, while keeping the changes to the modeled surface minimal. This uses the external program gtsrefine. The surface should be a closed orientable non-intersecting manifold. Use the
check()
method to find out.Parameters: - max_edges (int) – Stop the refining process if the number of edges exceeds this value.
- min_cost (float) – Stop the refining process if the cost of refining an edge is smaller. (Not recommended).
- log (bool) – If True, log the evolution of the cost.
- verbose (bool) – If True, print statistics about the surface.
Notes
If neither max_edges nor min_cost are specified, the refining process aims to double the number of edges.
-
gts_smooth
(niter=1, lamb=0.5, verbose=False)[source]¶ Smooth the surface using gtssmooth.
Smooth a surface by applying iterations of a Laplacian filter. This uses the external program gtssmooth. The surface should be a closed orientable non-intersecting manifold. Use the
check()
method to find out.Parameters:
-
gts_set
(surf, op, prop=[1, 1, 2, 2], check=False, verbose=False)[source]¶ Perform a boolean operation with another surface.
Boolean operations between surfaces are a basic operation in free surface modeling. Both surfaces should be closed orientable non-intersecting manifolds. Use the
check()
method to find out.Following is a list of defined operations, where surface 1 relates to self and surface 2 to the surf argument. For simplicity, the operations are identified by a short string.
Basic operations:
‘i’ : the part of surface 1 inside surface 2 ‘o’ : the part of surface 1 outside surface 2 ‘2i’ : the part of surface 2 inside surface 1 ‘2o’ : the part od surface 2 outside surface 1
These surface are manifolds, but may be closed or not. From these basic parts, the following set operation can be constructed. These are mathematical set operation on the volumes in side the surfaces, and result in closed surfaces:
‘+’ : the union of surfaces 1 and 2 ‘*’ : the intersection of surfaces 1 and 2 ‘-‘ : the difference of surface 1 minus surface 2 ‘2-‘ : the difference of surface 2 minus surface 1 ‘^’ : the symmetric difference of the surfaces (equal to ‘-‘ + ‘2-‘)
Parameters: - surf (TriSurface) – Another TriSurface that is a closed manifold surface.
- op (str or list of str) – The operation(s) to perform: one of the operations specified above, or a list of such operations. A special value ‘a’ will return the full list of 9 surfaces in the above order.
- prop (list of int) – A list of 4 integer values that will be set as props on the four base surfaces, to facilitate identification of the parts of the result(s). The default value will give prop values 1 or 2 depending on the original surface the parts belonged to. Specifying None or an empty list will return surfaces without props.
- check (bool) – If True, a check is done that the surfaces are not self-intersecting; if one of them is, the set of self-intersecting faces is written (as a GtsSurface) on standard output
- verbose (bool) – If True, print statistics about the surface.
Returns: TriSurface
or list thereof – A single manifold surface, or a list of such surfaces, corresponding to the specified oppetaion(s). The base operation may not be closed. The set operations always are closed.Note
This method uses the external command ‘gtsset’ and will not run if it is not installed (available from pyformex/extras).
-
boolean
(surf, op, check=False, verbose=False)[source]¶ Perform a boolean operation with another surface.
Boolean operations between surfaces are a basic operation in free surface modeling. Both surfaces should be closed orientable non-intersecting manifolds. Use the
check()
method to find out.The boolean operations are set operations on the enclosed volumes: union(‘+’), difference(‘-‘) or intersection(‘*’).
Parameters: - surf (TriSurface) – Another TriSurface that is a closed manifold surface.
- op ('+', '-' or '*') – The boolean operation to perform: union(‘+’), difference(‘-‘) or intersection(‘*’).
- check (bool) – If True, a check is done that the surfaces are not self-intersecting; if one of them is, the set of self-intersecting faces is written (as a GtsSurface) on standard output
- verbose (bool) – If True, print statistics about the surface.
Returns: TriSurface – A closed manifold TriSurface that is the volume union, difference or intersection of self with surf.
Note
This method uses the external command ‘gtsset’ and will not run if it is not installed (available from pyformex/extras).
-
intersection
(surf, check=False, verbose=False)[source]¶ Return the intersection curve(s) of two surfaces.
Boolean operations between surfaces are a basic operation in free surface modeling. Both surfaces should be closed orientable non-intersecting manifolds. Use the
check()
method to find out.Parameters: - surf (TriSurface) – A closed manifold surface.
- check (bool, optional) – If True, a check is made that the surfaces are not self-intersecting; if one of them is, the set of self-intersecting faces is written (as a GtsSurface) on standard output
- verbose (bool, optional) – If True, statistics about the surface are printed on stdout.
Returns: Mesh – A Mesh with eltype Line2 holding all the line segments of the intersection curve(s).
-
inside
(pts, method='gts', tol='auto', multi=False, tmpdir=None)[source]¶ Test which of the points pts are inside the surface.
Parameters: - pts (:term_`coords_like`) – The points to check agains the surface.
- method` (str) –
Method to be used for the detection. Depending on the software you have installed the following are possible:
- ’gts’: provided by pyformex-extra (default)
- ’vtk’: provided by python-vtk (slower)
- tol (float) – Tolerance on equality of floating point values.
- multi (bool) – If True, uses multiprocessing to speed up the operation. Only available with method ‘gts’.
- tmpdir (path_like) – If specified, it is a directory path where the intermediate results from the gtsinside program are stored. The default is to use temporary directories and destroy the intermediary results.
Returns: int array – The indices of the points that are inside the surface. The indices refer to the onedimensional list of points as obtained from Coords(pts).points().
-
outside
(pts, **kargs)[source]¶ Returns the points outside the surface.
This is the complement of
inside()
. See there for parameters and return value.
-
voxelize
(n, bbox=0.01, return_formex=False)[source]¶ Voxelize the volume inside a closed surface.
Parameters: - n (int or (int, int, int)) – Resolution, i.e. number of voxel cells to use along the three axes.
If a single int is specified, the number of cells will be adapted
according to the surface’s
sizes()
(as the voxel cells are always cubes). The specified number of voxels will be used along the largest direction. - bbox (float or (point,point)) – Defines the bounding box of the volume that needs to be voxelized. A float specifies a relative amount to add to the surface’s bounding box. Note that this defines the bounding box of the centers of the voxels.
- return_formex (bool) – If True, also returns a Formex with the centers of the voxels.
Returns: - voxels (int array (nz,ny,nx)) – The array has a value 1 for the voxels whose center is inside the surface, else 0.
- centers (Formex) – A plex-1 Formex with the centers of the voxels, and property values 0 or 1 if the point is respectively outside or inside the surface. The voxel cell ordering in the Formex is z-direction first, then y, then x.
Notes
See also example Voxelize, for saving the voxel values in a stack of binary images.
- n (int or (int, int, int)) – Resolution, i.e. number of voxel cells to use along the three axes.
If a single int is specified, the number of cells will be adapted
according to the surface’s
-
remesh
(*, method='acvd', **kargs)[source]¶ Create a quality remesh of the TriSurface.
Uses
instant_meshes()
to remesh a TriSurface into a quality Tri3 or Quad4 Mesh.Parameters: - method (str) –
One of ‘acvd’, ‘instant’ or ‘vmtk’. The first character suffices. Depending on this value, one of the
remesh_acvd()
,remesh_instant()
orremesh_vmtk()
is called.The ‘acvd’ method is included with pyFormex and is normally always available on a successful install. The ‘instant’ method requires an external program ‘instant-meshes’. The Help menu contains an option to install it. The ‘vmtk’ method requires the external program ‘vmtk’. This option is deprecated and scheduled for withdrawal in future.
- kargs – Keyword arguments to be passed to the specific method selected. See the specific method for explanation of the parameters.
Returns: TriSurface | Mesh | None – In most cases a TriSurface is returned. The ‘instant’ method however allows remeshing to quads. In that cases a Mesh of eltype ‘quad4’ is returner. If the external conversion failed, None is returned.
Raises: ValueError: – If the requested external remeshing program is not available.
- method (str) –
-
remesh_acvd
(npoints=None, ndiv=2)[source]¶ Create a quality remesh of the TriSurface.
Parameters: - npoints (int, optional) – The targeted number of vertices in the output mesh. If not provided, it is set equal to the number of vertices in the input mesh.
- ndiv (int, optional) – The number of subdivisions to created in order to have a finer mesh for the clustering method. A higher number will results in a more regular mesh, at the expense of a longer computation time.
Returns: TriSurface – The remeshed TriSurface, resembling the input mesh, but having a more regular mesh. Note that if the input Mesh contains sharp folds, you may need to clean up the surface by calling
removeNonManifold()
and/orfixNormals()
.Notes
This uses a clustering technique based on https://www.creatis.insa-lyon.fr/site7/en/acvd to resample the mesh. The actual implementation is a modification of https://github.com/pyvista/pyacvd to directly use pyFormex data structures instead of pyvista/vtk.
-
remesh_instant
(*, infile=None, outfile=None, **kargs)[source]¶ Create a quality remesh of the TriSurface.
Uses
instant_meshes()
to remesh a TriSurface into a quality Tri3 or Quad4 Mesh.Parameters: - infile (path_like) – The name of an .obj file where the TriSurface will be stored for processing. If not provided, a temporary file is used.
- outfile (path_like) – The name of an .obj file for storing the output Mesh. If not provided, it is generated from the infile with the ‘.obj’ suffix replaced ‘with _remesh.obj’.
- kargs – Other keyword arguments passed to
instant_meshes()
. All the keyword parameters accepted by that function, except for ‘dominant, can be specified here.
Returns: Mesh | None – A Mesh of eltype ‘tri3’ or ‘quad4’ if the conversion was successful, or else None.
Notes
If neither scale, faces or vertices is provided, vertices will be set equal to the number of vertices in the TriSurface. This is because the default of
instant_meshes()
results in a much too coarse Mesh.If the boundaries parameter is not provided, it is set True if the TriSurface is not a closed manifold.
As a side effect, if file names were specified, the .obj files with the original TriSurface and remeshed surface remain available.
-
tetgen
(quality=2.0, volume=None, filename=None)[source]¶ Create a tetrahedral mesh inside the surface.
This uses
tetMesh()
to generate a quality tetrahedral mesh inside the surface. The surface should be a closed manifold.Parameters: - quality (float) – The quality of the output tetrahedral mesh. The value is a constraint on the circumradius-to-shortest-edge ratio. The default (2.0) already provides a high quality mesh. Providing a larger value will reduce quality but increase speed. With quality=None, no quality constraint will be imposed.
- volume (float, optional) – If provided, applies a maximum tetrahedron volume constraint.
- filename (path_like) – Specifies where the intermediate files will be stored. The default will use a temporary directory which will be destroyed after return. If the path of an existing directory is provided, the files will be stored in that directory with a name ‘surface.off’ for the original surface model and files ‘surface.1.*’ for the generated tetrahedral model (in tetgen format). If the path does not exist or is an existing file, the parent directory should exist and files are stored with the given file name as base. Existing files will be silently overwritten.
Returns: Mesh – A tetrahedral Mesh (eltype=’tet4’) filling the input surface, provided the
tetMesh()
function finished successfully.
-
webgl
(name, caption=None)¶ Create a WebGL model of a surface
- S: TriSurface
- name: basename of the output files
- caption: text to use as caption
-
surface2webgl
(name, caption=None)¶ Create a WebGL model of a surface
- S: TriSurface
- name: basename of the output files
- caption: text to use as caption
40.2. Functions defined in module trisurface¶
-
trisurface.
fillBorder
(border, method='radial', dir=None)[source]¶ Create a triangulated surface inside a given closed polygonal line.
Parameters: - border (
PolyLine
,Mesh
orCoords
) –A closed polygonal line that forms the border of the triangulated surface to be created. The polygon does not have to be planar. The line can be provided as one of the following:
- a closed PolyLine,
- a 2-plex Mesh, with a Connectivity table such that the elements in the specified order form a closed polyline,
- a simple Coords holding the subsequent vertices of the polygonal border line.
- method (str) –
Specifies the algorithm to be used to fill the polygon. Currently available are:
- ’radial’: this method adds a central point and connects all border segments with the center to create triangles.
- ’border’: this method creates subsequent triangles by connecting the endpoints of two consecutive border segments and thus works its way inwards until the hole is closed. Triangles are created at the line segments that form the smallest angle.
See also Notes below.
Returns: TriSurface – A TriSurface filling the hole inside the border.
Notes
The ‘radial’ method produces nice results if the border is relative smooth, nearly convex and nearly planar. It adds an extra point though, which may be unwanted. On irregular 3D borders there is a high change that the resulting TriSurface contains intersecting triangles.
The ‘border’ method is slower on large borders, does not introduce any new point and has a better chance of avoiding intersecting triangles on irregular 3D borders.
The resulting surface can be checked for intersecting triangles with the
check()
method.Because the ‘border’ does not create any new points, the returned surface can use the same point coordinate array as the input object.
- border (
-
trisurface.
instant_meshes
(infile, outfile=None, **kargs)[source]¶ Remesh a tri3 mesh to a quality tri3 and/or quad4 mesh
Uses the external ‘Instant Meshes’ program to remesh a tri3 mesh to a tri3 and/or quad4 mesh of the desired quality.
Parameters: - infile (path_like) – An .obj file containing a pure tri3 mesh.
- outfile (path_like) – The output file with the quad (or quad dominated) Mesh. It can be a .obj or .ply file. If not provided, it is generated from the input file with the ‘.obj’ suffix replaced ‘with _quad.obj’.
- threads (int) – Number of threads to use in parallel computations.
- deterministic (bool) – If True, prefer (slower) deterministic algorithms. Default False.
- crease (float) – Dihedral angle threshold for creases.
- smooth (int) – Number of smoothing & ray tracing reprojection steps (default: 2). Setting this to 0 may result in degenerate quads (with two adjacent edges along the same line).
- dominant (bool) – If True, generate a quad dominant mesh instead of a pure quad mesh. The output may contain some triangles and pentagones as well. Default False.
- intrinsic (bool) – If True, use intrinsic mode (extrinsic is the default).
- boundaries (bool) – If True, align the result on the boundaries. Default False. Only applies when the surface is not closed.
- posy (3 | 4 | 6) – Specifies the position symmetry type. Default 4.
- rosy (2 | 4 | 6) – Specifies the orientation symmetry type. Default 4.
- scale (float) – The intended edge length of the quad elements. Ignored if either faces or vertices is provided. See notes.
- faces (int) – The intended number of quads in the output mesh. Ignored if vertices is provided. See notes.
- vertices (int) – The intended number of vertices in the output mesh. See notes.
Returns: Path | None – The path of the output file if the conversion was successful, else None.
Notes
The ‘Instant Meshes’ executable should be installed as ‘instant-meshes’.
To control the output resolution, one should specify exactly one of scale, faces or vertices. These are mutually exclusive.
If a pure quad mesh is requested (the default), the number of faces/vertices may end up to be around 4 times larger and edges two times shorter than requested. This is because the initial remeshing may end up with some triangles and/or pentagones, which then require a subdivision of all faces into smaller quads. This late subdivision is not done if
dominant=True
is specified, or if there are no triangles or pentagones with the default.With dominant=False, posy = 3 or 6 results in a Tri3 Mesh, while posy = 4 yields a Quad4 Mesh. The best quality is usually obtained with posy=rosy=6 to produce triangles and posy=rosy=4 for quads.
See also
TriSurface.remesh()
- apply remeshing on a TriSurface