test_demo/MX-PD-盘古 - new/PanGu.DieBonderApp/MainShell/Motion/ApproachAlignment/README.md

逼近对位功能快速参考

1. 文档范围

本文档基于当前仓库 main 分支最新已提交代码整理，描述 MainShell/Motion/ApproachAlignment 目录下逼近对位模块的真实实现、调用方式和接入注意事项。

说明：

• 本文档以 git 最新已提交代码为准。
• 若旧 README、注释或设计文档与代码不一致，以代码为准。
• 当前模块的流程框架已具备，但坐标变换仍需业务侧补齐真实实现。

2. 文件清单

文件	说明
ApproachAlignment.cs	数据结构和接口定义
ApproachAlignmentService.cs	逼近对位主流程
CenterRecognizer.cs	中心识别实现
CoordinateTransformer.cs	坐标转换实现

3. 核心类型

当前代码中，以下类型定义在 ApproachAlignment.cs 中：

• ApproachAlignmentAxis
• ApproachAlignmentRequest
• ApproachAlignmentResult
• CoordinateTransformResult
• ICenterRecognizer
• ICoordinateTransformer

3.1 ApproachAlignmentAxis

用于描述参与逼近对位的单根轴：

• AxisName：轴名
• ToleranceValue：该轴允许误差
• Description：可选描述，用于日志或调试

3.2 ApproachAlignmentRequest

用于描述一次逼近对位请求：

• Axes：参与对位的轴列表
• Camera：相机类型，默认 CameraType.UpCamera
• MaxIterations：最大迭代次数，默认 5
• MoveTimeoutMilliseconds：运动超时，默认 30000
• RecognitionTimeoutMilliseconds：识别超时，默认 10000

3.3 ApproachAlignmentResult

用于描述逼近对位结果：

• Succeeded：是否成功收敛
• CompletedIterations：实际完成的迭代次数
• FinalErrors：各轴最终误差
• FinalAxisPositions：各轴最终位置
• Exception：失败或取消时的异常
• Message：结果消息

4. 当前真实入口

当前 git 最新代码中，逼近对位的真实调用入口是：

• ApproachAlignmentService.cs

主要方法：

Task<ApproachAlignmentResult> ApproachAlignmentAsync(
    ApproachAlignmentRequest request,
    CancellationToken cancellationToken = default(CancellationToken))

注意：

• 当前 SafeAxisMotion 中并没有 ApproachAlignmentAsync() 或 ApproachAlignment() 这组方法。
• 旧 README 中写到 SafeAxisMotion.ApproachAlignmentAsync() 的内容，和当前代码不一致。
• 实际接入时应直接注入并调用 ApproachAlignmentService。

5. 工作流程

ApproachAlignmentService.cs 当前实现的是一个迭代式流程：

1. 根据请求进入循环，最多执行 MaxIterations 次。
2. 首次迭代调用 ICenterRecognizer.RecognizeCenterAsync() 识别中心。
3. 调用 ICoordinateTransformer.TransformAsync() 将视觉中心转换为各轴目标位置。
4. 把转换结果封装为 MotionMoveRequest 数组。
5. 调用 SafeAxisMotion.SafeMoveAsync() 执行多轴移动。
6. 再次识别中心。
7. 再次做坐标转换。
8. 用“当前轴位置”和“新转换目标位置”计算误差。
9. 如果所有轴误差都在各自 ToleranceValue 内，则成功结束。
10. 否则继续下一轮迭代，直到达到最大迭代次数。

6. 必须实现或理解的接口

6.1 ICenterRecognizer

接口定义：

Task<(double CenterX, double CenterY)?> RecognizeCenterAsync(
    CameraType camera,
    int timeoutMilliseconds,
    CancellationToken cancellationToken = default(CancellationToken));

当前默认实现是 CenterRecognizer.cs。

它的真实行为是：

• 依赖 IVisionAlgorithmService
• 构造 VisionProcessRequest
• AlgorithmType = VisionAlgorithmType.FindCenter
• CaptureOptions = CameraCaptureOptions.CreateStream(timeoutMilliseconds)
• 从结果里读取 OffsetX / OffsetY
• 识别失败时返回 null

如果你们已有自己的视觉流程，也可以替换成自定义的 ICenterRecognizer 实现。

6.2 ICoordinateTransformer

接口定义：

Task<CoordinateTransformResult> TransformAsync(
    double centerX,
    double centerY,
    IEnumerable<ApproachAlignmentAxis> axes);

当前默认实现是 CoordinateTransformer.cs。

但需要特别注意：

• 当前实现只是占位版本
• 它会给每根轴写入 0.0 作为目标位置
• 然后直接返回 Succeeded = true

这表示：

• 逼近对位的流程框架是完整的
• 但真实标定坐标转换还没有完成
• 若直接用于生产逻辑，目标位置会被错误地写成固定值

因此，接入前必须替换为你们设备真实可用的坐标变换实现。

7. 依赖关系

当前 ApproachAlignmentService 构造函数依赖：

• SafeAxisMotion
• ICenterRecognizer
• ICoordinateTransformer
• HardwareManager

依赖注入示例：

protected override void ConfigureIoC(IStyletIoCBuilder builder)
{
    builder.Bind<SafeAxisMotion>().ToSelf().InSingletonScope();
    builder.Bind<ICenterRecognizer>().To<CenterRecognizer>().InSingletonScope();
    builder.Bind<ICoordinateTransformer>().To<CalibratedCoordinateTransformer>().InSingletonScope();
    builder.Bind<ApproachAlignmentService>().ToSelf().InSingletonScope();
}

说明：

• CenterRecognizer 可以直接复用当前实现
• ICoordinateTransformer 建议替换为你们自己的真实标定实现，不建议直接使用当前占位版 CoordinateTransformer

8. 推荐接入方式

8.1 典型调用流程

1. 创建 ApproachAlignmentAxis 列表
2. 创建 ApproachAlignmentRequest
3. 调用 ApproachAlignmentService.ApproachAlignmentAsync()
4. 检查 ApproachAlignmentResult.Succeeded
5. 如失败，查看 Exception 或 Message
6. 如成功，读取 FinalAxisPositions 和 FinalErrors

8.2 示例代码

public async Task<ApproachAlignmentResult> RunApproachAlignmentAsync(CancellationToken cancellationToken)
{
    var request = new ApproachAlignmentRequest(
        new[]
        {
            new ApproachAlignmentAxis("Axis_X", 0.01) { Description = "X axis" },
            new ApproachAlignmentAxis("Axis_Y", 0.01) { Description = "Y axis" }
        },
        camera: CameraType.UpCamera)
    {
        MaxIterations = 5,
        MoveTimeoutMilliseconds = 30000,
        RecognitionTimeoutMilliseconds = 10000
    };

    var result = await _approachAlignmentService.ApproachAlignmentAsync(
        request,
        cancellationToken);

    if (!result.Succeeded)
    {
        throw result.Exception ?? new InvalidOperationException(result.Message);
    }

    return result;
}

9. 自定义坐标转换器示例

以下示例展示如何替换当前占位版 CoordinateTransformer：

public class CalibratedCoordinateTransformer : ICoordinateTransformer
{
    public Task<CoordinateTransformResult> TransformAsync(
        double centerX,
        double centerY,
        IEnumerable<ApproachAlignmentAxis> axes)
    {
        var result = new CoordinateTransformResult();

        foreach (var axis in axes)
        {
            var target = CalculateTarget(axis.AxisName, centerX, centerY);
            result.AxisPositions[axis.AxisName] = target;
        }

        result.Succeeded = true;
        return Task.FromResult(result);
    }

    private double CalculateTarget(string axisName, double centerX, double centerY)
    {
        // 替换为实际标定变换逻辑
        throw new NotImplementedException();
    }
}

10. 日志输出示例

当前代码里，ApproachAlignmentService 会输出类似这样的日志：

[INFO] Approach alignment iteration 1/5 started.
[INFO] Center recognized: X=1024.5600, Y=768.3200
[INFO] Coordinate transformation completed: 2 axes.
[INFO] Axes moved successfully: 2 axes completed.
[INFO] Center recognized again: X=1023.9800, Y=768.1500
[INFO] Axis: Axis_X, Current: 100.0250, Expected: 100.0200, Error: 0.005000, Tolerance: 0.0100, WithinTolerance: True
[INFO] Axis: Axis_Y, Current: 200.0150, Expected: 200.0100, Error: 0.005000, Tolerance: 0.0100, WithinTolerance: True
[INFO] Approach alignment succeeded after 1 iteration(s).

如果异常发生，也会记录失败日志，例如：

• Center recognition failed.
• Coordinate transformation failed: ...
• Failed to get current position for axis ...

11. 常见问题

Q: 如何修改最大迭代次数？

A: 设置 ApproachAlignmentRequest.MaxIterations。

Q: 如何设置不同轴的允许误差？

A: 为每个 ApproachAlignmentAxis 设置不同的 ToleranceValue。

Q: 能否在执行中途取消？

A: 可以，通过 CancellationToken 取消。取消后结果中的 Exception 会记录取消异常。

Q: 如何查看每个轴的最终误差？

A: 查看 ApproachAlignmentResult.FinalErrors。

Q: 逼近失败时如何获取原因？

A: 查看 ApproachAlignmentResult.Exception 或 ApproachAlignmentResult.Message。

Q: 当前默认实现能直接用于生产吗？

A: 不建议。CenterRecognizer 基本可接真实视觉流程，但 CoordinateTransformer 仍是占位实现，必须先替换。

12. 当前状态总结

当前 ApproachAlignment 模块的真实状态是：

• 数据结构已经完整
• 主流程已经完整
• 视觉识别已有可接真实系统的实现
• 运动执行复用了 SafeAxisMotion
• 坐标变换仍需业务侧补齐真实算法
• README 中旧的 SafeAxisMotion.ApproachAlignmentAsync() 说法已经不适用

接入建议：

• 直接注入 ApproachAlignmentService
• 保留当前 CenterRecognizer 或替换成自定义实现
• 优先补齐真实的 ICoordinateTransformer
• 在真实设备上联调前，不要使用默认 CoordinateTransformer 做生产动作