Go image/draw 的偏移画布绘制方案

Go 的 image/draw 适合把一张源图放到另一张画布的指定偏移位置。最小规则只有一句话：draw.Draw 会把目标矩形 r 的左上角 r.Min 与源图中的点 sp 对齐，然后把对应区域写入目标画布。

官方地址：https://pkg.go.dev/image/draw

因此，偏移绘制不是给源图坐标直接加一个整数那么简单，而是要同时确定目标画布、目标矩形、源点和组合操作。下面按一条完整工作流把这些坐标关系拆开。

一、先明确偏移绘制的四个对象

一次普通的偏移绘制至少涉及四个对象：可写的目标画布 dst、目标矩形 r、只读的源图 src，以及源点 sp。调用形式是：

draw.Draw(dst, r, src, sp, draw.Over)

// dst 是最终要被修改的画布；它必须实现 image/draw.Image。
// r 是目标区域，r.Min 决定源图的哪个点落在画布的什么位置。
// src 是被复制或叠加的源图，sp 是源图中的起始坐标。
// draw.Over 表示按透明度叠加；需要完全替换时再考虑 draw.Src。

官方文档的关键语义是把 r.Min 与 sp 对齐，再把源图绘制到目标图像。因此想把源图左上角放到画布的 (40, 30)，通常写成 r := image.Rect(40, 30, 40+width, 30+height)，而不是修改源图本身。

二、把偏移量转换成目标矩形

最容易复用的写法是把偏移量拆成 offsetX、offsetY，再用源图尺寸计算目标矩形。这样调用方只表达“放在哪里”，不会手写右下角坐标。

package main

import (
    "image"
    "image/color"
    "image/draw"
)

func drawAtOffset(dst draw.Image, src image.Image, offset image.Point) {
    // 读取源图边界，兼容源图尺寸不是从零开始的情况。
    srcBounds := src.Bounds()
    width, height := srcBounds.Dx(), srcBounds.Dy()

    // 目标矩形的 Min 是放置位置，Max 由源图的宽高推导。
    target := image.Rectangle{
        Min: offset,
        Max: image.Point{X: offset.X + width, Y: offset.Y + height},
    }

    // 用源图边界的 Min 作为 sp，保持非零坐标源图的左上角对齐。
    draw.Draw(dst, target, src, srcBounds.Min, draw.Over)
}

func exampleCanvas() draw.Image {
    // 画布从 (0,0) 开始，颜色只用于说明目标对象的创建方式。
    canvas := image.NewRGBA(image.Rect(0, 0, 320, 220))
    draw.Draw(canvas, canvas.Bounds(), &image.Uniform{C: color.White}, image.Point{}, draw.Src)
    return canvas
}

这里的 target.Min 就是偏移量。target.Max 只表示目标区域的尺寸，不应该直接拿源图的 Max 当作目标右下角，因为源图可能有非零 Min。

三、理解 r.Min 与 sp 的对齐关系

可以把每个目标像素写成一个简单的对应关系：目标坐标 p 对应源坐标 sp + (p - r.Min)。所以当 r.Min 是 (40,30)、sp 是 (0,0) 时，源图左上角会落在目标画布的 (40,30)。

如果源图的边界是 image.Rect(10, 20, 110, 80)，它的逻辑左上角不是 (0,0)，此时应把 src.Bounds().Min 作为 sp。这能避免源图内容整体偏移一个额外的 (10,20)。

func drawSourceOrigin(dst draw.Image, src image.Image, offset image.Point) {
    // 让源图 Bounds 的 Min 与目标矩形 Min 对应，忽略源图的外部坐标起点。
    bounds := src.Bounds()
    target := image.Rectangle{
        Min: offset,
        Max: offset.Add(image.Pt(bounds.Dx(), bounds.Dy())),
    }

    // sp 不写死为 image.Point{}，否则非零 Bounds 的源图会出现位置误差。
    draw.Draw(dst, target, src, bounds.Min, draw.Over)
}

四、按透明度选择 Over 或 Src

draw.Over 会把源图按 alpha 叠加到目标上，适合贴纸、半透明水印和带透明背景的图层。draw.Src 则表示用源图像素替换目标区域，适合你明确希望目标区域的颜色和 alpha 都由源图决定的场景。

func pasteOpaque(dst draw.Image, src image.Image, offset image.Point) {
    // 目标区域与源图等大，确保替换范围不会多出一圈旧像素。
    b := src.Bounds()
    target := image.Rectangle{
        Min: offset,
        Max: offset.Add(image.Pt(b.Dx(), b.Dy())),
    }

    // Src 会覆盖目标区域；源图的透明像素也会按 Src 规则参与结果。
    draw.Draw(dst, target, src, b.Min, draw.Src)
}

不要把两种操作当成“性能开关”。它们改变的是合成语义：需要保留背景时用 Over，需要替换目标矩形时才用 Src。如果目标画布有预先填充的颜色，误用 Src 可能让透明区域的结果与预期不同。

五、处理非零边界和画布外偏移

偏移量可以是负数，目标矩形也可以部分落在画布外。draw.Draw 会按目标画布和目标矩形的可见交集处理，画布外部分不会凭空扩展画布。真正需要关注的是：你是否还要把完整源图保留在画布内。

func drawWithVisibleArea(dst draw.Image, src image.Image, offset image.Point) {
    // 目标矩形可以越过画布边缘；这里只负责描述完整的目标范围。
    b := src.Bounds()
    target := image.Rectangle{
        Min: offset,
        Max: offset.Add(image.Pt(b.Dx(), b.Dy())),
    }

    // draw.Draw 只会影响 dst 与 target 的可见交集，画布尺寸不会自动增长。
    draw.Draw(dst, target, src, b.Min, draw.Over)
}

如果业务不允许裁剪，可以在调用前检查 target.In(dst.Bounds())。检查失败时返回错误，比静默截断更容易发现头像、贴图或导出画布尺寸配置错误。

六、封装一条稳定的偏移绘制流程

把流程收敛到一个函数时，建议固定以下顺序：读取源图边界，计算目标矩形，按业务选择 sp，最后调用 draw.Draw。这样可以把坐标判断集中在一个地方。

func pasteFullyInside(dst draw.Image, src image.Image, offset image.Point) error {
    // 源图的尺寸来自 Bounds，避免把非零 Min 误当成尺寸。
    srcBounds := src.Bounds()
    target := image.Rectangle{
        Min: offset,
        Max: offset.Add(image.Pt(srcBounds.Dx(), srcBounds.Dy())),
    }

    // 这个版本拒绝越界，适合不允许裁剪的头像或图层合成任务。
    if !target.In(dst.Bounds()) {
        return fmt.Errorf("目标矩形 %v 超出画布 %v", target, dst.Bounds())
    }

    // 对齐源图真实起点，避免非零 Bounds 造成整体偏移。
    draw.Draw(dst, target, src, srcBounds.Min, draw.Over)
    return nil
}

上面的函数需要导入 fmt。这里保留错误返回，是为了让上层决定是调整偏移、扩大画布还是拒绝当前任务；不要在底层绘制函数里偷偷修改画布尺寸。

七、常见误区和速查表

为什么图像位置总是偏一截？

优先检查源图的 Bounds().Min 是否非零，以及 r.Min 是否被当成尺寸使用。偏移绘制依赖的是两个坐标系的对齐，不是简单的宽高相加。

画布外的部分会自动扩大画布吗？

不会。draw.Draw 只写入目标画布已有的可见区域，若需要更大的输出，应先创建尺寸合适的新画布，再执行绘制。

什么时候必须拒绝负偏移？

当业务要求整张源图完整出现时，应拒绝或调整负偏移；当业务明确允许裁剪时，可以保留负偏移，并把裁剪视为预期结果。

总结

Go image/draw 的偏移画布绘制可以归纳为：用偏移量构造目标矩形，把 r.Min 与 src.Bounds().Min 对齐，按透明度语义选择 draw.Over 或 draw.Src，再根据是否允许裁剪决定检查或直接绘制。把这四个决定集中封装后，贴图、头像合成和画布导出都能复用同一套坐标规则。