Skip to content

About

Превью STL и 3MF в yazi: свой рендерер на Rust без зависимостей в песочнице bubblewrap · STL & 3MF previews for yazi, sandboxed

Topics

Resources

Stars

8 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

model3d.yazi

Превью 3D-моделей STL и 3MF в файловом менеджере yazi: наводишь курсор на файл — справа картинка модели, её габариты в миллиметрах и число треугольников. Без слайсера, прямо в терминале.

English: README.en.md

Превью шестерни в yazi

Возможности

  • STL — двоичный и текстовый (ASCII).
  • 3MF — обычный и проекты Bambu Studio / OrcaSlicer (детали лежат в отдельных файлах внутри архива, 3D/Objects/*.model). Учитываются положения и повороты деталей на столе и единицы измерения (дюймы, сантиметры… пересчитываются в мм).
  • Если слайсер положил в 3MF своё превью (Metadata/plate_1.png у Bambu/Orca, Metadata/thumbnail.png у PrusaSlicer) размером от 400 px, показывается оно, цветное. Иначе модель рисуется своим рендером.
  • Фон картинки прозрачный — модель ложится на фон терминала.
  • Быстро: модель на 2 млн треугольников — около 0,3 с; результат кэшируется.
  • Безопасно — см. ниже: разбор файла идёт в песочнице без сети и без доступа к файлам.

Требования

  • Linux (песочница — bubblewrap).
  • yazi ≥ 26.8.15 и терминал, в котором yazi показывает картинки (kitty, WezTerm, Ghostty, foot, Konsole…). Проверено в kitty.
  • bubblewrap ≥ 0.8 (bwrap) с разрешёнными непривилегированными user namespaces — в большинстве дистрибутивов так по умолчанию; build.sh проверит, что песочница работает.
  • prlimit (util-linux) и nice (coreutils) — обычно уже есть.
  • Для сборки: Rust ≥ 1.80 (cargo) и статическая glibc (в Arch она входит в пакет glibc; в Debian/Ubuntu — libc6-dev, в Fedora — glibc-static). Сторонние библиотеки не нужны, при сборке ничего не скачивается.
  • Для тестов: Python 3 (только стандартная библиотека).

Установка

Плагин состоит из двух частей: main.lua (сам плагин yazi) и рендерера model3d-render, который собирается из исходников скриптом build.sh и ставится в ~/.local/share/model3d.yazi/ (или $XDG_DATA_HOME/model3d.yazi/).

Вариант 1 — git clone прямо в папку плагинов (проще обновлять)

git clone https://github.com/HelpFreedom/model3d.yazi ~/.config/yazi/plugins/model3d.yazi
~/.config/yazi/plugins/model3d.yazi/build.sh

Вариант 2 — через ya pkg

ya pkg копирует только main.lua, README и лицензию, поэтому рендерер собирается из отдельного клона:

ya pkg add HelpFreedom/model3d
git clone https://github.com/HelpFreedom/model3d.yazi ~/src/model3d.yazi
~/src/model3d.yazi/build.sh

build.sh в конце сам запускает рендерер в песочнице на маленькой модели и пишет ok.

Подключение в yazi.toml

Добавьте в ~/.config/yazi/yazi.toml правило. Оно должно стоять первым среди prepend_previewers, иначе текстовый STL уйдёт в превью текста, а 3MF — в превью архивов:

[[plugin.prepend_previewers]]
url = "*.{stl,STL,Stl,3mf,3MF,3Mf}"
run = "model3d"

Перезапустите yazi.

Параметры

Дописываются в run после --:

run = 'model3d -- --lang ru --no-thumbs --color 8fbcbb'
Параметр Что делает
--lang ru / --lang en язык подписей и сообщений; по умолчанию — по локали (LANG)
--no-thumbs всегда свой рендер, превью слайсера не брать
--thumb-min N минимальный размер превью слайсера в пикселях (по умолчанию 400)
--color RRGGBB цвет модели (по умолчанию c7ccd6)
--azimuth Г, --elevation Г угол камеры в градусах (по умолчанию −60 и 28: ось Z вверх, вид спереди-справа сверху)

Размер картинки берётся из [preview] max_width / max_height yazi (не больше 2048 px). Параметры входят в ключ кэша: после их смены превью перестроится само.

Безопасность

Модели часто скачаны из интернета, и превью строится, как только на файл наведён курсор, то есть до того, как вы решили ему доверять. Поэтому файл разбирается так, чтобы даже специально испорченный файл ничего не мог сделать с системой.

Своя программа без зависимостей. model3d-render написан на Rust только на стандартной библиотеке: чтение zip, распаковка DEFLATE, разбор XML и запись PNG сделаны внутри (renderer/src, около 1900 строк). Нет чужого кода, который мог бы оказаться уязвимым или подменённым. Rust защищает от ошибок работы с памятью, переполнения чисел проверяются; при любой внутренней ошибке программа аварийно завершается, и картинка просто не выдаётся.

Песочница bubblewrap. Рендерер запускается так:

  • нет сети, нет файловой системы — внутри песочницы есть только сам бинарник (поэтому он собран статически), нет /proc, /home, /etc;
  • файл модели открывает sh снаружи и отдаёт программе как stdin; картинка возвращается через stdout. Путь к файлу передаётся аргументом и никогда не становится текстом команды, так что имя вроде $(rm -rf ~).stl безопасно;
  • нельзя создавать новые user namespace, все capabilities сброшены, окружение очищено, процесс завершается вместе с родителем;
  • если песочница не запустилась, превью не показывается вовсе (fail-closed) — рендерер никогда не запускается без изоляции.

Лимиты.

Что Предел
память процесса 3 ГиБ (prlimit --as)
процессорное время 60 с (prlimit --cpu), приоритет nice 19
входной файл 512 МиБ
распаковка из 3MF 768 МиБ на одну часть и 1 ГиБ всего — zip-бомбы обрываются
треугольники 25 млн
вложенность деталей 3MF 32 уровня; циклы и экспоненциальное размножение (1 млн экземпляров) отсекаются
превью слайсера только корректный PNG до 4096×4096 и 32 МиБ

Разбор форматов.

  • XML: объявления DTD и сущностей отвергаются целиком — атаки «billion laughs» и XXE невозможны в принципе.
  • Пути внутри 3MF используются только как имена для поиска в архиве; на диск ничего не распаковывается, ../../etc/passwd просто «не найден».
  • Контрольные суммы CRC в zip проверяются.

Нагрузка. Рендер идёт только для файла под курсором — соседние файлы в фоне не обрабатываются. Если увести курсор, процесс сразу убивается. Ошибки разбора кэшируются, чтобы битый файл не разбирался при каждом наведении.

Что остаётся на стороне yazi. Готовую картинку (свою или превью слайсера) декодирует сам yazi — его декодер изображений тоже написан на Rust. Кэш превью лежит в кэше yazi.

Нашли проблему с безопасностью — сообщите приватно: вкладка Security → Report a vulnerability в репозитории (не в открытом issue).

Тесты

./tests/run.sh          # ~40 проверок, рендерер берётся из ~/.local/share/model3d.yazi
./tests/run.sh --big    # плюс модель на 2 млн треугольников (≈100 МБ во временной папке)

tests/gen.py генерирует нормальные модели и «вредные» файлы: zip-бомбу на 1,6 ГБ, billion laughs, XXE, циклы и экспоненциальное разветвление деталей, обход пути, битые архивы и CRC, NaN в координатах, файл с $(touch PWNED) в имени. tests/run.sh проверяет результат каждого файла, запускает рендерер через ту же команду песочницы, что и плагин, и гоняет cargo test (сжатие/распаковка).

Обновление и удаление

Обновление: git pull в клоне (или ya pkg upgrade), затем снова build.sh.

Удаление: убрать правило из yazi.toml, затем (для варианта 2 сначала ya pkg delete HelpFreedom/model3d)

rm -rf ~/.config/yazi/plugins/model3d.yazi ~/.local/share/model3d.yazi ~/.cache/model3d.yazi-build
yazi --clear-cache   # по желанию — очистить кэш превью

Ограничения

  • Модель рисуется одним цветом: цвета и материалы из 3MF не учитываются (цветную картинку даёт превью слайсера, если оно есть).
  • Вид фиксированный, покрутить модель нельзя.
  • STEP, OBJ, GLB и другие форматы не поддерживаются.
  • Единицы STL неизвестны по формату — считаются миллиметрами, как в слайсерах.

Авторы

Black Triangle (@HelpFreedom) — автор и владелец проекта. Код написан вместе с Claude (Anthropic).

Лицензия

MIT

About

Превью STL и 3MF в yazi: свой рендерер на Rust без зависимостей в песочнице bubblewrap · STL & 3MF previews for yazi, sandboxed

Topics

Resources

Stars

8 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages