Scenes and 3D meshes

Mesh

A struct representing a 3D mesh. Every three vertices represents a triangle. Properties per triangle are stored in a dictionary of arrays.

Fields

• vertices: A vector containing the vertices of the mesh.
• properties: A dictionary containing additional properties of the mesh (arrays of properties per triangle).

Example

julia> v = [Vec(0.0, 0.0, 0.0), Vec(0.0, 1.0, 0.0), Vec(1.0, 0.0, 0.0)];

julia> p = Dict{Symbol, AbstractVector}(:normal => [Vec(0.0, 0.0, 1.0)]);

julia> m = Mesh(v, p);

Mesh(meshes)

Merge multiple meshes into a single one

Arguments

• meshes: Vector of meshes to merge.

Returns

A new Mesh object that is the result of merging all the input meshes.

Example

julia> e = Ellipse(length = 2.0, width = 2.0, n = 10);

julia> r = Rectangle(length = 10.0, width = 0.2);

julia> m = Mesh([e,r]);

Mesh(vertices)

Generate a triangular mesh from a vector of vertices.

Arguments

• vertices: List of vertices (each vertex implement as Vec).

Returns

A Mesh object.

Example

julia> verts = [Vec(0.0, 0.0, 0.0), Vec(0.0, 1.0, 0.0), Vec(1.0, 0.0, 0.0)];

julia> Mesh(verts);

Mesh(nt, type)

Generate a triangular dense mesh with enough memory allocated to store nt triangles. The behaviour is equivalent to generating an empty mesh but may be computationally more efficient when appending a large number of primitives. If a lower floating precision is required, this may be specified as an optional third argument as in Mesh(10, Float32).

Arguments

• nt: The number of triangles to allocate memory for.
• type: The floating-point precision type for the mesh data (default is Float64).

Returns

A Mesh object with no vertices or normals.

Example

julia> m = Mesh(1_000);

julia> nvertices(m);

julia> ntriangles(m);

julia> Mesh(1_000, Float32);

Mesh(type = Float64)

Generate an empty triangular dense mesh that represents a primitive or 3D scene. By default a Mesh object will only accept coordinates in double floating precision (Float64) but a lower precision can be generated by specifying the corresponding data type as in Mesh(Float32).

Arguments

• type: The floating-point precision type for the mesh data (default is Float64).

Returns

A Mesh object with no vertices or normals.

Example

julia> m = Mesh();

julia> nvertices(m);

julia> ntriangles(m);

julia> Mesh(Float32);

Vec(x, y, z)

3D vector or point with coordinates x, y and z.

julia> v = Vec(0.0, 0.0, 0.0);

julia> v = Vec(0f0, 0f0, 0f0);

BBox(pmin::Vec, pmax::Vec)

Build an axis-aligned bounding box given the vector of minimum (pmin) and maximum (pmax) coordinates.

Arguments

• pmin: The minimum coordinates of the bounding box.
• pmax: The maximum coordinates of the bounding box.

Examples

julia> p0 = Vec(0.0, 0.0, 0.0);

julia> p1 = Vec(1.0, 1.0, 1.0);

julia> box = BBox(p0, p1);

BBox(m::Mesh)

Build a tight axis-aligned bounding box around a Mesh object.

Arguments

• m: The mesh to build the bounding box around.

Examples

julia> m = Rectangle();

julia> box = BBox(m);

Ellipse(;length = 1.0, width = 1.0, n = 20)

Create a triangular mesh approximating an ellipse with dimensions given by length and width, discretized into n triangles (must be even) and standard location and orientation.

Arguments

• length = 1.0: The length of the ellipse.
• width = 1.0: The width of the ellipse.
• n = 20: The number of triangles to be used in the mesh.

Examples

julia> Ellipse(;length = 1.0, width = 1.0, n = 20);

HollowCone(;length = 1.0, width = 1.0, height = 1.0, n = 20)

Create a hollow cone with dimensions given by length, width and height, discretized into n triangles (must be even) and standard location and orientation.

Arguments

• length = 1.0: The length of the cone (distance between base and apex).
• width = 1.0: The width of the base of the cone.
• height = 1.0: The height of the base of the cone.
• n = 20: The number of triangles to be used in the mesh.

Examples

julia> HollowCone(;length = 1.0, width = 1.0, height = 1.0, n = 20);

HollowCube(;length = 1.0, width = 1.0, height = 1.0)

Create a hollow cube (a prism) with dimensions given by length, width and height, standard location and orientation.

Arguments

• length = 1.0: The length of the cube.
• width = 1.0: The width of the base of the cube.
• height = 1.0: The height of the base of the cube.

Examples

julia> HollowCube(;length = 1.0, width = 1.0, height = 1.0);

HollowCylinder(;length = 1.0, width = 1.0, height = 1.0, n = 40)

Create a hollow cylinder with dimensions given by length, width and height, discretized into n triangles (must be even) and standard location and orientation.

Arguments

• length = 1.0: The length of the cylinder (distance between bases).
• width = 1.0: The width of the base of the cylinder.
• height = 1.0: The height of the base of the cylinder.
• n = 40: The number of triangles to discretize the cylinder into.

Examples

julia> HollowCylinder(;length = 1.0, width = 1.0, height = 1.0, n = 40);

HollowFrustum(;length = 1.0, width = 1.0, height = 1.0, ratio = 1.0, n = 40)

Create a hollow frustum with dimensions given by length, width and height, discretized into n triangles (must be even) and standard location and orientation.

Arguments

• length = 1.0: The length of the frustum (distance between bases).
• width = 1.0: The width of the base of the frustum.
• height = 1.0: The height of the base of the frustum.
• ratio = 1.0: The ratio between the top and bottom base radii.
• n = 40: The number of triangles to discretize the frustum into.

Examples

julia> HollowFrustum(;length = 1.0, width = 1.0, height = 1.0, n = 40, ratio = 0.5);

O()

Returns the origin of the 3D coordinate system as a Vec object. By default, the coordinates will be in double floating precision (Float64) but it is possible to generate a version with lower floating precision as in O(Float32).

julia>  O();

julia>  O(Float32);

Rectangle(;length = 1.0, width = 1.0)

Create a rectangle with dimensions given by length and width, standard location and orientation.

Arguments

• length = 1.0: The length of the rectangle.
• width = 1.0: The width of the rectangle.

Examples

julia> Rectangle(;length = 1.0, width = 1.0);

SolidCone(;length = 1.0, width = 1.0, height = 1.0, n = 40)

Create a solid cone with dimensions given by length, width and height, discretized into n triangles (must be even) and standard location and orientation.

Arguments

• length = 1.0: The length of the cone (distance between base and apex).
• width = 1.0: The width of the base of the cone.
• height = 1.0: The height of the base of the cone.
• n = 40: The number of triangles to be used in the mesh.

Examples

julia> SolidCone(;length = 1.0, width = 1.0, height = 1.0, n = 40);

SolidCube(;length = 1.0, width = 1.0, height = 1.0)

Create a solid cube with dimensions given by length, width and height, standard location and orientation.

Arguments

• length = 1.0: The length of the cube.
• width = 1.0: The width of the base of the cube.
• height = 1.0: The height of the base of the cube.

Examples

julia> SolidCube(;length = 1.0, width = 1.0, height = 1.0);

SolidCylinder(;length = 1.0, width = 1.0, height = 1.0, n = 80)

Create a solid cylinder with dimensions given by length, width and height, discretized into n triangles (must be even) and standard location and orientation.

Arguments

• length = 1.0: The length of the cylinder (distance between bases).
• width = 1.0: The width of the base of the cylinder.
• height = 1.0: The height of the base of the cylinder.
• n = 80: The number of triangles to discretize the cylinder into.

Examples

julia> SolidCylinder(;length = 1.0, width = 1.0, height = 1.0, n = 80);

SolidFrustum(;length = 1.0, width = 1.0, height = 1.0, ratio = 1.0, n = 40)

Create a solid frustum with dimensions given by length, width and height, discretized into n triangles and standard location and orientation.

Arguments

• length = 1.0: The length of the frustum (distance between bases).
• width = 1.0: The width of the base of the frustum.
• height = 1.0: The height of the base of the frustum.
• ratio = 1.0: The ratio between the top and bottom base radii.
• n = 40: The number of triangles to discretize the frustum into.

Examples

julia> SolidFrustum(;length = 1.0, width = 1.0, height = 1.0, n = 40, ratio = 0.5);

Trapezoid(;length = 1.0, width = 1.0, ratio = 1.0)

Create a trapezoid with dimensions given by length and the larger width and the ratio between the smaller and larger widths. The trapezoid is generted at the standard location and orientation.

Arguments

• length = 1.0: The length of the trapezoid.
• width = 1.0: The larger width of the trapezoid (the lower base of the trapezoid).
• ratio = 1.0: The ratio between the smaller and larger widths.

Examples

julia> Trapezoid(;length = 1.0, width = 1.0, ratio = 1.0);

Triangle(;length = 1.0, width = 1.0)

Create a triangle with dimensions given by length and width, standard location and orientation.

Arguments

• length = 1.0: The length of the triangle.
• width = 1.0: The width of the triangle.

Examples

julia> Triangle(;length = 1.0, width = 1.0);

X(s)

Returns scaled vector in the direction of the X axis with length s as a Vec object using the same floating point precision as s.

julia>  X(1.0);

julia>  X(1f0) ;

X()

Returns an unit vector in the direction of the X axis as a Vec object. By default, the coordinates will be in double floating precision (Float64) but it is possible to generate a version with lower floating precision as in X(Float32).

julia>  X();

julia>  X(Float32);

Y(s)

Returns scaled vector in the direction of the Y axis with length s as a Vec object using the same floating point precision as s.

julia>  Y(1.0);

julia>  Y(1f0);

Y()

Returns an unit vector in the direction of the Y axis as a Vec object. By default, the coordinates will be in double floating precision (Float64) but it is possible to generate a version with lower floating precision as in Y(Float32).

julia>  Y();

julia>  Y(Float32);

Z(s)

Returns scaled vector in the direction of the Z axis with length s as a Vec object using the same floating point precision as s.

julia>  Z(1.0);

julia>  Z(1f0);

Z()

Returns an unit vector in the direction of the Z axis as a Vec object. By default, the coordinates will be in double floating precision (Float64) but it is possible to generate a version with lower floating precision as in Z(Float32).

julia>  Z();

julia>  Z(Float32);

add!(mesh1, mesh2; kwargs...)

Manually add a mesh to an existing mesh with optional properties captured as keywords. Make sure to be consistent with the properties (both meshes should end up with the same lsit of properties). For example, if the scene was created with :colors, then you should provide:colors`` for the new mesh as well.

Arguments

• mesh1: The current mesh we want to extend.
• mesh1: A new mesh we want to add.
• kwargs: Properties to be set per triangle in the new mesh.

Example

julia> t1 = Triangle(length = 1.0, width = 1.0);

julia> using ColorTypes: RGB

julia> add_property!(t1, :colors, rand(RGB));

julia> t2 = Rectangle(length = 5.0, width = 0.5);

julia> add!(t1, t2, colors = rand(RGB));

add_property!(m::Mesh, prop::Symbol, data, nt = ntriangles(m))

Add a property to a mesh. The property is identified by a name (prop) and is stored as an array of values (data), one per triangle. If the property already exists, the new data is appended to the existing property, otherwise a new property is created. It is possible to pass a single object for data, in which case the property will be set to the same value for all triangles.

Arguments

• mesh: The mesh to which the property is to be added.
• prop: The name of the property to be added as a Symbol.
• data: The data to be added to the property (an array or a single value).
• nt: The number of triangles to be assumed if data is not an array. By default this is the number of triangles in the mesh.

Returns

The mesh with updated properties.

Example

julia> r = Rectangle();

julia> add_property!(r, :absorbed_PAR, [0.0, 0.0]);

area(mesh::Mesh)

Total surface area of a mesh (as the sum of areas of individual triangles).

Arguments

• mesh: Mesh which area is to be calculated.

Returns

The total surface area of the mesh as a number.

Example

julia> r = Rectangle(length = 10.0, width = 0.2);

julia> area(r);

julia> r = Rectangle(length = 10f0, width = 0.2f0);

julia> area(r);

areas(m::Mesh)

A vector with the areas of the different triangles that form a mesh.

Arguments

• mesh: Mesh which areas are to be calculated.

Returns

A vector with the areas of the different triangles that form the mesh.

Example

julia> r = Rectangle(length = 10.0, width = 0.2);

julia> areas(r);

julia> r = Rectangle(length = 10f0, width = 0.2f0);

julia> areas(r);

get_triangle(m::Mesh, i)

Retrieve the vertices for the i-th triangle in a mesh.

Arguments

• mesh: The mesh from which to retrieve the triangle.
• i: The index of the triangle to retrieve.

Returns

A vector containing the three vertices defining the i-th triangle.

Example

julia> v = [Vec(0.0, 0.0, 0.0), Vec(0.0, 1.0, 0.0), Vec(1.0, 0.0, 0.0),
            Vec(0.0, 0.0, 0.0), Vec(0.0, 1.0, 0.0), Vec(0.0, 0.0, 1.0)];

julia> m = Mesh(v);

julia> get_triangle(m, 2);

load_mesh(filename, type = Float64)

Import a mesh from a file given by filename. Supported formats include stl, ply, obj and msh. By default, this will generate a Mesh object that uses double floating-point precision. However, a lower precision can be specified by passing the relevant data type as in load_mesh(filename, Float32).

Arguments

• filename: The path to the file containing the mesh.
• type: The floating-point precision type for the mesh data (default is Float64).

Example

julia> mesh = load_mesh("path/to/mesh.obj");

julia> mesh = load_mesh("path/to/mesh.obj", Float32);

normals(mesh::Mesh)

Retrieve the normals of a mesh.

Arguments

• mesh: The mesh from which to retrieve the normals.

Returns

A vector containing the normals of the mesh.

Example

julia> v = [Vec(0.0, 0.0, 0.0), Vec(0.0, 1.0, 0.0), Vec(1.0, 0.0, 0.0)];

julia> m = Mesh(v);

julia> normals(m);

ntriangles(mesh)

Extract the number of triangles in a mesh.

Arguments

• mesh: The mesh from which to extract the number of triangles.

Returns

The number of triangles in the mesh as an integer.

Example

julia> v = [Vec(0.0, 0.0, 0.0), Vec(0.0, 1.0, 0.0), Vec(1.0, 0.0, 0.0)];

julia> m = Mesh(v);

julia> ntriangles(m);

nvertices(mesh)

The number of vertices in a mesh.

Arguments

• mesh: The mesh from which to retrieve the number of vertices.

Returns

The number of vertices in the mesh as an integer.

Example

julia> v = [Vec(0.0, 0.0, 0.0), Vec(0.0, 1.0, 0.0), Vec(1.0, 0.0, 0.0)];

julia> m = Mesh(v);

julia> nvertices(m);

properties(mesh::Mesh)

Retrieve the properties of a mesh. Properties are stored as a dictionary with one entry per type of property. Each property is an array of objects, one per triangle. Each property is identified by a symbol (e.g.).

Arguments

• mesh: The mesh from which to retrieve the normals.

Returns

A vector containing the normals of the mesh.

Example

julia> r = Rectangle();

julia> add_property!(r, :absorbed_PAR, [0.0, 0.0]);

julia> properties(r);

rotate!(m::Mesh; x::Vec, y::Vec, z::Vec)

Rotate a mesh m to a new coordinate system given by x, y and z

rotatex!(m::Mesh, θ)

Rotate a mesh m around the x axis by angle θ.

Arguments

• m: The mesh to be scaled.
• θ: Angle of rotation in radians.

Examples

julia> m = Rectangle();

julia> θ = pi/2;

julia> rotatex!(m, θ)

rotatey!(m::Mesh, θ)

Rotate a mesh m around the y axis by angle θ.

Arguments

• m: The mesh to be scaled.
• θ: Angle of rotation in radians.

Examples

julia> m = Rectangle();

julia> θ = pi/2;

julia> rotatey!(m, θ);

rotatez!(m::Mesh, θ)

Rotate a mesh m around the z axis by angle θ.

Arguments

• m: The mesh to be scaled.
• θ: Angle of rotation in radians.

Examples

julia> m = Rectangle();

julia> θ = pi/2;

julia> rotatez!(m, θ);

save_mesh(mesh; fileformat = :STL_BINARY, filename)

Save a mesh into an external file using a variety of formats.

Arguments

• mesh: Object of type Mesh.
• fileformat: Format to store the mesh as symbol.
• filename: Name of the file in which to store the mesh as string.

Details

The fileformat should take one of the following arguments: :STL_BINARY, :STL_ASCII, :PLY_BINARY, :PLY_ASCII or :OBJ. Note that these names should be passed as symnols.

Example

julia> v = [Vec(0.0, 0.0, 0.0), Vec(0.0, 1.0, 0.0), Vec(1.0, 0.0, 0.0)];

julia> mesh = Mesh(v);

julia> save_mesh(mesh, fileformat = :STL_BINARY, filename = "path/to/mesh.bstl");

scale!(m::Mesh, vec::Vec)

Scale a mesh m along the three axes provided by vec.

Arguments

• m: The mesh to be scaled.
• vec: A vector containing the scaling factors for the x, y, and z axes.

Examples

julia> m = Rectangle();

julia> scaling_vector = Vec(2.0, 1.5, 3.0);

julia> scale!(m, scaling_vector);

translate!(m::Mesh, v::Vec)

Translate the mesh m by vector v.

Arguments

• m: The mesh to be translated.
• v: The vector by which the mesh is to be translated.

Examples

julia> m = Rectangle();

julia> v = Vec(2.0, 1.5, 3.0);

julia> translate!(m, v);

vertices(mesh::Mesh)

Retrieve the vertices of a mesh.

Arguments

• mesh: The mesh from which to retrieve the vertices.

Returns

A vector containing the vertices of the mesh.

Example

julia> v = [Vec(0.0, 0.0, 0.0), Vec(0.0, 1.0, 0.0), Vec(1.0, 0.0, 0.0)];

julia> m = Mesh(v);

julia> vertices(m);

eltype(mesh::Mesh)

Extract the the type used to represent coordinates in a mesh (e.g., Float64).

Fields

• mesh: The mesh from which to extract the element type.

Example

julia> v = [Vec(0.0, 0.0, 0.0), Vec(0.0, 1.0, 0.0), Vec(1.0, 0.0, 0.0)];

julia> m = Mesh(v);

julia> eltype(m);