Русский · English

Warehouse Vision Demo

Сквозной пайплайн видеоаналитики для складских сцен: YOLO11n находит объекты, ByteTrack сохраняет их ID, а ориентированная линия формирует события IN/OUT с выгрузкой результатов в JSON и CSV. Это независимый учебный проект по прикладному компьютерному зрению.

Реальный запуск: детекция YOLO11n, ByteTrack ID и события IN/OUT. Это функциональная демонстрация, а не оценка точности.

Возможности

• видеофайлы, веб-камера и отдельные изображения;
• Object detection — обнаружение объектов: YOLO11n;
• Object tracking — отслеживание объектов: ByteTrack и стабильный track ID;
• настраиваемая ориентированная линия и направленные события IN/OUT;
• защита от дрожания около линии и повторного подсчёта;
• аннотированное видео, события CSV и сводка JSON;
• выбор классов, порогов, устройства и разрешения через CLI;
• геометрия, логика подсчёта и сериализация тестируются независимо от модели.

Как работает

flowchart LR
    A[Видео / камера / изображение] --> B[OpenCV: чтение и масштабирование]
    B --> C[YOLO11n: Object Detection]
    C --> D[ByteTrack: Object Tracking]
    D --> E[Track ID]
    E --> F[Line Crossing]
    F --> G[Визуализация]
    F --> H[CSV: события]
    F --> I[JSON: статистика]
    G --> J[Аннотированное видео]

Loading

Быстрый запуск

git clone https://github.com/Leo0742/Warehouse-Vision-Demo.git
cd Warehouse-Vision-Demo
uv sync --python 3.12
uv run python -m warehouse_vision \
  --source path/to/input.mp4 \
  --output outputs/result.mp4

Результат запуска:

outputs/
├── result.mp4
├── events.csv
└── summary.json

Проверенные демонстрации

Это проверки сквозной интеграции на лицензированных видео, а не датасет с разметкой и не benchmark точности или производительности.

Видео	Наблюдавшийся результат	CPU throughput
Pexels, склад	259 кадров; основной отслеживаемый человек сохранял ID 1 на протяжении всего видео; IN — кадр 50, OUT — кадр 108; источник demo.gif и demo.jpg	~22.177 FPS
Mixkit	555 кадров; основной отслеживаемый человек сохранял ID 1 на протяжении всего видео; IN — кадр 49, OUT — кадр 131; повторный IN около кадра 485 подавлен; итог IN=1, OUT=1	~21.929 FPS
Pexels, несколько людей	254 кадра; 721 наблюдение, 8 ID, 2 события IN; отмечена фрагментация ID при выходах и перекрытиях	метрика точности не заявляется

Во всех основных запусках согласованы аннотация, JSON и CSV. Логика выбора устройства поддерживает MPS, но в этой среде MPS не запускался. Подробнее: Источники демонстрационных видео и лицензии.

Политика подсчёта

Для одного непрерывного Track ID последовательность сторон A → B → A → B создаёт события:

IN, OUT

Повторный IN подавляется. За один запуск каждый Track ID учитывается не более одного раза в каждом направлении. Это осознанный выбор в пользу устойчивого подсчёта уникальных направленных пересечений. Для учёта каждого прохода нужна иная политика сброса — например cooldown или конечный автомат; в текущую реализацию она не входит.

Ориентация линии

Порядок точек (x1, y1) → (x2, y2) задаёт положительную и отрицательную стороны линии. Параметр --in-side positive|negative выбирает, какая из них считается входом. Для центра bounding box (px, py) знак определяется выражением:

s = (x2 - x1) × (py - y1) - (y2 - y1) × (px - x1)

s > 0 — положительная сторона, s < 0 — отрицательная. При --in-side positive подтверждённый переход negative→positive означает IN, обратный — OUT. Перестановка концов линии меняет знаки сторон, поэтому направления IN/OUT также поменяются, если одновременно не переключить --in-side.

Точки внутри --line-margin игнорируются, а новая сторона должна наблюдаться несколько кадров, заданных --crossing-confirmation-frames. Координаты pixels относятся к кадру после масштабирования; normalized обычно удобнее при разных разрешениях.

Инженерные решения

• YOLO11n выбран как компактная готовая модель для запуска на ноутбуке, а не как доказанно лучший детектор для склада.
• ByteTrack даёт простой baseline с постоянными ID и связывает покадровые детекции во времени.
• Центр bounding box используется как однозначная и дешёвая точка для проверки стороны линии.
• Dead band и подтверждение на нескольких кадрах гасят колебания около границы.
• Один подсчёт на направление для ID снижает дублирование при повторном движении того же трека.
• JSON/CSV отделены от визуализации: события пригодны для машинной обработки независимо от MP4.

Установка

Рекомендуемый вариант с uv использует зафиксированный uv.lock:

uv sync --python 3.12

Стандартный Python 3.11/3.12 и editable install:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

Первый реальный запуск может загрузить выбранные веса Ultralytics. Файлы моделей исключены из Git.

Использование

Все классы модели и окно предпросмотра:

python -m warehouse_vision \
  --source path/to/input.mp4 \
  --output outputs/result.mp4 \
  --classes all \
  --preview

Веб-камера 0 без сохранения видео, но с JSON/CSV:

python -m warehouse_vision --source 0 --no-save --preview

Отдельное изображение поддерживает детекцию и аннотацию, но не временной трекинг или осмысленное событие пересечения:

python -m warehouse_vision --source path/to/input.jpg --output outputs/result.jpg

Параметры CLI

Актуальный список выводит python -m warehouse_vision --help.

Параметр	По умолчанию	Назначение
--source	обязательный	Путь к видео/изображению или индекс камеры, например 0
--output	outputs/result.mp4	Путь к аннотированному медиа
--summary / --events	рядом с output	Пути к JSON и CSV
--model	yolo11n.pt	Имя модели или путь к локальным весам
--confidence	0.25	Минимальная confidence детектора
--iou	0.70	IoU-порог NMS
--classes	4 класса COCO	Имена через запятую или all
--device	auto	cpu, mps, 0 или значение устройства Ultralytics
--tracker	bytetrack.yaml	Встроенный или пользовательский YAML трекера
--line	0.1,0.5,0.9,0.5	Ориентированные точки x1,y1,x2,y2
--line-coordinates	normalized	normalized в [0,1] или pixels
--line-margin	6	Dead band вокруг линии в пикселях
--crossing-confirmation-frames	2	Сколько кадров подтверждают новую сторону
--in-side	positive	Какая сторона линии означает IN
--max-width	1280	Уменьшить широкие кадры; 0 отключает
--preview	выключен	Показывать кадры; q завершает запуск
--no-save	выключен	Не писать медиа, но сохранить аналитику

auto выбирает CUDA, затем Apple MPS, затем CPU — по доступности. Это поддержка выбора backend, а не утверждение, что каждый backend был проверен.

Структура проекта

warehouse-vision-demo/
├── src/warehouse_vision/
│   ├── cli.py              # CLI и сообщения об ошибках
│   ├── config.py           # проверенные настройки запуска
│   ├── detector.py         # YOLO, классы и выбор устройства
│   ├── tracker.py          # нейтральное представление Track
│   ├── geometry.py         # геометрия ориентированной линии
│   ├── counter.py          # состояние и дедупликация пересечений
│   ├── pipeline.py         # обработка изображения, видео и камеры
│   ├── visualization.py    # OpenCV-аннотации
│   ├── analytics.py        # JSON и CSV
│   └── utils.py            # масштабирование и FPS
├── tests/                  # тесты без загрузки весов
├── docs/                   # демо и сведения об источниках
├── examples/               # рекомендации по входным данным
├── outputs/                # генерируемые файлы; в Git только .gitkeep
├── pyproject.toml
├── uv.lock                 # зафиксированное разрешение зависимостей
└── LICENSE

Основные понятия CV

• Classification назначает метку всему изображению; Object Detection также находит положение каждого объекта; Segmentation оценивает пиксели его формы.
• Bounding box — прямоугольник объекта, Confidence score — уверенность модели.
• IoU измеряет пересечение двух рамок, а NMS подавляет дублирующиеся детекции.
• Inference — применение обученной модели к новым данным; обучение в обычном запуске не идёт.
• Tracking связывает детекции между кадрами; Track ID даёт объекту временную идентичность, необходимую для подсчёта пересечений.
• Transfer learning — перенос обучения: использование предобученной модели как начальной точки. Дообучение на данных целевого домена помогает адаптировать модель к domain shift — сдвигу домена между COCO и реальными складскими камерами.

Ограничения

• COCO не содержит общего класса «посылка»; модель не дообучалась на коробках, паллетах и складских камерах.
• Перекрытия, выходы из кадра, размытие и сложный свет могут фрагментировать ID.
• Результат зависит от геометрии камеры, размещения линии и стабильности треков.
• В репозитории нет размеченного benchmark, поэтому precision, recall, mAP и tracking-метрики не заявляются.
• Один кадр не даёт временного трекинга или события пересечения.

Дальнейшее развитие

• собрать целевой датасет и дообучить классы посылок и паллет;
• оценить ReID и настройки трекера при перекрытиях;
• добавить зоны, dwell time и межкамерную аналитику;
• использовать калибровку или глубину для физических расстояний;
• добавить версионирование данных, мониторинг качества и domain drift.

Проверка проекта

uv sync --python 3.12 --extra dev
uv run ruff format --check .
uv run ruff check .
uv run pytest
uv run python -m compileall -q src tests
uv run python -m warehouse_vision --help

Тесты используют поддельный вывод трекера и не загружают веса модели.

Лицензия

Код распространяется по GNU Affero General Public License v3.0 or later — см. LICENSE. Выбор согласован с open-source лицензированием пакета Ultralytics по AGPL-3.0. Для сценариев, несовместимых с AGPL, Ultralytics предлагает Enterprise License; перед распространением или коммерческим использованием проверьте актуальные условия лицензирования. Это краткое описание не является юридической консультацией.