Go rtreego 怎样按矩形范围检索空间对象

在 Go 里做地图要素、碰撞区域或画布对象检索时，最容易混淆的是“对象的中心点”和“对象的边界”。rtreego 的矩形范围查询要求对象实现 Spatial 接口，并通过 Bounds() *Rect 返回自己的边界；查询时再把一个 Rect 传给 SearchIntersect。只要对象边界与查询矩形存在非零交集，它就会进入结果集。

官方地址：https://pkg.go.dev/github.com/dhconnelly/rtreego

实战中先把“对象怎样覆盖空间”定义清楚，再写范围查询。查询为空时优先检查维度、矩形方向和 Bounds 返回值，而不是先怀疑 R-tree 没有工作。

先确认查询模型：查的是矩形交集

rtreego 支持 N 维空间。本文用二维坐标举例：对象返回一个由左下角和边长构成的矩形，查询也使用一个矩形。SearchIntersect 返回与查询矩形有非零交集的对象；只擦到边界、没有面积交集的情况不要当成命中。

这也是排查结果不符合预期时的第一层检查：你要查的是“覆盖范围相交”，还是“中心点落在框内”？如果是后者，就需要自己定义点包含判断，不能把 SearchIntersect 当成中心点查询。

让对象先拥有可查询的边界

存入树的对象只需要满足 Spatial 接口。下面把房间看作二维平面中的一个矩形，并把边界保存为指针。代码中的中文注释解释了坐标约定和错误处理。

package main

import (
    "fmt"

    "github.com/dhconnelly/rtreego"
)

// Room 用左下角坐标和宽高描述一个可检索对象。
type Room struct {
    ID    string
    Bound *rtreego.Rect
}

// Bounds 让 Room 满足 rtreego.Spatial 接口。
func (r *Room) Bounds() *rtreego.Rect {
    return r.Bound
}

func newRoom(id string, x, y, width, height float64) (*Room, error) {
    // NewRect 要求 p 是各维度最小点，长度必须为正数。
    rect, err := rtreego.NewRect(rtreego.Point{x, y}, []float64{width, height})
    if err != nil {
        return nil, fmt.Errorf("创建房间 %s 的边界失败: %w", id, err)
    }
    return &Room{ID: id, Bound: &rect}, nil
}

这里没有把中心点单独存成查询依据，因为 R-tree 需要的是对象的空间边界。若对象是一个点，可以用 Point.ToRect(tol) 生成一个带容差的小矩形；容差过小会让边界接触和浮点误差更明显。

创建二维树并插入对象

NewTree(dim, min, max, objs...) 的第一个参数是维度，后两个参数是节点的最小、最大分支因子。示例使用二维树和常见的 25、50 参数；它们影响树节点组织，不改变范围查询的语义。

func buildTree() (*rtreego.Rtree, error) {
    // 二维坐标树：min/max 只控制节点分支范围，不是查询范围。
    tree := rtreego.NewTree(2, 25, 50)

    rooms := []struct {
        id            string
        x, y          float64
        width, height float64
    }{
        {"A", 0, 0, 4, 3},
        {"B", 5, 1, 3, 3},
        {"C", 9, 6, 2, 2},
    }
    for _, item := range rooms {
        room, err := newRoom(item.id, item.x, item.y, item.width, item.height)
        if err != nil {
            return nil, err
        }
        // Insert 接收 Spatial；树会根据 Bounds 自动组织节点。
        tree.Insert(room)
    }
    return tree, nil
}

如果对象已经在初始化阶段准备好，也可以作为 NewTree 的可变参数传入。对于持续变化的数据，逐个 Insert 更容易和对象生命周期对应。

用 NewRectFromPoints 构造查询矩形

范围查询最容易写反的是矩形的两个角点。建议显式使用最小点和最大点，避免把右上角误当成长度参数。

func searchRooms(tree *rtreego.Rtree) []string {
    // minPoint 是每一维的较小坐标，maxPoint 是每一维的较大坐标。
    query, err := rtreego.NewRectFromPoints(
        rtreego.Point{2, 1},
        rtreego.Point{7, 4},
    )
    if err != nil {
        // 维度不一致或坐标关系不合法时，先返回空结果并保留原因。
        fmt.Printf("创建查询矩形失败: %v\\n", err)
        return nil
    }

    // SearchIntersect 返回与 query 有非零交集的对象。
    matches := tree.SearchIntersect(&query)
    ids := make([]string, 0, len(matches))
    for _, item := range matches {
        ids = append(ids, item.(*Room).ID)
    }
    return ids
}

上面的查询矩形覆盖了从 (2,1) 到 (7,4) 的区域，房间 A 和 B 的边界会与它相交，房间 C 则不会命中。结果顺序不要当成业务排序；如果页面需要按距离、名称或优先级展示，应在结果返回后另行排序。

结果为空时，按四层清单排查

1. 检查维度：树是二维时，Point、Rect 和每个对象的边界都必须是二维。维度不一致通常在构造矩形阶段就会返回错误。
2. 检查角点：NewRect 的点是各维度最小点，长度必须为正；不确定时优先用 NewRectFromPoints。
3. 检查 Bounds：对象返回的边界必须稳定且覆盖真实对象。返回了错误区域，查询即使正常也找不到它。
4. 检查交集定义：只接触边界不代表有非零交集；需要“边界相接也命中”时，先扩大查询矩形或实现自己的判定。

数量限制与对象更新怎么处理

如果只需要最多若干条结果，可以用 LimitFilter。它会在结果达到上限时终止搜索，但这不是“距离最近的前 N 条”，结果顺序也不应被解释成稳定排序。

func searchAtMost(tree *rtreego.Rtree, query *rtreego.Rect, limit int) []*Room {
    if limit 

对象位置改变时，不要只修改对象内部的矩形。官方说明要求先从树中删除对象，修改边界后再插入，否则树中的包围盒可能与对象的新位置不一致。

func moveRoom(tree *rtreego.Rtree, room *Room, next *rtreego.Rect) {
    // 先删除旧索引，再替换边界，最后重新插入以维护树结构。
    if removed := tree.Delete(room); !removed {
        return
    }
    room.Bound = next
    tree.Insert(room)
}

一张可复用的检查清单

常见问题

SearchIntersect 返回的是 Rect 还是原对象？

返回的是实现 Spatial 的对象切片。示例中通过类型断言还原为 *Room，再读取业务字段。

查询框与对象只碰到一条边会返回吗？

不要把边界接触当成非零交集。若业务需要包含这类对象，应该在查询范围上增加明确容差，并把该规则写进业务层。

什么时候使用 SearchIntersectWithLimit？

它是兼容性接口；新代码可以直接使用 SearchIntersect 配合 LimitFilter，让数量限制成为查询参数的一部分。

总结

Go rtreego 的矩形范围检索可以浓缩成四步：让对象通过 Bounds 暴露稳定边界，创建同维度的 Rtree，用最小点和最大点构造查询 Rect，最后调用 SearchIntersect。当结果异常时，优先按维度、角点、Bounds 和交集定义逐层检查；当对象移动时，始终按删除、更新、重新插入的顺序维护索引。