Modules

geometor.polyhedra

GEOMETOR Polyhedra.

Exact symbolic Platonic, Archimedean, Catalan, and Keplerian polyhedral geometry in SymPy, Rational Trigonometry, and the GEOMETOR Digital Scriptorium.

Submodules

Attributes

PHI

PHI_INV

SQRT_PHI

__version__

Classes

PolyhedronEntry

Exact symbolic catalog entry for a polyhedral manifold.

PolyhedronFamily

Specification of a thematic polyhedral family in the catalog.

GoldenPolyhedronTheorem

Exact symbolic specification of a golden proportion theorem in polyhedra.

Line3D

Exact 3D line passing through two distinct points.

Plane3D

Exact 3D plane represented by algebraic equation a*x + b*y + c*z + d = 0.

Point3D

Exact 3D symbolic point over algebraic number fields.

Solid3D

Exact 3D polyhedral manifold with oriented face cycles and metadata.

Sphere3D

Exact 3D sphere defined by center and quadrance.

Vector3D

Exact 3D symbolic vector over algebraic number fields.

RegularSolid

Exact symbolic specification of a regular convex Platonic solid.

PyramidModelProfile

Exact symbolic specification of a Great Pyramid architectural or geometric model.

Functions

build_catalog_solid(slug) → geometor.polyhedra.model3d.primitives.Solid3D

Constructs an exact 3D solid for any of the 26 canonical polyhedra.

build_pentagonal_pyramid_solid(*[, center_origin]) → geometor.polyhedra.model3d.primitives.Solid3D

Constructs the exact equilateral Regular Pentagonal Pyramid (Johnson Solid J2).

build_rhombicuboctahedron_solid() → geometor.polyhedra.model3d.primitives.Solid3D

Constructs Leonardo's 26-Base Body (Vigintisex Basium, Rhombicuboctahedron).

get_polyhedra_catalog() → dict[str, PolyhedronEntry]

Retrieves all 26 canonical polyhedra mapped by slug.

get_polyhedra_families() → dict[str, PolyhedronFamily]

Retrieves all five polyhedral families mapped by slug.

get_polyhedron_entry(slug) → PolyhedronEntry

Retrieves a single polyhedron entry by slug name.

build_dodecahedron_five_cubes() → DodecahedronFiveCubesResult

Finds and certifies all five regular cubes inscribed in the dodecahedron.

build_icosahedron_golden_rectangles() → GoldenRectanglesResult

Extracts and certifies the three mutually orthogonal golden rectangles in the icosahedron.

build_icosahedron_meridian_model() → tuple[geometor.model.Model, dict[str, sympy.Expr]]

Constructs the exact 2D principal meridian section of the icosahedron.

build_octahedron_golden_icosahedron() → OctahedronGoldenIcosahedronResult

Divides the twelve edges of a regular octahedron in the golden ratio.

build_odom_tetrahedron_section_model() → tuple[geometor.model.Model, dict[str, sympy.Expr]]

Constructs George Odom's golden section on the regular tetrahedron face circumcircle.

build_pentagon_cross_section_model() → tuple[geometor.model.Model, dict[str, sympy.Expr]]

Constructs the regular pentagon and pentagram section over Q(phi, sqrt(5 - sqrt(5))).

build_rhombic_triacontahedron_golden() → RhombicTriacontahedronResult

Constructs the exact 32-vertex Rhombic Triacontahedron over Q(phi).

get_golden_theorem(slug) → GoldenPolyhedronTheorem

Retrieves a single golden proportion theorem by slug name.

get_golden_theorems() → dict[str, GoldenPolyhedronTheorem]

Retrieves all canonical golden proportion theorems in polyhedra.

slice_solid_to_model(solid, plane, u_axis, v_axis[, ...]) → geometor.model.Model

Computes exact planar cross-section of a Solid3D and constructs a 2D Model.

unfold_net_2d(solid[, root_face]) → list[dict[str, object]]

Unfolds faces of a Solid3D onto a 2D plane via dual graph BFS spanning tree.

elevate(solid[, height_scale]) → geometor.polyhedra.model3d.primitives.Solid3D

Constructs Pacioli/Leonardo's stellation (Elevatum / Conway kis).

polar_dual(solid[, sphere_quadrance]) → geometor.polyhedra.model3d.primitives.Solid3D

Constructs exact polar dual of an origin-centered polyhedral solid.

rectify(solid) → geometor.polyhedra.model3d.primitives.Solid3D

Constructs Pacioli's edge-midpoint truncation (Abscisum).

truncate(solid[, ratio]) → geometor.polyhedra.model3d.primitives.Solid3D

Constructs Archimedean corner truncation at an exact rational ratio.

vacuate(solid[, aperture, shell]) → geometor.polyhedra.model3d.primitives.Solid3D

Constructs Leonardo da Vinci's hollow manifold (Corpus Vacuum).

cross_3d(u, v) → tuple[sympy.Expr, sympy.Expr, sympy.Expr]

Computes the exact cross product of two 3D vectors.

dihedral_spread_3d(n1, n2) → sympy.Expr

Computes the exact dihedral spread (sin^2 theta) between two face normals.

dot_3d(u, v) → sympy.Expr

Computes the exact dot product of two 3D vectors.

face_normal_3d(vertices, face) → tuple[sympy.Expr, sympy.Expr, sympy.Expr]

Computes the unnormalized outward normal vector of a planar face.

get_platonic_solid(slug) → RegularSolid

Retrieves a single Platonic solid by slug name.

get_platonic_solids() → dict[str, RegularSolid]

Retrieves all five Platonic solids mapped by slug.

quadrance_3d(v) → sympy.Expr

Computes the exact 3D quadrance (squared Euclidean norm) of a vector.

build_kepler_bipyramid_solid() → geometor.polyhedra.model3d.primitives.Solid3D

Constructs the exact 3D Golden Square Bipyramid over Q(sqrt(phi)).

build_kepler_pyramid_solid(*[, center_origin]) → geometor.polyhedra.model3d.primitives.Solid3D

Constructs the exact 3D Solid3D model of the Kepler Golden Pyramid over Q(sqrt(phi)).

build_kepler_triangle_model() → tuple[geometor.model.Model, dict[str, sympy.Expr]]

Constructs the exact 2D Kepler Right Triangle model over Q(sqrt(phi)).

build_pyramid_squaring_circle_model() → tuple[geometor.model.Model, dict[str, sympy.Expr]]

Constructs the Great Pyramid Squaring the Circle & Earth-Moon Cosmogram in 2D.

build_seked_pyramid_solid(*[, royal_cubits, center_origin]) → geometor.polyhedra.model3d.primitives.Solid3D

Constructs the exact 3D Solid3D model of the Seked 14:11 Khufu Pyramid.

get_great_pyramid_profile(slug) → PyramidModelProfile

Retrieves a single Great Pyramid model profile by slug.

get_great_pyramid_profiles() → dict[str, PyramidModelProfile]

Returns mapping of canonical Great Pyramid model profiles.

verify_kepler_pyramid_identities() → dict[str, tuple[sympy.Expr, sympy.Expr]]

Certifies the eleven foundational exact identities of the Great Pyramid models.

export_blender_script(solids, script_path[, spacing]) → pathlib.Path

Emits a standalone Blender 5.x Python script generating a studio showcase.

export_ingetrazo_script(solids, script_path[, spacing]) → pathlib.Path

Emits a runnable Python script for IngeTrazo 0.6.0 CAD modeler.

export_obj_mtl(solid, obj_path) → tuple[pathlib.Path, pathlib.Path]

Exports a Solid3D to Wavefront .obj and companion .mtl material library.

render_model2d_svg(model, *[, golden_segments, width, ...]) → str

Renders a 2D GEOMETOR symbolic Model to publication-grade SVG.

render_net_svg(solid, *[, width, height, graphic_id]) → str

Renders unfolded 2D papercraft net layout of a Solid3D to SVG.

render_solid_svg(solid, *[, yaw_deg, pitch_deg, ...]) → str

Renders a 3D polyhedral solid to publication-grade theme-adaptive SVG.

Package Contents

class geometor.polyhedra.PolyhedronEntry

Exact symbolic catalog entry for a polyhedral manifold.

Variables:
  • slug – Short lowercase identifier.

  • canonical_id – Canonical catalog code (‘P-01.01’ .. ‘P-05.04’).

  • family – Family slug.

  • order – Order index within family.

  • title – Standard English title.

  • latin_name – Classical Latin designation.

  • subtitle – Descriptive subtitle.

  • enunciation – Crisp geometric definition.

  • number_field – Algebraic number field in LaTeX.

  • symmetry_group – Full symmetry point group and order.

  • is_convex – Whether the solid is convex.

  • dual_slug – Polar dual slug or descriptive name.

  • historical_source – Primary literature citation.

  • leonardo_plates – Tuples of (tabula_roman, folio_id, latin_caption).

  • tags – Categorical search and indexing tags.

  • vertices_count – Number of vertices (V).

  • edges_count – Number of edges (E).

  • faces_count – Number of faces (F).

  • face_summary – Description of constituent polygon faces.

  • edge_quadrances – Sorted unique exact edge quadrances.

  • vertex_quadrances – Sorted unique exact vertex quadrances from origin.

  • primary_dihedral_spread – Exact dihedral spread between adjacent faces.

  • vacuum_genus – Topological genus of the hollow vacuate manifold (F - 1).

slug: str
canonical_id: str
family: str
order: int
title: str
latin_name: str
subtitle: str
enunciation: str
number_field: str
symmetry_group: str
is_convex: bool
dual_slug: str | None
historical_source: str
leonardo_plates: tuple[tuple[str, str, str], ...]
tags: tuple[str, ...]
vertices_count: int
edges_count: int
faces_count: int
face_summary: str
edge_quadrances: tuple[sympy.Expr, ...]
vertex_quadrances: tuple[sympy.Expr, ...]
primary_dihedral_spread: sympy.Expr | None
vacuum_genus: int
__post_init__() → None

Validates exact algebraic parameters.

class geometor.polyhedra.PolyhedronFamily

Specification of a thematic polyhedral family in the catalog.

Variables:
  • slug – Unique identifier (‘01-platonic’, ‘02-archimedean’, etc.).

  • order – Order index in catalog (1..5).

  • title – Descriptive title of the family.

  • subtitle – Scholarly subtitle.

  • summary – Mathematical and historical summary.

slug: str
order: int
title: str
subtitle: str
summary: str
geometor.polyhedra.build_catalog_solid(slug: str) → geometor.polyhedra.model3d.primitives.Solid3D

Constructs an exact 3D solid for any of the 26 canonical polyhedra.

Parameters:

slug – Canonical identifier for one of the 26 cataloged solids.

Returns:

Exact Solid3D instance.

Raises:

KeyError – If slug is not recognized.

geometor.polyhedra.build_pentagonal_pyramid_solid(*, center_origin: bool = True) → geometor.polyhedra.model3d.primitives.Solid3D

Constructs the exact equilateral Regular Pentagonal Pyramid (Johnson Solid J2).

Constructed directly from the 6-vertex icosahedral cap of Euclid Elements XIII.16 and Leonardo da Vinci’s Tabulae LI–LII over Q(phi).

Parameters:

center_origin – If True (default), translates vertices by -C so the centroid is at (0, 0, 0), placing the origin strictly inside the solid for manifold orientation and vacuation. If False, retains raw icosahedral coordinates.

Returns:

Exact symbolic Solid3D instance.

geometor.polyhedra.build_rhombicuboctahedron_solid() → geometor.polyhedra.model3d.primitives.Solid3D

Constructs Leonardo’s 26-Base Body (Vigintisex Basium, Rhombicuboctahedron).

Generates the exact Archimedean rhombicuboctahedron over Q(sqrt(2)) with 24 vertices, 48 edges of uniform quadrance 4, and 26 faces (6 axial squares, 12 chamfer squares, and 8 octant equilateral triangles).

Returns:

Exact symbolic Solid3D instance centered at the origin.

geometor.polyhedra.get_polyhedra_catalog() → dict[str, PolyhedronEntry]

Retrieves all 26 canonical polyhedra mapped by slug.

Returns:

Dictionary mapping solid slug to PolyhedronEntry instances.

geometor.polyhedra.get_polyhedra_families() → dict[str, PolyhedronFamily]

Retrieves all five polyhedral families mapped by slug.

Returns:

Dictionary mapping family slugs (‘01-platonic’ .. ‘05-pyramids’) to PolyhedronFamily instances.

geometor.polyhedra.get_polyhedron_entry(slug: str) → PolyhedronEntry

Retrieves a single polyhedron entry by slug name.

Parameters:

slug – Standard slug identifier (‘tetrahedron’, ‘rhombicuboctahedron’, etc.).

Returns:

Corresponding PolyhedronEntry instance.

Raises:

KeyError – If slug is not recognized.

class geometor.polyhedra.GoldenPolyhedronTheorem

Exact symbolic specification of a golden proportion theorem in polyhedra.

Variables:
  • slug – Short lowercase identifier (‘icosahedron_golden_rectangles’, etc.).

  • title – Standard English title of the theorem or construction.

  • subtitle – Descriptive subtitle highlighting key geometric properties.

  • historical_source – Scholarly citation (Euclid, Pacioli, Kepler, Odom).

  • summary – Concise mathematical summary of the theorem and geometric proof.

  • golden_identities – Sequence of (description, lhs, rhs) triples where lhs - rhs simplifies to exact zero.

slug: str
title: str
subtitle: str
historical_source: str
summary: str
golden_identities: tuple[tuple[str, sympy.Expr, sympy.Expr], ...]
geometor.polyhedra.build_dodecahedron_five_cubes() → DodecahedronFiveCubesResult

Finds and certifies all five regular cubes inscribed in the dodecahedron.

Euclid Elements XIII.17 constructs the regular dodecahedron upon an inscribed cube by adding roof-like wedges above each square face. There are five distinct inscribed regular cubes whose 60 edges partition all 60 diagonals of the twelve pentagonal faces.

Returns:

DodecahedronFiveCubesResult containing dodecahedron geometry and the five cubes.

geometor.polyhedra.build_icosahedron_golden_rectangles() → GoldenRectanglesResult

Extracts and certifies the three mutually orthogonal golden rectangles in the icosahedron.

Euclid Elements XIII.16 shows that the twelve vertices of a regular icosahedron form the vertices of three congruent golden rectangles whose planes are pairwise perpendicular and meet at the center of the circumscribing sphere.

Returns:

GoldenRectanglesResult certifying rectangle dimensions, orthogonality, and edges.

geometor.polyhedra.build_icosahedron_meridian_model() → tuple[geometor.model.Model, dict[str, sympy.Expr]]

Constructs the exact 2D principal meridian section of the icosahedron.

In the principal plane X = 0, the canonical regular icosahedron has four vertices forming a golden rectangle (±1, ±phi) and two equatorial crossings at (±phi, 0) in (Y, Z) coordinates.

Returns:

Tuple of (Model, metrics_dict) certifying golden proportions in the meridian slice.

geometor.polyhedra.build_octahedron_golden_icosahedron() → OctahedronGoldenIcosahedronResult

Divides the twelve edges of a regular octahedron in the golden ratio.

Starts with a regular octahedron of scale phi^2 = phi + 1 whose vertices lie along the coordinate axes: (±phi^2, 0, 0), (0, ±phi^2, 0), (0, 0, ±phi^2). Dividing each directed edge in the golden ratio AG : GB = 1 : phi yields the exact twelve vertices of the canonical regular icosahedron.

Returns:

OctahedronGoldenIcosahedronResult containing octahedron geometry and inscribed icosahedron.

geometor.polyhedra.build_odom_tetrahedron_section_model() → tuple[geometor.model.Model, dict[str, sympy.Expr]]

Constructs George Odom’s golden section on the regular tetrahedron face circumcircle.

In 1983, George Odom discovered that connecting the midpoints of two sides of an equilateral triangle inscribed in a circle and extending the line to meet the circle divides the chord in the exact golden ratio.

Returns:

Tuple of (Model, metrics_dict) with certified exact golden proportions.

geometor.polyhedra.build_pentagon_cross_section_model() → tuple[geometor.model.Model, dict[str, sympy.Expr]]

Constructs the regular pentagon and pentagram section over Q(phi, sqrt(5 - sqrt(5))).

Euclid Elements XIII.8 demonstrates that the diagonals of a regular pentagon cut one another in extreme and mean ratio (the golden ratio). This configuration represents the vertex figure of the icosahedron and the face of the dodecahedron.

Returns:

Tuple of (Model, metrics_dict) certifying pentagon-pentagram golden proportions.

geometor.polyhedra.build_rhombic_triacontahedron_golden() → RhombicTriacontahedronResult

Constructs the exact 32-vertex Rhombic Triacontahedron over Q(phi).

Unites the twenty vertices of the canonical regular dodecahedron with the twelve vertices of the dual-oriented regular icosahedron. Each of the thirty faces is a planar golden rhombus whose long diagonal joins two acute degree-5 icosahedral vertices and whose short diagonal joins two obtuse degree-3 dodecahedral vertices, with diagonal quadrance ratio equal to phi^2.

Returns:

RhombicTriacontahedronResult specifying vertices, rhombic faces, and metric ratios.

geometor.polyhedra.get_golden_theorem(slug: str) → GoldenPolyhedronTheorem

Retrieves a single golden proportion theorem by slug name.

Parameters:

slug – Short lowercase identifier (‘icosahedron_golden_rectangles’, etc.).

Returns:

The corresponding GoldenPolyhedronTheorem instance.

Raises:

KeyError – If slug is not recognized.

geometor.polyhedra.get_golden_theorems() → dict[str, GoldenPolyhedronTheorem]

Retrieves all canonical golden proportion theorems in polyhedra.

Returns:

Dictionary mapping theorem slugs to GoldenPolyhedronTheorem instances.

class geometor.polyhedra.Line3D

Exact 3D line passing through two distinct points.

Variables:
  • p1 – First point on line.

  • p2 – Second point on line.

p1: Point3D
p2: Point3D
direction() → Vector3D

Returns direction vector from p1 to p2.

class geometor.polyhedra.Plane3D

Exact 3D plane represented by algebraic equation a*x + b*y + c*z + d = 0.

Variables:
  • a – Coefficient for x.

  • b – Coefficient for y.

  • c – Coefficient for z.

  • d – Constant term.

a: sympy.Expr
b: sympy.Expr
c: sympy.Expr
d: sympy.Expr
__post_init__() → None

Validates exact algebraic coefficients.

classmethod from_points(p1: Point3D, p2: Point3D, p3: Point3D) → Plane3D

Constructs plane passing through three non-collinear points.

Parameters:
  • p1 – First point.

  • p2 – Second point.

  • p3 – Third point.

Returns:

Plane3D passing through p1, p2, and p3.

Raises:

ValueError – If points are collinear.

classmethod from_normal_point(normal: Vector3D, point: Point3D) → Plane3D

Constructs plane from normal vector and point on plane.

Parameters:
  • normal – Non-zero normal vector.

  • point – Point lying on plane.

Returns:

Plane3D with given normal containing point.

Raises:

ValueError – If normal vector is zero.

normal() → Vector3D

Returns normal vector (a, b, c).

eval_point(pt: Point3D) → sympy.Expr

Evaluates linear form a*pt.x + b*pt.y + c*pt.z + d.

contains(pt: Point3D) → bool

Tests whether point lies exactly on plane.

intersect_segment(p1: Point3D, p2: Point3D) → Point3D | None

Computes exact intersection point of segment [p1, p2] with plane.

Parameters:
  • p1 – Segment start point.

  • p2 – Segment end point.

Returns:

Exact Point3D if segment intersects plane, or None otherwise.

class geometor.polyhedra.Point3D

Exact 3D symbolic point over algebraic number fields.

Variables:
  • x – Exact X coordinate.

  • y – Exact Y coordinate.

  • z – Exact Z coordinate.

  • label – Optional symbolic label.

x: sympy.Expr
y: sympy.Expr
z: sympy.Expr
label: str = ''
__post_init__() → None

Validates exact algebraic coordinates.

vector_to(other: Point3D) → Vector3D

Returns displacement vector from self to other.

quadrance_to(other: Point3D) → sympy.Expr

Returns exact quadrance (squared Euclidean distance) to other.

lerp(other: Point3D, t: sympy.Expr | int) → Point3D

Computes exact linear interpolation (1 - t)*self + t*other.

scale(factor: sympy.Expr | int) → Point3D

Scales point coordinates from origin by exact factor.

to_tuple() → tuple[sympy.Expr, sympy.Expr, sympy.Expr]

Returns coordinate 3-tuple.

to_vector() → Vector3D

Returns position vector from origin to this point.

__add__(vec: Vector3D) → Point3D

Translates point by a vector.

class geometor.polyhedra.Solid3D

Exact 3D polyhedral manifold with oriented face cycles and metadata.

Variables:
  • slug – Short lowercase identifier.

  • title – Descriptive human-readable title.

  • vertices – Sequence of exact 3D vertices.

  • faces – Sequence of oriented face cycles (indices in counter-clockwise order).

  • edges – Sorted sequence of unique undirected edge index pairs (i, j) with i < j.

  • face_roles – Role tags corresponding to each face in faces sequence.

slug: str
title: str
vertices: tuple[Point3D, ...]
faces: tuple[tuple[int, ...], ...]
edges: tuple[tuple[int, int], ...] = ()
face_roles: tuple[str, ...] = ()
__post_init__() → None

Normalizes edges and face roles.

classmethod from_regular_solid(solid: geometor.polyhedra.platonic.RegularSolid) → Solid3D

Constructs Solid3D from a RegularSolid instance.

Parameters:

solid – Exact symbolic RegularSolid instance.

Returns:

Corresponding Solid3D instance.

property num_vertices: int

Returns number of vertices.

property num_edges: int

Returns number of edges.

property num_faces: int

Returns number of faces.

property euler_characteristic: int

Returns Euler characteristic V - E + F.

property genus: int

Returns topological genus (2 - chi) // 2.

face_centroid(face_idx: int) → Point3D

Computes exact centroid of a face.

Parameters:

face_idx – Index of face in faces tuple.

Returns:

Point3D representing the centroid.

face_normal(face_idx: int) → Vector3D

Computes unnormalized outward normal vector of a face.

Parameters:

face_idx – Index of face in faces tuple.

Returns:

Vector3D normal vector via cycle cross product sum.

are_faces_coplanar() → bool

Verifies that all vertices of every face are strictly coplanar.

Returns:

True if all faces are planar, False otherwise.

is_outward_oriented() → bool

Checks consistent outward orientation relative to origin or cavity.

Returns:

True if all face normal orientations match expected outwards conventions.

class geometor.polyhedra.Sphere3D

Exact 3D sphere defined by center and quadrance.

Variables:
  • center – Center point of sphere.

  • quadrance – Exact squared radius Q = R^2.

center: Point3D
quadrance: sympy.Expr
__post_init__() → None

Validates exact algebraic parameters.

contains(pt: Point3D) → bool

Tests whether point lies exactly on sphere surface.

class geometor.polyhedra.Vector3D

Exact 3D symbolic vector over algebraic number fields.

Variables:
  • x – Exact X component.

  • y – Exact Y component.

  • z – Exact Z component.

x: sympy.Expr
y: sympy.Expr
z: sympy.Expr
__post_init__() → None

Validates exact algebraic coordinates.

__add__(other: Vector3D) → Vector3D

Adds two 3D vectors.

__sub__(other: Vector3D) → Vector3D

Subtracts two 3D vectors.

__neg__() → Vector3D

Negates vector coordinates.

__mul__(scalar: sympy.Expr | int) → Vector3D

Multiplies vector by exact scalar.

__rmul__(scalar: sympy.Expr | int) → Vector3D

Multiplies vector by exact scalar from left.

dot(other: Vector3D) → sympy.Expr

Computes exact dot product with another vector.

cross(other: Vector3D) → Vector3D

Computes exact cross product with another vector.

quadrance() → sympy.Expr

Computes exact quadrance (squared norm) of vector.

to_tuple() → tuple[sympy.Expr, sympy.Expr, sympy.Expr]

Returns coordinate 3-tuple.

geometor.polyhedra.slice_solid_to_model(solid: geometor.polyhedra.model3d.primitives.Solid3D, plane: geometor.polyhedra.model3d.primitives.Plane3D, u_axis: geometor.polyhedra.model3d.primitives.Vector3D, v_axis: geometor.polyhedra.model3d.primitives.Vector3D, origin: geometor.polyhedra.model3d.primitives.Point3D | None = None, name: str = 'slice', normalize_axes: bool = False) → geometor.model.Model

Computes exact planar cross-section of a Solid3D and constructs a 2D Model.

Intersects all boundary edges of the solid with the given slicing plane, projects the exact intersection points onto the 2D plane defined by u_axis and v_axis, sorts them cyclically around their centroid, and constructs exact points, segments, and polygon entities in a 2D Model.

Parameters:
  • solid – Exact 3D polyhedral solid.

  • plane – Slicing plane.

  • u_axis – Direction vector for 2D X axis.

  • v_axis – Direction vector for 2D Y axis.

  • origin – Optional 3D point mapped to 2D origin (0, 0). Defaults to (0,0,0).

  • name – Name identifier for the constructed Model.

  • normalize_axes – If True, divides projections by axis quadrances.

Returns:

Exact 2D Model containing the cross-section polygon and boundary segments.

geometor.polyhedra.unfold_net_2d(solid: geometor.polyhedra.model3d.primitives.Solid3D, root_face: int = 0) → list[dict[str, object]]

Unfolds faces of a Solid3D onto a 2D plane via dual graph BFS spanning tree.

Starting from root_face, flattens each adjacent face around its shared hinge edge without folding backward or overlapping adjacent faces.

Parameters:
  • solid – Exact 3D polyhedral solid.

  • root_face – Index of the base face placed first at 2D origin.

Returns:

  • face_index: Index of the face in solid.faces.

  • role: Role string from solid.face_roles.

  • pts_2d: List of 2D vertex coordinates as (x, y) floats.

  • parent_face: Index of parent face across hinge, or None for root.

  • hinge_2d: Pair of (start, end) 2D coordinates of hinge, or None for root.

Return type:

List of dictionaries with face net layout metadata

geometor.polyhedra.elevate(solid: geometor.polyhedra.model3d.primitives.Solid3D, height_scale: sympy.Expr | None = None) → geometor.polyhedra.model3d.primitives.Solid3D

Constructs Pacioli/Leonardo’s stellation (Elevatum / Conway kis).

Replaces each k-gon face with k triangular pyramid faces meeting at an apex above the face centroid. When height_scale is None, calculates the exact algebraic height making all lateral triangular faces equilateral.

Parameters:
  • solid – Exact 3D polyhedral solid.

  • height_scale – Optional exact height scaling factor. When None, calculates exact equilateral pyramid height.

Returns:

Exact elevated Solid3D instance.

Raises:

ValueError – If face circumradius exceeds edge length for equilateral pyramid.

geometor.polyhedra.polar_dual(solid: geometor.polyhedra.model3d.primitives.Solid3D, sphere_quadrance: sympy.Expr | None = None) → geometor.polyhedra.model3d.primitives.Solid3D

Constructs exact polar dual of an origin-centered polyhedral solid.

Reciprocates every face plane across a concentric sphere of quadrance sphere_quadrance, producing dual vertices at poles of face planes and dual faces corresponding to original vertices.

Parameters:
  • solid – Exact origin-centered Solid3D instance.

  • sphere_quadrance – Optional exact sphere quadrance. Defaults to midquadrance of the first edge.

Returns:

Exact dual Solid3D instance.

geometor.polyhedra.rectify(solid: geometor.polyhedra.model3d.primitives.Solid3D) → geometor.polyhedra.model3d.primitives.Solid3D

Constructs Pacioli’s edge-midpoint truncation (Abscisum).

Places vertices at exact midpoints of all edges, yielding shrunk faces on original faces and vertex-figure polygons at all original vertices.

Parameters:

solid – Exact 3D polyhedral solid.

Returns:

Exact rectified Solid3D instance.

geometor.polyhedra.truncate(solid: geometor.polyhedra.model3d.primitives.Solid3D, ratio: sympy.Expr = sp.Rational(1, 3)) → geometor.polyhedra.model3d.primitives.Solid3D

Constructs Archimedean corner truncation at an exact rational ratio.

Divides each directed edge at parameter ratio, creating 2k-gons on original k-gon faces and q-gon vertex-figure faces at vertices of degree q.

Parameters:
  • solid – Exact 3D polyhedral solid.

  • ratio – Truncation ratio in (0, 1/2). Defaults to 1/3.

Returns:

Exact truncated Solid3D instance.

geometor.polyhedra.vacuate(solid: geometor.polyhedra.model3d.primitives.Solid3D, aperture: sympy.Expr = sp.Rational(3, 5), shell: sympy.Expr = sp.Rational(4, 5)) → geometor.polyhedra.model3d.primitives.Solid3D

Constructs Leonardo da Vinci’s hollow manifold (Corpus Vacuum).

Generates outer and inner concentric shell vertices and mitered frame quadrilaterals around window openings for each face of the solid.

Parameters:
  • solid – Exact 3D polyhedral solid.

  • aperture – Shrink factor for face window opening in (0, 1). Defaults to 3/5.

  • shell – Shrink factor for inner concentric shell in (0, 1). Defaults to 4/5.

Returns:

Exact Solid3D representing the 2-manifold hollow cage polyhedron.

geometor.polyhedra.PHI: sympy.Expr
geometor.polyhedra.PHI_INV: sympy.Expr
class geometor.polyhedra.RegularSolid

Exact symbolic specification of a regular convex Platonic solid.

Variables:
  • slug – Short lowercase identifier (‘tetrahedron’, ‘hexahedron’, etc.).

  • name – Standard English name (‘Tetrahedron’, ‘Hexahedron’, etc.).

  • latin_name – Classical Latin name from Pacioli, Kepler, and Renaissance texts.

  • greek_name – Ancient Greek name with polytonic Greek orthography.

  • element – Classical natural element assigned in Plato’s Timaeus.

  • schlafli – Schläfli symbol {p, q} indicating p-gons with q meeting per vertex.

  • dual_slug – Slug of the polar dual regular solid.

  • euclid_prop – Proposition in Euclid’s Elements Book XIII constructing the solid.

  • g_index – GEOMETOR G-Index citation in elements canon.

  • leonardo_plates – Mapping of variant keys to (plate_roman, folio_number) pairs.

  • vertices – Tuple of exact 3D vertex coordinates over Z or Q(phi).

  • faces – Tuple of oriented planar faces (vertex index cycles CCW outward).

  • edges – Tuple of undirected edge pairs (i, j) with i < j.

  • dihedral_spread – Exact rational dihedral spread sin^2(theta).

  • q_in_over_q_out – Exact ratio of inquadrance to circumquadrance Q_in / Q_out.

  • q_mid_over_q_out – Exact ratio of midquadrance to circumquadrance Q_mid / Q_out.

slug: str
name: str
latin_name: str
greek_name: str
element: str
schlafli: tuple[int, int]
dual_slug: str
euclid_prop: str
g_index: str
leonardo_plates: dict[str, tuple[str, str]]
vertices: tuple[tuple[sympy.Expr, sympy.Expr, sympy.Expr], ...]
faces: tuple[tuple[int, ...], ...]
edges: tuple[tuple[int, int], ...]
dihedral_spread: sympy.Rational
q_in_over_q_out: sympy.Expr
q_mid_over_q_out: sympy.Expr
geometor.polyhedra.cross_3d(u: tuple[sympy.Expr, sympy.Expr, sympy.Expr], v: tuple[sympy.Expr, sympy.Expr, sympy.Expr]) → tuple[sympy.Expr, sympy.Expr, sympy.Expr]

Computes the exact cross product of two 3D vectors.

Parameters:
  • u – First 3D vector.

  • v – Second 3D vector.

Returns:

Exact 3D vector u x v.

geometor.polyhedra.dihedral_spread_3d(n1: tuple[sympy.Expr, sympy.Expr, sympy.Expr], n2: tuple[sympy.Expr, sympy.Expr, sympy.Expr]) → sympy.Expr

Computes the exact dihedral spread (sin^2 theta) between two face normals.

In Rational Trigonometry, the spread between two planes with normal vectors n1 and n2 is 1 - (n1 . n2)^2 / (Q(n1) * Q(n2)).

Parameters:
  • n1 – First face normal vector.

  • n2 – Second face normal vector.

Returns:

Exact rational or algebraic dihedral spread in [0, 1].

geometor.polyhedra.dot_3d(u: tuple[sympy.Expr, sympy.Expr, sympy.Expr], v: tuple[sympy.Expr, sympy.Expr, sympy.Expr]) → sympy.Expr

Computes the exact dot product of two 3D vectors.

Parameters:
  • u – First 3D vector.

  • v – Second 3D vector.

Returns:

Exact symbolic dot product u_x * v_x + u_y * v_y + u_z * v_z.

geometor.polyhedra.face_normal_3d(vertices: tuple[tuple[sympy.Expr, sympy.Expr, sympy.Expr], ...], face: tuple[int, ...]) → tuple[sympy.Expr, sympy.Expr, sympy.Expr]

Computes the unnormalized outward normal vector of a planar face.

Parameters:
  • vertices – Sequence of 3D vertex coordinates.

  • face – Sequence of vertex indices ordered counter-clockwise outward.

Returns:

Exact 3D normal vector via cross product of first two directed edges.

geometor.polyhedra.get_platonic_solid(slug: str) → RegularSolid

Retrieves a single Platonic solid by slug name.

Parameters:

slug – Standard slug identifier (‘tetrahedron’, ‘hexahedron’, etc.).

Returns:

The corresponding RegularSolid instance.

Raises:

KeyError – If slug is not recognized.

geometor.polyhedra.get_platonic_solids() → dict[str, RegularSolid]

Retrieves all five Platonic solids mapped by slug.

Returns:

Dictionary mapping slug names (‘tetrahedron’, ‘hexahedron’, ‘octahedron’, ‘icosahedron’, ‘dodecahedron’) to their exact symbolic RegularSolid instances.

geometor.polyhedra.quadrance_3d(v: tuple[sympy.Expr, sympy.Expr, sympy.Expr]) → sympy.Expr

Computes the exact 3D quadrance (squared Euclidean norm) of a vector.

Parameters:

v – 3D vector coordinates (x, y, z).

Returns:

Exact symbolic quadrance v_x^2 + v_y^2 + v_z^2.

geometor.polyhedra.SQRT_PHI: sympy.Expr
class geometor.polyhedra.PyramidModelProfile

Exact symbolic specification of a Great Pyramid architectural or geometric model.

Variables:
  • slug – Unique identifier (‘kepler_golden’, ‘pi_quadrature’, ‘seked_14_11’, ‘half_octahedron’).

  • title – Descriptive human-readable title.

  • historical_source – Primary source or historical citation.

  • half_base – Exact half-base length (unit baseline = 1).

  • height – Exact vertical apex height h above base.

  • apothem – Exact face altitude (slant height) s = sqrt(half_base^2 + height^2).

  • lateral_edge – Exact edge length from base corner to apex.

  • base_perimeter – Exact perimeter of square base (8 * half_base).

  • apex_circle_circumference – Exact circumference 2 * pi * height.

  • base_area – Exact base area (4 * half_base^2).

  • face_area – Exact area of one triangular lateral face (half_base * apothem).

  • lateral_area – Exact total lateral area of the four triangular faces (4 * face_area).

  • total_area – Exact total surface area (base_area + lateral_area).

  • volume – Exact solid volume (1/3 * base_area * height).

  • slope_spread – Exact Rational Trigonometry face slope spread sin^2(alpha) = h^2 / s^2.

  • adjacent_dihedral_spread – Exact spread between normals of adjacent lateral faces.

  • opposite_apex_spread – Exact spread between opposite meridian apothems.

slug: str
title: str
historical_source: str
half_base: sympy.Expr
height: sympy.Expr
apothem: sympy.Expr
lateral_edge: sympy.Expr
base_perimeter: sympy.Expr
apex_circle_circumference: sympy.Expr
base_area: sympy.Expr
face_area: sympy.Expr
lateral_area: sympy.Expr
total_area: sympy.Expr
volume: sympy.Expr
slope_spread: sympy.Expr
adjacent_dihedral_spread: sympy.Expr | None
opposite_apex_spread: sympy.Expr
__post_init__() → None

Validates that all symbolic parameters contain no floats or sp.Float atoms.

geometor.polyhedra.build_kepler_bipyramid_solid() → geometor.polyhedra.model3d.primitives.Solid3D

Constructs the exact 3D Golden Square Bipyramid over Q(sqrt(phi)).

Formed by reflecting the Kepler Golden Pyramid across its square base z = 0, producing an 8-faced convex polyhedron with 6 vertices: (±1, ±1, 0), (0, 0, sqrt(phi)), and (0, 0, -sqrt(phi)).

Returns:

Exact symbolic Solid3D instance centered at (0, 0, 0).

geometor.polyhedra.build_kepler_pyramid_solid(*, center_origin: bool = False) → geometor.polyhedra.model3d.primitives.Solid3D

Constructs the exact 3D Solid3D model of the Kepler Golden Pyramid over Q(sqrt(phi)).

When center_origin is False (default), the square base rests on z = 0 with corners (±1, ±1, 0) and apex at (0, 0, sqrt(phi)). When center_origin is True, the Z coordinates are shifted downward by h/4 = sqrt(phi)/4 so that the centroid is at (0, 0, 0), placing the origin strictly inside the solid. This guarantees is_outward_oriented(), vacuate(), and polar_dual() behave as valid 3D manifolds.

Parameters:

center_origin – If True, shifts vertices along Z by -h/4 to center the solid.

Returns:

Exact symbolic Solid3D instance.

geometor.polyhedra.build_kepler_triangle_model() → tuple[geometor.model.Model, dict[str, sympy.Expr]]

Constructs the exact 2D Kepler Right Triangle model over Q(sqrt(phi)).

Constructs unit base O(0, 0), A(1, 0), W(-1, 0), midpoint E(1/2, 0), north point N(0, 1), golden section point P(phi, 0), midpoint K((phi - 1)/2, 0), Thales circle cutting positive Y-axis at B(0, sqrt(phi)), Kepler Right Triangle OAB, and altitude foot H dividing hypotenuse AB into golden major BH = 1 and minor HA = phi - 1 = 1/phi.

Returns:

Tuple of (Model, metrics_dict) with certified exact SymPy quadrances.

geometor.polyhedra.build_pyramid_squaring_circle_model() → tuple[geometor.model.Model, dict[str, sympy.Expr]]

Constructs the Great Pyramid Squaring the Circle & Earth-Moon Cosmogram in 2D.

Constructs:

  • Base square corners SW(-1, -1), SE(1, -1), NE(1, 1), NW(-1, 1) of side 2, perimeter 8, and area 4.

  • Meridian pyramid triangle on base W(-1, 0) to E(1, 0) with apex S(0, sqrt(phi)).

  • Apex circle centered at O(0, 0) passing through S(0, sqrt(phi)) with radius R = sqrt(phi) and circumference 2 * pi * sqrt(phi) ≈ 8.

  • Inscribed Earth circle centered at O(0, 0) passing through T(0, 1) and E(1, 0) tangent to the square of side 2 (radius 1).

  • Tangent Moon circle centered at apex S(0, sqrt(phi)) tangent to the Earth circle at T(0, 1) with radius sqrt(phi) - 1 ≈ 3/11.

Returns:

Tuple of (Model, metrics_dict) certifying exact symbolic circle-squaring metrics.

geometor.polyhedra.build_seked_pyramid_solid(*, royal_cubits: bool = False, center_origin: bool = False) → geometor.polyhedra.model3d.primitives.Solid3D

Constructs the exact 3D Solid3D model of the Seked 14:11 Khufu Pyramid.

When royal_cubits is True, half-base is 220 and height is 280 (base 440 x 440 cubits, height 280 cubits). When royal_cubits is False (default), unit half-base 1 and height 14/11 are used. When center_origin is True, vertices are shifted along Z by -h/4 so the origin is at the solid’s interior centroid.

Parameters:
  • royal_cubits – If True, uses historical Khufu dimensions (220, 280 cubits).

  • center_origin – If True, shifts vertices along Z by -h/4 to center the solid.

Returns:

Exact symbolic Solid3D instance.

geometor.polyhedra.get_great_pyramid_profile(slug: str) → PyramidModelProfile

Retrieves a single Great Pyramid model profile by slug.

Parameters:

slug – Unique identifier (‘kepler_golden’, ‘pi_quadrature’, ‘seked_14_11’, ‘half_octahedron’).

Returns:

Corresponding PyramidModelProfile.

Raises:

KeyError – If slug is not recognized.

geometor.polyhedra.get_great_pyramid_profiles() → dict[str, PyramidModelProfile]

Returns mapping of canonical Great Pyramid model profiles.

Returns:

Mapping of slug identifiers to PyramidModelProfile specifications.

geometor.polyhedra.verify_kepler_pyramid_identities() → dict[str, tuple[sympy.Expr, sympy.Expr]]

Certifies the eleven foundational exact identities of the Great Pyramid models.

Certifies Herodotus’s area law, Kepler’s right triangle geometric progression, golden ratio area ratios, the icosahedron circumquadrance bridge, Rational Trigonometry slope and dihedral spreads, and Rhind Papyrus Seked 14:11 relations.

Returns:

Mapping of identity names to exact (lhs, rhs) pairs where sp.simplify(lhs - rhs) == 0.

geometor.polyhedra.export_blender_script(solids: list[geometor.polyhedra.model3d.primitives.Solid3D], script_path: pathlib.Path, spacing: float = 4.5) → pathlib.Path

Emits a standalone Blender 5.x Python script generating a studio showcase.

Creates collections, meshes, Principled BSDF materials (Boxwood, Alabaster, Gold), studio 3-point lighting, and camera framing.

Parameters:
  • solids – List of Solid3D polyhedral models to include in the scene.

  • script_path – Target filesystem path for the emitted Python script.

  • spacing – Center-to-center offset along the X axis between models.

Returns:

Path to the generated Python script.

geometor.polyhedra.export_ingetrazo_script(solids: list[geometor.polyhedra.model3d.primitives.Solid3D], script_path: pathlib.Path, spacing: float = 4.5) → pathlib.Path

Emits a runnable Python script for IngeTrazo 0.6.0 CAD modeler.

Lays out polyhedra along the X-axis on named layers (‘Platonic_Solida’, ‘Leonardo_Vacua’) with warm boxwood and alabaster materials.

Parameters:
  • solids – List of Solid3D polyhedral models to include in the scene.

  • script_path – Target filesystem path for the emitted Python script.

  • spacing – Center-to-center offset along the X axis between models.

Returns:

Path to the generated Python script.

geometor.polyhedra.export_obj_mtl(solid: geometor.polyhedra.model3d.primitives.Solid3D, obj_path: pathlib.Path) → tuple[pathlib.Path, pathlib.Path]

Exports a Solid3D to Wavefront .obj and companion .mtl material library.

Maps face_roles (‘base’, ‘outer_frame’, ‘window_reveal’, ‘inner_frame’, ‘truncation’, ‘pyramid’) to distinct Renaissance boxwood, alabaster, and stone material definitions.

Parameters:
  • solid – Exact symbolic Solid3D polyhedral model.

  • obj_path – Target filesystem path for the .obj file.

Returns:

Tuple of (obj_path, mtl_path).

geometor.polyhedra.render_model2d_svg(model: geometor.model.Model, *, golden_segments: list[tuple[str, str, str]] | None = None, width: int = 520, height: int = 480, graphic_id: str = 'slice') → str

Renders a 2D GEOMETOR symbolic Model to publication-grade SVG.

Renders circles, polygons, 3-vertex midpoint path segments, points, and labels with data-ref attributes using luminous gold and sky-blue theme colors with full dark-mode adaptation.

Parameters:
  • model – Exact symbolic 2D geometor.model.Model instance.

  • golden_segments – Optional list of (pt1_label, pt2_label, role) triples designating golden ratio segments to highlight in gold or terracotta.

  • width – SVG viewport width in pixels.

  • height – SVG viewport height in pixels.

  • graphic_id – Unique identifier for data-graphic-id attribute.

Returns:

Valid XML SVG string with class ‘euclid-graphic’.

geometor.polyhedra.render_net_svg(solid: geometor.polyhedra.model3d.primitives.Solid3D, *, width: int = 520, height: int = 420, graphic_id: str = 'net') → str

Renders unfolded 2D papercraft net layout of a Solid3D to SVG.

Uses dual graph BFS unfolding from geometor.polyhedra.model3d.bridge, drawing filled face polygons, dashed interior hinge folds, solid boundary cut lines, and centered face index labels.

Parameters:
  • solid – Exact symbolic Solid3D polyhedral model.

  • width – SVG viewport width in pixels.

  • height – SVG viewport height in pixels.

  • graphic_id – Unique identifier for data-graphic-id attribute.

Returns:

Valid XML SVG string with class ‘euclid-graphic’.

geometor.polyhedra.render_solid_svg(solid: geometor.polyhedra.model3d.primitives.Solid3D, *, yaw_deg: float = 32.0, pitch_deg: float = 22.0, roll_deg: float = 0.0, camera_dist: float = 5.2, focal_length: float = 4.4, width: int = 520, height: int = 480, style: str = 'elemental', show_hidden_edges: bool = True, golden_polygons_3d: list[list[tuple[float, float, float]]] | None = None, graphic_id: str = 'g1') → str

Renders a 3D polyhedral solid to publication-grade theme-adaptive SVG.

Uses orbit camera perspective projection with depth-sorted painter’s algorithm, back-face culling, and directional lighting.

Parameters:
  • solid – Exact symbolic Solid3D polyhedral model.

  • yaw_deg – Horizontal orbit yaw angle in degrees.

  • pitch_deg – Vertical orbit pitch angle in degrees.

  • roll_deg – Camera roll angle in degrees.

  • camera_dist – Orbit distance from model center.

  • focal_length – Perspective camera focal length.

  • width – SVG viewport width in pixels.

  • height – SVG viewport height in pixels.

  • style – Visual style (‘elemental’, ‘woodcut_vacuum’, ‘woodcut_solidum’).

  • show_hidden_edges – Whether to render dashed back-facing edges.

  • golden_polygons_3d – Optional list of 3D polygon vertex loops to render as translucent golden planes depth-interleaved with faces.

  • graphic_id – Unique identifier for data-graphic-id attribute.

Returns:

Valid XML SVG string with class ‘euclid-graphic’.

Raises:

ValueError – If style is unknown or solid has no vertices.

geometor.polyhedra.__version__: str = '0.4.3'