Geometry 3D

biotuner.harmonic_geometry.geometry_3d

Phase 7: 3-D geometry structures derived from harmonic inputs.

Functions

lissajous_tube – tube mesh extruded around a 3-D Lissajous curve harmonic_knot – ratio-derived torus knot extruded into a tube mesh harmonic_surface – deformed parametric surface (torus / sphere / cylinder) lsystem_3d – 3-D turtle L-system branching tree recursive_polyhedron – Koch-style recursively stellated Platonic solid harmonic_point_cloud – point cloud on sphere / torus with harmonic-phase modulation

lissajous_tube(input: HarmonicInput, n_points: int = 800, n_periods: int = 6, tube_radius: float = 0.05, n_sides: int = 12) → GeometryData

Tube mesh extruded around a 3-D Lissajous curve.

The first three ratio components drive the x, y, z frequencies. Amplitude is mapped to tube-radius variation so louder components swell the tube.

Parameters:

• input (HarmonicInput)

• n_points (int, default=800) – Number of sample points along the curve.

• n_periods (int, default=6) – Number of full periods of the base (lowest-ratio) oscillation.

• tube_radius (float, default=0.05) – Base tube radius.

• n_sides (int, default=12) – Polygon sides for the tube cross-section.

Returns:

GeometryData – geom_type='mesh_3d'.

harmonic_knot(input: HarmonicInput, n_points: int = 600, tube_radius: float = 0.06, n_sides: int = 16, major_radius: float = 2.0, minor_radius: float = 0.7) → GeometryData

Torus knot T(p, q) derived from the dominant harmonic ratio.

The simplest ratio p/q in the input determines the winding numbers. A 3/2 input (perfect fifth) gives a trefoil knot T(3, 2); 5/4 gives T(5, 4). Amplitude modulates the tube radius so louder harmonics thicken the knot.

Parameters:

• input (HarmonicInput)

• n_points (int, default=600) – Sample points along the knot curve.

• tube_radius (float, default=0.06) – Base tube radius.

• n_sides (int, default=16) – Cross-section polygon sides.

• major_radius (float, default=2.0) – Torus major radius (distance from torus centre to tube centre).

• minor_radius (float, default=0.7) – Torus minor radius (tube radius of the underlying torus).

Returns:

GeometryData – geom_type='mesh_3d'.

harmonic_surface(input: HarmonicInput, mode: str = 'torus', resolution: int = 64) → GeometryData

Deformed parametric surface driven by harmonic ratio frequencies.

Each ratio p/q contributes a standing-wave ripple whose angular frequency is (p, q) in the two surface parameters. Amplitude controls the ripple depth.

Parameters:

• input (HarmonicInput)

• mode ({‘torus’, ‘sphere’, ‘cylinder’}, default=’torus’) – Base surface geometry.

• resolution (int, default=64) – Grid resolution per parameter axis (total vertices ≈ resolution²).

Returns:

GeometryData – geom_type='mesh_3d'.

lsystem_3d(input: HarmonicInput, depth: int = 3, step_length: float = 1.0, rules: Dict[str, str] | None = None, axiom: str = 'F') → GeometryData

3-D turtle L-system branching tree driven by harmonic ratios.

The branch angle θ is derived from the dominant ratio 360 / (p + q). The turtle supports the full six-degree-of-freedom rotation set: +/- yaw around U, ^/& pitch around L, </> roll around H, | for a 180-degree U-turn, and [/] for state push/pop.

Parameters:

• input (HarmonicInput)

• depth (int, default=3) – L-system rewriting depth (keep ≤ 5 to avoid memory issues).

• step_length (float, default=1.0) – Length of each forward (F) segment.

• rules (dict, optional) – Custom symbol→replacement rules; defaults to a ratio-derived 3-D grammar.

• axiom (str, default=’F’) – Starting string.

Returns:

GeometryData – geom_type='tree' with 3-D node coordinates (N, 3).

recursive_polyhedron(input: HarmonicInput, depth: int = 2, solid: str | None = None, per_face_bump: bool = True, apex_twist: bool = True) → GeometryData

Koch-style recursively stellated Platonic solid, ratio-differentiated.

At each depth level every triangular face is subdivided into four smaller triangles and a tetrahedral bump is raised at the centre face. By default each face’s bump scale is keyed to the closest harmonic ratio (the ratio whose log2 value best matches the face’s normal-vector polar angle), so chord-tones literally sculpt their own surface region.

Parameters:

• input (HarmonicInput)

• depth (int, default=2) – Recursion levels. Faces quadruple each level; keep ≤ 4.

• solid ({‘tetrahedron’, ‘cube’, ‘icosahedron’} or None) – Base solid. When None (default), picks based on n_components: ≤3 → tetrahedron, 4 → cube, ≥5 → icosahedron, so chord size also differentiates the silhouette.

• per_face_bump (bool, default=True) – If True, each face’s bump scale interpolates between component amplitudes weighted by alignment of the face normal with each ratio’s pitch-class direction. If False, all faces share a single global scale (the legacy behaviour).

• apex_twist (bool, default=True) – If True, each bump apex is shifted laterally in the face’s tangent plane by an amount proportional to input.phases[k], where k is the nearest-ratio index. The lateral offset is scaled by edge length and clamped so the apex stays above the face. This makes the bump visibly tilted (rather than just rotating about the normal, which would be invisible).

Returns:

GeometryData – geom_type='mesh_3d'. metadata['face_ratio_index'] is a per-face int array mapping each face to its nearest-ratio index — renderers can use it to colour the surface by chord-tone.

harmonic_point_cloud(input: HarmonicInput, n_points: int = 2000, surface: str = 'sphere') → GeometryData

Point cloud on a sphere or torus with harmonic-phase density modulation.

Base points are distributed via Fibonacci spiral (golden-angle method) for uniform coverage, then the field value at each point is computed as a superposition of ratio-frequency waves. Points where the field exceeds its median are retained; the remainder are discarded (up to n_points survivors).

Parameters:

• input (HarmonicInput)

• n_points (int, default=2000) – Number of points in the output cloud.

• surface ({‘sphere’, ‘torus’, ‘klein’, ‘hyperbolic’, ‘mos’}, default=’sphere’) –

  • 'sphere' / 'torus' — classic surfaces, see Phase 7.

  • 'klein' — Klein bottle (immersion in R³ via Lawson form).

  • 'hyperbolic' — Poincaré disk lifted to a saddle / pseudosphere.

  • 'mos' — moment-of-symmetry helical curve at log-equave height.

• oversample (int, default=3) – Multiplier for the candidate-point pool before field-based selection. Higher values give finer-grained density at the cost of more compute.

Returns:

GeometryData – geom_type='point_cloud_3d'. weights carries the field value at each point (useful for colouring); metadata['surface'] and metadata['field_range'] describe the underlying scalar field.