SuperAPI AI Directory

edu-physics-3d

General & other

View repository

Updated 10-15 23:23

About this skill

3D Physics → Interactive Teaching Webpage

What this skill produces

A single-page HTML that can be opened directly in a browser (three columns):

  • Left column: problem statement + dynamic console — a variable parameter slider (such as angle θ / time t / velocity v) drives real-time recomputed physical quantities, as well as "fixed-value indicators" (conservation laws).
  • Middle column: KaTeX step-by-step analysis, collapsible with one click.
  • Right column: Three.js 3D interactive canvas (spheres/vector arrows/trajectory curves + grid coordinate axes + rotatable/zoomable/pannable OrbitControls), overlaid with view control buttons.

Dependencies

  • Three.js r128(loaded via CDN, no local dependencies)
  • OrbitControls(loaded via CDN)
  • KaTeX(loaded via CDN)
  • No sympy dependency(physical quantities are computed on the frontend using scalars expressions)

Workflow

Step 1: Determine the problem specification

Clarify:

  • Physical scenario: Lorentz force, cross product/right-hand rule, atomic orbitals, crystal structures, and other content requiring 3D visualization
  • Variable parameters: angle θ, time t, velocity v, etc.
  • Physical laws: F=qv×B, right-hand rule, orbital shape parameters, etc.
  • Interaction paradigm: sliders control parameter changes, 3D arrows/spheres/trajectories respond in real time
  • Language: output language follows the prompt language (Chinese/English)

Step 2: Design the 3D physical system

This is the most critical step. Choose an appropriate coordinate system and camera viewpoint.

Coordinate placement tips:

  • Place the origin at the center of the physical system (such as the charge position, lattice origin)
  • Choose the camera's initial position in a direction that clearly shows the three-dimensional relationships
  • A grid ground plane helps observe spatial orientation
  • Label the coordinate axes in red/green/blue for the x/y/z directions

3D object construction patterns:

Scenario Object type Description
Lorentz force 3 arrows (v/B/F vectors) Starting from the same point, demonstrating the right-hand rule
Atomic orbitals Sphere (atomic nucleus) + curve (orbital shape) Draw the orbital outline using parametric curves
Crystal structures Spheres (atoms) + cylinders (bonds) Arranged at lattice positions
Rigid body rotation Sphere/cuboid + rotation axis arrow Show the direction of angular momentum

Verify physical correctness(mental check):

  • Cross product direction: F=0 when θ=0°, F=qvB when θ=90°, verify the direction using the right-hand rule
  • Orbital shape: whether the parametric equations are correct
  • Conserved quantities: whether they are always constant (such as energy conservation)

Step 3: Assemble the data and inject it into the template

📍 Output location & sole artifact: delivered to the userthere is only one .html, written tothe current working directory (Path.cwd()). Do not leave any other files in the cwd—the build script (.py)、__pycache__, screenshots, and other temporary files must all be placed in /tmp or deleted immediately after use. Also never write into the skill's own directory.

Data format(three-part JSON, schema see template/board3d.html data island __LESSON_DATA__):

{
  "lesson": {
    "language": "zh-CN",
    "title": "页面标题",
    "problem": "<p>题面 HTML,公式用 $…$ / $$…$$</p>",
    "answer": "$F = q(v\\times B)$"
  },
  "steps": [
    { "title": "步骤一", "content": "<p>解析内容...</p>" },
  ],
  "board3d": {
    "view": {
      "cameraPos": [5, 4, 8],         // 相机初始位置
      "target": [0, 0, 0],            // 注视点
      "showGrid": true,
      "showAxes": true
    },
    "param": {
      "name": "theta",
      "label": "轨道角 $\\theta$ (°)",
      "min": 0, "max": 360,
      "step": 1, "value": 0, "unit": "°"
    },
    "scalars": [
      { "name": "r", "expr": "2" },                         // 轨道半径
      { "name": "rad", "expr": "theta*PI/180" },            // 角度转弧度
      { "name": "px", "expr": "r*cos(rad)" },               // 粒子位置 x
      { "name": "py", "expr": "0" },                        // 粒子位置 y(在 xz 平面圆周运动)
      { "name": "pz", "expr": "r*sin(rad)" },               // 粒子位置 z
      { "name": "vx", "expr": "-r*sin(rad)" },              // 速度 x(切向)
      { "name": "vy", "expr": "0" },
      { "name": "vz", "expr": "r*cos(rad)" },               // 速度 z
      { "name": "vmag", "expr": "sqrt(vx*vx+vy*vy+vz*vz)" },// 速率(恒定)
      { "name": "B", "expr": "3" },                         // 磁场强度(沿 y 轴)
      { "name": "q", "expr": "1" },                         // 电荷
      { "name": "F", "expr": "q*vmag*B" }                   // 洛伦兹力大小(恒定)
    ],
    "objects": [
      {
        "id": "charge",
        "type": "sphere",
        "position": ["px", "py", "pz"],   // 表达式坐标:随滑块移动
        "radius": 0.3,
        "color": "#f87171",
        "label": "电荷 q"
      },
      {
        "id": "v_arrow",
        "type": "arrow",
        "from": ["px", "py", "pz"],
        "to": ["px+vx*0.4", "py+vy*0.4", "pz+vz*0.4"],   // 速度方向箭头
        "color": "#60a5fa",
        "headLength": 0.3,
        "headWidth": 0.15
      },
      {
        "id": "B_arrow",
        "type": "arrow",
        "from": [0, -2.5, 0],
        "to": [0, 2.5, 0],                // 磁场方向(沿 y 轴,固定)
        "color": "#34d399",
        "headLength": 0.3,
        "headWidth": 0.15
      },
      {
        "id": "orbit",
        "type": "curve",
        // 圆轨道:用 theta 作曲线参数(注意 curve 的 expr 用的是同一套 scalars 环境,
        // 这里直接用 cos/sin 画半径 r 的圆)
        "expr": { "x": "r*cos(theta*PI/180)", "y": "0", "z": "r*sin(theta*PI/180)" },
        "tMin": 0, "tMax": 360,
        "segments": 120,
        "color": "#c084fc"
      }
    ],
    "readouts": [
      { "id": "v", "label": "速率 $|v|$", "type": "expr", "expr": "vmag", "digits": 2 },
      { "id": "B", "label": "磁场 $B$", "type": "expr", "expr": "B", "digits": 1 },
      { "id": "F", "label": "洛伦兹力 $F=qvB$", "type": "expr", "expr": "F", "digits": 2, "highlight": true }
    ],
    "constant": { "of": "F", "label": "$F = qvB \\equiv \\text{常数}$" },
    "legend": [
      { "color": "#f87171", "text": "电荷" },
      { "color": "#60a5fa", "text": "$\\vec{v}$" },
      { "color": "#34d399", "text": "$\\vec{B}$" },
      { "color": "#c084fc", "text": "轨道" }
    ]
  }
}

Note: the example aboveAll expression variables (r/rad/px/vx/vmag/B/q/F, etc.) are defined in scalars defined in, constant.of:"F" also points to an id that actually exists in readouts F. This way, copying it will run correctly, and you won't get issues like curves disappearing, arrows disappearing, or the conservation banner not showing.

Build script method(Python, recommended):

#!/usr/bin/env python3
import json, sys
from pathlib import Path
sys.dont_write_bytecode = True

SKILL_DIR = Path(".claude/skills/edu-physics-3d")
TEMPLATE = SKILL_DIR / "template" / "board3d.html"
PLACEHOLDER = "__LESSON_DATA__"

data = {
    "lesson": { ... },
    "steps": [ ... ],
    "board3d": { ... }
}

template = TEMPLATE.read_text(encoding="utf-8")
out_path = Path.cwd() / "solution-xxx.html"
out_path.write_text(
    template.replace(PLACEHOLDER, json.dumps(data, ensure_ascii=False)),
    encoding="utf-8"
)
print("written:", out_path)
python3 -B /tmp/build.py && rm -f /tmp/build.py

Step 4: Self-check and delivery

  • Physical correctness: verify that arrow directions are correct (cross product direction, right-hand rule) and values are correct
  • Browser preview: start a local static server and check:
    • The Three.js scene loads normally (no WebGL errors)
    • OrbitControls can rotate/zoom/pan
    • 3D objects update in real time when sliders are dragged
    • Trace trajectory lines are correct
    • readouts and constants display correctly
  • Close ports: stop the local server immediately after previewing
  • Cleanup: delete /tmp 's temporary scripts, and confirm that the cwd contains only .html

Data format reference (core fields)

board3d key field descriptions

Field Type Description
view {cameraPos, target, showGrid, showAxes} 3D view configuration
param {name, min, max, step, value, label, unit, ticks} Slider definition
scalars [{name, expr}] Physical quantities derived from param
objects Array of objects sphere / arrow / curve
trace {of, samples, color} Trajectory sampling
readouts [{id, label, type, expr, ...}] Real-time physical quantity values
constant {of, label} Conservation law indicator
legend [{color, text}] Legend

3D object types

type Field Description
sphere position:[x,y,z], radius, color Sphere (point mass/atomic nucleus)
arrow from:[x,y,z], to:[x,y,z], color, headLength, headWidth Vector arrow
curve expr:{x,y,z}, tMin, tMax, segments, color Parametric curve (trajectory/orbit)

Coordinate values such as position/radius support expression strings, and the engine evaluates them every frame using the current scalars environment.

Expression engine

Supports:+ - * / ^ sqrt cbrt abs sin cos tan asin acos atan atan2 exp log pow min max sign floor ceil hypot PI Trigonometric functions use radians (angles must be converted:theta*PI/180). Parameter names must be valid JS identifiers (such as t/theta/v0, do not use θ)。

trace trajectory system

In board3d configure trace: { of: [x_expr, y_expr, z_expr], color: "locus" } then, the engine samples 160 steps uniformly over param's [min, max] interval and draws a 3D trajectory curve. Suitable for helical trajectories of charged particles in magnetic fields, spatial motion paths, etc.

When to use edu-physics-3d (instead of edu-physics)

Division of labor between edu-physics (2D) and edu-physics-3d:

Scenario Use skill Reason
Projectile motion, simple harmonic motion, waves edu-physics 2D is completely sufficient
Lorentz force F=qv×B edu-physics-3d The cross product direction is perpendicular to the plane; must be 3D
Right-hand rule visualization edu-physics-3d The direction of the force is perpendicular to the plane of v and B
Atomic orbital shapes edu-physics-3d s/p/d orbitals are three-dimensional spatial distributions
Crystal structure/lattice edu-physics-3d Three-dimensional spatial arrangement
Rigid body rotation/angular momentum edu-physics-3d The rotation axis is in three-dimensional space
Electromagnetic wave E/B orthogonal edu-physics-3d The two fields propagate orthogonally in three-dimensional space
Magnetic field (solenoid) edu-physics-3d Field lines are distributed in three-dimensional space

Table of Contents

  • template/board3d.html — Three.js rendering template (self-contained single-page HTML)
  • references/conventions.md — 3D physics construction patterns, coordinate conventions
  • examples/ — Example reference