Shell (Default)

The Shell (Default) morphospace generates 3D shells from a parametric model of coiling geometry Contreras-Figueroa & Aragón (2023), with thickness allometry following Okabe & Yoshimura (2017).
Traits come from your dataset; hyperparameters come from the configuration.

Traits (dataset columns)

These correspond to arguments of sample() (excluding name and hyperparameters).
In the paper, most of them control the coiling geometry and aperture shape along the growth axis.

Trait name	Default	Description	Range (paper)
b	0.2	Whorl expansion rate. How fast the spiral and generating curve of the shell expand.	0 ≤ b < ∞. b = 0 → torus; b → ∞ → straight shell.
d	1.65	Horizontal distance from the spiral to the coiling axis (before rescaling by S).	0 < d < ∞. d → ∞ → infinitely expanded shell.
z	0	Vertical translation of the spiral (vertical distance to the x–y plane).	−∞ < z < ∞. Dextral: z > 0; sinistral: z < 0; planispiral: z = 0.
a	1	Ratio of major to minor axes of the ellipse modeling the aperture.	0 < a < ∞. Narrow: a < 1; circular: a = 1; wide: a > 1.
phi	0	Initial tilt angle of the aperture before it is placed in the Frenet frame.	0 ≤ φ < π.
psi	0	Rotation angle around the binormal axis in the local Frenet frame.	0 ≤ ψ < π/2 to avoid invagination.
c_depth	0	Axial ribbing amplitude. How pronounced the ribs are that run along the shell (growth direction).	0 = no axial ribs; higher (e.g. 0–1) = deeper ribs.
c_n	70	Axial ribbing frequency. Number of axial ribs per rotation (per 2π radians of growth).	Positive; e.g. 70 ≈ 70 ribs per full turn of the spiral.
n_depth	0	Spiral ribbing amplitude. How pronounced the ribs are that run around the aperture.	0 = no spiral ribs; higher (e.g. 0–1) = deeper ribs.
n	0	Spiral ribbing frequency. Number of ribs around the aperture (circumference).	Non-negative integer; e.g. 0, 4, 8, 12.
t	100	End of the growth interval in the parametric curve (growth parameter in radians).	Positive; larger values = more whorls (one whorl ≈ 2π radians).
eps	0.8	Thickness allometry exponent (ε). Wall thickness scales as (aperture size)^eps. eps = 1 is isometric (thickness ∝ size); eps < 1 is allometric (thickness grows more slowly than aperture size, as in many ammonoids).	0 = constant thickness; 1 = isometric; < 1 typical for real shells (e.g. ≈ 0.8).
h_0	0.1	Reference thickness. Scale factor in the thickness formula: thickness = (aperture size)^eps × h_0. Sets the thickness scale before any S rescaling.	Small positive (e.g. 0.01–0.3).
S	5.0	Target aperture diameter in cm (global scaling).	S ≥ 0 required (shell does not exist for S < 0). None or 0 = no scaling; positive = final aperture size in cm.

Hyperparameters (configuration)

These live under the morphospace.hyperparams section in the config file.

Hyperparameter	Default	Description	Typical range / notes
n_vertices_aperture	20	Number of points around each aperture ring (mesh resolution).	Integers ~12–64. Higher = smoother but heavier.
time_step	0.05	Step size for the growth parameter t.	Positive; smaller = more segments (smoother shells).
use_inner_surface	false	Whether to generate an inner surface with wall thickness.	Enable when you need closed/thick shells for meshes.

To change these hyperparameters, edit the YAML:

morphospace:
  name: Shell (Default)
  hyperparams:
    n_vertices_aperture: 24
    time_step: 0.03
    use_inner_surface: true

References

• Contreras-Figueroa, R. & Aragón, L. (2023). A mathematical model for mollusc shells based on parametric surfaces and the application to Conus shells. Diversity 15, 431. https://doi.org/10.3390/d15030431
• Okabe, T. & Yoshimura, J. (2017). Optimal designs of mollusk shells from bivalves to snails. Scientific Reports 7, 42445. https://doi.org/10.1038/srep42445