6. mesh

This module is used to manipulate 3D triangular mesh data.

6.1. Overview

Mesh([points, triangles, normals, colors, …])	3D triangular mesh object.
load_mesh(fn[, file_type])	Load a triangular mesh from a file, stored either as a “PLY” or “STL” file.
decode_ply(f[, require_triangles])	Decode a ply file, converting all saved attributes to dictionary entries.
encode_ply(points, tris[, normals, colors, …])	Convert triangular mesh data into a PLY file data.

6.2. Classes and Functions

exception ilpm.mesh.MeshWarning

Bases: Warning

exception ilpm.mesh.ShapeError

Bases: Exception

exception ilpm.mesh.ToDoError

Bases: Exception

ilpm.mesh.set_opencl_params(use_doubles=None, device=None, context=None)

Set the parameters of the OpenCL Session used for computations.

See simple_cl documentation for details.

Note: this function must be called before any functions that use it, or an error will be raised.

Parameters

use_doublesbool, optional (default: False)

devicestring or list, optional (default: ‘cpu’)

contextpyopencl Context or CLSession object, optional

If specified, causes CLSession to share a context.

class ilpm.mesh.Mesh(points=None, triangles=None, normals=None, colors=None, attached={})

Bases: object

3D triangular mesh object.

Parameters

points(num points, 3) array

triangles(num triangles, 3) array

normals(num points, 3) array (optional)

Vertex normal vectors.

colors(num points, 3 or 4) array (optional)

Vertex colors, as RGB or RGBA. Alpha channel is optional. Type should either be "float" (range: [0.0-1.0]) or "u1" (range: [0-255]).

attacheddict of (num points,) arrays (optional)

Arbitrary attributes attached to vertices. Shape is checked on initialization, and an error will be thrown if it is not a 1D array with correct length. (Note: vector or other multivalued arrays must be split into components; this is necessary to get consistent results when saved to a PLY mesh.)

Methods

attach(self, key, val)	Attach a named vertex parameter.
clip(self, a[, level, both_sides])	Clip a mesh by some parameter defined for each point.
color_by_proximity(self, p[, c, w, …])	Color a mesh by proximity to another path, tangle, or set of colored points.
colorize(self, c[, cmap, clim])	Color a mesh using matplotlib specifications.
convert_colors(self, dtype)	Convert type of colors field, rescaling if required.
copy(self)	Return a copy of the mesh, with sub-arrays copied as well.
euler_char(self)	Return the total Euler Characteristic of a mesh: \(\chi = V - E + F\).
face_normals(self[, right_hand, normalize])	Compute triangle face normals.
invert(self)	Flip the mesh normals, including triangle winding order and the normals field (if present).
inverted(self)	Return an inverted copy of a mesh.
is_closed(self[, tol])	Check if the mesh is closed by calculating the volume of a transposed copy.
periodic_separate(self[, top])	Separate into sections and then reconnect across periodic boundaries.
remove_degenerate_triangles(self)	Remove triangles with repeated edges.
rotate(self, rv)	Rotate the mesh (in place).
rotated(self, rv)	Return a rotated copy of a mesh
save(self, fn[, file_type])	Save mesh as a file.
save_pov(self, fn[, include_extras, …])	Save a mesh into a POV file; optionally create a sample scene.
scale(self, s)	Scale the Mesh in place.
scaled(self, s)	Return a scaled copy of a mesh.
separate(self[, return_point_indices])	Break the mesh into disconnected parts.
translate(self, delta)	Rotate the mesh (in place).
translated(self, delta)	Return an translated copy of a mesh.
volume(self)	Return the volume of the mesh.

attach(self, key, val)

Attach a named vertex parameter.

Equivalent to setting an item in the attached attribute, but also does shape checking.

Parameters

keystring

valnumpy array shaped (num_points, )

save(self, fn, file_type=None)

Save mesh as a file.

Supported file types:

• ply: The most useful format; will also save attached parameters.

• stl: Used primarily by 3D printers. Only save geometry, not

  colors, normals, etc.

• pov: Used to render object in POVRay. If normals exists,

  smooth triangles will be saved, but colors, etc. are not retained. See save_pov() for more options and details, including sample scene generation.

Parameters

fnstring

File name

file_typestring, optional

File type, should be one of the supported formats. If not specified, determined from the file name.

rotate(self, rv)

Rotate the mesh (in place).

Parameters

rvvector

Rotation vector, will rotate counter-clockwise around axis by an amount given be the length of the vector (in radians).

rotated(self, rv)

Return a rotated copy of a mesh

scale(self, s)

Scale the Mesh in place.

Parameters

scalefloat or vector

scaled(self, s)

Return a scaled copy of a mesh.

invert(self)

Flip the mesh normals, including triangle winding order and the normals field (if present).

inverted(self)

Return an inverted copy of a mesh.

translate(self, delta)

Rotate the mesh (in place).

Parameters

deltavector

translated(self, delta)

Return an translated copy of a mesh.

volume(self)

Return the volume of the mesh.

The mesh is assumed to be closed and non-interecting.

is_closed(self, tol=None)

Check if the mesh is closed by calculating the volume of a transposed copy.

This routine is not fool-proof, but catches most open meshes.

Parameters

tolfloat (optional)

The relative tolerance of the volume comparison. Defaults to 1E-12 if the vertex data type is double precision, otherwise 1E-6.

colorize(self, c, cmap='jet', clim=None)

Color a mesh using matplotlib specifications.

Parameters

cstring or array

• If type is string, it is interpreted like a normal matplotlib color (e.g., "r" for red, or "0.5" for 50% gray, or "#FF8888" for pink).

• If type is array, it should have the same length as the number of points, and it will be converted to a colormap.

cmapstring or matplotlib colormap (default: ‘jet’)

The color map to use. Only relevant if c is an array.

climtuple (default: None)

The color limits. If None, the max/min of c are used.

copy(self)

Return a copy of the mesh, with sub-arrays copied as well.

face_normals(self, right_hand=True, normalize=True)

Compute triangle face normals.

Parameters

right_handbool (default: True)

Right-hand or left hand normals? Normally, right-hand normals are used, meaning triangles are wound counter-clockwise when viewed from “outside” the mesh.

normalizebool (default: True)

If True, normals are normalized after being computed.

Returns

n[num triangles, 3] array

Normals corresponding to each face, generated as a cross product.

convert_colors(self, dtype)

Convert type of colors field, rescaling if required.

Note: usually the type of the color field is not important, e.g. when saving to ``”ply”`` format the color is automatically converted on saving.

Parameters

dtypevalid numpy data type (usually "f" or "u1")

Data type to convert colors to. If converting from "u1" to a float type, rescales from [0-255] to [0.0-1.0], and vice-versa. If converting from float to "u1", colors will first be clipped from (0-1).

euler_char(self)

Return the total Euler Characteristic of a mesh: \(\chi = V - E + F\).

Note that orphaned points (not connected to triangles) are automatically excluded.

If the mesh is composed of multiple parts, they can first be separated with Mesh.separate().

separate(self, return_point_indices=False)

Break the mesh into disconnected parts.

Parts are considered connected if any of their triangles share a corner.

Note: This algorithm is unoptimized and may run slower than you expect.

Parameters

return_point_indicesbool, optional (default: False)

If true, returns the indices of the points in the original mesh which are in each sub-mesh.

Returns

mesheslist of meshes

point_indiceslist of int arrays (optional)

Only returned if return_point_indices==True.

periodic_separate(self, top=None)

Separate into sections and then reconnect across periodic boundaries.

Similar to separate(), but checks for periodic reconnections.

Ideally this mase generated by ilpm.geometry_extractor.periodic_isosurface(), but in principle this is not necessary. The algorithm looks for sections that touch the bottom edge (x/y/z=0) and tries to move them to the top and join them.

Parameters

milpm.mesh.Mesh

toplist of floats, optional

The period of each axis. If not specified it will be the maximum value of any points along each axis.

Note: this is generally ok even if the maximum value isn’t the period; in this case there should also be no points touching the bottom boundary, so this axis will have no effect. However, if you have a mesh where the points touch the “bottom” (x/y/z=0) and not the “top”, then you must manually specify the “top” to get correct results.

Returns

mesheslist of Mesh objects

The reconnected sections. Any mesh touching a bottom boundary will be pushed to the top and merged with coindident sections.

clip(self, a, level=0, both_sides=False)

Clip a mesh by some parameter defined for each point.

Parameters

a[N] array

An array with the same size as the number of points.

levelfloat, optional (default: 0)

The level at which to clip the mesh, keeps all sections with (a-level) >=0, clipping triangles that span the boundary.

both_sidesbool, optional (default: False)

If True, returns two meshes, one for each side of the split.

Returns

clipped_meshMesh

A clipped version of the mesh. All attached attributes are clipped and retained as well.

other_side: Mesh, optional

If both_sides == True, returns the other side of the clip.

color_by_proximity(self, p, c=None, w=None, rgb_only=True, power=-6, period=None)

Color a mesh by proximity to another path, tangle, or set of colored points.

Parameters

pPath, Tangle or [N, 3] array

c[N, 3 or 4] array

The color of each point; required if p is an array, and ignored if it is a Path or Tangle (in this case the color attribute is used).

w[N] array, optional

Weight array.

rgb_onlybool, optional (default: True)

If True, the alpha component is dropped

powerint, optional (default: -6)

The power of the radial weighting function. Recommended values are <= -4.

periodNone, float or (3,) array_like (optional)

If not None, the period to use for wrapping the proximity calculation (data assumed to be go from 0-period on each axis). If one number is specified, the period is assumed to be the same on all three axes.

save_pov(self, fn, include_extras=False, mesh_name=None, precision=5)

Save a mesh into a POV file; optionally create a sample scene.

The resulting POV file contains only a definition of the mesh, which can be imported into other files.

The POV file will not contain colors or other attached attributes, but corner normals will cause it to render smooth triangles.

Parameters

fnstring

Filename to save to; .pov extension will be forced.

include_extrasbool, optional (default: False)

If True, creates <mesh_name>_scene.pov and <mesh_name>_scene.sh, which are a sample scene and script for rendering the mesh.

mesh_namestring, optional (default: <mesh_name>_mesh)

The name of the mesh in the declare statement. (i.e. this is the name of the object created in the POV file.)

precisionint, optional (default: 5)

The precision of the the points

remove_degenerate_triangles(self)

Remove triangles with repeated edges.

ilpm.mesh.surface_of_revolution(r, z, N=100)

Create a mesh from a surface of revolution.

Surface is revolved around the z axis.

Parameters

r, zarray_like, 1D

The radius and z coordinate of the surface of revolution.

Nint, optional (default: 100)

The number of points in the revolution

Returns

surfaceMesh

The revolved surface.

ilpm.mesh.extrude_shape(X, A, B, outline=10, outline_normals=None, scale=1, closed=True, enforce_normality=True, enforce_direction=True, outline_closed=True)

Create a tubular mesh by extruding a shape along a path.

Parameters

X[N, 3] array

The centerline of the extrusion

A, B[N, 3] arrays

The vectors which will correspond to the x and y coordinate of the polygon. Nomimally, dX, A, B form an orthonormal basis.

outlineint or array

If int, a circle is automatically generated with that number of points. If array, shape should be [M, 2] -or- [N, M, 2], where M is the number of points in the outline (for an outline which varies along the tube).

outline_normals: array, optional

The 2D normals of each point in the outline. Shape should match outline.

scalefloat or [N] array

The scale of the outline. Note: If scale is negative, the mesh will be inside out.

closedbool, optional (default: True)

If True, the centerline is taken to be closed.

enforce_normalitybool, optional (default: True)

If True, A and B are forced to be unit length and perpendicular. (A is normalized, and B is reorientated and normalized with Graham Schmidt.)

enforce_directionbool, optional (default: True)

If True, orients the path counter-clockwise automatically, accounting for the fact that the basis vector may be right or left-handed. Note: if variable outline is specified, it only checks the first outline, and flips all outlines.

outline_closedbool, optional (default: True)

If True, the outline is assumed to be closed.

ilpm.mesh.load_mesh(fn, file_type=None)

Load a triangular mesh from a file, stored either as a “PLY” or “STL” file.

Parameters

fnstring

file_typestring, optional

File type, either ‘ply’ or ‘stl’. If not specified, determined from the file name.

Returns

meshMesh object

Mesh object with the data in the file. If type is “PLY”, extra vertex attributes will appear in the attached attribute.

exception ilpm.mesh.PLYError

Bases: Exception

ilpm.mesh.decode_ply(f, require_triangles=True)

Decode a ply file, converting all saved attributes to dictionary entries.

Note: this function usually does not need to be used directly; for converting ply’s to meshes, use open_mesh(). Alternatively, this function can be used if you require access to fields beyond the basic mesh geometry, colors and point normals.

For more info on the PLY format, see:

• http://www.mathworks.com/matlabcentral/fx_files/5459/1/content/ply.htm

• http://paulbourke.net/dataformats/ply/

Parameters

fstring or file

A valid PLY file

require_trianglesbool (default: True)

If true, converts element_data["face"]["vertex_indices"] to an array with shape ([number of triangles], 3). Raises a PLYError if there are not triangular faces. Note: if ``require_triangles=False``, ``element_data[“face”][“vertex_indices”]`` will be a numpy array of data type ``”object”`` which contains arrays of possibly variable length.

Returns

element_datadict

A dictionary of all the properties in the original file. The main dictinoary should contain two sub-dictionaries with names "vertex" and "face". These dictionaries contain all of the named properties in the PLY file. Minimal entries in "vertex" are "x", "y", and "z". "face" should at least contain "vertex_indices".

ilpm.mesh.encode_ply(points, tris, normals=None, colors=None, enforce_types=True, extra_vertex_attributes=None)

Convert triangular mesh data into a PLY file data.

Note: if you wish to convert a Mesh object to a “ply” file, use Mesh.save().

Parameters

points(num points, 3) array

tris(num triangles, 3) array

normals(num points, 3) array, optional

Vertex normals.

colors(num points, 3 or 4) array, optional

Vertex colors, as RGBA. Alpha channel is optional, and will not be saved if not included. Type should either be float (ranging from 0-1) or uchar (ranging from 0-255). If type is float, will be clipped, scaled, and converted to uchar if enforce_types=True.

enforce_typesbool, optional (default: True)

If True, the data types of all the inputs will be converted to standard values (float for points, tris, and normals and uchar for colors). Although saving data with non-standard types is supported by the PLY format, files may not open in standard programs (e.g. Meshlab).

extra_vertex_attributesdict, optional

A dictionary of extra attributes to be added to each vertex. Each entry should consist of: [string name]:[numpy array] Type will not be altered, regardless of the value for enforce_types. If vectors need to be saved, the need to be broken out into subarrays: all arrays in the dictionary should have shape (num. vert., ).

Returns

ply_datastring

The PLY file data as a string.