Similari

⭐ 在GitHub上关注我们——这对我们很有激励！

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

介绍

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

该框架帮助构建各种类型的跟踪和相似度搜索引擎——最简单的一种是存储向量特征，并允许将新向量与数据库中存储的向量进行比较。更复杂的引擎在轨迹上操作——同一特征在生命周期中收集的一系列观测。

开箱即用的功能

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

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

2D点卡尔曼滤波器，可以预测2D点的运动。

2D点向量卡尔曼滤波器，可以预测独立2D点运动的向量（用于Keypoint Tracker）。

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

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

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

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

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

批量视觉排序 - 批量VisualSORT变种；

适用性说明

尽管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等。这对紫外光非常有益。

或者，您可以添加构建说明到.cargo/config

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

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

性能基准测试

这里展示了部分基准测试数据：基准测试

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

rustup default nightly
cargo bench

Apple硅芯片构建说明

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

[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接口提供以下功能：

• 用于轴对齐和定向（旋转）框预测的卡尔曼滤波器；
• 用于二维点运动预测的卡尔曼滤波器；
• 二维点向量卡尔曼滤波器，预测独立二维点运动的向量（用于关键点跟踪）；
• NMS（非极大值抑制）；
• 萨瑟兰-霍德曼裁剪，定向（旋转）框的交叠区域；
• 使用IoU和马氏距离度量的SORT；
• 使用IoU和马氏距离度量的批处理SORT；
• 视觉SORT - 类似于DeepSORT的跟踪器，具有欧几里得/余弦度量用于视觉特征，IoU/马氏距离用于位置跟踪（VisualSort）；
• 批处理视觉SORT - 批处理视觉SORT变体；

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_py -f docker/rust_1.67/Dockerfile .

# optional: copy and install to host system
docker run --rm -it -v $(pwd)/distfiles:/tmp similari_py cp -R /opt/dist /tmp
pip3 install --force-reinstall distfiles/dist/*.whl

Python 3.8基础镜像

Python 3.8仍然是一个非常常用的版本。以下是使用它构建Similari的方法

docker build -t similari_py -f docker/python_3.8/Dockerfile .

# optional: copy and install to host system
docker run --rm -it -v $(pwd)/distfiles:/tmp similari_py cp -R /opt/dist /tmp
pip3 install --force-reinstall distfiles/dist/*.whl

Python 3.10基础镜像

如果您使用最新的Python环境，您可以使用基础Python容器进行构建

docker build -t similari_py -f docker/python_3.10/Dockerfile .

# optional: copy and install to host system
docker run --rm -it -v $(pwd)/distfiles:/tmp similari_py cp -R /opt/dist /tmp
pip3 install --force-reinstall distfiles/dist/*.whl

注意：如果您遇到像以下这样的pip3错误

ERROR: similari_py-0.22.5-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.13

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

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

4. 在虚拟环境中。构建 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 追踪器（带卡尔曼滤波器，中间件实现）。