API Reference

AbstractFace{N_indices, T} <: StaticVector{N_indices, T}

Parent type for all face types. The standard face type is typically a GLTriangleFace = NgonFace{3, GLIndex}.

abstract type AbstractGeometry{Dimension, T<:Number}

Base type for geometry types like GeometryPrimites and Polytopes.

AbstractMesh

An abstract mesh is a collection of Polytope elements (Simplices / Ngons). The connections are defined via faces(mesh) and the coordinates of the elements are returned by coordinates(mesh).

Circle{T}

An alias for a HyperSphere of dimension 2. (i.e. HyperSphere{2, T})

Cylinder{T}(origin::Point3, extremity::Point3, radius)

A Cylinder is a 3D primitive defined by an origin, an extremity (end point) and a radius.

FaceView(data, faces)

A FaceView is an alternative to passing a vertex attribute directly to a mesh. It bundles data with a new set of faces which may index that data differently from the faces defined in a mesh. This can be useful to avoid duplication in data.

For example, data can be defined per face by giving each face just one (repeated) index:

per_face_normals = FaceView(
    normals,                 # one per face
    FT.(eachindex(normals))  # with FT = facetype(mesh)
)

If you need a mesh with strictly per-vertex data, e.g. for rendering, you can use expand_faceviews(mesh) to convert every vertex attribute to be per-vertex. This will duplicate data and reorder faces as needed.

You can get the data of a FaceView with values(faceview) and the faces with faces(faceview).

HyperRectangle{N, T}

A HyperRectangle is a generalization of a rectangle into N-dimensions. Formally it is the cartesian product of intervals, which is represented by the origin and widths fields, whose indices correspond to each of the N axes.

HyperSphere{N, T}

A HyperSphere is a generalization of a sphere into N-dimensions. A center and radius, r, must be specified.

LineString(points::AbstractVector{<:Point})

A LineString is a collection of points connected by line segments.

Mat{R, C, T[, L]}(args::Union{UniformScaling, Tuple, AbstractMatrix})
Mat{R, C}(args::Union{Tuple, AbstractMatrix})
Mat{C}(args::Tuple)

Constructs a static Matrix from the given inputs. Can also take multiple numeric args. If only one size is given the matrix is assumed to be square.

Aliases

Mesh{PositionDim, PositionType, FaceType, VertexAttributeNames, VertexAttributeTypes, FaceVectorType} <: AbstractMesh{PositionDim, PositionType} <: AbstractGeometry{PositionDim, PositionType}

The type of a concrete mesh. The associated struct contains 3 fields:

struct Mesh{...}
    vertex_attributes::NamedTuple{VertexAttributeNames, VertexAttributeTypes}
    faces::FaceVectorType
    views::Vector{UnitRange{Int}}
end

A vertex typically carries multiple distinct pieces of data, e.g. a position, a normal, a texture coordinate, etc. We call those pieces of data vertex attributes. The vertex_attributes field contains the name and a collection <: AbstractVector or <: FaceView for each attribute. The n-th element of that collection is the value of the corresponding attribute for the n-th vertex.

#                   vertex       1        2        3
vertex_attributes[:position] = [pos1,    pos2,    pos3,    ...]
vertex_attributes[:normal]   = [normal1, normal2, normal3, ...]
...

A NamedTuple is used here to allow different meshes to carry different vertex attributes while also keeping things type stable. The constructor enforces a few restrictions:

• The first attribute must be named position and must have a Point{PositionDim, PositionType} eltype.
• Each vertex attribute must refer to the same number of vertices. (All vertex attributes defined by

AbstractVector must match in length. For FaceViews, the number of faces needs to match.)

See also: vertex_attributes, coordinates, normals, texturecoordinates, decompose, FaceView, expand_faceviews

The faces field is a collection <: AbstractVector{FaceType} containing faces that describe how vertices are connected. Typically these are (GL)TriangleFaces or QuadFaces, but they can be any collection of vertex indices <: AbstractFace.

See also: faces, decompose

The views field can be used to separate the mesh into mutliple submeshes. Each submesh is described by a "view" into the faces vector, i.e. submesh n uses mesh.faces[mesh.views[n]]. A Mesh can be constructed without views, which results in an empty views vector.

See also: merge, split_mesh

Mesh(faces[; views, attributes...])
Mesh(positions, faces[; views])
Mesh(positions, faces::AbstractVector{<: Integer}[; facetype = TriangleFace, skip = 1])
Mesh(; attributes...)

Constructs a mesh from the given arguments.

If positions are given explicitly, they are merged with other vertex attributes under the name position. Otherwise they must be part of attributes. If faces are not given attributes.position must be a FaceView.

Any other vertex attribute can be either an AbstractVector or a FaceView thereof. Every vertex attribute that is an AbstractVector must be sufficiently large to be indexable by mesh.faces. Every vertex attribute that is a FaceView must contain similar faces to mesh.faces, i.e. contain the same number of faces and have faces of matching length.

views can be defined optionally to implicitly split the mesh into multi sub-meshes. This is done by providing ranges for indexing faces which correspond to the sub-meshes. By default this is left empty.

MetaMesh(mesh; metadata...)
MetaMesh(positions, faces; metadata...)

Constructs a MetaMesh either from another mesh or by constructing another mesh with the given positions and faces. Any keyword arguments given will be stored in the meta field in MetaMesh.

This struct is meant to be used for storage of non-vertex data. Any vertex related data should be stored as a vertex attribute in Mesh. One example of such data is material data, which is defined per view in mesh.views, i.e. per submesh.

The metadata added to the MetaMesh can be manipulated with Dict-like operations (getindex, setindex!, get, delete, keys, etc). Vertex attributes can be accessed via fields and the same getters as mesh. The mesh itself can be retrieved with Mesh(metamesh).

MultiPoint(points::AbstractVector{AbstractPoint})

A collection of points

MultiPolygon(polygons::AbstractPolygon)

A collection of polygons

NgonFace{N, T}

A planar face connecting N vertices. Shorthands include:

• LineFace{T} = NgonFace{2,T}
• TriangleFace{T} = NgonFace{3,T}
• QuadFace{T} = NgonFace{4,T}
• GLTriangleFace = TriangleFace{GLIndex}

OffsetInteger{O, T}

OffsetInteger type mainly for indexing.

• O - The offset relative to Julia arrays. This helps reduce copying when

communicating with 0-indexed systems such as OpenGL.

Point{N, T}(args...)
Point{N, T}(args::Union{AbstractVector, Tuple, NTuple, StaticVector})

Constructs a Point of length N from the given arguments.

Note that Point and Vec don't follow strict mathematical definitions. Instead we allow them to be used interchangeably.

Aliases

Polygon(exterior::AbstractVector{<:Point})
Polygon(exterior::AbstractVector{<:Point}, interiors::Vector{<:AbstractVector{<:Point}})

Constructs a polygon from a set of exterior points. If interiors are given, each of them cuts away from the Polygon.

Polytope{Dim, T} <: AbstractGeometry{Dim, T}

A Polytope is the generalization of a Polygon to higher dimensions, i.e. a geometric object consisting of flat faces.

A Polygon and Ngon are both 2D Polytopes. A Simplex is the simplest Polytope in arbitrary dimensions.

Polytope(::Type{<: Point}, ::Type{<: AbstractNgonFace})

The Ngon Polytope element type when indexing an array of points with a SimplexFace

Polytope(::Type{Point{Dim,T}}, ::Type{<:AbstractSimplexFace{N}})

The Simplex Polytope element type when indexing an array of points with a SimplexFace

Polytope(::Type{<:NSimplex{N}}, P::Type{Point{NDim,T}})

The fully concrete Simplex type, when constructed from a point type!

Polytope(::Type{<: Ngon}, P::Type{<: Point})

The fully concrete Ngon type, when constructed from a point type!

Pyramid(middle::Point3, length::Real, width::Real)

A Pyramid is an axis-aligned primitive where the tip of the Pyramid extends by length from middle in z direction and the square base extends by width in ±x and ±y direction from middle.

const Rect{N,T} = HyperRectangle{N,T}

A rectangle in N dimensions, formally the cartesian product of intervals. See also HyperRectangle. Its aliases are

There is an additional unexported alias RectT that simply reverses the order of type parameters: RectT{T,N} == Rect{N,T}.

Rect(vals::Number...)

Rect(vals::Number...)

Rect constructor for individually specified intervals. e.g. Rect(0,0,1,2) has origin == Vec(0,0) and width == Vec(1,2)

Rect(points::AbstractArray{<: Point})

Construct a bounding box countaining all the given points.

Rect(primitive::GeometryPrimitive)

Construct a bounding box for the given primitive.

const Rect{N,T} = HyperRectangle{N,T}

A rectangle in N dimensions, formally the cartesian product of intervals. See also HyperRectangle. Its aliases are

There is an additional unexported alias RectT that simply reverses the order of type parameters: RectT{T,N} == Rect{N,T}.

const Rect{N,T} = HyperRectangle{N,T}

A rectangle in N dimensions, formally the cartesian product of intervals. See also HyperRectangle. Its aliases are

There is an additional unexported alias RectT that simply reverses the order of type parameters: RectT{T,N} == Rect{N,T}.

const Rect{N,T} = HyperRectangle{N,T}

A rectangle in N dimensions, formally the cartesian product of intervals. See also HyperRectangle. Its aliases are

There is an additional unexported alias RectT that simply reverses the order of type parameters: RectT{T,N} == Rect{N,T}.

const Rect{N,T} = HyperRectangle{N,T}

A rectangle in N dimensions, formally the cartesian product of intervals. See also HyperRectangle. Its aliases are

There is an additional unexported alias RectT that simply reverses the order of type parameters: RectT{T,N} == Rect{N,T}.

const Rect{N,T} = HyperRectangle{N,T}

A rectangle in N dimensions, formally the cartesian product of intervals. See also HyperRectangle. Its aliases are

There is an additional unexported alias RectT that simply reverses the order of type parameters: RectT{T,N} == Rect{N,T}.

const Rect{N,T} = HyperRectangle{N,T}

A rectangle in N dimensions, formally the cartesian product of intervals. See also HyperRectangle. Its aliases are

There is an additional unexported alias RectT that simply reverses the order of type parameters: RectT{T,N} == Rect{N,T}.

const Rect{N,T} = HyperRectangle{N,T}

A rectangle in N dimensions, formally the cartesian product of intervals. See also HyperRectangle. Its aliases are

There is an additional unexported alias RectT that simply reverses the order of type parameters: RectT{T,N} == Rect{N,T}.

const Rect{N,T} = HyperRectangle{N,T}

A rectangle in N dimensions, formally the cartesian product of intervals. See also HyperRectangle. Its aliases are

There is an additional unexported alias RectT that simply reverses the order of type parameters: RectT{T,N} == Rect{N,T}.

const Rect{N,T} = HyperRectangle{N,T}

A rectangle in N dimensions, formally the cartesian product of intervals. See also HyperRectangle. Its aliases are

There is an additional unexported alias RectT that simply reverses the order of type parameters: RectT{T,N} == Rect{N,T}.

const Rect{N,T} = HyperRectangle{N,T}

A rectangle in N dimensions, formally the cartesian product of intervals. See also HyperRectangle. Its aliases are

There is an additional unexported alias RectT that simply reverses the order of type parameters: RectT{T,N} == Rect{N,T}.

const Rect{N,T} = HyperRectangle{N,T}

A rectangle in N dimensions, formally the cartesian product of intervals. See also HyperRectangle. Its aliases are

There is an additional unexported alias RectT that simply reverses the order of type parameters: RectT{T,N} == Rect{N,T}.

Simplex{D, T<:Real, N}(points::NTuple{N, Point{D, T}})

A Simplex is a generalization of an N-dimensional tetrahedra and can be thought of as a minimal convex set containing the specified points.

• A 0-simplex is a point.
• A 1-simplex is a line segment.
• A 2-simplex is a triangle.
• A 3-simplex is a tetrahedron.

Note that this datatype is offset by one compared to the traditional mathematical terminology. So a one-simplex is represented as Simplex{2,T}. This is for a simpler implementation.

It applies to infinite dimensions. The structure of this type is designed to allow embedding in higher-order spaces by parameterizing on T.

Sphere{T}

An alias for a HyperSphere of dimension 3. (i.e. HyperSphere{3, T})

Tessellation(primitive, nvertices)

When generating a mesh from an abstract geometry, we can typically generate it at different levels of detail, i.e. with different amounts of vertices. The Tessellation wrapper allows you to specify this level of detail. When generating a mesh from a tessellated geometry, the added information will be passed to coordinates, faces, etc.

sphere = Sphere(Point3f(0), 1)
m1 = mesh(sphere) # uses a default value for tessellation
m2 = mesh(Tessellation(sphere, 64)) # uses 64 for tessellation
length(coordinates(m1)) != length(coordinates(m2))

For grid based tessellation, you can also use a tuple:

rect = Rect2(0, 0, 1, 1)
Tessellation(rect, (5, 5))

TupleView{T, N, Skip, A}

TupleView, groups elements of an array as tuples. N is the dimension of the tuple, M tells how many elements to skip to the next tuple. By default TupleView{N} defaults to skip N items.

a few examples:

x = [1, 2, 3, 4, 5, 6]
TupleView{2, 1}(x):
> [(1, 2), (2, 3), (3, 4), (4, 5), (5, 6)]

TupleView{2}(x):
> [(1, 2), (3, 4), (5, 6)]

TupleView{2, 3}(x):
> [(1, 2), (4, 5)]

TupleView{3, 1}(x):
> [(1, 2, 3), (2, 3, 4), (3, 4, 5), (4, 5, 6)]

TupleView can be used together with reinterpret:

x = [1, 2, 3, 4]
y = reinterpret(Point{2, Int}, TupleView{2, 1}(x))
> [Point(1, 2), Point(2, 3), Point(3, 4)]

Vec{N, T}(args...)
Vec{N, T}(args::Union{AbstractVector, Tuple, NTuple, StaticVector})

Constructs a Vec of length N from the given arguments.

Note that Point and Vec don't follow strict mathematical definitions. Instead we allow them to be used interchangeably.

Aliases

area(contour::AbstractVector{Point}})

Calculate the area of a polygon.

For 2D points, the oriented area is returned (negative when the points are oriented clockwise).

area(vertices::AbstractVector{Point{3}}, faces::AbstractVector{TriangleFace})

Calculate the area of all triangles.

area(vertices::AbstractVector{Point{3}}, face::TriangleFace)

Calculate the area of one triangle.

connect(points::AbstractVector{<: Point}, P::Type{<: Polytope{N}}, skip::Int = N)

Creates a view that connects a number of points to a Polytope P. Between each polytope, skip elements are skipped untill the next starts. Example: ```julia x = connect(Point[(1, 2), (3, 4), (5, 6), (7, 8)], Line, 2) x == [Line(Point(1, 2), Point(3, 4)), Line(Point(5, 6), Point(7, 8))]

convert_simplex(::Type{Face{2}}, f::Face{N})

Extract all line segments in a Face.

convert_simplex(::Type{Face{3}}, f::Face{N})

Triangulate an N-Face into a tuple of triangular faces.

convert_simplex(::Type{TargetType}, x)

Used to convert one object into another in decompose(::Type{TargetType}, xs).

coordinates(geometry)

Returns the positions/coordinates of a geometry.

This is allowed to return lazy iterators. Use decompose(ConcretePointType, geometry) to get a Vector{ConcretePointType} with ConcretePointType being something like Point3f.

decompose(::Type{TargetType}, primitive)
decompose(::Type{TargetType}, data::AbstractVector)

Dependent on the given type, extracts data from the primtive and converts its eltype to TargetType.

Possible TargetTypes:

• <: Point extracts and converts positions (calling coordinates())
• <: AbstractFace extracts and converts faces (calling faces())
• <: Normal{<: Vec} extracts and converts normals, potentially generating them (calling normals())
• <: UV{<: Vec} extracts and converts 2D texture coordinates, potentially generating them (calling texturecoordinates())
• <: UVW{<: Vec} extracts and converts 3D texture coordinates, potentially generating them (calling texturecoordinates())

decompose(facetype, contour::AbstractArray{<:Point})

Triangulate a Polygon without hole.

Returns a Vector{facetype} defining indexes into contour.

expand_faceviews(mesh::Mesh)

Returns the given mesh if it contains no FaceViews. Otherwise, generates a new mesh that contains no FaceViews, reordering and duplicating vertex atttributes as necessary. If the mesh has views they will be adjusted as needed to produce the same submeshes.

face_normals(positions::Vector{Point3{T}}, faces::Vector{<: NgonFace}[, target_type = Vec3{T}])

Compute face normals from the given positions and faces and returns an appropriate FaceView.

faces(geometry)

Returns the faces of a geometry.

This is allowed to return lazy iterators. Use decompose(ConcreteFaceType, geometry) to get a Vector{ConcreteFaceType} with ConcreteFaceType being something like GLTriangleFace.

uv_normal_mesh(primitive::GeometryPrimitive{N}[; pointtype = Point{N, Float32}, facetype = GLTriangleFace, uvtype = Vec2f, normaltype = Vec3f])

Creates a triangle mesh with texture coordinates and normals from a given primitive. The pointtype, facetype and uvtype and normaltype are set by the correspondering keyword arguments.

See also: triangle_mesh, normal_mesh, uv_mesh, uv_normal_mesh

normal_mesh(primitive::GeometryPrimitive{N}[; pointtype = Point{N, Float32}, facetype = GLTriangleFace, normaltype = Vec3f])

Creates a triangle mesh with normals from a given primitive. The pointtype, facetype and uvtype and normaltype are set by the correspondering keyword arguments.

See also: triangle_mesh, normal_mesh, uv_mesh, uv_normal_mesh

normals(primitive)

Returns the normals of a geometry.

This is allowed to return lazy iterators. Use decompose_normals(ConcreteVecType, geometry) to get a Vector{ConcreteVecType} with ConcreteVecType being something like Vec3f.

normals(positions::Vector{Point3{T}}, faces::Vector{<: NgonFace}[; normaltype = Vec3{T}])

Compute vertex normals from the given positions and faces.

This runs through all faces, computing a face normal each and adding it to every involved vertex. The direction of the face normal is based on winding direction and assumed counter-clockwise faces. At the end the summed face normals are normalized again to produce a vertex normal.

self_intersections(points::AbstractVector{<:Point})

Finds all self intersections of polygon points

split_intersections(points::AbstractVector{<: Point})

Splits polygon points into it's self intersecting parts. Only 1 intersection is handled right now.

texturecoordinates(primitive)

Returns the texturecoordinates of a geometry.

This is allowed to return lazy iterators. Use decompose_uv(ConcreteVecType, geometry) (or decompose_uvw) to get a Vector{ConcreteVecType} with ConcreteVecType being something like Vec2f.

triangle_mesh(primitive::GeometryPrimitive[; pointtype = Point, facetype = GLTriangleFace])

Creates a simple triangle mesh from a given primitive with the given pointtype and facetype.

See also: triangle_mesh, normal_mesh, uv_mesh, uv_normal_mesh

uv_mesh(primitive::GeometryPrimitive{N}[; pointtype = Point{N, Float32}, facetype = GLTriangleFace, uvtype = Vec2f])

Creates a triangle mesh with texture coordinates from a given primitive. The pointtype, facetype and uvtype are set by the correspondering keyword arguments.

See also: triangle_mesh, normal_mesh, uv_mesh, uv_normal_mesh

uv_normal_mesh(primitive::GeometryPrimitive{N}[; pointtype = Point{N, Float32}, facetype = GLTriangleFace, uvtype = Vec2f, normaltype = Vec3f])

Creates a triangle mesh with texture coordinates and normals from a given primitive. The pointtype, facetype and uvtype and normaltype are set by the correspondering keyword arguments.

See also: triangle_mesh, normal_mesh, uv_mesh, uv_normal_mesh

vertex_attributes(mesh::Mesh)

Returns a dictionairy containing the vertex attributes of the given mesh. Mutating these will change the mesh.

volume(mesh)

Calculate the signed volume of all tetrahedra. Be sure the orientation of your surface is right.

volume(triangle)

Calculate the signed volume of one tetrahedron. Be sure the orientation of your surface is right.

Ngon{D, T, N}(points::NTuple{N, Point{D, T}})

Defines a flat polygon (without holes) in D dimensional space using N points, e.g.:

• N 1-2 : Illegal!
• N = 3 : Triangle
• N = 4 : Quadrilateral (or Quad, Or tetragon)
• N = 5 : Pentagon
• ...

For polygons with holes, see Polygon.

const Rect{N,T} = HyperRectangle{N,T}

A rectangle in N dimensions, formally the cartesian product of intervals. See also HyperRectangle. Its aliases are

There is an additional unexported alias RectT that simply reverses the order of type parameters: RectT{T,N} == Rect{N,T}.

*(m::Mat, h::Rect)

Transform a Rect using a matrix. Maintains axis-align properties so a significantly larger Rect may be generated.

in(b1::Rect, b2::Rect)

Check if Rect b1 is contained in b2. This does not use strict inequality, so Rects may share faces and this will still return true.

in(pt::VecTypes, b1::Rect{N, T})

Check if a point is contained in a Rect. This will return true if the point is on a face of the Rect.

in(point, triangle)

Determine if a point is inside of a triangle.

intersect(h1::Rect, h2::Rect)

Perform a intersection between two Rects.

isempty(h::Rect)

Return true if any of the widths of h are negative.

merge(meshes::AbstractVector{Mesh})

Generates a new mesh containing all the data of the individual meshes.

If all meshes are consistent in their use of FaceViews they will be preserved. Otherwise all of them will be converted with expand_faceviews(mesh).

This function will generate views in the new mesh which correspond to the inputs of this function.

union(r1::Rect{N}, r2::Rect{N})

Returns a new Rect{N} which contains both r1 and r2.

mesh(primitive::GeometryPrimitive[; pointtype = Point, facetype = GLTriangleFace, vertex_attributes...])

Creates a mesh from a given primitive with the given pointtype and facetype.

This method only generates positions and faces from the primitive. Additional vertex attributes like normals and texture coordinates can be given as extra keyword arguments.

Note that vertex attributes that are nothing get removed before creating a mesh.

See also: triangle_mesh, normal_mesh, uv_mesh, uv_normal_mesh

mesh(polygon::AbstractVector{P}; pointtype=P, facetype=GLTriangleFace)

Create a mesh from a polygon given as a vector of points, using triangulation.

mesh(positions, faces[, facetype = GLTriangleFace, vertex_attributes...])

Creates a mesh from the given positions and faces. Other vertex attributes like normals and texture coordinates can be added as keyword arguments.

Note that vertex attributes that are nothing get removed before creating a mesh.

See also:normal_mesh

mesh(mesh::Mesh[; pointtype = Point, facetype = GLTriangleFace, vertex_attributes...]

Recreates the given mesh with the given pointtype, facetype and vertex attributes. If the new mesh would match the old mesh, the old mesh is returned instead.

Note that vertex attributes that are nothing get removed before creating a mesh.

orthogonal_vector(p1, p2, p3)

Calculates an orthogonal vector cross(p2 - p1, p3 - p1) to a plane described by 3 points p1, p2, p3.

remove_duplicates(faces)

Uses a Dict to remove duplicates from the given faces.

split(rectangle, axis, value)

Splits an Rect into two along an axis at a given location.

split_mesh(mesh::Mesh, views::Vector{UnitRange{Int}} = mesh.views)

Creates a new mesh containing faces(mesh)[range] for each range in views. This also removes unused vertices.