Convenience API

Experimental

This part of the PMesh API is experimental and subject to changes or removal in the future.

Predefined types and Mesh templates

The module PMesh.Types defines some common types for mesh attributes (e.g., vectors V2, V3), their specification (e.g., POSITION3D, NORMAL or "combined" P3, P3N). In addition, it defines some "template" meshes (e.g., MESH3, MESH3N).

See also createmesh, similar

PMesh.Types.V3         # is a 3-vector (SVector{3, Float64})
PMesh.Types.V3d        # is an alias for V3
PMesh.Types.V3f        # is a 3-vector (SVector{3, Float32})

PMesh.Types.POSITION3D # is short for attribute specification :x => V3

PMesh.Types.P3         # is short for list specification (:x => V3)
PMesh.Types.P3N        # is short for list specification (:x => V3, :n => V3)

mesh = similar(MESH3N) # create mesh with vertex position and v/f normals
Note

The default scalar type of Float64 (e.g., for V2, V3).

Mesh template literal

Types in PMesh.Types are also available as custom string literals with prefix mt"..." ("mesh template").

mt"3" === PMesh.Types.MESH3
mt"3N" === PMesh.Types.MESH3N
mt"3NT" === PMesh.Types.MESH3NT

API extensions

Uniform naming

This is an extension of the API by methods that provide uniform – usually shorter – names for different handle types (e.g. remove!).

Bind handles to meshes

This is an extension that binds a handle in order to imitate an object-oriented call style with the bound mesh as self reference.

A second form binds a mesh as first argument of a function.

Note

Many method signatures follow the pattern method(mesh, handle, ...), the API extension just applies argument splatting on tuples (mesh, handle).

Note

Generally, only methods for local navigation return tuples (mesh, hnd). Other methods from the convenience API return plain handles.

In particular, methods that return a sequence of handles return the same sequence (and not a sequence of tuples) for performance reasons, e.g., vertices, star.

There are convenience methods for

Additionally, plain handles are obtained as

v = VHnd((mesh, v))
f = HHnd((mesh, f))
h = HHnd((mesh, h))
e = EHnd((mesh, e))

Examples

remove!(mesh, v)      # same as removevertex!(mesh, v)
remove!(mesh, f)      # same as removeface!(mesh, f)

all(bind(isinner, mesh), vertices(mesh))

vm = bind(mesh, v)
isinner(vm)          # same as isinner(mesh, v)

hm = bind(mesh, h)

v = hm |> opposite |> next |> source |> VHnd
Base.bind — Function
ch = bind(mesh, h::H) :: Tuple{Mesh, H}

Bind handle h to mesh.

fm = bind(f, mesh)

Bind mesh as first argument to function f.

See also Convenience API

source

Generate simple meshes

import PMesh.Meshes

mesh = Meshes.triangle()  # standard triangle
mesh = Meshes.quad()      # standard quad
mesh = Meshes.wing()      # standard quad split into two triangles

# single 1-ring
mesh = ring(; n=6, r=t->1, α->2π*t) # triangulated around center VHnd(1)
mesh = ngon(; n=6, r=t->1, α->2π*t) # single polygon of degree n

# cube
mesh = cube()
mesh = cube(triangles=true)

# tetrahedron
mesh = tetrahedron()

# sphere and torus sampled regularly with m × n faces
mesh = sphere(r=1.0, m=16, n=16)
mesh = sphere(r=1.0, m=16, m=16, triangles=false)

# torus with inner radius ri and outer radius ro
mesh = torus(ro=1.0, ri=0.25, m=16, n=16)
mesh = torus(ro=1.0, ri=0.25, m=16, n=16, triangles=false)

# cylinder with radius r and height h, optionally with closed boundaries
mesh = cylinder(r=1.0, h=1.0, m=16, n=16, closed=false)
mesh = cylinder(r=1.0, h=1.0, m=16, n=16, triangles=false, closed=true)

# rectangular path with width w and height h,
# optinally third coordinate is lifted to z(x, y)
mesh = rectangle(w=1.0, h=1.0, m=16, n=16, z = (x, y) -> x * y)
mesh = rectangle(w=1.0, h=1.0, m=16, n=16, triangles=false)
PMesh.Meshes._samplemesh — Method
x, t = _samplemesh(f, u, v; boundary=identity)

Sample (x, y, z) = f(u, v)given rangesuandv, apply tessellation and return meshx, t` in shared vertex representation.

The function boundary reassigns vertex indices: _rowsperiodic and _colsperiodic! create periodic "boundaries", _rowpoles! maps v boundaries to a single vertex. The boudary function takes an index grid as input and returns the same grid to enable concatenation, e.g., _rowsperiodic! ∘ _colsperiodic! for a torus.

The method "filters: unused vertex indices and invalid triangles.

source
PMesh.Meshes.cube — Method
mesh = cube([; triangulate=false, template::Mesh])

Create standard cube with each quad optionally split into two triangles.

source
PMesh.Meshes.cylinder — Method
mesh = cylinder([; rh=1, h=1, m=8, n=8,
                   triangles=true, closed=false, template::Mesh])

Generate cylinder mesh with radius r and heighthtessellated on am × n` grid of faces.

See also sphere

source
PMesh.Meshes.ngon — Method
mesh = ngon([;n = 6, r=A(t), α=B(t), template::Mesh])

Create 3d mesh of a n-gon.

The functions r(t) and α(t)determine the vertex positions fort = [0, 1/n, ..., (n-1)/m]. The default positions boundary vertices regularly on the unit circle in thex-y-plane`.

See also nring

source
PMesh.Meshes.nring — Method
mesh = nring([;n = 6, r=A(t), α=B(t), template::Mesh])

Create 3d mesh of a 1-ring with n neighbors around the center vertex VHnd(1) at (0, 0, 0).

The functions r(t) and α(t) determine the vertex positions for t = [0, 1/n, ..., (n-1)/m]. The default positions boundary vertices regularly on the unit circle in the x-y-plane.

See also ngon

source
PMesh.Meshes.rectangle — Method
mesh = rectangle([; w=1.0, h=1.0, triangles=true, z=(x, y) -> 0.0,
                    template::Mesh])

Generate a rectangular patch with width w and height h tessellated on a m × n grid of faces. Optionally lift third coordinate to z(x, y).

See also sphere

source
PMesh.Meshes.sphere — Method
mesh = sphere([; r=1, m=8 ,n=m, triangles=true, template::Mesh])

Generate sphere mesh with radius r tessellated on a m × n grid of faces (with two poles).

See also torus

source
PMesh.Meshes.torus — Method
mesh = torus([; ro=1, ri=0.25, m=8, n=8, triangles=true, template::Mesh])

Generate torus mesh with outer radius ro and inner ("tube") radiusritessellated on am × n` grid of faces.

See also sphere

source
PMesh.Meshes.wing — Method
mesh = wing([; template::Mesh])

Create planar 3d mesh with two triangles, which triangulate a quad.

source

Simple attribute maps

PMesh.Maps provides a set of simple maps for attributes, mainly projections into a subset of components (e.g., xyz -> xy).

Tip

Use with map! and Virtual attributes.

import PMesh.Maps

v = SVector(1, 2, 3)

p = proj(1, 2)      # projection onto 1st and 2nd component
p(v)                # gives SVector(1, 2)

xy(v) == p(v)
PMesh.Maps.proj — Function
xy = proj(1, 2)
xy(@SVector [2.0, 3.0, 5.0]) # == SVector(2.0, 3.0)

Construct function f(x) that projects onto indexed elements of x.

p = proj(SVector(i, j, ...))
p = proj((i, j, ...))
p = proj(i, j, ...)

For all

p(x) == SVector(x[i], x[j], ...)
Note

This method collects indices in SVector, and projections yield SVectors.

See also Π

source