kompas-plugin/plugin/skills/kompas-3d/reference/parametrization.md

Параметризация: сначала переменные, потом геометрия

Дополнение к SKILL.md §«Параметризация». Читай это перед первым эскизом нового документа — план переменными стоит один вызов на размер, пока деталь пуста, и пересборку после десятка операций.

В новом документе первым делом опиши будущую модель переменными — до первого эскиза. Набор переменных — это план построения числами и паспорт, по которому человек поймёт модель, не разбирая дерево.

• Заводи переменной то, что было РЕШЕНИЕМ: габариты из ТЗ, толщины, зазоры, отступы, кегли, радиусы. Выводимое задавай формулой (plate_L = badge_L - 2*edge_gap) — правка ведущего размера пересчитает зависимые сама. Позиции, подобранные замером, оставляй числами: связь — обещание, что правка переменной даст осмысленный результат, а на позиционных числах она чаще ломает деталь.
• Размер передавай выражением прямо в операцию (extrude(depth="badge_T")) — параметр сразу становится ведомым, внутреннее имя параметра («Расстояние 1») знать не нужно. Переменная должна существовать ДО операции — потому паспорт и заводят первым. Задним числом и для параметров, которых нет среди аргументов инструмента (углы уклона, второе направление), — link_parameter.
• Размер КОНТУРА — тоже выражением, но не в координатах, а в dimensions у sketch_create/sketch_update: ширина, длина отрезка, Ø/R, а с to — расстояние между точками (шаг отверстий, отступ от края) и угол между отрезками. Координаты достаточно нарисовать примерно — контур встанет по значению сразу.
• Эскиз определён полностью, только когда привязан к модели. Форма — размерами, положение — от начала координат и осей: to:{ref:"origin"} (расстояние от базовых плоскостей, угол или центр в начало через coincident), coincident с ref:"xAxis"|"yAxis" (точка на оси), symmetric с axis (деталь симметрична оси — ширина растёт в обе стороны). Порядок для каждого эскиза: (1) где он стоит — привязка к началу координат/осям; (2) форма — все длины, радиусы, углы; (3) взаимное положение элементов — от привязанного контура или от оси. Симметричную деталь строй симметрично оси модели: тогда её плоскости симметрии совпадают с базовыми, и следующие эскизы привязываются к тем же осям. Нужна симметрия на уровне грани — ставь эскиз не на грань, а на базовую плоскость со смещением (offset): у грани осей модели нет.
• Читай хвост ответа. «полностью определён» без строки «Закреплено там, где нарисовано» — цель. Строка «Закреплено…» значит, что положение держит закреплённая сервером точка, а не привязка: добавь ref. «⚠ НЕДООПРЕДЕЛЁН» — часть контура свободна и сдвинется при смене переменной: допиши размер (чаще всего радиус дуги, угол наклонного отрезка или вторую ось положения). Отказ «размер ЛИШНИЙ» — величина уже следует из других (касание, сшивка, симметрия) — убери один. Поля, правила опоры и пример VESA — help(topic="sketch-dimensions").
• Промахи сервер ловит сам: ссылка на несуществующее имя — отказ с перечнем виновных (и в выражениях операций, и в set_variable), функции в формулах — предупреждение (тригонометрия в радианах, разделитель аргументов «;», непонятая запись = молчаливый 0). Имена: в ФОРМУЛЕ регистр значим (aq не найдёт Aq), а две переменные, различающиеся только регистром, не уживаются — spl_d перезапишет spl_D. Константы π нет: заведи dg = 0.017453292519943295 (градус в радианах) и пиши sin(a*dg).
• Связь — ограничением, а не арифметикой. Центр дуги на окружности — coincident с to.point: "curve"; опора вне профиля (основная окружность, ось паза) — примитив с construction: true; сторона «в 3.5 от оси под 22.5°» — distance до origin плюс angle к оси. Так связь живёт в эскизе и переживает смену переменной; посчитанные числа — нет.
• Считает КОМПАС, а не ты: связь — ограничением в эскизе, скругление — примитивом fillet, точная начальная координата — выражением прямо в точке ({"x": "rb*sin(phi*dg)"}). Заводить переменные-калькуляторы и переносить их значения в JSON не нужно. Твоя часть — сверить результат с прикидкой (sketch_describe).
• note обязателен и пишется по-русски, со смыслом и единицей; (ТЗ) в тексте по-прежнему полезен человеку, но для машины число из ТЗ метится ПРИЗНАКОМ: set_variable([{name:"dish_r", expression:"90", note:"по ТЗ", information:true}]). Комментарий вычистка не читает, признак — читает. Что замерил — верни в переменную (фактический кегль, прирост каймы), иначе паспорт разойдётся с моделью и станет дезинформацией. Переосмысливать можно всё, кроме помеченного (ТЗ).
• После связывания правка паспорта перестраивает деталь (проверено: set_variable(badge_T=4) → габарит по Z 3.00 → 4.00, объём 5154.5 → 5861.5 мм³). Это и есть параметрическая модель, а не комментарий к ней. До связывания — не перестраивает, и set_variable говорит об этом прямо: «⚠ НИЧЕГО НЕ ВЕДЁТ». Такой ответ — не успех: число поменялось, деталь нет. Исключение одно — переменная и не должна ничего вести (справка из ТЗ): пометь её information=true, и пометка уйдёт вместе с риском вычистки.
• Сверка и уборка в конце: describe_model(sections=variables) помечает «⚠ ничего не ведёт» — это либо забытая связь, либо справка, которую забыли пометить, либо мусор; разбери все три. delete_variable(unused=true) не трогает справочные (information) и внешние (external) — остальное сносит без разбора. Значит порядок такой: link_parameter на всё, что должно вести геометрию, set_variable(information=true) на всё, что остаётся справкой, и только потом уборка.