Polyhedrons

Polyhedron mathematical functions; 3-polytope. More...

Collaboration diagram for Polyhedrons:

Files
file	polyhedron.scad
	Polyhedron shapes, conversions, properties, and tests functions.

Properties
function	polyhedron_area (c, f)
	Compute the surface area of a polyhedron in a Euclidean 3d-space. More...
function	polyhedron_tf_volume (c, f)
	Compute the signed volume of a triangulated polyhedron in a Euclidean 3d-space. More...
function	polyhedron_tf_centroid (c, f)
	Compute the center of mass of a triangulated polyhedron in a Euclidean 3d-space. More...

Usage Details

Polyhedron mathematical functions; 3-polytope.

Validation Summary

file	group	script	results	no test	skipped	passed	failed	warning
math/polyhedron.scad	Polyhedrons	Script	Results	3	0	0	0	0

No Failures

See complete validation results.

Requires:
include <omdl-base.scad>;

Conventions

All functions in this group operate on polyhedra defined by a list of 3d cartesian coordinates c and a list of faces f, following OpenSCAD's native polyhedron() convention:

• Coordinates are given as [[x,y,z], ...].
• Face vertex indices are ordered counter-clockwise when viewed from outside the solid (right-hand rule outward normal).
• Functions whose names include the tf infix require that all faces be triangulated (exactly 3 vertex indices per face). Non-triangulated meshes must be tessellated before being passed to these functions. Passing a face with fewer or more than 3 indices to a tf function produces undef in the corresponding term and will silently corrupt the result.

Function and/or Module Documentation

polyhedron_area()

function polyhedron_area	(	c	,
		f
	)

Compute the surface area of a polyhedron in a Euclidean 3d-space.

Parameters

c	<points-3d> A list of 3d cartesian coordinates [[x, y, z], ...].
f	<integer-list-list> A list of faces that enclose the polyhedron, where each face is a list of coordinate indexes. Faces may be polygons with any number of vertices >= 3 and need not be triangulated.

Returns

<decimal> The total surface area of the polyhedron in square units of the coordinate space.

The surface area is computed by summing the area of each face polygon via polygon3d_area(). Faces are not required to be triangular, but each face is assumed to be planar.

Example — unit cube (expected area = 6.0):

c = [[0,0,0],[1,0,0],[1,1,0],[0,1,0],
     [0,0,1],[1,0,1],[1,1,1],[0,1,1]];
 
f = [[0,3,2,1],[4,5,6,7],
     [0,1,5,4],[1,2,6,5],[2,3,7,6],[3,0,4,7]];
 
echo(polyhedron_area(c, f));  // ECHO: 6

polyhedron_tf_volume()

function polyhedron_tf_volume	(	c	,
		f
	)

Compute the signed volume of a triangulated polyhedron in a Euclidean 3d-space.

Parameters

c	<points-3d> A list of 3d cartesian coordinates [[x, y, z], ...].
f	<integer-list-3-list> A list of triangular faces that enclose the polyhedron, where each face is a list of exactly three coordinate indexes. Non-triangular faces must be tessellated before calling this function; any face with a vertex count other than 3 is skipped (contributing 0 to the sum) and a warning is implicitly indicated by an undef guard — see note below.

Returns

<decimal> The volume of the given polyhedron in cubic units of the coordinate space. The sign of the result is positive when face normals point outward (counter-clockwise winding per OpenSCAD convention) and negative otherwise.

Volume is computed using the divergence theorem applied to a signed tetrahedral decomposition. For each triangular face with vertices , the signed tetrahedral volume relative to the origin is:

The total volume is the sum over all faces:

This formula is exact for any closed, consistently wound triangulated mesh regardless of whether the mesh encloses the origin.

See Wikipedia: Polyhedron – Volume for background.

Note

All faces must be triangles (exactly 3 vertex indices) wound counter-clockwise when viewed from outside (OpenSCAD's native polyhedron() convention). Faces that do not satisfy len(fi)==3 are excluded from the summation via a filtered list comprehension, preventing silent undef corruption.

The result is a signed volume. Take abs() of the return value if the sign of winding is uncertain.

Example — unit cube triangulated (expected volume = 1.0):

c = [[0,0,0],[1,0,0],[1,1,0],[0,1,0],
     [0,0,1],[1,0,1],[1,1,1],[0,1,1]];
 
f = [[0,1,2],[0,2,3],[4,6,5],[4,7,6],
     [0,5,1],[0,4,5],[1,6,2],[1,5,6],
     [2,7,3],[2,6,7],[3,4,0],[3,7,4]];
 
echo(polyhedron_tf_volume(c, f));  // ECHO: 1

polyhedron_tf_centroid()

function polyhedron_tf_centroid	(	c	,
		f
	)

Compute the center of mass of a triangulated polyhedron in a Euclidean 3d-space.

Parameters

c	<points-3d> A list of 3d cartesian coordinates [[x, y, z], ...].
f	<integer-list-3-list> A list of triangular faces that enclose the polyhedron, where each face is a list of exactly three coordinate indexes. Non-triangular faces must be tessellated before calling this function.

Returns

<point-3d> The center of mass (centroid) of the solid polyhedron in the same coordinate space as c.

The centroid is computed via the divergence theorem using first- order midpoint quadrature. For each triangular face with vertices and signed weight

the centroid contribution is:

and the overall centroid is:

where is the signed volume returned by polyhedron_tf_volume(). Volume and the weighted centroid sum are computed in a single pass over the face list to avoid redundant iteration.

Approximation notice: midpoint quadrature is exact only when the integrand is linear over each face. For a flat triangulated mesh this is exact; for curved or high-curvature approximations the error is where is the maximum edge length.

See Wikipedia: Centroid for background.

Note

All faces must be triangles (exactly 3 vertex indices) wound counter-clockwise when viewed from outside (OpenSCAD's native polyhedron() convention), consistent with polyhedron_tf_volume(). Faces that do not satisfy len(fi)==3 are excluded from the summation.

Example — unit cube triangulated (expected centroid = [0.5, 0.5, 0.5]):

c = [[0,0,0],[1,0,0],[1,1,0],[0,1,0],
     [0,0,1],[1,0,1],[1,1,1],[0,1,1]];
 
f = [[0,1,2],[0,2,3],[4,6,5],[4,7,6],
     [0,5,1],[0,4,5],[1,6,2],[1,5,6],
     [2,7,3],[2,6,7],[3,4,0],[3,7,4]];
 
echo(polyhedron_tf_centroid(c, f));  // ECHO: [0.5, 0.5, 0.5]