Technical notes

Technical Notes

How Hyperfolder computes, and the background behind it

For version 2.4.0 / Back to About & history

1. Structure

Hyperfolder is a web app that does all its computation inside the browser, without a server. It bundles the open-source three.js (r160) for 3D rendering; all geometric computation is done in its own JavaScript. The main modules are:

2. Representation and generation

2.1 Representation

A polyhedron is represented by a list of vertex coordinates and, for each face, the list of vertex indices around it. The vertices of each face are ordered counterclockwise as seen from outside, so that the right-hand rule gives the outward normal. Edges are derived from the faces. This orientation convention underlies the decision of which side of the net is the front and which folds are mountain or valley folds.

2.2 Convex hull

Many Johnson solids are built as the convex hull (the smallest convex polyhedron enclosing all the points) of a set of vertices made by stacking “rings” of regular polygons at different heights. The hull is computed incrementally, adding one point at a time, as a collection of triangles; coplanar triangles are then merged into a single polygon. Cupolae are built from rings of a 2n-gon and an n-gon, rotundae from half of an icosidodecahedron, and the rest from combinations of prisms, antiprisms and cupolae.

2.3 Conway operations

Conway polyhedron notation describes a shape by applying operators, from right to left, to a seed polyhedron (T, C, O, D, I, the prism P_n, the antiprism A_n, the pyramid Y_n). For example, tI is the truncation (t) of the icosahedron (I): the soccer-ball-shaped truncated icosahedron.

The implementation builds dual d, ambo a, kis k, gyro g, chamfer c and propeller p directly as primitive operations, and defines the others as compositions:

The primitive operations work by rewriting the incidences of faces, vertices and edges (flags), so the topology (how everything is connected) comes out exact. The coordinates, however, are only provisional, and the shape is tidied up by the canonicalization that follows.

2.4 Canonicalization

It is known that for every convex polyhedron there is, for each combinatorial type, exactly one shape (the canonical form) that satisfies the following three conditions at once (a theorem based on the circle-packing theory of Koebe, Thurston and others):

1. Every edge is tangent to the unit sphere (the midsphere).
2. The centroid of the points where the edges touch the sphere is at the origin.
3. Every face is planar.

Following George W. Hart’s iterative algorithm (1997), the vertices are moved a little at a time towards these three conditions, repeating until the movement falls below 10⁻¹¹ (at most 4000 iterations, adjusted to the number of edges). In an Archimedean solid all vertices are equivalent under symmetry, so the canonical form coincides with the uniform shape with equal edge lengths. Indeed, for all 13 the ratio of edge lengths comes out as 1.000000 (except the truncated icosidodecahedron, at 1.000005). The Catalan solids are obtained by canonicalizing the duals of the Archimedean solids in the same way.

2.5 Stellations and geodesics

• Stellated octahedron, small stellated dodecahedron — On each face, a pyramid is erected whose apex is the point where the planes of the neighboring faces, extended, meet (the first stellation).
• Great dodecahedron — Each face of the icosahedron is indented using the plane of the regular pentagon around a vertex.
• Great stellated dodecahedron — On each face of the icosahedron, a triangular pyramid made of golden triangles with a 36° apex angle is erected.
• Geodesic sphere — Each face of the icosahedron is divided into f×f triangles (Class I) and the vertices are pushed out onto the sphere. The dome is the upper half of the sphere with a vertex pointing up; when f is even, the equator runs exactly along edges.
• Goldberg polyhedron — The polar dual of a geodesic sphere. The poles of the planes of the faces containing a vertex v all lie on the plane x·v = 1, so the faces are automatically planar.

3. Shape analysis

Congruent-face classes

Each face is described by its sequence of edge lengths and interior angles; congruent faces are grouped by comparing the representation that is minimal under rotation and reflection (lengths rounded to 1/2000 of the longest edge, angles to 0.05°). This is used for coloring, the legend, and identifying the kinds of parts in a geodesic dome.

Vertex configuration

The sequence of the numbers of sides of the faces around a vertex (e.g. 3.4.5.4), written in its minimal form under rotation and reflection.

Dihedral angle

Obtained from the angle θ between the normals of adjacent faces: π − θ at a convex edge and π + θ at a reflex (concave) edge. Convex edges are mountain folds and reflex edges are valley folds (when assembled with the printed side outward).

Volume and surface area

Computed as sums over the faces using the divergence theorem, and displayed scaled to the size of the template.

4. Nets

4.1 A net is a spanning tree of the faces

Consider the graph whose vertices are the faces and whose edges are the shared edges (the dual graph). Choosing a spanning tree of this graph determines a net: the tree’s edges become folds and all other edges become cuts. The root face is laid on the plane, and each child face is placed by a rigid motion so that its shared edge coincides with the same edge of its parent.

4.2 Overlap testing

Each time a new face is placed, it is checked against the faces already placed using the separating axis theorem (two convex polygons are disjoint exactly when their projections onto the normal direction of some edge of one of them are separated). Faces that merely touch at an edge or vertex are not counted as overlapping. A preliminary test with bounding rectangles saves computation.

4.3 Fitting on the paper

For print nets, each time a face is added, the rotating calipers method is applied to the convex hull of the whole piece to find its minimum bounding rectangle, and the piece is checked to fit within the printable area (the paper minus the margins and footer). If it does not fit, that face starts a new piece.

4.4 Glue tabs and numbering

Each pair of cut edges is given the same number, and a glue tab is attached to one of them. The tabs are trapezoids whose side angles are at most 50° and at most 92% of the angle of the face they are glued to. If a tab would overlap an adjacent face or another tab, 19 shapes with progressively narrower end angles and heights are tried in turn. At a vertex where the gap in the net is almost 0°, a tab physically cannot fit, so such edges are reported on screen as “edges without tabs”.

4.5 On screen: nets chosen for symmetry

The on-screen view and the 3D unfolding animation use the same symmetry-first net.

• Growth order — Faces are added from the root face in order of depth, then distance from the root, then angle around the root. When the root is a regular polygon, angles are compared in the same order within each sector (2π / number of sides), so the net grows with rotational symmetry.
• Choice of center — Besides centering on a face, the net is also grown from the midpoint of an edge where two congruent faces meet, with a sector of π and the same order on both sides. Twofold-symmetric shapes, such as the dodecahedron net with two “flowers” side by side, come from this option.
• Symmetry scoring — Treating the face centroids as points labelled by congruence class, the net is tested for coincidence under k-fold rotation about its center (k = 12, 10, 8, 6, 5, 4, 3, 2) and under reflection in mirror axes (the directions of the centroids and the directions halfway between them), within a tolerance of 2% of the edge length. The score is the order of rotation × (2 if there is a mirror).
• Selection — Candidates are ranked by: connected in one piece → no missing tabs → higher symmetry → more compact.
• Tabs — Tabs follow the rule “on the side farther from the center; if equal, on the counterclockwise side”, so that the result is the same under rotation. Nets with mirror symmetry are displayed with the axis of symmetry vertical.

4.6 For printing: layouts chosen for paper efficiency

For print, SVG and DXF, several candidates with different roots and growth orders (compact, breadth-first, strip, random) are generated under the paper constraints, and the best is chosen by: missing tabs → number of pages → number of pieces → paper usage. Each piece is rotated to the orientation of its minimum bounding rectangle and packed onto shelves in order of height (First-Fit Decreasing).

4.7 3D unfolding animation

Each face opens into the plane of its parent when rotated about their shared edge by the angle that brings the two faces’ normals into line. These rotations are composed from parent to child in the original 3D coordinates and scaled in proportion to the unfold amount t. At t = 1 all faces lie in the plane of the root face, giving the same shape as the on-screen net.

4.8 An open problem

The question “Can every convex polyhedron be cut open along its edges alone into a single non-overlapping net?” is called Dürer’s problem, after Dürer’s nets, and has remained unsolved since G. C. Shephard formulated it in 1975. Hyperfolder’s unfolding is heuristic, but every convex polyhedron in the library unfolds into a single piece. For nonconvex polyhedra, a non-overlapping edge unfolding may not exist at all; in that case the net is split into several pieces.

5. 4D polytopes

5.1 Vertex coordinates

• Tesseract (8-cell): the 16 points (±1, ±1, ±1, ±1)
• 16-cell: the 8 permutations of (±1, 0, 0, 0)
• 24-cell: the 24 permutations of (±1, ±1, 0, 0)
• 600-cell: (±½, ±½, ±½, ±½), the permutations of (±1, 0, 0, 0), and the even permutations of ½(±φ, ±1, ±1/φ, 0) — 120 points in all (φ is the golden ratio)
• 120-cell: 600 points in seven families of coordinates involving the golden ratio
• Uniform polychora, polyhedral prisms and duoprisms are likewise built from permutations of coordinates and Cartesian products.

5.2 Finding the cells

In a convex 4D polytope, the edges are the pairs of points at the shortest distance (all the shapes treated here have equal edge lengths). For each vertex v, centrally projecting the directions to its neighbors onto a hyperplane on the opposite side from v gives a three-dimensional “vertex figure”. Each face of its convex hull corresponds to a cell containing v. The normal of the cell’s hyperplane is found as the vector orthogonal to three edge vectors (a generalized cross product), and all vertices lying on that hyperplane are collected to form the cell. The shape of the cell is obtained by taking the convex hull in 3D coordinates within the hyperplane. The result is checked with the Euler characteristic V − E + F − C = 0 (it holds for all 20).

5.3 Projection to 3D

Schlegel diagram

A perspective projection from a viewpoint on the axis through the center of the nearest cell, just outside that cell’s hyperplane. Placing the viewpoint so that it lies beyond only the nearest cell’s hyperplane and no other (r_f < d < d_max) makes the nearest cell the outer shell, with the remaining cells filling its interior without gaps.

Perspective (vertex first)

A perspective projection with the viewpoint in the direction of a vertex.

Parallel projection

A projection that simply drops the fourth coordinate. The vertex-first parallel projection of the tesseract has the outline of a rhombic dodecahedron.

5.4 4D rotation

Rotations in the three planes XW, YW and ZW are combined. Because the Schlegel viewpoint is very close to the solid, rotating would carry the viewpoint inside it. The viewpoint is therefore smoothly pulled back, according to the amount of rotation, to outside the circumscribed sphere (1.8 times its radius).

5.5 Unfolding the cells into 3D

This is the same idea as a 3D net, raised by one dimension. In 4D, the face (two-dimensional) shared by a parent cell and its child is held fixed, and the child is rotated within the two-dimensional plane orthogonal to that face. This plane is spanned by the two cells’ normals; rotating by the angle between the normals opens the child cell into the same hyperplane as its parent. Overlap between cells is tested with the three-dimensional separating axis theorem (using face normals and cross products of pairs of edges as axes). Even the 120-cell and 600-cell yield non-overlapping nets in a single connected piece. During unfolding, the view switches smoothly from perspective to parallel projection, so that the cells’ true shapes are visible once fully opened.

5.6 Models

• Projected cells (3D puzzle) — Perspective projection maps planes to planes and convex sets to convex sets, so each cell of a Schlegel diagram is a convex polyhedron. With the nearest cell as the outer shell, templates are made for the remaining cells, grouped by congruence class.
• Outline of the projection — The convex hull of all the projected vertices.
• True-shape cells — Templates for the cells in their true shape, as many of each kind as are needed.
• Strut-model parts list — The edges of the projection are grouped by length to 0.1 mm and tabulated together with the number of struts meeting at each node.

6. Display and interaction

• Faces have their own vertices, for the folding animation; edges and vertices are drawn as instanced cylinders and spheres. Back faces are drawn in the color of paper, so the reverse side is visible during unfolding.
• Rotation keeps the speed of the drag as angular velocity, so the solid keeps turning, gradually slowing, after release.
• Demo mode runs from a small script that loads scenes, rotates and unfolds in sequence.
• On phones, each settings block is moved into a tab of the control panel and sliders are replaced by steppers. Switching back to the desktop layout returns them to their original places.

7. Timeline of the mathematics of polyhedra

Dates follow the generally accepted accounts. “c.” indicates that the date is approximate.

8. References

Classics and foundations

1. Euclid, Elements, Book XIII (Japanese translation: Nakamura Kōshirō, Terasaka Hidetaka, Itō Shuntarō, Ikeda Mie, trans., ユークリッド原論 [Yūkuriddo genron], Kyōritsu Shuppan, 1971).The classical proof that there are only five regular polyhedra.
2. H. S. M. Coxeter, Regular Polytopes, 3rd ed., Dover, 1973. (Japanese translation: Hitotsumatsu Shin, supervising ed., 正多胞体 [Sei tahōtai], Maruzen Publishing, 2022.)A systematic treatment of regular polyhedra and polytopes; the basis for the 4D coordinates and the approach to projection.
3. H. S. M. Coxeter, M. S. Longuet-Higgins, J. C. P. Miller, “Uniform Polyhedra,” Philosophical Transactions of the Royal Society A 246 (1954), 401–450.
4. N. W. Johnson, “Convex Polyhedra with Regular Faces,” Canadian Journal of Mathematics 18 (1966), 169–200.Source of the names and numbers (J1–J92) of the Johnson solids.
5. Hitotsumatsu Shin, 正多面体を解く [Sei tamentai o toku, “Solving the Regular Polyhedra”], Tokai University Press, 1983.

Geometry and unfolding of polyhedra

6. Peter R. Cromwell, Polyhedra, Cambridge University Press, 1997.Covers the mathematics and history of polyhedra broadly; used to check many items in the timeline.
7. Erik D. Demaine, Joseph O’Rourke, Geometric Folding Algorithms: Linkages, Origami, Polyhedra, Cambridge University Press, 2007.Computational geometry of nets: existence, overlap, Dürer’s problem and more.
8. G. C. Shephard, “Convex Polytopes with Convex Nets,” Mathematical Proceedings of the Cambridge Philosophical Society 78 (1975), 389–403.
9. John H. Conway, Heidi Burgiel, Chaim Goodman-Strauss, The Symmetries of Things, A K Peters, 2008.Describing symmetry, and notation for operations on polyhedra.

Algorithms and models

10. George W. Hart, “Calculating Canonical Polyhedra,” Mathematica in Education and Research 6(3) (1997), 5–10.Source of the canonicalization algorithm.
11. George W. Hart, “Conway Notation for Polyhedra,” Virtual Polyhedra. georgehart.com
12. Magnus J. Wenninger, Polyhedron Models, Cambridge University Press, 1971; Dual Models, 1983.The classics on making paper models and their templates.
13. Robert Webb, “Stella: Polyhedron Navigator,” Symmetry: Culture and Science, 2000.

Higher dimensions

14. Thomas F. Banchoff, Beyond the Third Dimension, Scientific American Library, 1990.Visualizing higher dimensions through projections, slices and shadows.
15. Edwin A. Abbott, Flatland: A Romance of Many Dimensions, 1884.Source of the homage in the app’s introductory text.

9. Related software

What sets Hyperfolder apart: it is free and runs entirely in the browser; it uses separate nets for the screen (symmetry) and for printing (paper efficiency); it goes from projections of 4D polytopes all the way to 3D puzzles and strut-model parts lists; and it switches between Japanese and English.

10. Related websites

• Virtual Polyhedra: The Encyclopedia of Polyhedra (George W. Hart)An encyclopedic site on polyhedra, including explanations of Conway notation and canonical forms.
• Polytope WikiA collaboratively edited wiki on the classification and description of polytopes: regular, uniform, Johnson and more.
• Polytopes & their incidence matrices (Richard Klitzing)Incidence structures and numerical data for polyhedra and polytopes.
• Visual Polyhedra (David I. McCooey)Coordinate data and images for a large number of polyhedra.
• Polytope GalleryA gallery of projections of four-dimensional polytopes.
• Wolfram MathWorld — PolyhedraExplanations of terms and properties of polyhedra.

The content of linked sites is maintained by their operators and may change (checked October 2026).

11. License and credits

• 3D rendering: three.js r160 (MIT License) is bundled.
• The implementation of the Conway operations draws on the ideas of George W. Hart and polyHédronisme.
• Flatland (1884) is in the public domain.
• App and documentation: © 2026 Miyamoto. Generative AI was used in their production.