Three.js TorusKnotGeometry Mathematical Customization

This article provides a comprehensive overview of TorusKnotGeometry in Three.js, explaining what it is and how you can mathematically customize its shape. By understanding the underlying parameters—specifically the relationship between its winding numbers—you can manipulate this complex 3D shape to create a wide variety of intricate, knotted structures for your web graphics projects.

What is TorusKnotGeometry?

In Three.js, TorusKnotGeometry is a built-in class used to generate a torus knot mesh. A torus knot is a mathematical curve that wraps around the surface of a torus (a donut shape) a specified number of times. Unlike a standard torus, which is a simple ring, a torus knot loops through and around itself, creating a complex, continuous 3D knot.

The Constructor and Its Parameters

To customize a torus knot, you pass specific mathematical arguments into the TorusKnotGeometry constructor:

const geometry = new THREE.TorusKnotGeometry(radius, tube, tubularSegments, radialSegments, p, q);

Each parameter directly controls the mathematical formulation of the knot:

• radius (Default: 1): The radius of the overall torus on which the knot is wound.
• tube (Default: 0.4): The thickness of the tube making up the knot.
• tubularSegments (Default: 64): The number of segments that make up the length of the tube. Higher values make the curve smoother.
• radialSegments (Default: 8): The number of segments that make up the cross-section of the tube. Higher values make the tube look rounder.
• p (Default: 2): This integer defines how many times the knot winds around its axis of rotational symmetry (co-axial with the torus hole).
• q (Default: 3): This integer defines how many times the knot winds around a circle inside the torus.

Mathematical Customization via p and q

The core visual identity of the torus knot is determined by the ratio of p to q. By changing these two integers, you alter the fundamental topology of the knot.

Creating Standard Knots

To create a true, single-loop mathematical knot, p and q must be coprime (meaning their greatest common divisor is 1).

• Trefoil Knot (p = 2, q = 3): This is the simplest non-trivial knot. It loops around the central axis twice and around the interior of the tube three times.
• Cinquefoil Knot (p = 2, q = 5): A more star-like knot that winds around five times internally.
• Decorative “Granny” style knots (p = 3, q = 4): This produces a highly symmetrical, blockier knot structure.

What Happens When p and q are Not Coprime?

If p and q share a common divisor (for example, p = 2, q = 4), the geometry mathematically resolves into a link (multiple disconnected loops) rather than a single continuous knot. In Three.js, this will still render as a single continuous tube, but it may visually overlap or appear distorted because the generator forces a single-loop path through a multi-loop mathematical space.

Dynamic Customization

For advanced mathematical customization, you do not have to rely solely on the static constructor. You can dynamically modify the geometry by creating a custom curve using the THREE.Curve class, defining your own trigonometric equations for \(X\), \(Y\), and \(Z\) coordinates, and passing that custom curve into a THREE.TubeGeometry.

However, for standard torus knots, simply adjusting the p and q parameters in TorusKnotGeometry remains the most efficient way to achieve complex, mathematically precise symmetry in Three.js.