Similari

较新版本（已重命名）

较旧版本

⭐ 在 GitHub 上星标我们——这对我们有很大的激励！

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

简介

Similari 的主要目的是提供构建复杂的内存中多对象跟踪引擎的手段。

该框架有助于构建各种类型的跟踪和相似性搜索引擎——最简单的一种是存储向量特征，并允许将新向量与数据库中存储的向量进行比较。更复杂的引擎在轨迹上操作——同一特征在整个生命周期中收集的一系列观测值。此类系统通常用于视频处理或其他系统，其中观察者收到模糊或变化的观测结果。

开箱即用

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

边界框卡尔曼滤波器，预测与场景平行的矩形边界框，同时支持定向（旋转）的边界框。

二维点卡尔曼滤波器，预测二维点运动。

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

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

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

SORT 跟踪 算法（支持轴对齐和定向框） - 支持IoU和马氏距离。

批处理排序跟踪算法（支持轴对齐和方向盒子） - 支持IoU和马氏距离。批处理跟踪器允许在一次批处理中向跟踪器传递多个场景，并返回它们。如果平台支持批处理（如Nvidia DeepStream或Intel DL Streamer），则批处理跟踪器更有利于使用。

视觉SORT跟踪 - 一种类似于DeepSORT的算法（支持轴对齐和方向盒子） - 支持位置跟踪的IoU和马氏距离，在特征向量上使用欧几里得距离和余弦距离进行视觉跟踪。

批处理视觉SORT - 批处理的视觉SORT版本；

适用性说明

尽管Similari允许构建各种跟踪和相似度引擎，但有时可能存在更合适的竞争工具。本节将说明其适用性以及存在的替代方案。

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

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

不适配：剽窃数据库，当单个文档由一个（或多个）常量ReID向量描述时，文档被添加但不会被删除。任务是找到与检查的文档最相似的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 Silicone构建说明

您可能需要将以下行添加到您的~/.cargo/config中，以在Apple Silicone上构建代码

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

# Apple Silicone fix
[target.aarch64-apple-darwin]
rustflags = [
    "-C", "link-arg=-undefined",
    "-C", "link-arg=dynamic_lookup",
]

Python API

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

• 用于轴对齐和方向（旋转）框预测的卡尔曼滤波器；
• 用于2D点运动预测的卡尔曼滤波器；
• 2D点向量卡尔曼滤波器，它预测独立2D点运动的向量（用于Keypoint Tracker）；
• NMS（非极大值抑制）；
• Sutherland-Hodgman裁剪，方向（旋转）框的交集区域；
• 使用IoU和Mahalanobis度量的SORT；
• 使用IoU和Mahalanobis度量的BatchSORT；
• VisualSORT - 深度类似跟踪器，具有欧几里得/余弦度量用于视觉特征和IoU/Mahalanobis度量用于位置跟踪（VisualSort）；
• BatchVisualSORT - 批量VisualSORT版本；

Python API类和函数可以在python 文档和提供的小示例中进行探索。

还提供了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 .

# optional: copy and install to host system
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 .

# optional: copy and install to host system
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 .

# optional: copy and install to host system
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 指令

0. 安装最新的 Rust 工具集

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

1. 安装构建基本工具 apt install build-essential -y。

2. 安装 Python3（>= 3.8）及其开发文件（python3-dev）。

3. 安装 Maturin

pip3 install --upgrade maturin~=0.15

4. 不在 VENV 中。构建 Python 模块

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

4. 在 VENV 中。构建 Python 模块

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

5. 用法示例位于 python。
6. Similari 跟踪器和传统跟踪器的 MOT Docker 镜像在这里 这里。您可以轻松构建完整的 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 跟踪器（带有卡尔曼滤波器，中间件实现）。