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/tmpor 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
scalarsdefined in,constant.of:"F"also points to an id that actually exists in readoutsF. 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 conventionsexamples/— Example reference