AutoFocus 扫描范围扩大与电机限位 — 实现计划

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 扩大 AutoFocus 标定的水平找圆与 Z 对焦扫描范围，并对所有电机移动加行程限位，解决"well 没转进画面导致整段检不出圆"的问题。

Architecture: 全部改动集中在 Calib/CalibrationEngine.cs 单文件。新增可配置参数字段 + 两个钳位方法 + 一个全行程水平定位方法；修改 CoarseFocus（固定大窗口）、CalibrateWell（调用新定位、扩精对焦半幅）。不改协议层与电机接口。

Tech Stack: .NET 8 / WPF / C#。无单元测试框架——验证靠 dotnet build 编译 + 一个纯逻辑钳位自检（写进 SelfTest 控制台工程）+ 真机标定验证。

设计依据：docs/superpowers/specs/2026-06-16-autofocus-scan-range-design.md

文件结构

修改：Calib/CalibrationEngine.cs
- 新增字段（限位 + 水平全行程粗扫 + Z 大窗口粗对焦 + 精对焦半幅/步距）
- 新增 ClampH(int)、ClampZ(int) 私有方法
- 新增 HCoarseLocate(int well) 方法（全行程粗扫定位 + 局部密扫）
- 改 CoarseFocus：固定中心 90000、半幅 30000、步距 2000
- 改 CalibrateWell：用 HCoarseLocate 替换 ②首次 ScanForCenter；精对焦半幅改 FineZHalf、步距改 FineZStep
- 所有 _motor.HorizontalMoveTo 经 ClampH，_motor.VerticalMoveTo 经 ClampZ

无新增文件。ClampH/ClampZ 是两行 Math.Max/Min，逻辑通过编译 + 真机日志验证（越界写 Log），不单独造测试文件（无测试框架，SelfTest Main 需硬件）。

Task 1: 新增参数字段 + 钳位方法

Files:

Modify: Calib/CalibrationEngine.cs:27-43（在现有参数字段区追加新字段）
Modify: Calib/CalibrationEngine.cs:51（在 CenterRoi40 之前新增钳位方法）
[ ] Step 1: 追加新参数字段

在 CalibrationEngine.cs 第 43 行 public int CenterScanExposure = 60; 之后插入：


        // ── 行程限位（所有电机移动前钳到该区间）──
        /// <summary>水平电机行程下/上限脉冲（旧工程自检值 70000）。</summary>
        public int HMin = 0, HMax = 70000;
        /// <summary>垂直电机行程下/上限脉冲（旧工程软上限 125000）。</summary>
        public int ZMin = 0, ZMaxPulse = 125000;

        // ── 水平全行程粗扫定位 ──
        /// <summary>水平全行程粗扫起点/终点/步距。命中完整圆即停。</summary>
        public int HCoarseStart = 0;
        public int HCoarseEnd = 70000;
        public int HCoarseStep = 2000;

        // ── Z 全范围粗对焦（固定中心大窗口）──
        /// <summary>Z 粗对焦固定中心（实测焦面集中区间 60000~120000 的中点）。</summary>
        public int ZCoarseCenter = 90000;
        /// <summary>Z 粗对焦半幅 → 区间 60000~120000。</summary>
        public int ZCoarseHalf = 30000;
        /// <summary>Z 粗对焦步距 → 约 31 层。</summary>
        public int ZCoarseStep = 2000;

        // ── Z 精对焦（围绕粗峰）──
        /// <summary>精对焦半幅（覆盖粗扫 ±2000 峰定位误差并留余量）。</summary>
        public int FineZHalf = 6000;
        /// <summary>精对焦步距 → 约 24 层（精度优先）。</summary>
        public int FineZStep = 500;

Step 2: 新增钳位方法

在 CalibrationEngine.cs 第 51 行 /// <summary>中央40% ROI... 注释之前插入：

        /// <summary>水平脉冲钳到 [HMin,HMax]，越界写 Log。</summary>
        int ClampH(int p)
        {
            int c = Math.Max(HMin, Math.Min(HMax, p));
            if (c != p) Log?.Invoke($"  ⚠ 水平脉冲 {p} 越界，钳到 {c} [{HMin},{HMax}]");
            return c;
        }

        /// <summary>垂直脉冲钳到 [ZMin,ZMaxPulse]，越界写 Log。</summary>
        int ClampZ(int p)
        {
            int c = Math.Max(ZMin, Math.Min(ZMaxPulse, p));
            if (c != p) Log?.Invoke($"  ⚠ 垂直脉冲 {p} 越界，钳到 {c} [{ZMin},{ZMaxPulse}]");
            return c;
        }

Step 3: 编译验证

Run: dotnet build AutoFocusTool.csproj -c Debug Expected: 生成成功，0 错误（新字段/方法暂未被调用，会有 0 或仅"未使用"提示，可忽略）

[ ] Step 4: 提交

git add Calib/CalibrationEngine.cs
git commit -m "feat(calib): 新增扫描范围参数与电机限位钳位方法

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"

Task 2: 改 CoarseFocus 为固定大窗口 + 钳位

Files:

Modify: Calib/CalibrationEngine.cs:280-300（整个 CoarseFocus 方法）

当前 CoarseFocus(int well, int centerZ, int half, int layers) 以传入的 EEPROM 零点为中心、半幅 ZHalf=1500、层数 CoarseFocusLayers=7。改为固定中心 ZCoarseCenter=90000、半幅 ZCoarseHalf=30000、步距 ZCoarseStep=2000，并对每个 Z 目标钳位。

Step 1: 替换 CoarseFocus 方法体

将 CalibrationEngine.cs:280-300 的整个方法（从 int CoarseFocus(...) 到其结尾 }）替换为：

        int CoarseFocus(int well)
        {
            int lo = ZCoarseCenter - ZCoarseHalf;
            int hi = ZCoarseCenter + ZCoarseHalf;
            int bestZ = ZCoarseCenter; double bestS = -1;

            // P0-6: 粗对焦使用中央40%区域ROI，避免背景干扰
            var centerROI = CenterRoi40();

            int layers = 0;
            for (int z = lo; z <= hi; z += ZCoarseStep)
            {
                layers++;
                _motor.VerticalMoveTo(ClampZ(z), ScanDelayMs);
                // P0-5: 丢弃旧帧
                Grab();
                var b = Grab();
                double sc = Sharpness.Compute(b, W, H, centerROI); // 中央ROI(避免背景带偏)
                if (sc > bestS) { bestS = sc; bestZ = z; }
                OnStep?.Invoke($"粗对焦 Z={z} (区间{lo}~{hi})", null, null);
            }
            Log?.Invoke($"[well{well}] 粗对焦扫{layers}层 区间[{lo},{hi}] 步距{ZCoarseStep}");
            return bestZ;
        }

注意：方法签名由 CoarseFocus(int well, int centerZ, int half, int layers) 改为 CoarseFocus(int well)——调用方在 Task 4 同步修改。同时更新方法上方的 XML 注释（CalibrationEngine.cs:275-279），把"围绕 centerZ±half"改为"固定中心 ZCoarseCenter±ZCoarseHalf"：

        /// <summary>
        /// 粗对焦：固定中心 ZCoarseCenter±ZCoarseHalf 按 ZCoarseStep 扫描，中央40% ROI 找焦点。
        /// 实测所有 well 焦面集中在 60000~120000，故用固定大窗口，不依赖 EEPROM 零点。
        /// </summary>

Step 2: 编译验证（预期此时报错）

Run: dotnet build AutoFocusTool.csproj -c Debug Expected: FAIL — CalibrateWell 仍按旧签名调用 CoarseFocus(well, eepromZ, ZHalf, CoarseFocusLayers)，报"无重载匹配"。这是预期的，Task 4 修复调用方。

若希望每个 Task 都能独立编译通过，可将 Task 2、4 合并为一次提交执行。本计划按"先改被调方再改调用方"的顺序，最终在 Task 4 末尾统一编译通过。

Step 3: 暂不提交，继续 Task 3、4

（CoarseFocus 与调用方需一起编译通过后再提交，见 Task 4 Step 末尾）

Task 3: 新增 HCoarseLocate（水平全行程粗扫定位 + 局部密扫）+ ScanForCenter 钳位

Files:

Modify: Calib/CalibrationEngine.cs:109-129（ScanForCenter 内的移动加钳位）
Modify: Calib/CalibrationEngine.cs:129（在 ScanForCenter 方法后新增 HCoarseLocate）
[ ] Step 1: ScanForCenter 的移动加钳位

将 CalibrationEngine.cs:111-113 这三行：

                int hp = center - range + step * i;
                if (hp < 0) continue;
                _motor.HorizontalMoveTo(hp, actualDelay);

替换为（去掉 if (hp < 0) continue;，改用 ClampH 统一钳位）：

                int hp = ClampH(center - range + step * i);
                _motor.HorizontalMoveTo(hp, actualDelay);

Step 2: 新增 HCoarseLocate 方法

在 CalibrationEngine.cs 第 129 行（ScanForCenter 方法的结尾 } 之后、CalibrateWell 之前）插入：

        /// <summary>
        /// 水平全行程粗扫定位 + 局部密扫居中。不依赖 EEPROM 水平位置准确：
        /// ① 从 HCoarseStart 到 HCoarseEnd 按 HCoarseStep 扫，命中完整圆即停，记录该位置；
        /// ② 以命中点为中心做局部密扫(ScanForCenter)优化 Y 居中；
        /// ③ 全程未命中完整圆则取扫描中 |Y偏移| 最小且检出的位置；仍无返回 (-1,null)。
        /// </summary>
        (int bestHPos, WellCircle bestCircle) HCoarseLocate(int well)
        {
            _cam.SetExposure(CenterScanExposure);

            int hitHPos = -1; WellCircle hitCircle = null;
            int fallbackHPos = -1; WellCircle fallbackCircle = null;
            double fallbackScore = double.MaxValue;

            // ① 全行程粗扫，命中完整圆即停
            for (int hp = HCoarseStart; hp <= HCoarseEnd; hp += HCoarseStep)
            {
                int p = ClampH(hp);
                _motor.HorizontalMoveTo(p, ScanDelayMs);
                var b = Grab();
                var c = WellDetector.Detect(b, W, H);
                DebugSave?.Invoke(b, $"hcoarse_w{well}_hp{p}");
                Log?.Invoke(c.Found
                    ? $"  粗扫水平{p}: Y偏移={c.OffsetYPct:F1}% 完整={c.Complete}"
                    : $"  粗扫水平{p}: 未检出圆");
                OnStep?.Invoke($"水平粗扫 hp={p}", c, null);
                if (c.Found)
                {
                    double score = Math.Abs(c.OffsetYPct) + (c.Complete ? 0 : 100);
                    if (score < fallbackScore) { fallbackScore = score; fallbackHPos = p; fallbackCircle = c; }
                    if (c.Complete) { hitHPos = p; hitCircle = c; break; }
                }
            }

            // 命中完整圆 → 局部密扫；否则用检出最优的降级点
            int center = hitHPos >= 0 ? hitHPos : fallbackHPos;
            if (center < 0)
            {
                Log?.Invoke($"[well{well}] ✗ 水平全行程未检出任何圆");
                return (-1, null);
            }

            // ② 以命中/降级点为中心局部密扫居中（范围取粗扫步距量级）
            int fineRange = HCoarseStep;
            var fine = ScanForCenter(well, center, fineRange, FineScanSteps, 800);
            if (fine.bestCircle != null) return (fine.bestHPos, fine.bestCircle);

            // ③ 局部密扫没检出 → 回退到粗扫命中/降级结果
            return (center, hitCircle ?? fallbackCircle);
        }

Step 3: 暂不提交，继续 Task 4 后统一编译提交

Task 4: 改 CalibrateWell（调用新定位、新粗对焦、扩精对焦半幅、全程钳位）

Files:

Modify: Calib/CalibrationEngine.cs:135-273（CalibrateWell 方法多处）
[ ] Step 1: 初始水平移动加钳位

将 CalibrationEngine.cs:140 这行：

            if (!RetryMove(() => _motor.HorizontalMoveTo(eepromHPos, ScanDelayMs), $"well{well}初始水平"))

替换为：

            if (!RetryMove(() => _motor.HorizontalMoveTo(ClampH(eepromHPos), ScanDelayMs), $"well{well}初始水平"))

Step 2: 粗对焦调用改新签名 + 钳位

将 CalibrationEngine.cs:150-151：

            int coarseZ = CoarseFocus(well, eepromZ, ZHalf, CoarseFocusLayers);
            _motor.VerticalMoveTo(coarseZ, ScanDelayMs);

替换为：

            int coarseZ = CoarseFocus(well);
            _motor.VerticalMoveTo(ClampZ(coarseZ), ScanDelayMs);

Step 3: ②居中改用 HCoarseLocate

将 CalibrationEngine.cs:156-162：

            Log?.Invoke($"[well{well}] ②旋转居中(优化Y偏移)...");
            var coarse = ScanForCenter(well, eepromHPos, HScanRange, HScanSteps);
            int fineRange = Math.Max(300, 2 * HScanRange / Math.Max(1, HScanSteps - 1));
            var fine = ScanForCenter(well, coarse.bestHPos, fineRange, FineScanSteps, 800);  // 细扫用800ms长延时确保检测准确

            int bestHPos = fine.bestCircle != null ? fine.bestHPos : coarse.bestHPos;
            WellCircle bestCircle = fine.bestCircle ?? coarse.bestCircle;

替换为：

            Log?.Invoke($"[well{well}] ②水平全行程定位+居中...");
            var located = HCoarseLocate(well);
            if (located.bestHPos < 0)
            {
                Log?.Invoke($"[well{well}] ✗ 水平全行程未找到圆，跳过该well");
                return new WellCalib { Well = well, Note = "水平全程未检出圆" };
            }
            int bestHPos = located.bestHPos;
            WellCircle bestCircle = located.bestCircle;

Step 4: 居中后水平移动加钳位

将 CalibrationEngine.cs:166：

            if (!RetryMove(() => _motor.HorizontalMoveTo(bestHPos, ScanDelayMs), $"well{well}居中水平"))

替换为：

            if (!RetryMove(() => _motor.HorizontalMoveTo(ClampH(bestHPos), ScanDelayMs), $"well{well}居中水平"))

Step 5: 精对焦半幅/步距改用新字段 + 钳位

将 CalibrationEngine.cs:211-217：

            int fineZHalf = Math.Max(200, ZHalf / 3);   // 精对焦围绕粗焦点小范围
            int zstep = ZLayers > 1 ? 2 * fineZHalf / (ZLayers - 1) : 1;
            var curve = new List<(int z, double s)>();
            for (int i = 0; i < ZLayers; i++)
            {
                int z = Math.Max(0, coarseZ - fineZHalf) + zstep * i;
                _motor.VerticalMoveTo(z, ScanDelayMs);

替换为（半幅用 FineZHalf，步距用 FineZStep，层数由半幅/步距算出，移动用 ClampZ）：

            int zstep = FineZStep > 0 ? FineZStep : 500;
            int fineLayers = 2 * FineZHalf / zstep + 1;   // 半幅6000步距500 → 25层
            var curve = new List<(int z, double s)>();
            for (int i = 0; i < fineLayers; i++)
            {
                int z = coarseZ - FineZHalf + zstep * i;
                _motor.VerticalMoveTo(ClampZ(z), ScanDelayMs);

Step 6: 精对焦循环内的层数显示与 OnStep 同步

将 CalibrationEngine.cs:223（精对焦 OnStep）：

                OnStep?.Invoke($"精对焦 {i + 1}/{ZLayers} Z={z} 分={sc:F4}", circle, null);

替换为：

                OnStep?.Invoke($"精对焦 {i + 1}/{fineLayers} Z={z} 分={sc:F4}", circle, null);

Step 7: 最终对焦移动加钳位

将 CalibrationEngine.cs:267：

            _motor.VerticalMoveTo(r.FocusZ, ScanDelayMs);

替换为：

            _motor.VerticalMoveTo(ClampZ(r.FocusZ), ScanDelayMs);

Step 8: 编译验证（预期通过）

Run: dotnet build AutoFocusTool.csproj -c Debug Expected: 生成成功，0 错误。

旧字段 HScanRange/HScanSteps/ZHalf/ZLayers/CoarseFocusLayers 现可能不再被引用，编译器不会报错（public 字段）。保留以兼容外部设置，无需删除。

[ ] Step 9: 提交 Task 2~4

git add Calib/CalibrationEngine.cs
git commit -m "feat(calib): 水平全行程粗扫定位 + Z固定大窗口粗对焦 + 扩精对焦半幅

- CoarseFocus 改固定中心90000±30000步距2000
- 新增HCoarseLocate全行程粗扫(0~70000)命中完整圆即停+局部密扫
- 精对焦半幅6000步距500, 所有电机移动经ClampH/ClampZ限位

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"

Task 5: 验证

无单元测试框架，按以下方式验证。

Step 1: 编译全解决方案

Run: dotnet build AutoFocusTool.csproj -c Debug Expected: 生成成功，0 错误。

Step 2: 启动程序确认 UI 不崩溃

Run: ./bin/Debug/net8.0-windows/AutoFocusTool.exe（后台启动） Expected: 主窗口正常显示。不点"自动初始化"则不触发相机（已知相机抓帧段错误不在本次范围）。

Step 3: 真机验证（需连接设备，由用户执行）

清单：

扫描设备 → 连接相机+串口 → 勾选若干 well → 一键自动初始化。
观察标定窗口实时画面：水平粗扫阶段应能看到 well 圆转入画面并命中。
看日志确认：
- 出现 粗扫水平{p}: ... 完整=True 且命中即停。
- 出现 粗对焦扫{N}层区间[60000,120000] 步距2000。
- 精对焦层数约 25 层。
- 若有越界，出现 ⚠ 水平脉冲 ... 越界 / ⚠ 垂直脉冲 ... 越界 日志。
确认原先"找不到圆"的 well 现在能检出并完成标定。

Step 4: 清理后台进程

Run: tasklist | grep -i AutoFocus，确认后停止测试进程。

Self-Review（计划自检结果）

Spec 覆盖：4.1参数→Task1；4.2钳位→Task1 + 各调用点(Task3/4)；4.3水平全行程→Task3 + Task4 Step3；4.4 Z粗对焦→Task2 + Task4 Step2；4.5精对焦扩半幅→Task4 Step5；第7节错误处理(退化/钳位Log)→Task3 ③分支 + ClampH/Z；第8节测试→Task5。无遗漏。
占位符：无 TBD/TODO，每个代码步骤含完整代码。
类型/签名一致性：CoarseFocus(int well) Task2定义、Task4 Step2调用一致；HCoarseLocate(int well) 返回 (int bestHPos, WellCircle bestCircle)，Task4 Step3按此解构；新字段命名 FineZHalf/FineZStep/ZCoarseCenter/ZCoarseHalf/ZCoarseStep/HCoarseStart/HCoarseEnd/HCoarseStep/HMin/HMax/ZMin/ZMaxPulse 全计划一致。
编译顺序：Task2 改被调方后单独编译会失败（已注明），Task2~4 合并提交，Task4 Step8 编译通过——有意的"先改被调方再改调用方"顺序。

2026-06-16-autofocus-scan-range.md 18 KB Histórico Raw

AutoFocus 扫描范围扩大与电机限位 — 实现计划

文件结构

Task 1: 新增参数字段 + 钳位方法

Task 2: 改 CoarseFocus 为固定大窗口 + 钳位

Task 3: 新增 HCoarseLocate（水平全行程粗扫定位 + 局部密扫）+ ScanForCenter 钳位

Task 4: 改 CalibrateWell（调用新定位、新粗对焦、扩精对焦半幅、全程钳位）

Task 5: 验证

Self-Review（计划自检结果）

2026-06-16-autofocus-scan-range.md 18 KB

Histórico Raw