anatomy

解剖结构

这项技能会把图形做得像工作台上的一台小型仪器：厚重的底座由支脚支撑，导轨上带有刻度尺，滑架装在衬套上，旋钮带滚花，配有螺旋弹簧，指针会移动的刻度表，以及像小点一样的螺钉。读者能理解其中的原理，是因为他们认得这台机器。图中显示的每个数字，都来自同一个驱动各部件运动的模型。

这项技能附带 8 个完整示例。开始之前，先打开最接近你需求的示例。每个无需框架的示例都可通过 node examples/<name>/build.mjs 构建，该命令会在脚本旁生成一个独立的 HTML 页面；添加 --light 可使用浅色主题。

• examples/dial-indicator/ 最精简：一个置于支架上的表盘仪表，总共约 300 行。
• examples/desk-computer/ 是不依赖框架的 SVG：一台带键盘的桌面电脑，可以在键盘上打字。输入的文字会显示在沿机箱正面平面绘制的 CRT 屏幕上，关机时，图像会收缩成一条线和一个点。它包含约 85 个实体和 850 条路径。
• examples/arcade-cabinet/ 是一台侧板已卸下的立式街机，包含一个约有 240 个实体和 15 根线缆的 Hero。一枚硬币飞入投币口，以滚动的圆盘在 30° 斜坡上达到的速度沿投币槽滚下，触发投币开关的导线，然后落入钱箱；开关脉冲沿线缆逐段传至电路板，CRT 随后预热、自检，并播放在倾斜显示器平面上绘制的吸引模式。摇杆倾斜并触发面板下方的微动开关。它展示了如何摆放摄像机，让剖视图中的机构始终保持在视野内；如何沿任意轴将凹形电路板绘制为棱柱；如何在页面中使用与构建时相同的模块重建运动部件；以及如何在已确定的绘制顺序中预留的位置绘制实时硬币和导线。运行 node build.mjs --audit 可验证几何结构。
• examples/raptor-engine/ 是悬挂在测试支架上的火箭发动机。圆形部件来自 kit/lathe.mjs，管道和线束来自 kit/tube.mjs。它会拆分为 11 个组件，弹簧错开，并逐帧重新排序深度。每个部件都会记录其真实形状，而 node build.mjs --audit（kit/audit.mjs）会验证静止、拆分以及爆炸效果的每个重放帧，确保没有任何部件相互穿透；每个端点都位于真实安装座上；没有弯折处发生挤压、折叠或落在另一条线上；曲线轮廓的斜率不会晃动；所有重叠部分都按深度顺序绘制。WebGL 烟焰、激波、飞溅和蒸汽会在 SVG 的前后层之间渲染。它是密集管道布设、平滑着色和淡化效果的参考示例。
• examples/ripple-tank/ 是一台架在高腿支架上、纸屏上方的学校用波纹水槽，视角为仰角 44°。两个 WebGL 图层（纸面上的灯光、阴影和焦散，以及水面的反射和玻璃效果）与等距平面对齐，并由纯色散与光学模型（model.mjs）驱动；改变频率时，波纹会从振子出发，通过历史纹理向外传播。
• examples/test-rig/ 是来自真实网站（React/Next）的生产级图形：一个安装在弹簧托架上的玻璃按钮、一支沿导轨滑动并按压或拉动的探针手指，以及一个读取倾斜度的表盘仪表。它包含 53 个实体和约 470 条路径。
• examples/spot-plate/ 是来自同一网站的第二个生产级图形：点滴板上有六对玻璃液滴，每一对都由一个距离场绘制，因此当一对液滴之间的距离小于 merge 时，它们会融合成一块玻璃。一组扇形排列的测隙片用于设定 merge，每个间隙对应一片。它是展示形状相互变形以及单个控件驱动多个部件的参考示例。
• examples/turning-dial/ 是可选的 3D 模式：一个以真实 3D 方式转动的组合式密码盘，上面有一只小型机械手。它包含约 90 个使用金属材质的活动部件、第二组转动组件、一个铰链、一根可抬起的三铰链手指，以及一个会脱落成为自由物体的舱体。WebGL LED、其光池和火花会跟随运动部件。旁边的 stress.mjs 是一个约有 380 个部件、置于杂乱工坊中的复杂机械手，用于测量性能。

测试装置是绘图质量的标杆。Raptor 是着色器工作的标杆：WebGL 效果必须达到它在世界空间渲染、无跳变和无缝衔接方面的标准。

最重要的理念

物体本身就是解释。 不要画方框、箭头和标签。构思一个真实、精良的实体，让它的运作方式本身就体现概念。以下是此前各图中概念与物体的对应方式：

概念	物体
一个共享 GPU 上下文服务多个画布	龙门绘图仪：一个打印头依次访问 16 个工位
当内容没有变化时跳过工作的缓存键	弹子锁：所有弹子对齐时，锁芯转动，无须重绘
每个纹素字节数不同的七个渲染目标	七斗柜，每个抽屉的深度与其字节数相当
可分离模糊（49 × 49 次采样与 49 + 49 次采样）	一枚钉床印章，旁边放着两把装在滑轨上的梳子
可施压、可倾斜的弹簧	一套配有弹簧、探针和百分表的测试装置
高度轮廓	抵在边缘上的轮廓规
取决于朝向的光照	一间小型摄影棚：环绕转盘布置的主灯和补光灯

这类设计有两种常见的失败方式，实践中都见过：

• 过于抽象。 堆叠的板材、悬浮的薄板或带标签的方框，都无法让人一眼看出它是什么。
• 过于扁平、乏味。 一块大平板上只有几条线，既没有立体感，没有部件，也没有值得探索之处。

两种问题的解决办法相同：打造一台由许多细小、精准且各司其职的部件组成、令人一眼就能认出的机器。

每个作品都必须细节丰富。 无论想法或请求多么简单，这一点都适用于每一幅图：快速讲解也应是一台细节密集、真实可信的机器，绝不能只是几块薄板。细节的深入程度随规模而变（工作流第 1 步）：Figure 要围绕主题和机构进行 4× 全面细化，Hero 或 Epic 则要细化整幅图。

• 参照真实物体。 按照真实物体的结构来打造：每颗螺丝、每条接缝、每个倒角、衬套、铭牌、带连接器的线缆、有刻度线的标尺，以及固定其他部件的零件，都要呈现出来。
• 兼顾两种观感。 在 1× 视图下，它应是一台清晰易辨的机器。在 4× 视图下，每个区域都应有真实的细节可供发现；空白的表面或角落意味着工作未完成，而非简洁。
• 有目的，不添噪声。 细节应来自机构中的组成部件。每个部件都要依附于另一个部件，延伸至边缘，并逐渐淡出，而不是戛然而止。
• 最后检查。 完成前，将视图放大至 4×（Figure 检查主题和机构，Hero 或 Epic 检查整幅图），在所有显得空白的区域补上缺失的真实部件。

工作流

按此顺序进行。先写下概念和部件清单，再开始绘制任何几何形状。大部分质量都在这一步决定。

1. 先确定规模。 在开展其他工作之前先说明规模，并在下方对应规模要求预估时，告知用户大致需要多长时间。
   • Figure：一个机构、40–80 个零件、最多一层 WebGL。说明规模后直接制作，无需询问。不要向用户报时，因为 Figure 通常不到一小时就能完成。以下进度检查按最多一小时安排。
   • Hero：一个结构复杂的物体、多个 WebGL 层或一个 3D 主体，包含 80–150 个零件。约需 2–4 小时。说明预计时间，然后开始制作，除非用户要求快速完成。
   • Epic：一整辆车、建筑或工厂，包含多个运动系统；或多个主体均采用 3D 模式。至少需要 6 小时。不要开始制作。先给出时间预估，提出一个保留核心构想的 Hero 版本，并列出完整版本会增加的内容。只有用户选择 Epic 后才开始制作。
   • 无论规模如何，都要在第一小时内完成一个可在浏览器中打开的可用页面，然后继续完善。开始时和每个步骤都运行 date；如果某一步耗时超过其预估时长的两倍，要告知用户当前进度和剩余工作。
2. 真实为先。 收集所解释对象的真实数据和行为：尺寸、数量、阈值、曲线。读数、运动和说明文字都必须准确。尽可能把模型写成一个小型纯模块，例如测试台示例中的 rig.ts，并以它驱动所有内容。
3. 构想对象。 选择一种机器、工具、仪器或家具，其机构与概念一一对应。用一句话说明什么在运动，以及这种运动意味着什么。绝不照搬参考图像：借鉴其质感，而非其对象。
4. 零件清单。 至少列出 40 个零件（Figure 为 40–80 个，Hero 为 80–150 个，Epic 更多），并按类别分组：底座（板、支脚、凹槽、角螺钉、铭牌、标尺条）、结构（立柱、导轨、框架杆、限位块）、机构（滑架、轴套、弹簧、柱塞、指针）、控制件（滚花旋钮、手拧螺钉、旋钮）以及主体本身——它是唯一受光照的部分。每个零件都要装在另一个零件上。references/craft.md 中有零件词汇及制作方法。
5. 规划世界坐标。 世界单位约等于真实对象的 1 px：x 和 y 为地面坐标，z 轴向上。用圆角矩形 {x, y, w, d, r} 和圆来规划布局。选择摄像机：默认方位角为 45°；为展现长边，取 35–60°；仰角为 30°（要观察开放结构内部时可提高，例如波纹水箱的 44°）。然后用 fitProjection(points, width, height, { pad, azimuth }) 调整画面。
6. 几何只构建一次。 用工具包在几何模块中预计算所有静态路径：slabOf、cylinder、extrude、planOutline、topTicks、knurl、coil、radialTicks 等。任意轴向的圆形零件（钟体、法兰、阀门、执行器）都通过 kit/lathe.mjs 构建，管道和电缆则通过 kit/tube.mjs 构建。运动零件在静止位置构建一次，再用 translateAlong 移动。只有形状会变化的零件才在每帧重新构建。
7. 按从后到前、从下到上的顺序绘制。 用 depthOf 对重复零件排序。凡是环绕其他零件的部件，都拆分为后半部分和前半部分：例如，环绕杆的弹簧、环绕滑架的框架横杆。运动零件应在其实际所在的图层中绘制。参见 references/craft.md 中的“绘制顺序”。Figure 中一旦出现管道、电缆和圆形零件，就不要再凭感觉调整排序键：将每个项目的形状记录到 A.recorder(P, { order, spring }) 中，让 A.settle(R, P) 在两个项目重叠时测量真实深度并设置排序键，最后用 A.auditOrExit(R, P) 结束构建。绘制管道前先规划走向：两端都要连接真实接口，支管沿结构布设，交叉处位于直管段，用留有间隙的套环隔开管道（参见 references/craft.md 第 8 节）。记录所绘对象的真实形状：用替代形状来规避审计是缺陷，审计也会将其判定为失败。滑出填料函的杆属于同一根杆，由 G.rodOut 构建，并用 A.slide 记录。
8. 安排版面。 将 Figure 放入卡片中：左上角标注 Fig n，右上角放简短标题，左下角放交互提示，右下角放实时读数。图例和准确的说明文字放在卡片下方，除最多一个微小的蚀刻标签外，不要在绘图区域内放文字。
9. 让它动起来。 使用平缓的基于时间的运动：指数跟随或真实弹簧。无人操作时循环播放闲置演示。Figure 要响应指针和键盘操作，在离开视口时停止，并在减少动态效果设置下保持静止。将属性写入 refs，不要每帧都重新渲染。参见 references/motion.md。
10. 像评审者一样验证。 负责人会通过放大来发现缺陷，所以你要先放大查看。仔细检查生成的每张 PNG。

• 使用 scripts/capture.mjs 捕获桌面、手机（宽 390 px）、悬停状态及运动过程中的多个时刻；使用 scripts/drive.mjs 测试序列、拆解姿态和 --no-webgl 回退模式。
• 确保审计结果归零。 对于含管道、电缆或圆形零件的项目，运行 node build.mjs --audit 必须以 audit passed 结束，每项失败指标均为 0：静止、拆解及运动过程中的间隙、端口、自由端、折叠、自相交、拥挤（包括与细长实体的碰撞）、替代形状、支撑、晃动、鞍座和深度顺序。应在几何结构中修复卡扣问题，绝不要用排序键偏移来掩盖。
• 确保线条检查结果归零。 审计不会检查线条标记。运行 node scripts/lines.mjs page.html --out shots/lines.png（以及 -light 页面，并使用 drive.mjs 的 ["lines"] 操作检查每个静止姿态）必须输出 line ends: 0：每条接缝、刻度线、肋条、短线和指针都必须终止于描边、圆点或轮廓上。检查带圆圈标记的 PNG。
• 在两种主题下以 4× 放大检查所有接合处（也要构建 --light 版本），检查组装和拆解状态：每个法兰、三通、弯头、夹具、阀门、波纹管、箍带、鞍座、球形接头和交叉点；每个弯曲的主体（不得出现色调阶梯）；每处纹理结束的位置（必须位于边缘或逐渐淡出）；带接缝的平整箱体表面；每个纹理软管的分段接头；每根滑动杆在静止位置和全行程位置的状态；以及每个包含文字或着色器内容的窗口。
• 着色器： 使用 ["slow", 0.05] 减速每个过渡过程并生成拼图；不得出现跳变或颜色切换，边缘读数应为 0。浅色主题下，还要记录各过渡过程中每帧的墨色浓度（必须随亮度单调变化），并以 8–16× 放大裁切墨色与描边交接处（参见 references/verify.md 中的“浅色主题着色器”）。
• 将 PNG 放在示例旁边并自问：它能否让人一眼看出是个真实物体？细节是否丰富、富有体积感，且每条线都终止于某个部件上？在 1× 下是否细节清晰，在 4× 下是否依然值得细看，而且没有空白表面或空角？不断迭代，直到答案为是。检查清单：references/verify.md。

设置

该工具包位于 kit/ 中：

文件	用途
kit/iso-kit.ts	将整个核心放在一个文件中：摄像机、实体、零件库、SVG 字符串渲染器、卡片和页面构建器，以及 CSS（ISO_CSS）。将其复制到 TypeScript 项目中。
kit/iso-kit.mjs	编译为纯 ESM 的同一核心，供 Node 脚本使用。直接导入即可。
kit/iso.css	单独导出的 ISO_CSS。导入一次，并在包装元素或 <body> 上添加 class="iso"（浅色主题则加上 data-theme="light"）。
kit/react/draw.tsx	可安全用于服务端的 React 组件：Solid、Line、Wire、Dots、FaceText、IsoFigure、Plate。
kit/react/live.tsx	"use client" 钩子：useReadout、useLoop、useEased、useInView、useStillness，以及 spring 和 follow。
kit/lathe.mjs	沿任意轴创建圆形零件：frameAlong、lathe（只要轮廓包含平滑节点，就会自动启用平滑着色）、solidOf、disc、ringBand、sphereOf、saddleOf、bandsOf（将一个弯曲实体切成可按深度排序的带，这些带共享一个表面，并由 sidesOf 绘制一个轮廓）、圆形表面上的可见弧线、加强筋和螺栓圆（ribsOf 和 dotsOf 接受 fade，ribsOf 接受 seams）、用于从密封套中滑出的杆的 rodOut，以及用于管道路线的 fillet。
kit/tube.mjs	tubePieces 将 3D 管道或线缆拆分成可按深度排序的区段（支持 breaks、卡箍和夹具下方的 gaps、椭圆端盖，以及沿每个接头横截面延伸的编织、波纹或缠绕环 rings），tubeSvg 则绘制管道；crossingsOf 查找路线穿过夹具的位置，runsOf 获取绘制出的区段。其 .tb-* 填充样式位于 ISO_CSS 中。
kit/audit.mjs	用于验证几何结构。recorder(P, { order, spring }) 会在辅助函数绘制时收集项目、形状（旋转体、板体、棱柱、长方体、球体、管体、由宿主形状切割的垫块）和路线；settle(R, P) 会对所有重叠的形状对进行光线投射，验证静止、分离和重放爆炸效果下的真实深度，并设置绘制器的键（overlapsOf、orderKeys）；auditOrExit(R, P) 是 --audit 钩子，会运行所有检查（clearances、solidClearances、terminals、looseEnds、supports、folds、selfOverlaps、将细长实体视为线条的 crowding、针对替代形状的 coverage、wobble、seats、depthOrder），并在发现任何问题时以非零状态码退出。A.slide 会记录从密封套中滑出的杆。参见 references/kit.md 第 12 节。
kit/gl.mjs	绘图中着色器所用的 WebGL 层：GLSL_ISO（GLSL 中的摄像机，包含 rayOf 和 pixelOf）、glCamera(P)、glLayer(...)，以及 JS 动态曲线 smooth、burst 和 settle。对于 3D 图形，GLSL_TURN 和 glslPose(name) 会将世界坐标中的点变换到移动组中，并通过 coverOf 遮罩前景画布。
kit/turn.mjs、kit/turn-build.mjs、kit/turn-audit.mjs	可选的 3D 模式。turn-build.mjs 提供 turning(P, { recorder })：组（旋转、滑动、铰接、自由）、动态层、带材质的凸面零件，以及 T.build。turn.mjs 是运行时：TURN.mount、控制器、TURN.cover、TURN.poseUniforms 和 TURN_CSS。turn-audit.mjs 提供 orbitOrExit，用于对每个旋转角度和运动片段进行轨道审计。参见 references/3d.md。
scripts/capture.mjs	使用无头 Chrome 截取屏幕截图和特写，并检查控制台；启用 WebGL。使用 node 运行。
scripts/drive.mjs	使用 WebGL 的脚本化无头 Chrome：移动、点击、按键、慢动作、等待条件、执行 eval、截屏和生成可捕捉跳变的联系表；支持 --no-webgl 和 --preload。
scripts/lines.mjs	在无头 Chrome 中检查已构建页面的线条端点：每条纹理线都必须以描边、点或轮廓结束。使用 --out 标记错误位置；发现任何错误时退出码为 1。
scripts/inline-kit.mjs	kitScript()、glScript() 和 turnScript() 会返回工具包、WebGL 层和 3D 运行时的源代码，以便内联到独立页面中。
scripts/turn-check.mjs、scripts/turn-bench.mjs	3D 图形：与工具包构建器进行保真度对比、检查 Z 缓冲区顺序、检测像素跳变、在 24 个角度检查线条端点，并在浏览器中测量帧耗时；还会测量 Node 中每种零件类型的 CPU 耗时。
scripts/print.mjs、scripts/print-sheet.mjs	可打印图纸：将已构建页面的姿态定格为矢量静帧，并排版为 A4 或 Letter PDF，提供三种格式（海报、绘图、详细图）。参见 references/print.md。
选择适合项目的路径：

• 独立 HTML、静态 SVG、博客文章或任何非 React 网站。 编写一个 Node 构建脚本，例如 examples/dial-indicator/build.mjs。导入 kit/iso-kit.mjs，使用 solidSvg、lineSvg、dotsSvg、wireSvg 和 faceTextSvg 拼接字符串，再用 figureSvg 和 plateHtml 包装，并通过 pageHtml({ script: kitScript() + live }) 写入页面；如果包含着色器，则使用 kitScript() + glScript() + live。对于单独的 .svg 文件，使用 figureSvg({ standalone: "dark" | "light" })，它会嵌入样式。
• React 或 Next.js。 将 kit/ 复制到项目中（例如 components/iso/）。将几何图形放在纯 .ts 模块中，使用 draw.tsx 组件在服务端组件中构建静态图稿，并将其作为元素属性传递给一个负责移动元素的 "use client" 实时组件。references/react.md 说明了如何拆分，以及大型页面中的一个陷阱。

制作规则（简版）

这些规则能让精心制作的图形区别于示意图。完整的原理和制作方法见 references/craft.md。

• 实体，而非线框。 每个部件都以纸张颜色填充，并按顺序绘制，因此前面的物体会遮住后面的物体。不要有透明边缘或虚线隐藏线。
• 让工具集负责着色。 extrude 会根据朝向返回四种侧面色调，顶部则更亮。任何有高度的部件都应使用它；只有地面和厚度小于 1 个单位的镶嵌才使用 flat。
• 色调层级。 底座和支脚用 lo，结构用 mid，主体用 hi。恰好用一种强调色 lit（深色模式下为白色，浅色模式下为黑色）：用于读者应该关注的部件。凹槽用 faint，次要刻度用 lo，主要刻度用 mid，零刻度用 hi。只有在颜色本身是主题时才使用颜色，例如红、绿、蓝通道。
• 细节要精致明确，绝不杂乱。 倒角宽度为 0.4–1.6；凹槽距边缘 3–5；螺钉用直径为 0.4–0.55 的点表示，并在板件角落加圆环；旋钮上加滚花；尺刻度每隔 4–5 个单位设置一条，每 5 条设一条主刻度；铭牌上加三条横线。每个细节都应属于某个部件。
• 线条要有落点。 每条线的末端都应落在某个面、另一条线上或终端点上。连接线应为末端点落在物体上的 Wire。不要使用引线、气泡、尺寸箭头或悬空标签。
• 管道或电缆不能穿过任何物体。 静止、分离状态以及爆炸图的任何帧中，都不能穿过其他管道、电缆或实体。除线自身的连接处外，与所有物体保持约 1.5 倍半径的间距；线条应沿结构旁边走，而非横穿主体表面；法兰、带箍、波纹管、卡箍或阀门包覆管道的位置都要留出管道间隙。部件应齐平、相切或以边缘贴在表面上，绝不能嵌入：法兰的背面应贴合其接口（如果接口是曲面，则贴在鞍形垫片上，即 G.saddleOf）；支管应从球形三通接出；每个端头（包括分离状态下）都必须接到法兰、接头、连接器外壳或终端点上。
• 每处交叉都要按真实深度顺序绘制。 两个物体在屏幕上重叠时，较近的物体应绘制在上方，并通过 A.settle 和审计来验证，而非凭肉眼调整。线条应在深度相隔足够远的直线段处交叉：弯头、端头或卡箍若落在另一条线的轮廓上，就会看起来像连接处（杆、拉杆、立柱或横杆也算线：管道的最后一段绝不能在屏幕上沿着它们延伸）；朝向观察者再转弯的支腿会挤成 V 形（应通过弯头球接出这种接口）；路径绝不能在屏幕上折返。无法确定前后顺序的一对物体会互相穿插，解决方法应是切断或相切接触，绝不能靠偏移来处理。
• 曲面着色应平滑，绝不能呈阶梯状。 将曲面节点标记为平滑（[s, r, 1]），并让 lathe 根据同一条单调曲线着色和绘制轮廓；任何尺寸超过管件的曲面主体都应使用带 smooth: { slope } 的解析轮廓，用 G.bandsOf 将长主体分段，并用 G.sphereOf 绘制球体。色调带应逐渐收窄至消失，而不是在直线切口处结束；接缝应置于轮廓之下（inner）。
• 纹理应在真实边缘处结束，或逐渐淡出。 肋条、螺栓圆周、横线、接缝和凹槽在平面或曲面上都不能戛然而止：ribsOf 和 dotsOf 接受 fade（淡出的肋条用 fadedSvg 绘制）；一排肋条应在接缝处结束（ribsOf(…, { seams: true })）；盒体上的接缝或焊缝应绕过棱角（像板件的 inner 一样使用 k.sideSeam）；单个表面上的线条应从一边延伸到另一边；通风口应为封闭槽；刻度应从尺条边缘延伸出来；必须停止的单条线应使用 fadeLineSvg 逐渐淡出；朝上的一排特征（例如环顶的孔）应从四周都能看到（all: true）。管道上的纹理（编织层、波纹、包覆层）应贴合其横截面，并贯穿每个分段接头：使用 tubePieces(…, { rings })，绝不能沿中心线画虚线。管道的高光和阴影应延伸到端盖上，并贯穿每个分段接头。只有表示印刷文字的横线、指针的尾部和指针尖端可以在裸露表面上结束，并标记为 free。
• 着色器绝不能突然跳变或截断。 每个 uniform 都应带有包含起始和衰减阶段的包络；相位变化应由物理量驱动并进行交叉淡化；每个项都应在任何边界或画布边缘前归零；效果应处于图形自身摄像机的世界空间中（见下文）。
• 贴在表面上的内容要适配表面。 机器显示的文字应按最宽字符串适配其显示窗口，并裁剪到窗口范围内；开口后方可见的内容应同时按开口和自身所在平面裁剪，并绘制凹槽侧壁。
• 体积感。 让物体具有真实厚度，使其立在其他物体上，并在底座下方和任何抬起的物体下方加柔和光晕。
• 构图。 将图形居中，并让其占据卡片约 55–65% 的空间。同一组图形应保持比例一致，并确保在 390 px 宽时仍清晰可辨。

绘图中的 WebGL

着色器只用于线条无法绘制的内容：火焰和排气、水和焦散、真实灯光、辉光、蒸汽。其余部分保留为 SVG。核心规则源自第一个着色器示例，当时各阶段间的颜色变化看起来像是突然切换，而非交叉淡化：

• 三层。 后方 SVG 承载被效果覆盖的内容，画布承载效果（pointer-events: none），前方 SVG 承载覆盖效果的内容。如果某个部件或效果位于两侧，就将其拆分。
• 世界空间，相机一致。 通过 onFloor、onWallX 和 onWallY 构建每个着色器点，或沿像素射线 rayOf(vb) + t·towardViewer() 步进。所有尺寸都使用世界单位乘以 uK。位于平面上的任何内容都能与该平面的 SVG 线条精准对齐。
• 不突然跳变。 每个 uniform 都遵循带有渐入和渐出的包络（事件使用工具包的 burst，层级值使用 settle）。阶段变化采用交叉淡化，颜色随物理量连续变化；淡出时只会变暗。
• 没有硬截断。 每个项在任何 if、边界或画布边缘之前，以及单元噪声的任何单元边缘之前，都必须归零。
• 透过开口观看，并进行双重遮罩。 窗户或凹槽后方的内容，先在其自身平面上遮罩，再由正面平面上的开口进行遮罩，并将两者相乘（references/webgl.md，第 5 节）。
• 混合。 使用 tonemap() 和抖动。在暗色主题中，只添加光线的画布使用预乘输出和 mix-blend-mode: screen；必须同时变暗的画布（涟漪水槽中的水）则保持普通混合。
• 随附浅色主题，着色器也专为纸面而设计。 使用普通预乘 Alpha，绝不使用 screen。写出纸面应呈现的颜色，再反推出墨色。辉光应是带有浅色核心、彩色边缘和 Alpha 下限的饱和主体，绝不能使用变暗的深色主题颜色：那会产生 Raptor 的“红墨烟雾”。
  • 光线照射到的表面要带上色调，容纳光线的空腔则要呈现更深的物理底色（烟灰、耐火材料、水深）。
  • 高温主体统一使用与回退方案共用的黑体墨色表。
  • 墨色只会随光线增强：对最终墨色整体淡化一次，绝不逐项淡化。
  • 墨色止于每条笔画的内缘。
  • 逐帧测量墨色。references/webgl.md 第 8 节介绍了配方和评审人员发现的问题。
• 克制。 将设备像素比限制为 1.5，并且只在效果处于活动状态且位于屏幕上时渲染。开启减少动态效果时只显示一帧静止画面；即使没有 WebGL，SVG 也必须清晰可读。

编写任何着色器之前，请阅读 references/webgl.md。

3D：可转动的图形（beta）

3D 是一种类似 WebGL 的选项。只有当深度方向上的运动是核心创意时才使用它：例如转动的表盘或转台、弯曲的手指，或脱落坠下的部件。图形的其余部分保持为静态套件图稿。

它目前处于 beta 阶段：引擎已在示例和一个测试图形上验证，但尚未用于生产图形。每次只转动一个对象，并让周围的杂物保持静态。在负载较重的机器上，小型图形可以达到 60 fps；一个包含 380 个部件、会弯曲的复杂手部，在 1440 分辨率下测得约 20 fps，在手机配置（390 px、CPU 降频 4×）下测得 13–15 fps。

• 活动部件使用套件自身的图像。 每一帧，套件都会根据自身规则重新投影并重新着色凸面套件基本形状（棱柱、圆形件、穹顶、带平面的球体、车削件、管件）。转动 θ，即为套件按方位角 a − θ 绘制图像。
• 遮挡顺序由分离平面确定。 同组配对使用固定在组内的平面，不同连杆上的配对使用固定在它们公共坐标系中的平面，其余配对则每帧重新求解。审计结果证明，在任何角度或片段帧中都不存在循环。
• 接触处齐平、相切或边缘贴平面。 关节是位于子组上的同轴指节圆盘，与父级连杆接触；否则，审计会将整个子组判定为松动。没有实时线条跨越两个运动组：电缆通过关节时，两侧各由一个夹片固定；连接到转台时，则通过轮毂处的滑环。
• 实时管线在近水平平面内弯曲，或在配件内部弯曲，且绝不沿视线方向延伸。 弯曲半径需要满足 R ≥ 2r / sin²(e − θmax)，其中 θmax 包含管线经过的所有铰链的俯仰范围：平放时的界限为 8r，在 ±12° 铰链上则为 21r。每条路径都从安装表面延伸到安装表面，其端口位于 gaps 中。这样在任何角度和姿势下都能保持这一点。
• 材质会重新映射色阶。 金色、铬色、钢色、枪灰色、橡胶色、黄铜色和铜色各有一组亮色和暗色；色调仍由朝向决定。
• 自由组脱落时不会跳动。 同轴部件是带有旋转纹理的固定图像。
• 着色器跟随运动。 使用 controller.anchor 或 toGroup 将其锚定到某个组，用 coverOf 遮挡前景画布，并将世界效果（烟雾、落下的火花、工作台上的油）留在组空间之外。
• 使用 --audit（turn audit passed）和 scripts/turn-check.mjs（--fidelity、--order、--pops、--lines、--perf）进行验证。使用 --quick --only=… 迭代。只有完整运行才能证明图形符合要求；对于 30 个部件，这需要 15–20 分钟，因此请在后台运行。

请先阅读 references/3d.md。

可打印图页（A4）

当用户想把图稿打印到纸上（讲义、海报、PDF、A4 或 Letter 纸张）时，请从已完成的图稿生成打印件，而不是重新绘制。请在构建文件旁边编写 sheet.mjs：要捕捉的姿势以 drive.mjs 操作表示，部件以实时 SVG 的 CSS 选择器表示，所有文字都必须忠于模型。然后运行 node scripts/print.mjs sheet.mjs --format all --png，并阅读每一页。

• 海报（默认）：一页，名称以大号字体呈现，包含问题、大号数字、带编号标记的图稿，以及每个部件的一行说明。
• 绘图：一页技术图纸，包含部件清单、规格、局部放大图，以及一条显示工作部件亮起的步骤带。
• 详细：2–4 页，按机器大小缩放：概览页带有标记和圆形特写；“工作原理”页将每个步骤作为一张亮起的大图（每页六张，最后一个位置说明原因）；复杂图稿还会有一页“组件”，展示最多四张部件组的大幅特写（规格中的 assemblies）。简单图稿保持为 2 页；maxPages 用于限制页数。

如果用户尚未选择格式，请提供全部三种格式。当页面展示的图稿有 PDF 时，请在图稿区域内使用 kit/pdf-button.mjs 中的 pdfButton(href)，在卡片上添加 PDF 链接（参见 examples/push-button/build.mjs）；先打印，再重新构建页面。examples/raptor-engine/sheet.mjs 和 examples/arcade-cabinet/sheet.mjs 可作为参考。请先阅读 references/print.md。

参考资料

按需阅读以下内容：

• references/craft.md：深入介绍视觉风格，包括带代码的部件词汇表、色调表、绘制顺序模式、圆形部件、管道和线束、爆炸图、面部屏幕，以及导致图稿被拒的反模式。设计前请先阅读。
• references/kit.md：API，包含签名和示例。
• references/motion.md：实时行为（循环、弹簧、导览、指针、键盘、无障碍、减少动态效果），以及单次事件、爆炸图、深度重新排序和武装状态的包络，在原生 JS 和 React 中均有说明。
• references/react.md：React/Next.js 服务端/客户端拆分、元素属性，以及大型载荷的键警告陷阱。
• references/verify.md：capture.mjs 和 drive.mjs 命令、审核清单（包括着色器）及常见故障。
• references/webgl.md：绘图中的着色器：何时值得使用、图层堆叠、摄像机约定、等轴测摄像机中的光线步进、包含最小页面的完整 API、包含经验性缺陷的设计规则、浅色主题（纸上墨色、针对各类现象的配方、审核者指出的缺陷），以及如何验证。
• references/walkthrough.md：测试装置的设计过程，从概念到代码，逐步讲解。
• references/3d.md：可选的 3D 模式：组和姿势、实时图层、凸部件及其规则、材质、自由组、铰链链、绘制顺序、转台周围的静态杂物、随转台转动的着色器、轨道检查、浏览器检查、性能和限制。
• references/print.md：从已构建的图稿生成可打印的 A4 或 Letter 图页：三种格式、sheet.mjs 规格（姿势、作为选择器的部件、焦点、隐藏、裁剪、WebGL 光栅图），以及如何检查 PDF。
• references/publish.md：仅在用户提出要求时，使用 scripts/publish.mjs 将完成的图稿分享到社区图库；不会替用户推送任何内容。