42. 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.

42.1. Classes defined in module trisurface

class trisurface.TriSurface(*args, prop=None, **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 of 3. The surface contains ntri triangles and nedg edges. Each triangle has 3 vertices with 3 coordinates. The total number of vertices is ncoords.

Parameters
  • args

    Data to initialize the TriSurface. This can be 1, 2 or 3 arguments specifying one the the following data sets:

    • an (ntri,3,3) array_like specifying the coordinates of the vertices of the triangles,

    • a Formex with plexitude 3,

    • a Mesh with plexitude 3,

    • an (ncoords,3) coords_like with the vertex coordinates and an (ntri,3) int array_like specifying three vertex indices for each of the triangles

    • an (ncoords,3) coords_like with the vertex coordinates, an (nedg,2) int array_like specifying the vertex inidices of the edges, and an (ntri,3) int array_like specifying the edge indices of the triangles.

  • prop (int array_like, optional) – This keyword argument can be used to attribute property values to the elements of the TriSurface, like in the Mesh class.

See also

TriSurface.read

read a TriSurface from file

Formex.toSurface

convert a Formex to a TriSurface

Mesh.toSurface

convert a Mesh to a TriSurface

Examples

This example is a unit square divided in two triangles with the following following layout and numbering of nodes(n), elements(e) and edges:

n3      4    n2
  o---------o
  |        /|
  |  e1   / |
  |      /  |
  |     /   |
 2|    /1   |3
  |   /     |
  |  /      |
  | /   e0  |
  |/        |
  o---------o
n0     0     n1
>>> S = Mesh(eltype='quad4').convert('tri3-u').toSurface()
>>> print(S)
TriSurface: nnodes: 4, nelems: 2, nplex: 3, level: 2, eltype: tri3
  BBox: [0. 0. 0.], [1. 1. 0.]
  Size: [1. 1. 0.]
  Length: 4.0  Area: 1.0  Volume: 0.0
>>> print(S.coords)
[[0. 0. 0.]
 [1. 0. 0.]
 [1. 1. 0.]
 [0. 1. 0.]]
>>> print(S.elems)
[[0 1 2]
 [2 3 0]]
>>> print(S.nedges(), S.nfaces())
5 2
>>> print(S.edges)
[[0 1]
 [2 0]
 [3 0]
 [1 2]
 [2 3]]
>>> print(S.elem_edges)
[[0 3 1]
 [4 2 1]]
__getitem__(i)

Return element i of the Mesh.

This allows addressing element i of Mesh M as M[i].

Parameters

i (index) – The index of the element(s) to return. This can be a single element number, a slice, or an array with a list of numbers.

Returns

Coords – A Coords with a shape (nplex, 3), or if multiple elements are requested, a shape (nelements, nplex, 3), holding the coordinates of all points of the requested elements.

Notes

This is normally used in an expression as M[i], which will return the element i. Then M[i][j] will return the coordinates of node j of element i.

42.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 or Coords) –

    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.

    • ’planar’: this method projects the border on a plane, fills the border in 2D, then maps that back to the original border. The projection direction can be specified with dir.

    See also Notes below.

  • dir ((3,) array_like, optional) – A vector specyfing the direction of the projection in the case of method='planar'. If not provided, the best direction is automatically choosen.

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 ‘planar’ method gives very good results if the border curve is more or less planar.

The resulting surface can be checked for intersecting triangles with the check() method.

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 and vertices is likely to end up being around 4 times larger and the edges two times shorter than requested. This is because the initial remeshing may end up with some triangles and/or pentagons, which then require a subdivision of all faces into smaller quads. You may anticipate to this by specifying smaller values. This late subdivision is not done if dominant=True is specified, or if the initial remesh does not have any triangles or pentagons.

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

trisurface.remesh_instant(S, *, infile=None, outfile=None, nplex=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
  • S (TriSurface) – The TriSurface to be remeshed.

  • 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’.

  • nplex (3 | 4) – This is a convenient parameter to quickly create a quality mesh of triangles or quads. It overwrites the parameters rosy and posy with values 6 for nplex=3 and 4 for nplex=4.

  • 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.