# 两个 Figure 共用的理想模型

直线图和旋转图使用同一个 `model.mjs`。用户调整的是动画设定值，磁铁示意、数值、曲线游标和响应点都从这个设定值更新。直线三维载体按同一位置沿 STEP 导向移动；旋转模型仅中心载体随设定角度转动，PCB 和支架保持固定。显示值不是串口数据，也不是运行固件得到的位置结果。

## 给画面的接口

`linearState(xMm)` 返回 `positionMm`、`requestedPositionMm`、`sensorMm`、`sigmaMm` 和三项 `normalized`。`positionMm` 是经动画行程限制后的设定位置，单位 mm；`normalized` 为 0 到 1 之间的理想响应幅值，不是电压或 ADC 原码。

`rotaryState(deg)` 返回 `angleDeg`、`angleRad`、`requestedAngleDeg`、`ac` 和 `normalized`。`angleDeg` 是回绕到一圈内的设定角度；`ac` 是 -1 到 1 的理想交流分量；`normalized=(ac+1)/2` 只是便于比较响应曲线的 0 到 1 映射，不表示真实直流偏置或单片机输出。

`browserModelSource()` 把相同函数和常量转成可内嵌声明。这样 standalone HTML 不需要网络模块，也不需要重新手写另一份模型。

## 直线图依据

- 仓库快照日期为 2026-10-27，未同步原工程后续修改。
- 默认通道顺序是 U1、U2、U4；位置数组为 -10、0、+10 mm。正方向朝 U4。依据 `software/firmware/inc/hall_line.h` 第 5–6 行及 `software/firmware/src/hall_line.c` 第 23–25 行。
- 旧快照默认敏感宽度为 8000 µm，即 8 mm。依据 `software/firmware/inc/hall_line.h` 第 20 行。这个参数描述理想曲线的有效宽度，不是磁铁直径、实际气隙或经过实验测得的距离。
- 图中的响应使用 `exp(-(x-xi)²/(2σ²))`，σ=8 mm。它用于解释不同空间测点怎样提供位置相关信息，不是磁力线仿真，也不保证某种磁铁或气隙会产生这一曲线。
- 数学曲线在 ±15 mm 范围内展开，对照头文件中的内部限幅常量。新版三维载体的可操作区间另受装配几何限制，约为 −12.11 到 +15 mm；超出时限幅。**这不是已经验收的物理量程。**
- 实际固件先扣每路基线、找绝对值最大通道，必要时把三路同时反号，再选较强相邻通道，用定点对数比值计算，并处理邻路过弱、端部和限幅。Figure 没有执行这些步骤，因此不能把设定位置称作实际解算值。依据 `software/firmware/src/hall_line.c` 第 75–152 行。

## 旋转图依据

- 源码安装约定是俯视逆时针为正，U1、U2、U4 的相位顺序分别为 0°、120°、240°。零相位轴应由每张结构图的明确约定决定，不能仅凭图上方位猜测。依据 `software/firmware/inc/hall_encoder.h` 第 11–22 行。
- 理想交流分量为 `cos(θ)`、`cos(θ−120°)`、`cos(θ−240°)`。这是理想三相模型，不是测得的波形。
- 固件还会根据校准状态扣偏置、修相对增益、减三路平均，再进行整数向量和反正切近似、角度回绕及零点处理。Figure 不复现这些整数误差、校准、温漂、饱和或故障判断。依据 `software/firmware/src/hall_encoder.c` 第 216–275 行。
- 图中旋转读数是输入角度回绕到一圈内的值，不提供多圈累计和掉电绝对位置能力。

## 磁铁与结构范围

磁铁尺寸由项目维护者提供：直线 Φ10×3 mm、轴向充磁；旋转 Φ6×3 mm、径向充磁。模型常量保存这个规格供页面说明使用。

三维几何来自本次补充的 `mechanical/models/rendering/HALLPOS.step` 和 `ENCODER.step`，分别保留 93、96 个源实体、原表面颜色和装配坐标。哈希与检查记录见 [几何记录](cad/manifest.json)。原来的两份可打印夹具 STEP 保持原样，不与完整装配文件混用。

直线模型的导向沿世界 +Y。几何参考使用槽中心在 U2 封装中心方向上的投影，三维载体平移为 `[0, xMm + offsetMm, 0]`，`offsetMm` 由装配坐标计算，约 12.1125 mm。源姿态对应 `xMm≈−12.11`，页面控制范围约 −12.11 到 +15 mm，三路曲线仍显示 ±15 mm。

载体槽中心相对霍尔封装中心还有约 0.30 mm 的横向偏移；封装中心也不是经过确认的芯片敏感点。这个零参考用于把画面和公式对起来，不代替磁性校准。载体导向接触长度为 10 mm，圆形上部使整体 Y 外形长 14 mm，不能只看整体包围盒计算实际工作行程。槽径约 Φ10.2 mm，与 Φ10 mm 磁铁的实际打印配合仍需检查。

旋转模型含固定支架、完整 PCB 和中心轴载体，只有载体绕 Z 轴转动。源文件姿态作为展示角度 0°，未提供磁极方向或已校准机械零点。实际 PCB 的 U1 位于中心上方；旁边的理想相位图把 U1 画在右方，是单独标明的数学约定，不能据此推断实物电角度。载体孔径约 Φ6.1 mm，源装配没有独立磁铁实体。

两种模型的“分开看”都只改变观察用的分组偏移，不写回 STEP，不提供装配公差或步骤。显示网格近似源曲面，制造和继续设计仍使用原 STEP。

## 源码 SHA-256

- `software/firmware/inc/hall_line.h`：`c2b99084df47112298019d770d84cc3abdf417fa0e7280835791f10469dba75f`
- `software/firmware/src/hall_line.c`：`6b81b155623742f55ff6f161b695d379727fff3704d1f7d12c489ac1d370b58c`
- `software/firmware/inc/hall_encoder.h`：`b2ecfc8a17977af5b0f6ee456f790fb3e2c9e6b51f84349183ae6ed5b84739dd`
- `software/firmware/src/hall_encoder.c`：`24e1e883b9bf56e76437b67ce1b056af34f4b373c5a369026d3d86b153d75a7d`

运行 `node media/animation/anatomy/model-check.mjs`，检查镜像对称、三相信号相位与周期、输入限制、浏览器内嵌版一致性及源文件 SHA。校验仅验证动画数学和来源，没有连接实物或测量精度。