packing-mvp

packing-mvp — Windows desktop-приложение для укладки грузовых мест, заданных STEP-файлами, в кузов грузовика.

Текущий продуктовый сценарий:

• пользователь загружает один или несколько .step / .stp
• каждый STEP трактуется как один тип грузового места
• приложение автоматически определяет общие габариты Д x Ш x В
• при необходимости пользователь вручную исправляет размеры и количество
• выполняется практическая MVP-укладка в кузов
• результат показывается в GUI, сохраняется в result.json и может экспортироваться в STEP

README описывает именно этот V2 workflow. Старые экспериментальные режимы исследований по жёстким сборкам не являются рекомендуемым сценарием для текущего продукта.

Возможности

• загрузка STEP AP203 / AP214
• автоматическое извлечение общих габаритов из STEP
• ручная корректировка размеров
• количество для каждого типа грузового места
• удаление позиции из проекта
• физическое удаление STEP-файла с диска с подтверждением
• настройка кузова:
  • длина
  • ширина
  • высота
  • зазор между соседними местами
• упаковка нескольких типов одновременно
• отчёт о неразмещённых местах, если всё не помещается
• 2D-превью и 3D-предпросмотр
• экспорт результата в STEP
• сохранение / загрузка проекта .packproj
• фоновый расчёт и журнал сообщений

Правила упаковки MVP

• один STEP-файл = один тип грузового места
• упаковщик работает по общим габаритам, а не по разбору модели на дочерние тела
• допустимы только две ориентации для каждого типа:
  • исходная Д, Ш, В
  • поворот вокруг вертикальной оси на 90°: Ш, Д, В
• наклоны по X / Y не допускаются
• место должно оставаться стоящим на основании
• зазор применяется по длине и ширине
• пересечения между местами запрещены
• выход за габариты кузова запрещён
• если всё не помещается, результат обязан содержать список неразмещённых мест

Алгоритм упаковки в MVP жадный, а не оптимальный. Цель — надёжный и понятный практический результат, а не математически точный глобальный оптимум.

Габариты кузова по умолчанию

• длина: 13400 мм
• ширина: 2350 мм
• высота: 2400 мм
• зазор: 50 мм

Требования

• Windows 10 / 11
• Python 3.10+

Установка

cd C:\path\to\packing-mvp
py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

Пакет устанавливает основные зависимости для работы с STEP и визуализацией:

• gmsh
• cadquery-ocp / OCP
• numpy
• matplotlib
• pillow
• windnd

Запуск GUI

python -m packing_mvp.gui

или:

packing-gui

Базовый рабочий сценарий в GUI

1. Нажмите Загрузить STEP-файлы.
2. Проверьте автоматически определённые размеры в каталоге.
3. При необходимости отредактируйте Длина, Ширина, Высота, Количество.
4. Уточните параметры кузова.
5. Нажмите Рассчитать укладку.
6. После расчёта используйте:
   • Открыть результат
   • Вид сверху
   • Вид сбоку
   • 3D-предпросмотр
7. Сохраните проект через .packproj, если нужно вернуться к нему позже.

CLI

CLI полезен для пакетного запуска и smoke-test сценариев.

Пример: несколько STEP-файлов и количество

python -m packing_mvp.cli `
  --input "crate_a.step" "crate_b.step" `
  --quantity 2 3 `
  --out out

Пример: явные размеры кузова и зазор

python -m packing_mvp.cli `
  --input "crate_a.step" "crate_b.step" `
  --quantity 2 3 `
  --out out `
  --maxL 13400 `
  --maxW 2350 `
  --maxH 2400 `
  --gap 50

Пример: запуск из .packproj

python -m packing_mvp.cli --project ".\demo.packproj" --out out

Поддерживаемые аргументы CLI

• --input — один или несколько STEP-файлов
• --project — загрузка .packproj вместо сырых STEP-файлов
• --quantity — количество для каждого файла из --input
• --out — папка результата
• --maxL, --maxW, --maxH — габариты кузова в мм
• --gap — зазор в мм
• --scale — ручной множитель масштаба импорта STEP
• --seed — зарезервированный deterministic seed

Выходные файлы

После успешного или частично успешного расчёта приложение создаёт папку результата с артефактами:

• result.json
• placements.csv
• arranged.step
• preview_top.png
• preview_side.png
• preview.gif
• packing.log

Что содержит result.json

result.json используется как машинно-читаемый статус расчёта. В нём сохраняются:

• габариты кузова
• зазор
• каталог загруженных типов
• список размещённых мест
• список неразмещённых мест
• использованные габариты
• коэффициент заполнения
• признак успеха / неуспеха
• режим упаковки truck_loading_v2

Если всё помещается:

• success = true
• status = "ok"

Если не всё помещается:

• success = false
• status = "failed"
• в unplaced_items будет явный список того, что не удалось разместить

.packproj

Файл проекта .packproj хранит:

• список загруженных STEP-типов
• определённые или вручную исправленные размеры
• количество
• параметры кузова
• результат последнего расчёта, если он уже есть

Формат проекта JSON-совместимый, но с пользовательским расширением .packproj.

STEP-экспорт

arranged.step строится в соответствии с рассчитанными размещениями.

Предпочтительный путь MVP:

• экспорт преобразованных исходных моделей STEP

Резервный путь MVP:

• экспорт box-proxy представлений, если конкретный источник не удалось корректно перенести как исходную геометрию

Это поведение сделано намеренно: экспорт должен быть согласован с раскладкой, показанной пользователю.

3D-предпросмотр

3D-предпросмотр показывает:

• каркас кузова
• размещённые грузовые места
• номера размещений
• вращение / панорамирование / масштабирование камеры

Для MVP визуализация box-based: пользователь видит раскладку по габаритам, а не полный CAD-рендер каждого объекта.

Ограничения MVP

• упаковка основана на общих габаритах, а не на точной проверке CAD-коллизий по сложной геометрии
• алгоритм жадный, а не оптимальный
• нет произвольного поиска углов
• нет наклонов по X / Y
• один STEP трактуется как один тип грузового места
• sample STEP-файлы можно использовать для smoke-тестов, но логика не завязана на имена файлов

Тесты

cd C:\path\to\packing-mvp
python -m pytest -q

Ключевые тестовые сценарии покрывают:

• извлечение размеров и ручной override
• разворачивание количества в отдельные экземпляры
• допустимые ориентации только по Z
• базовое размещение в кузове
• корректный отчёт по неразмещённым местам
• сохранение / загрузку .packproj

Структура V2

Основные модули текущего продукта:

• src/packing_mvp/step_extract.py — извлечение габаритов из STEP
• src/packing_mvp/catalog.py — каталог типов грузовых мест и настройки кузова
• src/packing_mvp/packer.py — MVP-укладка в кузов
• src/packing_mvp/project_io.py — .packproj
• src/packing_mvp/gui.py — русский desktop GUI
• src/packing_mvp/visualization.py — 3D-предпросмотр
• src/packing_mvp/step_export.py — экспорт STEP-сцены
• src/packing_mvp/export.py — result.json и placements.csv