Большинство инструментов «восстановления сетки» показывают лишь индикатор загрузки и зелёную галочку. Meshwright сообщает, что именно не так, где именно на модели находится проблема, что было сделано для её устранения и какие фактические показатели имеет результат — Meshwright не теряет, не затирает и не портит вашу модель незаметно для вас.

канал автора:

https://www.youtube.com/@geekatplay-ru

Meshwright:

https://github.com/GeekatplayStudio/Meshwright

Meshwright

Документация

Meshwright — инструмент для анализа, ремонта, текстурирования и подготовки полигональных мешей к 3D-печати (Geekatplay Studio). Документ объединяет руководство пользователя, справочник по диагностике и руководство по редукции.

Содержание

ЧАСТЬ 1. Руководство пользователя

Перевод «USER_GUIDE.md»

Открытие модели

Перетащите файл в окно или нажмите Ctrl+O. Поддерживаются: *OBJ, FBX, GLB, GLTF, STL, PLY, 3MF, DAE, OFF, 3DS*.

Meshwright не поставляется вместе с 3D-моделями — это мастерская для файлов, которые у вас уже есть: ничего скачивать не нужно и папку с моделями настраивать не нужно. Чтобы попробовать без собственного файла, нажмите *Load demo model в пустом окне просмотра: в памяти будет построена небольшая модель с дыркой, пятном «вывернутых наизнанку» треугольников и отдельно лежащей деталью, которую Repair* доведёт до герметичности.

Загрузка показывает каждый шаг в *консоли активности (Activity console, кнопка справа вверху, или Ctrl+`*): какой парсер использован, сколько треугольников, слияние вершин, анализ и время на каждый этап. Модель на два миллиона треугольников загружается примерно за 20 секунд.

Чтение диагностики

Кольцо-индикатор даёт вердикт одним взглядом. Под ним — список всех проблем с меткой серьёзности:

• 🔴 **critical** (критическое) — модель не распечатается или распечатается неправильно
• 🟠 **warning** (предупреждение) — возможны артефакты
• 🔵 **note** (примечание) — полезно знать

Кликните по любой проблеме — камера подлетит к ней. Точные места отмечены голубым, а вокруг — полупрозрачная сфера-зона, чтобы можно было найти даже один «битый» треугольник. Кликните ещё раз, нажмите Esc или Clear* — отметки пропадут.

Re-analyse в любой момент перезапускает проверки для текущей сетки. Save JSON* сохраняет полный отчёт — диагностику и все применённые операции — для архива или для клиента.

Что значит каждая проверка — в [DIAGNOSTICS.md](DIAGNOSTICS.md).

Ремонт

Отметьте *Force watertight* (включено по умолчанию), чтобы разрешить voxel-пересборку как крайний приём: она гарантирует замкнутое твёрдое тело, но сглаживает мелкий рельеф. Снимите отметку, если деталь важнее гарантии герметичности.

Нажмите *Repair mesh (Ctrl+R*). После этого:

• **What was fixed** — только те этапы, которые реально что-то изменили.
• **Before → after** — каждая метрика, которая сдвинулась; улучшения — зелёным.
• Если проблемы остались — об этом сказано прямо: отчёт измерен на отремонтированной сетке, а не спрогнозирован.

Fix sliver triangles* появляется только если слэивы (игловидные треугольники) присутствуют. Они сшиваются с большими соседями, «крышечные» треугольники разворачиваются, а вся остальная геометрия остаётся на месте.

Если ремонт сделал бы сетку хуже, Meshwright отказывается, сохраняет ваше предыдущее состояние и предлагает *Apply anyway* («применить всё равно»). Это осознанное решение — см. [Безопасность](#безопасность).

Разделение деталей

Если модель состоит из нескольких несвязанных частей, они раскрашены в разные цвета в окне просмотра и перечислены с числом треугольников и размерами. Отметьте те, которые хотите убрать — они станут красными, — затем *Remove selected (Del). Ctrl+A — выделить все; Highlight* отключает раскраску.

Убрать все детали подряд нельзя.

Ориентация

Включите *Rotate на панели окна просмотра (R) и тяните кольца, либо используйте X / Y / Z +90°* в панели Orientation. Поворот мгновенный в окне просмотра и применяется к экспортируемому STL.

Редукция полигонов

Выберите движок, задайте цель и нажмите *Reduce polygons*. Пресеты — от 500 до 50k, либо введите точное число граней. В строке результата — отклонение поверхности в миллиметрах: честная мера того, что вы потеряли. Полное руководство — в [REDUCTION.md](REDUCTION.md).

Текстуры

Meshwright сохраняет все текстуры, которые пришли вместе с моделью, и держит их «в маппинге» на протяжении ремонта и редукции.

Что подхватывается при открытии. Текстуры, вшитые в файл (GLB, glTF, FBX), читаются из материала самой модели. Текстуры, на которые файл лишь ссылается — OBJ со своим .mtl, или папка с PNG рядом с моделью, — находятся по имени, включая раскладки, которые экспортируют Meshy, Tripo, Sketchfab и Blender: model.png, _baseColor, *_Normal_OpenGL, *_Roughness, *_AO, а также упакованные *_ORM / *_metallicRoughness-карты, которые распаковываются в отдельные каналы. Ищутся и подпапки textures/, images/, materials/ и .fbm. Если файл и объявляет текстуру, и рядом лежит «лишняя» картинка, побеждает объявленная файлом.

Ремонт и редукция сохраняют маппинг.* UV-координаты путешествуют вместе с моделью через все операции, и модель при этом остаётся правильно «сваренным» твёрдым телом: ремонт и децимация текстурированной модели не превращают её в кучу обломков, а оценка диагностики отражает реальную геометрию. Худшее смещение после редукции до одной пятидесятой исходного числа граней — меньше половины тексела на карте 2048 px.

Unwrap UVs* строит новую развёртку для модели, у которой её нет. Геометрию он при этом не трогает вообще: герметичная модель остаётся герметичной, и её оценка не меняется. Если у модели уже есть UV, Meshwright сначала спросит — новая развёртка обесценит любую текстуру, нарисованную под старую.

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

Плотные модели — не проблема: модель на 327 000 граней разворачивается примерно за две секунды. Если развёртка вообще не получается, вы получите об этом сообщение, а не крах: сначала *Reduce* модель, потом разворачивайте.

Если текстуры выглядят плоско или отсутствуют, проверьте, что пришло вместе с файлом. Некоторые генераторы — Meshy и Hi3D в том числе — кладут в FBX плейсхолдер 2×2, а настоящие карты 2048 px отдают отдельными PNG рядом; Meshwright игнорирует плейсхолдер и использует настоящие файлы. И ещё: у модели может просто не быть UV-координат — «generate»-экспорт из Meshy без текстур их не имеет, и никакая текстура на него не ляжет, пока вы не нажмёте Unwrap UVs*.

Load Image / Generate PBR* выводит normal-, roughness-, metallic-, ambient-occlusion- и height-карты из любого фото или текстуры.

Отметьте *Image tiles seamlessly*, если у вас повторяющийся материал — тогда края будут смешаны, и тайл ляжет без видимого шва, а рельеф продолжится через границы. Для фотографии или текстуры, нарисованной под эту конкретную модель, отметку ставить не стоит: если такие обрабатывать как тайлы, по всем четырём краям normal-мапы проставится жёсткая ложная «гряда».

Displace выталкивает поверхность вдоль height-мапы, в миллиметрах. Двигаются настоящие вершины, поэтому на плотной модели рельеф виден, а на low-poly — почти ничего; кнопка Height* в окне просмотра показывает саму мапу в любом случае.

Export Maps пишет все каналы плюс прозрачный UV-гайд, который можно открыть как слой в Photoshop или GIMP; Reload Maps подхватывает ваши правки обратно. Save Baked GLB* пишет один самодостаточный файл с мапами внутри.

Во всём, что пишет Meshwright, поля вокруг UV-островов «подкрашены» — цвет по краю каждого острова проступает наружу, в пустое пространство вокруг него, — поэтому текстура не даёт тёмной кромки по швам, когда рендерер фильтрует её или строит mip-карты.

Экспорт

Выберите *формат — STL, OBJ, PLY, OFF, GLB, glTF или 3MF — и единицы исходного файла (мм, см или дюймы), чтобы модель масштабировалась правильно, и оставьте отмеченным Rest on build plate, чтобы модель стояла по центру по X/Y и опускалась до Z = 0. Export (Ctrl+S) пишет файл; STL — бинарный. По умолчанию файл называется <original>-GS-<timestamp>-fixed.<ext>*, поэтому экспорт никогда не перезапишет ту модель, с которой вы начали.

OBJ, GLB и glTF уносят вместе с моделью UV-координаты и мапы. STL, PLY, OFF и 3MF хранить их не умеют, поэтому пишутся только геометрией — что слайсеру и нужно.

«Сохранено, но это не печатное твёрдое тело»

Meshwright измеряет сетку в момент записи и сообщает, если результат — не замкнутый объём. Это важно, потому что слайсер заполняет *внутренность* твёрдого тела: у открытой поверхности «внутренности» нет, поэтому она слагается как однослойная оболочка — один периметр, без заполнения — каким бы ни была настроено заполнение.

«Вывернутые наизнанку» модели при записи разворачиваются правильной стороной наружу, поэтому сетка, которую слайсер раньше читал как «полость», выходит как твёрдое тело.

Окно просмотра

Shaded · Clay · Normals · X-ray — смена вида материала. Wire накладывает каркас, Edges подсвечивает открытые краевые рёбра красным, Plate* включает сетку платформы печати.

Панель *Light* двигает ключевой свет — удобно читать рельеф поверхности перед печатью.

Рассекатель между окном просмотра и панелью можно тянуть; двойной клик — сброс. Ширина запоминается.

Как узнать, что происходит

Всё, что занимает больше мгновения, объявляет о себе в правом нижнем углу: что делается, сколько граней затронуто и сколько примерно ждать — с живым таймером и прогресс-баром. Когда работа закончится, уведомление отчитается о фактическом времени и результате. Кликните *×*, чтобы закрыть, или оставьте — уведомления о результате гаснут сами.

Та же информация, с метками времени, уходит в *консоль активности* и в терминал, чтобы за долгим прогоном можно было следить, не глядя в окно.

Оценки масштабируются по модели: ремонт двух миллионов граней объявляется как «минута–две», а мелкая деталь — «момент».

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

Каждое изменение создаёт *нумерованное состояние*, которое видно в верхней панели.

• <kbd>Ctrl</kbd>+<kbd>Z</kbd> — отмена, <kbd>Ctrl</kbd>+<kbd>Y</kbd> — повтор; это единственные пути назад.
• **Revert to original file** выбрасывает сессию и перечитывает файл так, как он был открыт. Спрашивает сначала, и сама по себе отменяется.
• Изменение, которое добавило бы критические проблемы или выбросило бы большую часть геометрии, **отклоняется**; ваше предыдущее состояние сохраняется, и вам предлагают «Apply anyway».
• Каждое принятое состояние в фоновом потоке пишется снапшотом на диск. Если Meshwright не закрылся чисто, при следующем запуске предложит **восстановить** его. Снапшоты лежат в `%LOCALAPPDATA%\Meshwright\sessions` (на macOS — в `~/Meshwright/sessions`) и удаляются при чистой остановке.

Детализация окна просмотра

Модель с миллионами треугольников рендерится не мгновенно, поэтому Meshwright показывает её упрощённую версию и сообщает об этом: «Viewport showing 18% of this model». Тяните слайдер *Detail* на панели окна просмотра вверх — для полной сетки, или вниз — если хотите, чтобы вид вращался свободнее.

Это касается только картинки. Диагностика, ремонт, редукция, ретопология и каждый экспорт всегда работают со всеми треугольниками модели — число в панели Geometry — настоящее. Пока вид упрощён, подсветка открытых рёбер отключается, потому что иначе подсвечивались бы рёбра упрощённой копии, а не вашей модели.

Чашка

Пока Meshwright занят — открывает файл, чинит, редусит, экспортирует — по низу окна ходит маленькая чашка и уходит, когда работа кончается. Она есть для того, чтобы сразу видеть: что-то ещё происходит.

Кликните по ней — и она остановится и спросит, не купить ли Владу кофе. Кликните по шарикам, чтобы открыть страницу, или кликните куда-нибудь ещё — и чашка отправится восвояси.

Начать заново

New в верхней панели (Ctrl+N) закрывает модель и очищает рабочее пространство — сетку, историю, диагностику и текстуры. Delete делает то же, только если в Separate pieces* отмечены детали — тогда он уберёт их. В любом случае, прежде чем выбросить что-то с несохранёнными изменениями, вас попросят подтвердить.

Клавиатура

Нажмите ? в любой момент — полный список. Те, что стоит запомнить: Ctrl+O — открыть · Ctrl+N — закрыть модель · Ctrl+Z — отмена · Ctrl+R — ремонт · Ctrl+S — экспорт · W — каркас · F — вписать · 1–7 — стандартные виды.

ЧАСТЬ 2. Справочник по диагностике

Перевод «DIAGNOSTICS.md»

Все проверки, которые выполняет Meshwright, что они значат для печати и как их исправить. Кликните по любой проблеме в панели Diagnostics, чтобы найти её на модели.

Серьёзность: *critical (критическое) — не распечатается или распечатается неправильно · warning (предупреждение) — возможны артефакты · note* (примечание) — полезно знать.

________________________________________________________________________________

Открытые дыры — *critical*

Краевые рёбра принадлежат только одному треугольнику, значит, поверхность не замкнута. Слайсер не может отличить «внутреннее» от «внешнего» и выдаст недостающие стенки или полую оболочку.

В отчёте: количество дыр (замкнутых петель краевых рёбер) и общее число открытых рёбер. Ремонт: *Repair mesh*. Маленькие дыры триангулируются напрямую; большие уходят в MeshFix или MeshLab.

В слайсере это симптом «тонкой оболочки».* Модель с открытыми рёбрами — не твёрдое тело, поэтому слайсер печатает одну стенку без заполнения — один периметр — каким бы ни было настроено заполнение. Meshwright повторяет предупреждение при экспорте, но панель диагностики уже сказала главное: если эта проверка есть — чините до экспорта. Модель готова только тогда, когда панель сообщает, что она герметична (watertight).

Неманifold-рёбра — *critical*

Рёбра, общие для трёх и более граней. Твёрдое тело неоднозначно — «внутреннего» в единственном числе нет. Обычно это следствие наложенной друг на друга геометрии или булевых операций, которые так и не привели в порядок.

Ремонт: *Repair mesh (этапы MeshFix / MeshLab). Если счёт высокий, модель, возможно, «суп из треугольников»; в крайнем случае Force watertight* пересоберёт её через воксели.

Несогласованное направление обхода граней — *warning*

Соседние треугольники обходится в противоположных направлениях, поэтому нормали «перещёлкиваются» по поверхности. Слайсер может воспринимать отдельные области как вывернутые наизнанку.

Ремонт: *Repair mesh* — этап Orientation сводит направление обхода к одному.

Вывернутая наизнанку сетка — *warning*

Все нормали направлены внутрь (объём отрицательный). Слайсер воспринимает модель как «полость».

Ремонт: *Repair mesh* — этап Orientation вывернёт её правильной стороной.

Вырожденные треугольники — *warning*

Грани нулевой площади, возникшие из схлопнувшихся или лежащих на одной прямой точек. У них нет нормали, и они сбивают с толку и слайсеры, и булевые движки.

Ремонт: *Repair mesh* (этап Cleanup) удаляет их.

Дублирующиеся грани — *warning*

Точные копии других треугольников, часто — следствие слияния импортов. Они создают двойные стенки.

Ремонт: *Repair mesh* (этап Cleanup).

Дублирующиеся вершины — *note*

Две вершины занимают одно положение, но не слиты, поэтому рёбра, которые выглядят склеенными, на самом деле не соединены. Это обычная скрытая причина «дыр, которые я не вижу».

Ремонт: *Repair mesh* сольёт их.

Неиспользуемые вершины — *note*

Вершины, на которые не ссылается ни одна грань. Не вредят, но раздувают файл.

Ремонт: *Repair mesh* (этап Cleanup).

Слэивы (игловидные треугольники) — *note*

Треугольники с минимальным углом менее 1°: «иголки» (одно очень короткое ребро) или «крышечки» (один угол близок к 180°). Они переживают слайсинг, но дают артефакты затенения, ненадёжные нормали и проблемы для булевых операций и последующей пере-сетки.

Ремонт: *Fix sliver triangles* — «иголки» схлопываются к лучше связанной вершине, «крышечки» разворачиваются вместе с соседом, и вся окружающая геометрия остаётся на месте. Кнопка появляется только тогда, когда слэивы присутствуют.

Каждое схлопывание и каждый разворот сначала проверяются: схлопывание должно удовлетворять link-условию (два конца ребра имеют ровно две общие вершины, «противоположные» ребру), а разворот не должен дублировать существующее ребро. Слэивы, которые нельзя убрать, не прорезав поверхность, остаются на месте — и об этом сообщается: несколько упрямых слэивов — куда лучше, чем дыра. Для печати они безвредны.

Отдельные оболочки — *note*

В файле несколько несвязанных частей. Часто это задумано (миниатюра с самоцветами и подставкой), но иногда это лишние обломки от неудачного экспорта.

Ремонт: панель *Separate pieces* перечисляет каждую часть с числом треугольников и размерами, раскрашивает их в окне просмотра и позволяет удалить ненужные.

Необычный масштаб — *note*

Крупнейший размер — меньше 1 мм или больше 1000 мм: исходный файл, вероятно, использует другие единицы (часто — метры, сантиметры или дюймы).

Ремонт: в панели Export выберите правильные *Source units*; Meshwright перемасштабирует при экспорте.

Нет геометрии — *critical*

В файле не оказалось ни одного треугольника. Печатать нечего — проверьте экспорт из вашей 3D-программы.

________________________________________________________________________________

Полые модели и толщина стенок

В герметичной модели со стенками 0,4 мм нет ничего «неправильного» — но принтер не способен её заполнить, и она выходит оболочкой. При экспорте Meshwright оценивает среднюю толщину стенки как 2 × объём ÷ площадь поверхности и говорит об этом, если на модели крупнее 10 мм она оказывается меньше 1,2 мм.

Обычные причины: поверхность, экспортированная из CAD без приложенной толщины; фотометрический скан, который «кожа», а не тело; либо модель, специально выдолбленная под печать на смоле (тогда всё верно — проверьте только, что есть сливные отверстия).

Оценка готовности

Стартует со 100, затем: минус 35 за каждую критическую проблему, минус 12 за предупреждение, минус 3 за примечание. Герметичная, согласованная по обходу и правильно сориентированная сетка никогда не набирает ниже 80.

ЧАСТЬ 3. Редукция полигонов

Перевод «REDUCTION.md»

Meshwright предлагает три движка за одной панелью *Reduce. Все они строятся на абсолютном числе граней* и все сообщают, насколько результат отклонился от оригинала.

Выбор движка

Эмпирическое правило: если модель вылеплена или отсканирована — Smart retopo. Если пришла из CAD — Decimate. Если размер треугольников в хаосе — сначала Uniform*, потом децимация.

Отклонение поверхности

После каждой редукции Meshwright сэмплирует обе поверхности и сообщает:

• **max** — самое плохое отклонение в любой точке, в миллиметрах
• **mean** — среднее отклонение
• **% of size** — максимум относительно крупнейшего размера модели

Меньше ~1 % — на печати визуально неотличимо. Больше ~5 % — вы теряете детали, которые вам, возможно, важны. Число видно в панели, в консоли и в JSON-отчёте.

Живой пример

Миниатюра из README: *1 994 490 треугольников, 23 отдельные части, род (genus) 114, герметичная.

Оценка готовности осталась *94* — та же, что у исходника.

Как Meshwright держит редукцию в безопасности

Ремешеры не обязаны возвращать валидное твёрдое тело — и на сложной топологии часто не возвращают. QuadriFlow на этой миниатюре сам по себе дал 24 дыры, 12 неманifold-рёбер и 6 лишних оболочек.

Поэтому Meshwright:

1. 1. **Обрабатывает каждую часть отдельно** — многодетальная модель сохраняет свои части, и каждая

получает пропорциональную долю граневого бюджета.

2. 2. **Пропускает ретопологию на мелких частях** (менее ~4 000 треугольников, или цель меньше 400) —

на самоцвете из 200 треугольников quad-поле не построить чисто, поэтому их просто децимируют.

3. 3. **Предварительно децимирует очень плотные части** перед построением quad-поля. QuadriFlow не

нужны два миллиона входных граней, чтобы дать 45 000 квадров; это примерно вдвое сокращает время без потери точности.

4. 4. **Проверяет каждую часть** после. Если исходник был герметичным, а результат — нет, MeshFix

его чинит; не помогло — часть уходит в следующий движок.

5. 5. **Приводит в порядок собранное целое** — сливает вершины, убирает вырожденные и дублирующиеся

грани, заделывает оставшиеся мелкие дыры, сводит направление обхода.

6. 6. **Измеряет отклонение** и записывает всё в JSON-отчёт.

Редукция никогда не возвращает худшую сетку, чем была получена. Если что-то всё равно не так, панель Diagnostics говорит об этом сразу — а Ctrl+Z отводит обратно.

Когда совсем в low-poly

Пресеты спускаются до *500 граней. Ниже пары сотен используйте Smart retopo*: quadric-схлопывание на экстремальных пропорциях рождает всё более уродливые слэивы, тогда как quad-поле деградирует грациозно. Следите за цифрой отклонения: на low-poly целях это единственный честный показатель того, что вы потеряли.

Почему smart-ретопология иногда идёт другим движком

QuadriFlow строит quad-поле, выровненное по кривизне, и эта оптимизация либо сходится быстро, либо не сходится вовсе. Время его работы не предсказать по размеру входа: на одной модели, с одного и того же исходника при разных уровнях децимации, — 2 секунды на 20 000 граней, больше четырёх минут на 32 000 и на 72 000, а на 189 000 — 7,5 секунды. Он и вовсе может сломаться — сбой ассерта внутри Eigen, который в пределах процесса просто закрыл бы приложение на середине операции.

Поэтому Meshwright запускает QuadriFlow в дочернем процессе и даёт ему две минуты на часть. Если он упадёт или не сойдётся, часть уйдёт в изотропный ремеш или quadric-схлопывание — быстрые и предсказуемые, — а в логе будет видно, какой движок реально отработал. Результат за две минуты лучше, чем «может, получится» за десять.

Прежде чем QuadriFlow увидит плотную часть, её децимируют до размера, на котором можно построить поле. Раньше это шло напрямую в сохраняющий топологию схлоп MeshLab — правильно, но медленно: 73 секунды, чтобы взять пять миллионов граней и дать двести тысяч. Разделить пополам — быстрее и лучше: fast-simplification делает основную работу за пять секунд, но рвёт поверхность, и MeshFix за 11 секунд сшивает её, сохранив 96 % треугольников. От старта до финиса на той же модели — 27 секунд вместо 82, и готовая ретопология отклоняется от оригинала на 4,95 %, а не на 9,68 %. MeshLab по-прежнему вступает в дело, когда эта цепочка не даёт manifold (замкнутую твёрдую поверхность).