Превью 3D-моделей STL и 3MF в файловом менеджере yazi: наводишь курсор на файл — справа картинка модели, её габариты в миллиметрах и число треугольников. Без слайсера, прямо в терминале.
English: README.en.md
- 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/).
git clone https://github.com/HelpFreedom/model3d.yazi ~/.config/yazi/plugins/model3d.yazi
~/.config/yazi/plugins/model3d.yazi/build.shya pkg копирует только main.lua, README и лицензию, поэтому рендерер собирается из
отдельного клона:
ya pkg add HelpFreedom/model3d
git clone https://github.com/HelpFreedom/model3d.yazi ~/src/model3d.yazi
~/src/model3d.yazi/build.shbuild.sh в конце сам запускает рендерер в песочнице на маленькой модели и пишет ok.
Добавьте в ~/.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).
