2个版本

0.0.2	2024年7月5日
0.0.1	2024年3月18日

#119 in 机器学习

109次每月下载

Apache-2.0

525KB
12K SLoC

相似

较新版本（已重命名）

较旧版本

⭐ 在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等。这对紫外光很有好处。

或者，您可以将构建说明添加到.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接口提供以下功能：

对齐和旋转（旋转）框预测的卡尔曼滤波器；
2D点运动预测的卡尔曼滤波器；
2D点向量卡尔曼滤波器，预测独立2D点运动的向量（用于关键点跟踪器）；
NMS（非极大值抑制）；
Sutherland-Hodgman裁剪，旋转（旋转）框的交叠面积；
使用IoU和马氏距离的SORT；
使用IoU和马氏距离的BatchSORT；
VisualSORT - 类似于DeepSORT的跟踪器，具有欧几里得/余弦距离度量用于视觉特征和IoU/马氏距离用于位置跟踪（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

注意：

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

不在VENV中。构建python模块

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

在VENV中。构建python模块

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

使用示例位于python。
Similari跟踪器和传统跟踪器的MOT Challenge Docker镜像在此。您可以轻松构建所有功能Docker镜像并尝试我们的跟踪器。

手册和文章

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

Medium.com

IoU目标跟踪示例；
Re-ID目标跟踪示例；
SORT目标跟踪示例；
Python SORT目标跟踪示例；
Python旋转SORT目标跟踪示例；
为什么您需要一个高性能的跟踪系统进行多目标跟踪.

使用示例

查看repo中的样本

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跟踪器（带有卡尔曼滤波器，中间件实现）。

依赖关系

~16–24MB
~343K SLoC