{
  "schemaVersion": 1,
  "id": "minimal-surface",
  "version": "1.0.0",
  "status": "published",
  "kind": "object",
  "title": "Minimal Surface",
  "summary": "A soap-film surface that bends from a catenoid into a helicoid and back without stretching. Loops perfectly.",
  "description": "A soap film's shape, and its famous disguise. The catenoid (the film between two rings) and the helicoid (a spiral ramp) look nothing alike, yet one bends into the other without stretching and without ever leaving the family of minimal surfaces: the Bonnet transformation. A single angle runs once round the circle, so the surface passes from catenoid to helicoid to the catenoid's mirror image and back, in iridescent glass with a net of curves. Choose the finish (iridescent, chrome, soap or gold), whether the net of curves is drawn, the mesh fineness, how far the surface reaches, the turns per loop, the backdrop colour and whether the camera sways.",
  "role": "Object (3D, three.js): a mathematical showpiece with a real transformation, for science, maths and design content.",
  "collections": [
    "chrome-glass",
    "hypnotic-loops",
    "product-reveals"
  ],
  "tags": [
    "minimal surface",
    "catenoid",
    "helicoid",
    "soap film",
    "bonnet transformation",
    "mathematics",
    "iridescent",
    "morph",
    "geometry",
    "studio",
    "loop",
    "3d"
  ],
  "synonyms": [
    "soap film",
    "catenoid to helicoid",
    "bonnet morph",
    "differential geometry",
    "minimal surface family",
    "spiral ramp"
  ],
  "useCases": [
    "A maths or physics explainer",
    "A design or architecture studio title scene",
    "An iridescent morphing showpiece"
  ],
  "featured": null,
  "publishedAt": "2026-10-05",
  "implementation": {
    "target": "three",
    "runtime": "browser",
    "language": "javascript",
    "module": "esm",
    "entry": "src/minimal-surface.js",
    "exports": [
      {
        "name": "createMinimalSurface",
        "signature": "createMinimalSurface({ finish?, lines?, detail?, reach?, turns? }) => { group, setProgress(progress), dispose() }",
        "description": "The morphing surface, about 5 across and 5 tall and centred on the origin; needs an environment map."
      },
      {
        "name": "FINISHES",
        "signature": "FINISHES: { iridescent, chrome, soap, gold }",
        "description": "Surface finishes: colour, metalness, roughness, iridescence and film index."
      }
    ],
    "reusable": [
      "src/minimal-surface.js"
    ],
    "demo": "demo.js",
    "harness": "index.html"
  },
  "dependencies": [
    {
      "id": "three",
      "version": "0.185.1",
      "reason": "Renderer, geometry and shader materials."
    },
    {
      "id": "chrome-material",
      "version": "1.1.0",
      "scope": "demo",
      "reason": "Studio environment light, backdrop and contact shadow."
    },
    {
      "id": "apw-runtime",
      "version": "1.0.0",
      "scope": "demo",
      "reason": "Demo harness."
    }
  ],
  "params": [
    {
      "key": "finish",
      "label": "Finish",
      "type": "select",
      "default": "iridescent",
      "options": [
        {
          "value": "iridescent",
          "label": "Iridescent"
        },
        {
          "value": "chrome",
          "label": "Chrome"
        },
        {
          "value": "soap",
          "label": "Soap film"
        },
        {
          "value": "gold",
          "label": "Gold"
        }
      ]
    },
    {
      "key": "lines",
      "label": "Surface lines",
      "type": "boolean",
      "default": true
    },
    {
      "key": "detail",
      "label": "Mesh detail",
      "type": "number",
      "min": 0.6,
      "max": 1.4,
      "step": 0.1,
      "default": 1
    },
    {
      "key": "reach",
      "label": "Reach",
      "type": "number",
      "min": 1,
      "max": 1.9,
      "step": 0.1,
      "default": 1.4
    },
    {
      "key": "turns",
      "label": "Turns per loop",
      "type": "integer",
      "min": 0,
      "max": 3,
      "step": 1,
      "default": 1
    },
    {
      "key": "background",
      "label": "Backdrop",
      "type": "color",
      "default": "#121620"
    },
    {
      "key": "orbit",
      "label": "Camera sway",
      "type": "boolean",
      "default": true
    }
  ],
  "presets": [
    {
      "id": "default",
      "label": "Iridescent, one turn",
      "params": {}
    },
    {
      "id": "soap",
      "label": "Soap film, wide",
      "params": {
        "finish": "soap",
        "reach": 1.9,
        "background": "#0c1620"
      }
    },
    {
      "id": "chrome",
      "label": "Chrome, bare",
      "params": {
        "finish": "chrome",
        "lines": false,
        "background": "#10141c"
      }
    },
    {
      "id": "gold",
      "label": "Gold, two turns",
      "params": {
        "finish": "gold",
        "turns": 2,
        "reach": 1.2,
        "background": "#241a12"
      }
    }
  ],
  "output": {
    "width": 1080,
    "height": 1080,
    "fps": 30,
    "durationSeconds": 16,
    "posterSeconds": 2,
    "alpha": false,
    "motion": "procedural",
    "loop": {
      "seamless": true,
      "cycleSeconds": 16,
      "method": "The Bonnet angle runs once round the circle over the loop, which returns the surface to itself, the group turns a whole number of times and its tilt is a sine of the loop, so the last frame meets the first."
    },
    "seed": null
  },
  "composition": {
    "inputs": "Time within the loop; the finish, lines, reach, detail, turns, backdrop and camera sway.",
    "outputs": "A full frame rendered in 3D with a studio environment.",
    "coordinates": "The surface's axis is vertical through the origin; the group hangs 3.3 above the floor; the surface is the Bonnet family x = cos α sinh v sin u + sin α cosh v cos u and so on, u over −π … π.",
    "lighting": "A warm key light with a shadow map and the studio environment.",
    "timing": "setProgress(progress) rewrites the mesh from the family's closed form; frames render in any order.",
    "compatibleWith": [
      "chrome-material",
      "orbit-camera",
      "kinetic-title",
      "number-reveal"
    ],
    "notes": [
      "About 7 400 vertices are rewritten on the CPU each frame and normals recomputed."
    ]
  },
  "reuse": [
    "Maths explainer: Iridescent, one turn.",
    "Delicate: Soap film, wide.",
    "Product-style: Chrome, bare."
  ],
  "integration": {
    "newProject": "Create a WebGLRenderer with a studio environment, add createMinimalSurface().group and call film.setProgress(progress) each frame.",
    "existingProject": "Copy src/minimal-surface.js; add the group to your scene with an environment map."
  },
  "performance": {
    "notes": "About 7 400 vertices rewritten and re-normalised each frame plus a net of lines: a couple of milliseconds a frame on an integrated Intel GPU.",
    "limits": "Software WebGL renders in about two seconds a frame."
  },
  "limitations": [
    "Only a patch of the surface is drawn, so it has open edges (a cut at u = ±π shows when it is a helicoid).",
    "The soap finish is transparent without true refraction."
  ],
  "license": {
    "spdx": "MIT",
    "notice": "Copyright (c) 2026 AI Pixel Wizard. Released under the MIT License. See LICENSE in this folder.",
    "thirdParty": []
  },
  "provenance": "Adapted from the owner's threejs-sketches/geometry-math/minimal-surface (MIT) and rebuilt for AI Pixel Wizard in October 2026 as an original studio object: the Bonnet associate family of the catenoid and helicoid evaluated each frame with one trip round the family per loop, on an exact loop.",
  "changelog": [
    {
      "version": "1.0.0",
      "date": "2026-10-05",
      "notes": "Initial release."
    }
  ]
}