Skip to content

Agent skill for creative 3D visualization: turn an idea into a Three.js/Blender scene worth exploring. Claude Code + Codex plugin, 223 recipes, 440 knowledge records, 22 proved kits, 37 runnable studies.

6.2 KB
Raw Blame
// bloch-ball.js - recipe.single-qubit-bloch-ball, drawn under knowledge.style-technical-illustration.
//
// State: r = (rx, ry, rz) with |r| <= 1; rho = (I + r . sigma) / 2. The frame shown is a pure
// state at theta = 55 deg polar from +Z, phi = 35 deg azimuth from +X toward +Y, so |r| = 1.
// Three's up axis is +Y, so the Bloch +Z axis is drawn along +Y and Bloch +Y along -Z; the axis
// labels say which is which, because a silently rotated frame is a wrong plate.
// The ball has radius 1 in state space and is drawn at 1 unit = 1 metre: a Bloch radius is not a
// spatial distance, and nothing in the frame claims it is.
import * as THREE from 'three';
import { makeLabel, disposeLabel } from './label-sprite.js';

const RADIUS = 1;
const STATE = { thetaDeg: 55, phiDeg: 35 };
const SEGMENTS = 128;

/** Bloch (x, y, z) -> three (x, y, z). */
const toWorld = (x, y, z) => new THREE.Vector3(x, z, -y);

function circle(material, axis) {
  const points = [];
  for (let i = 0; i <= SEGMENTS; i++) {
    const a = (i / SEGMENTS) * Math.PI * 2, c = Math.cos(a) * RADIUS, s = Math.sin(a) * RADIUS;
    points.push(axis === 'z' ? toWorld(c, s, 0)
              : axis === 'x' ? toWorld(0, c, s) : toWorld(c, 0, s));
  }
  return new THREE.Line(new THREE.BufferGeometry().setFromPoints(points), material);
}

/** A shaft plus a cone head, both unlit, pointing from origin toward `end`. */
function arrow(end, color, radius, group) {
  const material = new THREE.MeshBasicMaterial({ color });
  const length = end.length(), head = Math.min(0.12, length * 0.16);
  const shaft = new THREE.Mesh(new THREE.CylinderGeometry(radius, radius, length - head, 16),
                               material);
  const tip = new THREE.Mesh(new THREE.ConeGeometry(radius * 2.6, head, 20), material);
  const orient = new THREE.Quaternion().setFromUnitVectors(new THREE.Vector3(0, 1, 0),
                                                           end.clone().normalize());
  shaft.position.copy(end).multiplyScalar((length - head) / 2 / length);
  tip.position.copy(end).multiplyScalar((length - head / 2) / length);
  shaft.quaternion.copy(orient); tip.quaternion.copy(orient);
  group.add(shaft, tip);
  return material;
}

export function createBlochBall(look) {
  const group = new THREE.Group(), materials = [], labels = [];
  const { line, focus, callout, secondary } = look.palette;

  // The ball itself: a faint fill so the interior reads as a volume (mixed states live there),
  // never so strong that it competes with the line work.
  const shell = new THREE.Mesh(new THREE.SphereGeometry(RADIUS, 64, 48),
    new THREE.MeshBasicMaterial({ color: focus, transparent: true, opacity: 0.06,
                                  depthWrite: false }));
  group.add(shell); materials.push(shell.material);

  const lineMaterial = new THREE.LineBasicMaterial({ color: line, transparent: true, opacity: 0.55 });
  const faint = new THREE.LineBasicMaterial({ color: secondary });
  materials.push(lineMaterial, faint);
  group.add(circle(lineMaterial, 'z'), circle(faint, 'x'), circle(faint, 'y'));

  // Axes: 1.28 R so the arrow heads clear the sphere and the labels clear the heads.
  for (const [vector, text] of [[toWorld(1.28, 0, 0), '+x'], [toWorld(0, 1.28, 0), '+y'],
                                [toWorld(0, 0, 1.28), '+z  |0>'], [toWorld(0, 0, -1.28), '-z  |1>']]) {
    materials.push(arrow(vector, line, 0.008, group));
    const label = makeLabel(text, { color: line, height: 0.1 });
    label.position.copy(vector).multiplyScalar(1.12);
    group.add(label); labels.push(label);
  }

  // Six computational and superposition basis points, de-emphasised: they are reference, not state.
  const dot = new THREE.MeshBasicMaterial({ color: secondary });
  materials.push(dot);
  for (const point of [[1, 0, 0], [-1, 0, 0], [0, 1, 0], [0, -1, 0], [0, 0, 1], [0, 0, -1]]) {
    const mesh = new THREE.Mesh(new THREE.SphereGeometry(0.028, 16, 12), dot);
    mesh.position.copy(toWorld(...point));
    group.add(mesh);
  }

  // The state vector. |r| = 1 here, so this is a pure state and the tip sits on the surface.
  const theta = THREE.MathUtils.degToRad(STATE.thetaDeg), phi = THREE.MathUtils.degToRad(STATE.phiDeg);
  const r = toWorld(Math.sin(theta) * Math.cos(phi), Math.sin(theta) * Math.sin(phi), Math.cos(theta));
  materials.push(arrow(r, focus, 0.016, group));
  const tip = new THREE.Mesh(new THREE.SphereGeometry(0.04, 20, 16),
                             new THREE.MeshBasicMaterial({ color: focus }));
  tip.position.copy(r); group.add(tip); materials.push(tip.material);

  // Polar-angle wedge from +z to r: the angle theta is the quantity, so it is drawn, not written.
  const wedge = new THREE.Mesh(
    new THREE.CircleGeometry(0.42, 48, 0, theta),
    new THREE.MeshBasicMaterial({ color: focus, transparent: true, opacity: 0.14,
                                  side: THREE.DoubleSide, depthWrite: false }));
  wedge.quaternion.setFromEuler(new THREE.Euler(0, -THREE.MathUtils.degToRad(STATE.phiDeg + 90), 0));
  wedge.rotateZ(Math.PI / 2);
  group.add(wedge); materials.push(wedge.material);

  // One callout in the annotation hue, never on the focus part itself.
  const leaderEnd = r.clone().multiplyScalar(1.06).add(new THREE.Vector3(0.5, 0.34, 0.16));
  const leader = new THREE.Line(
    new THREE.BufferGeometry().setFromPoints([r.clone().multiplyScalar(1.03), leaderEnd]),
    new THREE.LineBasicMaterial({ color: callout }));
  group.add(leader); materials.push(leader.material);
  for (const [index, text] of ['|psi> = cos(t/2)|0> + e^(i p) sin(t/2)|1>',
                               't = 55 deg   p = 35 deg   |r| = 1.00',
                               'purity Tr(rho^2) = 1.00   P(0) = 0.79'].entries()) {
    const label = makeLabel(text, { color: index ? line : callout, height: index ? 0.075 : 0.085 });
    label.position.copy(leaderEnd).add(new THREE.Vector3(label.scale.x / 2, -index * 0.13, 0));
    group.add(label); labels.push(label);
  }

  return {
    group,
    /** Static plate: an instructional figure that drifts is harder to read, not livelier. */
    update() { return false; },
    dispose() {
      group.traverse(object => object.geometry?.dispose());
      for (const label of labels) disposeLabel(label);
      for (const material of materials) material.dispose();
    }
  };
}