Similari

较新版本（重命名）：

旧版本：

:star: 在 GitHub 上给我们点星 — 这对我们来说是很大的激励！

Similari 是一个带有 Python 绑定的 Rust 框架，用于构建复杂的跟踪系统。使用 Similari，可以开发高效并行化的 SORT、DeepSORT 以及其他复杂的单观察者（如摄像头）或多观察者跟踪引擎。

简介

Similari 的主要目的是提供构建复杂的内存多目标跟踪引擎的方法。

该框架有助于构建各种跟踪和相似性搜索引擎 - 最简单的引擎保存向量特征并允许将新向量与数据库中保存的向量进行比较。更复杂的引擎处理轨迹 - 在生命周期内为同一特征收集的一系列观察结果。这种系统通常用于视频处理或其他观察者接收模糊或变化的观察结果的系统。

开箱即用功能

Similari 是一个用于构建自定义跟踪器的框架，但它也提供了某些算法作为最终用户功能：

边界框卡尔曼滤波器，用于预测与场景轴对齐的矩形边界框，也支持定向（旋转）边界框。

2D 点卡尔曼滤波器，用于预测 2D 点运动。

2D 点向量卡尔曼滤波器，用于预测独立 2D 点运动的向量（用于关键点跟踪器）。

边界框裁剪，允许计算轴对齐和定向（旋转）边界框的交叉区域。

非极大值抑制（NMS） - 过滤与场景同轴的矩形边界框，并支持定向边界框。

SORT 跟踪算法（支持轴对齐和定向框） - 支持 IoU 和马哈拉诺比斯距离。

批量 SORT 跟踪算法（支持轴对齐和定向框） - 支持 IoU 和马哈拉诺比斯距离。批量跟踪器允许在单个批次中向跟踪器传递多个场景并获取结果。如果平台支持批处理（如 Nvidia DeepStream 或 Intel DL Streamer），使用批量跟踪器会更有益。

VisualSORT 跟踪 - 类似 DeepSORT 的算法（支持轴对齐和定向框） - 支持 IoU 和马哈拉诺比斯距离进行位置跟踪，欧几里得和余弦距离用于特征向量的视觉跟踪。

批量 VisualSORT - 批处理 VisualSORT 版本；

适用性说明

虽然 Similari 允许构建各种跟踪和相似性引擎，但有时也存在更适合的竞争工具。本节将解释其适用范围和现有的替代方案。

Similari 最适合那些对象由特定特征类的多个观察结果描述，而不是单一特征向量的跟踪任务。此外，它们的行为是动态的 - 你从索引中删除或修改它们的频率与添加新对象一样高。这是一个非常重要的点 - 它比处理增长或静态对象空间的工具效率略低。

适合：在房间内跟踪人员：在跟踪过程中多次收集人员重识别、年龄/性别和面部特征，用于合并轨迹或在轨迹结束时提供聚合结果；

不适合：抄袭数据库，其中单个文档由一个（或多个）常量重识别向量描述，文档只添加不删除。任务是找到与被检查文档最相似的前 X 个文档。

如果你的任务看起来不适合，可以使用 Similari，但你可能在寻找 HNSW 或 NMS 实现：

HNSW Rust - 链接
HNSW C/Python - 链接
NMSLib - 链接

Similari 对象支持以下特性：

轨迹生命周期 - 对象由其生命周期（轨迹）表示 - 它出现、演变和消失。在其生命周期内，对象根据其行为属性（属性和特征观察）演变。

观察 - Similari 假设对象被观察者实体多次观察，收集其特征（统一向量）和自定义观察属性（如 GPS 或屏幕框位置）。这些特征由浮点数向量和观察属性表示。当观察发生时，轨迹会用收集到的特征更新。未来的观察用于在索引中找到相似的轨迹并合并它们。

轨迹属性 - 任意属性描述了除特征观察之外的额外轨迹属性。当你在野外比较对象时，轨迹属性是至关重要的部分，因为可能存在属性差异使对象不兼容，比如 animal_type 禁止你比较 dogs 和 cats。属性的另一个常见用途是对象的空间或时间特征，例如，同一时间位于远距离位置的对象不能被比较。Similari 中的属性是动态的，随每次特征观察添加和对象合并而演变。它们既用于距离计算，也用于兼容性猜测（通过跳过不兼容的对象来减少计算空间）。

如果你计划使用 Similari 在大型索引中搜索，请考虑使用对象属性来分割查找空间。如果两个轨迹的属性不兼容，将跳过它们的距离计算。

性能

Similari 速度很快。它通常比用 Python 和 NumPy 构建的跟踪器更快。

为了高效运行视觉特征计算，该框架使用 ultraviolet - 一个用于快速 SIMD 计算的库。

并行计算通过索引分片和基于专用线程工作池的并行计算来实现。

向量操作性能在很大程度上取决于为构建定义的优化级别。在低或默认优化级别下，Rust 可能不会使用 f32 向量化，因此在运行基准测试时要注意配置适当的优化级别。

Rust 优化

使用 RUSTFLAGS="-C target-cpu=native" 来启用所有 CPU 特性，如 AVX、AVX2 等。这对 ultraviolet 有益。

或者，你可以在 .cargo/config 中添加构建指令：

[build]
rustflags = "-C target-cpu=native"

查看基准测试以获取数据。

性能基准测试

一些基准测试数据在这里呈现：基准测试

你可以通过以下方式运行自己的基准测试：

rustup default nightly
cargo bench

Apple Silicon 构建注意事项

你可能需要在 ~/.cargo/config 中添加以下行以在 Apple Silicon 上构建代码：

[build]
rustflags = "-C target-cpu=native"

# Apple Silicon 修复
[target.aarch64-apple-darwin]
rustflags = [
    "-C", "link-arg=-undefined",
    "-C", "link-arg=dynamic_lookup",
]

Python API

Python 接口暴露了 Similari 的现成函数和类。目前，Python 接口提供：

用于轴对齐和定向（旋转）框预测的卡尔曼滤波器；
用于 2D 点运动预测的卡尔曼滤波器；
2D 点向量卡尔曼滤波器，用于预测独立 2D 点运动的向量（用于关键点跟踪器）；
NMS（非极大值抑制）；
Sutherland-Hodgman 裁剪，定向（旋转）框的交叉区域；
具有 IoU 和马哈拉诺比斯度量的 SORT；
具有 IoU 和马哈拉诺比斯度量的 BatchSORT；
VisualSORT - 类似 DeepSORT 的跟踪器，使用欧几里得/余弦度量进行视觉特征跟踪，IoU/马哈拉诺比斯度量进行位置跟踪（VisualSort）。
BatchVisualSORT - 批处理 VisualSORT 版本；

可以在 Python 文档和提供的简单示例中探索 Python API 类和函数。

还提供了 MOTChallenge 评估工具包，你可以使用它来简单评估跟踪器性能和指标。

从 PyPi 安装 Python API

请注意，PyPi 包是为适应广泛的平台而构建的，因此它可能不如你为自己的平台本地构建的版本快（请参阅以下部分）。

支持的平台：

Linux：X86_64、ARM64、ARMv7；
Windows：X86_64；
MacOS：X86_64、ARM64。

pip3 install similari-trackers-rs

在Docker中构建Python API

你可以在Docker中构建wheel包，如果你想在宿主系统中安装它，可以按照以下示例将生成的包复制到宿主系统。

Rust 1.67 基础镜像

如果你使用其他Rust库，可能会发现使用基础Rust容器（和Python 3.8）构建更有益:

docker build -t similari-trackers-rs -f docker/rust_1.67/Dockerfile .

# 可选：复制并安装到宿主系统
docker run --rm -it -v $(pwd)/distfiles:/tmp similari-trackers-rs cp -R /opt/dist /tmp
pip3 install --force-reinstall distfiles/dist/*.whl

Python 3.8 基础镜像

Python 3.8仍然是一个使用非常频繁的版本。以下是如何用它构建Similari:

docker build -t similari-trackers-rs -f docker/python_3.8/Dockerfile .

# 可选：复制并安装到宿主系统
docker run --rm -it -v $(pwd)/distfiles:/tmp similari-trackers-rs cp -R /opt/dist /tmp
pip3 install --force-reinstall distfiles/dist/*.whl

Python 3.10 基础镜像

如果你使用最新的Python环境，可以使用基础Python容器构建:

docker build -t similari-trackers-rs -f docker/python_3.10/Dockerfile .

# 可选：复制并安装到宿主系统
docker run --rm -it -v $(pwd)/distfiles:/tmp similari-trackers-rs cp -R /opt/dist /tmp
pip3 install --force-reinstall distfiles/dist/*.whl

注意: 如果你遇到类似这样的pip3错误:

ERROR: similari-trackers-rs-0.26.4-cp38-cp38-manylinux_2_28_x86_64.whl is not a supported wheel on this platform.

这意味着宿主系统中的Python版本与用于构建wheel的镜像中的版本不匹配。

在宿主系统中构建Python API

Linux 说明

安装最新的Rust工具链:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
rustup update

安装build-essential工具 apt install build-essential -y。
安装Python3 (>= 3.8)和开发文件（python3-dev）。
安装Maturin:

pip3 install --upgrade maturin~=0.15

不在虚拟环境中。构建Python模块:

RUSTFLAGS=" -C target-cpu=native -C opt-level=3" maturin build --release --out dist
pip3 install --force-reinstall dist/*.whl

在虚拟环境中。构建Python模块:

RUSTFLAGS=" -C target-cpu=native -C opt-level=3" maturin develop

使用示例位于python。
Similari追踪器和传统追踪器的MOT Challenge Docker镜像在这里。你可以轻松构建一个all-in-one Docker镜像并尝试我们的追踪器。

手册和文章

收集的关于如何使用Similari解决特定问题的文章。

Medium.com

IoU对象追踪器示例；
Re-ID对象追踪器示例；
SORT对象追踪器示例；
Python SORT对象追踪器示例；
Python旋转SORT对象追踪器示例；
为什么你需要高性能追踪系统进行多目标追踪。

使用示例

查看仓库中的示例：

simple.rs - 简单使用的思路。
track_merging.rs - 摄像头内轨迹合并的思路。
incremental_track_build.rs - 非常简单的基于特征的追踪器。
simple_sort_iou_tracker.rs - SORT追踪器（带卡尔曼滤波，IoU）。
simple_sort_iou_tracker_oriented.rs - 面向（旋转）SORT追踪器（带卡尔曼滤波，IoU）。
simple_sort_maha_tracker.rs - SORT追踪器（带卡尔曼滤波，马氏距离）。
simple_sort_maha_tracker_oriented.rs - 面向SORT追踪器（带卡尔曼滤波，马氏距离）。
middleware_sort_tracker.rs - SORT追踪器（带卡尔曼滤波，中间件实现）。