kompas 0.3.0 (из fcedb44f5661313ffd0570e3808a5309f6ae8cb7)

plugin/skills/kompas-3d/reference/text-and-relief.md

@@ -1,10 +1,65 @@
 # Надписи и рельеф — точная подгонка и отделка
 
-Дополнение к разделу «Надписи, логотипы и рельеф» SKILL.md. Здесь — замеры и приёмы для точной
-компоновки надписи (подгонка кегля и ширины, поведение каймы, стыковка блоков) и отделки рельефа.
-Все числа получены пробами на конкретных начертаниях (Lobster, Bevan, Zilla Slab): это порядок
-величины и форма зависимости, а не константы — свои значения перезамеряй на своём шрифте,
-`widthFactor` и `thinThickness`.
+Дополнение к разделу «Надписи, логотипы и рельеф» SKILL.md: выбор маршрута для внешнего контура,
+перевод SVG-логотипа в примитивы эскиза, точная подгонка надписи (кегль, ширина, кайма, стыковка
+блоков) и отделка рельефа. Все числа получены пробами на конкретных начертаниях (Lobster, Bevan,
+Zilla Slab): это порядок величины и форма зависимости, а не константы — свои значения перезамеряй
+на своём шрифте, `widthFactor` и `thinThickness`.
+
+## Внешний контур: не диктуй координаты, если фигуру нельзя описать формулой
+
+Три маршрута, и выбор между ними механический — не по вкусу, а по происхождению геометрии.
+
+| Откуда фигура | Чем строить |
+|---|---|
+| **Вычисляется**: пластины, рёбра, сетка отверстий | `sketch_create(entities[])` — прямо в вызове, размеры вяжи переменными |
+| **Срисована**: логотип, шаблон, кулачок, профиль | внешний вектор → JSON → `sketch_create(entitiesFile=…)` |
+| **Пришла в CAD-формате**: файл от смежника | `import_drawing` (.dxf/.dwg) → фрагмент → `fragment_place` |
+
+**Обводка занимает сотни примитивов, и переписывать их в тело вызова незачем.** У `sketch_create`,
+`sketch_add` и `fragment_create` есть `entitiesFile` — путь к JSON того же формата, что `entities`;
+сервер читает файл сам. Замер на эмблеме Volvo: SVG в 1.5 КБ даёт 96 примитивов (50 отрезков +
+46 дуг) и 9.5 КБ JSON; через `entitiesFile` это один вызов на одну строку аргументов, а эскиз
+строится за один заход. Оба параметра можно задать вместе — сначала `entities`, следом файл:
+так к готовому контуру дописывают рамку или ось, не трогая файл.
+
+Что проверить **до** постройки, а не после: габарит в ответе (`fragment_create` печатает
+фактический — сверь с задуманным) и вложенные контуры. Правил заливки у эскиза КОМПАС нет: любой
+вложенный контур он режет как отверстие, даже там, где вектор заливал материал. Конвертер такие
+места называет заранее — на них смотри до выдавливания, иначе дыры обнаружатся на снимке.
+
+## Логотип, которого нет в шрифте: SVG → примитивы эскиза
+
+Переводи готовый вектор в примитивы эскиза сам — `line` и `arc3points`, а не ломаной: контур из
+сотен звеньев даёт деталь в сотни граней, и фаска по такому низу не строится. Кубические Безье режь
+пополам, пока дуга по трём точкам не ляжет в допуск. Четыре вещи, каждая из которых стоила захода:
+
+- **Ось Y в SVG смотрит вниз** — без инверсии контур встаёт вверх ногами, и это видно только на снимке.
+- **Дуги задавай тремя точками** (`arc3points`): концы заданы явно, соседние примитивы стыкуются
+  точно. Перед постройкой проверь цепочку — конец примитива против начала следующего, разрыв 0.
+- **Чисти мелочь под масштаб детали — параметром `minSegment`.** SVG рисуют в своём габарите (сотня
+  условных единиц), и его скругления после масштабирования превращаются в дуги по 0.02–0.5 мм;
+  замыкающий `z` часто даёт ещё и сегмент нулевой длины. `chamfer_edge` по такому набору отвечает
+  «катет больше длины N из M рёбер» — и это правда. Передай `sketch_create(minSegment=катет)` (тот же
+  параметр есть у `sketch_update` и `fragment_create`), и та же фаска пройдёт с первой попытки;
+  отчёт о выброшенном читай, а не пролистывай — `help(topic="contour-cleanup")`.
+
+**Порядок для фаски по контуру логотипа — только такой, и он неочевиден:**
+
+1. **чистка** порогом ≈ будущего катета (`minSegment`);
+2. **замер ЧИЩЕНОГО силуэта** — `sketch_measure_thickness(entitiesFile, minSegment=тот же порог)`;
+3. **катет по узкому месту** чищеного силуэта: `c ≤ (узкое_место − 2·w)/2`, где `w` — ширина нити.
+
+Менять шаги местами нельзя: **чистка СУЖАЕТ узкое место**. Она заменяет скругление острым углом —
+в выпуклом углу это добавляет материал (габарит подрастает), а в вогнутом срезает его, и именно
+вогнутые углы образуют перемычки между штрихами. Сужение доходит до единиц процентов узкого места —
+этого хватает, чтобы катет, подобранный по нечищеному контуру, перестал проходить свой же критерий.
+Числа снимай на СВОЁМ контуре: они принадлежат рисунку, а не приёму.
+
+- **Ширину штриха и узкое место меряй инструментом, а не глазом** — `sketch_measure_thickness`
+  ничего не строит и документа не требует, поэтому зовётся ДО эскиза
+  (`help(topic="silhouette-thickness")`). От этих чисел зависит, останется ли что-то от рисунка
+  после фаски и напечатается ли он вообще; шаг растра в ответе — точность округления катета.
 
 ## Подгонка ширины и кегля
 
@@ -61,7 +116,11 @@
 - **Толщина каймы — ещё и параметр стыковки блоков.** Кайма опускает силуэт надписи ниже её
   глифов на `t`, и именно это перекрытие с плашкой держит деталь одним телом. Считай так: низ
   каймы = низ глифов − t, и он должен зайти на плашку хотя бы на несколько десятых. Проверка —
-  сводка «Тел:» в ответе самого `primitive(union)`.
+  сводка «Тел:» в ответе самого `primitive(union)`: у примитивов она надёжна, потому что сервер
+  сам сверяет объём до и после и отвергает объединение, ничего не давшее. **У `loft`/`sweep` этой
+  сводке верить нельзя** — там она однажды напечатала «Тел: 1», когда тел было два (см. основной
+  навык, п. «Ответ мутирующей операции»); в сомнительном случае считай тела
+  `describe_model(sections="bodies")`.
 - **Кайма вокруг ПРЯМОУГОЛЬНОЙ плашки — вторым примитивом, а не тонкой стенкой.** Стенка обходит
   контуры эскиза, а плашка по playbook'у строится `primitive`, и каймы у неё не появится. Клади под
   неё второй блок на `2·t` больше и на высоту подложки (85 × 13.5 × 2 под плашкой 82 × 10.5 × 3) —
@@ -89,16 +148,15 @@
   до нужной части силуэта помогает `minY`/`maxY`). **Порядок «сначала скругления углов, потом фаска»
   работает** — дуги от R0.5 фаске не мешают. В отборе встречается тип `other` (у сложных кривых) —
   он тоже принимается параметром `type`.
-- **Отказ фаски на НЕЧИЩЕНОМ контуре — не повод уменьшать катет: попробуй УВЕЛИЧИТЬ.** Успех
-  немонотонен по размеру. На контуре логотипа (54 ребра низа, острые клинья между элементами)
-  `chamfer_edge` отказывает при 0.4, 0.5, 0.6 и 0.7 и проходит при **0.8** — проверено подряд,
-  с `rebuild` между попытками и на неизменных индексах рёбер. Похоже, малый катет оставляет в остром
-  клине вырожденный «нос», который КОМПАС сшить не может, а большой срезает остриё целиком.
-  **Но это верно ТОЛЬКО пока контур не почищен**, и полагаться на такой подбор не нужно: правильное
-  лечение — `minSegment` (см. SKILL.md §«Надписи, логотипы и рельеф»), а не перебор катета.
-  Замер на том же логотипе: почищенный порогом 0.5 контур (34 примитива) фаску **0.5 принимает**,
-  а эталонные **0.8 отвергает** — рабочий диапазон катета сдвигается ВНИЗ вместе с узким местом
-  (1.98 → 1.82 мм). После чистки совет «попробуй увеличить» уже вреден.
+- **Отказ фаски на НЕЧИЩЕНОМ контуре — не повод уменьшать катет: успех немонотонен по размеру.**
+  На контуре с острыми клиньями между элементами `chamfer_edge` отказывает на нескольких катетах
+  подряд и проходит на большем — проверено подряд, с `rebuild` между попытками и на неизменных
+  индексах рёбер. Похоже, малый катет оставляет в остром клине вырожденный «нос», который КОМПАС
+  сшить не может, а большой срезает остриё целиком. **Но перебирать катет не надо**: правильное
+  лечение — `minSegment` (см. SKILL.md §«Надписи, логотипы и рельеф»). После чистки совет «попробуй
+  увеличить» становится вреден: рабочий диапазон катета сдвигается ВНИЗ вместе с узким местом, и
+  катет, проходивший на нечищеном контуре, чищеный отвергает. Не переносите подобранное значение
+  между состояниями контура — оно к ним привязано.
   Прежняя формулировка добавляла «исключение самых коротких рёбер картину не меняет, то есть дело
   не в них» — вывод неверен: исключённое из `edgeIndices` ребро остаётся в теле, и это не то же
   самое, что убрать сегмент из контура. Убранный из контура — меняет.