From 92833c9bb2bc2e98eaad74fc2d6ce179bfec7c4b Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 15:48:26 +0300 Subject: [PATCH 01/10] docs: add Russian documentation --- CHANGELOG.md | 2 + CHANGELOG.ru.md | 84 ++++++++++++++++++++++++++++++ docs/releases/v0.1.5.md | 2 + docs/releases/v0.1.5.ru.md | 43 ++++++++++++++++ docs/releases/v0.2.0.md | 2 + docs/releases/v0.2.0.ru.md | 49 ++++++++++++++++++ docs/releases/v1.0.0.md | 2 + docs/releases/v1.0.0.ru.md | 102 +++++++++++++++++++++++++++++++++++++ docs/releases/v1.0.1.md | 2 + docs/releases/v1.0.1.ru.md | 25 +++++++++ docs/releases/v1.1.0.md | 2 + docs/releases/v1.1.0.ru.md | 56 ++++++++++++++++++++ 12 files changed, 371 insertions(+) create mode 100644 CHANGELOG.ru.md create mode 100644 docs/releases/v0.1.5.ru.md create mode 100644 docs/releases/v0.2.0.ru.md create mode 100644 docs/releases/v1.0.0.ru.md create mode 100644 docs/releases/v1.0.1.ru.md create mode 100644 docs/releases/v1.1.0.ru.md diff --git a/CHANGELOG.md b/CHANGELOG.md index cb14da5..d02473f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,7 @@ # Changelog +[Русская версия](CHANGELOG.ru.md) + ## 1.1.0 — 2026-10-25 - Add six Noise fields: Smooth Noise, Reaction Diffusion, Directional Fibers, Topographic, Gyroid Field and Blue Noise. Move Voronoi to Noise, last in the list; keep 12 repeating shapes in Pattern. diff --git a/CHANGELOG.ru.md b/CHANGELOG.ru.md new file mode 100644 index 0000000..61384b4 --- /dev/null +++ b/CHANGELOG.ru.md @@ -0,0 +1,84 @@ +# История изменений + +[English](CHANGELOG.md) + +## 1.1.0 — 2026-10-25 + +- Добавлены шесть полей Noise: Smooth Noise, Reaction Diffusion, Directional Fibers, Topographic, Gyroid Field и Blue Noise. Voronoi перемещён в конец Noise; в Pattern сохранены 12 повторяемых форм. +- Основные настройки шума — Cell Size и Web Thickness, с необязательной Add Bridges и дополнительными настройками полей. Сохранены старые пороги заполнения. Цвет Fast Preview по умолчанию — Magenta. +- Добавлены Along Path, Contour, Fan, Phyllotaxis, Poisson Disk, Wave, Chevron и Between Curves: всего 11 доступных семейств Distribution. Новые команды используют ревизию 2; сохранённые Features сохраняют свою ревизию и старый Running Bond. +- Поддерживаются цилиндрические, конические и регулярные гладкие грани произвольной формы твёрдых тел, а также до 32 областей одного типа поверхности в одном компоненте. +- Добавлена входящая в пакет браузерная площадка с тем же ядром геометрии Python, что и Fusion, всеми 19 формами и параметрами, которыми можно делиться. +- На всех платформах сохраняются LF и явное чтение UTF-8, чтобы байтовые хеши встроенного ядра, подписи демо и содержимое ZIP релиза оставались согласованными и в Windows. +- Ограничена дискретизация органических полей на больших областях и сохранены частичные отверстия у границы с заданным отступом. +- Исправлена зависимость Custom Feature от собственного результата: ссылки Object сохраняются через исходные грани и привязываются до поглощения геометрии булевыми операциями. Edit Feature OK обновляет старые ссылки Object. +- После завершения команды восстанавливается положение таймлайна, чтобы Cancel сохранял геометрию и состояние узла без дополнительного шага Undo. Точный предпросмотр Feature отделён от окончательного CAD-построения. +- Зафиксированная до подготовки релиза приёмка: 200 тестов Python, 36 браузерных сценариев, все шесть шумовых полей и Voronoi на копиях реальной геометрии Box, нативные Edit Feature OK/Cancel и Undo/Redo, восстановление старого узла, операции с несколькими областями, представительные криволинейные источники и локальное повторное открытие F3D. +- ZIP релиза и контрольная сумма собираются и публикуются обычным workflow GitHub Actions на трёх ОС. Локальные проверки и проверки Fusion при подготовке релиза не повторяются; нативная CAD-приёмка Windows и облачное сохранение не заявляются. + +## 1.0.1 — 2026-10-24 + +- Исправлена потеря целевого тела Feature Cut при уменьшении исходной грани с Trim to Boundary и ненулевым Edge Offset. Точное смещение вычисляется по временным BRep-контурам без редактирования вспомогательного эскиза на грани при пересчёте. +- Добавлена регрессионная проверка в реальном Fusion для изменений высоты оболочки 70 → 20 → 70 → 20 мм с проверкой состояния вложенного Combine и видимого твёрдого тела. + +## 1.0.0 — 2026-10-24 + +Первый стабильный выпуск Perfora. Опубликован как обычный GitHub Release с отметкой Latest. + +### Узор, размещение и удобство + +- Добавлены шесть цветов Fast Preview, по умолчанию Gold, и более толстые контуры; при выборе цвета повторно используется подготовленная геометрия. Подсветка выбора Fusion по-прежнему может окрашивать или перекрывать контуры. +- При первоначальном открытии команды по умолчанию выбирается Feature; последующие изменения пользователя сохраняются. +- Исправлены профили эскиза на гранях: их опорная геометрия определяется в правильной позиции таймлайна, маркер вызывающей стороны восстанавливается, а Objects выводятся из опорного тела для Cut/Intersect (и Feature Join). Split Face не требуется. + +### Производительность + +- Перед точными проверками зазора фильтруются близкие рёбра границы; для малых узоров сохранён прямой путь и проверка замкнутых пустот. +- Пропускается обрезка Voronoi полуплоскостью без изменений порядка соседей, Seed, очистки или условий скругления. +- Единая неизменяемая раскладка ячеек разделяется Fast Preview и финальным построением; ключ включает полные Region, разрешённые Settings и систему координат плоскости, а перед построением источник читается заново. +- Булевы операции обрезки, относящиеся только к Panel, откладываются до её запроса; кешированная панель предоставляется только после успеха всех операций. +- Источник, внутренний отступ и радиальная область кешируются раздельно; данные источника предпросмотра сбрасываются при изменении нативных ревизий тела или эскиза либо базиса плоскости. + +### Параметрическое размещение + +- Добавлен Spread Radius (0 = вся граница) для всех распределений с ограниченной генерацией кандидатов, точной круговой обрезкой и нативным параметром модели в новых узлах Feature. +- Выбранный центр сохраняется как зависимость Feature с пересчётом, заменой и очисткой в Edit Feature. +- Для всех распределений добавлен общий Start Point с выбором точек эскиза, вершин и конструкционных точек; он используется Fast/Full Preview и финальной геометрией. +- Помимо Fixed и Radial добавлена явная ориентация Tangential. +- Для всех 36 пустых числовых полей, включая целочисленные, восстанавливаются значения по умолчанию; явные нули, корректный заменяющий текст, выражения единиц и параметров Fusion и ошибки проверки непустых значений сохраняются. +- Неявные единицы полей нормализуются до передачи выражений в штатный Extrude; ожидающие обратные вызовы значений по умолчанию освобождаются при закрытии команды. +- Добавлено распределение Circular для 12 повторяемых форм с автоматическими концентрическими кольцами, Start Radius и ориентацией Fixed/Radial. +- Минимальная перемычка сохраняется за счёт шага по хорде и консервативных ограничивающих контуров, включая замыкающий стык кольца; сохранены точная обрезка, предпросмотр и штатные операции Extrude. +- Смещения круговой раскладки перемещают центр по осям эскиза без периодического заворачивания; Voronoi сохраняет собственное распределение. + +### Документация и проверка + +- Добавлены реальные скриншоты Fusion с круговой ориентацией, зоной по точке, профилями на грани без Split Face и пересчётом Feature по радиусу. +- Опубликованы воспроизводимые сценарии и результаты измерений с разделением генерации на чистом Python и предпросмотра/построения в Fusion. +- Сохранены стабильные ID команды, UUID манифеста, атрибуты документа и лицензия GPL-3.0-only этого выпуска. +- Нативная CAD-приёмка зафиксирована для Fusion 2706.1.14 на macOS 27.0.1. CI Windows охватывает Python и упаковку; нативный CAD на Windows не заявлен как проверенный. + +## 0.2.0 — 2026-10-23 + +- Voronoi как тринадцатая форма отверстий с воспроизводимыми начальными значениями, нерегулярностью, минимальной перемычкой, точной обрезкой и необязательным касательным скруглением углов. +- Экспериментальный результат Feature: параметрический узел Perfora в таймлайне с редактируемыми параметрами узора, зависимостями от исходной геометрии и пользовательским обработчиком пересчёта. Sketch и штатный Extrude остаются доступны. +- Все 13 форм, точная обрезка, скруглённые отверстия Voronoi, кешируемый Fast и транзакционный Full Preview; прямое выдавливание Distance с Join, Cut, Intersect и New Body. +- Edit Feature восстанавливает настройки узора и выражения с поддержкой Cancel и Undo/Redo. Autodesk Preview API требует работающего аддона. +- Создаваемая Fusion конфигурация `.vscode` исключена из установки и ZIP-архивов. +- Нативная приёмка Fusion на macOS: все 13 форм, пересчёт, Edit Feature, откат Full Preview, Undo/Redo и повторное открытие архива F3D. При переключении связанных копий из разных папок перезапустите Fusion; нативная CAD-приёмка Windows остаётся невыполненной. + +## 0.1.5 — 2026-10-23 + +Первый публичный экспериментальный выпуск Perfora от 4FusionLab. + +- Двенадцать форм отверстий, прямоугольное и шахматное распределение, толщина перемычек, отступы от края, независимые повороты и смещения размещения. +- Точная обрезка ячеек на границе, включая зазор вокруг внутренних отверстий. +- Профили эскиза и перфорированные панели; штатные операции Extrude Join, Cut, Intersect, New Body и New Component. +- Кешируемый предпросмотр контуров и необязательный полный CAD-предпросмотр. +- Английский диалог со штатной терминологией Fusion и значками операций. +- Графика проекта, установщик macOS/Windows с резервными копиями, переносимый ZIP, контрольная сумма SHA-256 и автоматические проверки релиза. +- Стабильные ID команды и пространство имён атрибутов документа для установок, ранее называвшихся Perforator. + +### Известные ограничения + +Только плоская геометрия. Пользовательской параметрической операции для перестроения всего узора нет. Поведение CAD на Windows, сложные сборки, сохранение и повторное открытие документов ещё требуют приёмки. Экспериментальные сборки используйте на копиях рабочих моделей. diff --git a/docs/releases/v0.1.5.md b/docs/releases/v0.1.5.md index a09f104..807087c 100644 --- a/docs/releases/v0.1.5.md +++ b/docs/releases/v0.1.5.md @@ -1,5 +1,7 @@ ## Perfora's first public release +[Русская версия](v0.1.5.ru.md) + **Goddess of holes. Precision for Fusion.** Create ventilation panels, grilles, and hole patterns directly in Autodesk Fusion. diff --git a/docs/releases/v0.1.5.ru.md b/docs/releases/v0.1.5.ru.md new file mode 100644 index 0000000..3880cd7 --- /dev/null +++ b/docs/releases/v0.1.5.ru.md @@ -0,0 +1,43 @@ +## Первый публичный выпуск Perfora + +[English](v0.1.5.md) + +**Богиня отверстий. Точность для Fusion.** + +Создавайте вентиляционные панели, решётки и узоры отверстий прямо в Autodesk Fusion. + +### Основные возможности + +- 12 форм отверстий с настройкой толщины перемычек, отступа от края, поворота и размещения. +- Прямоугольные и шахматные раскладки; точная обрезка по границе. +- Профили эскиза или штатные операции Join, Cut, Intersect, New Body и New Component. +- Быстрый кешируемый предпросмотр контуров и необязательный полный CAD-предпросмотр. +- Английский интерфейс, графика проекта и резервные копии при установке. + +### Установка без терминала + +Отдельная установка Python не требуется: Fusion включает необходимую Perfora среду выполнения. + +1. Скачайте **Perfora-0.1.5.zip** и распакуйте его в постоянную папку. +2. В Fusion откройте **Utilities → Scripts and Add-Ins**. +3. Нажмите **+ → Script or add-in from device** и выберите внутреннюю папку **Perfora**, содержащую `Perfora.py` и `Perfora.manifest`. +4. Выберите **Perfora → Run**; при желании включите **Run on Startup**. +5. Найдите **Perfora** в **Design → Solid → Create** или нажмите **S** для поиска. + +Fusion связывается с выбранной папкой. Сохраняйте её на месте: не перемещайте и не удаляйте после добавления. + +**Необязательно:** если Python 3 уже установлен, `python3 install.py` на macOS или `py -3 install.py` на Windows скопирует аддон в каталог Fusion API и создаст резервные копии предыдущих установок Perfora. Для способа с подключением папки этот помощник не нужен. + +`Perfora-0.1.5.zip.sha256` содержит контрольную сумму SHA-256. Создаваемые GitHub архивы «Source code» являются снимками репозитория; установочный пакет — именованный ZIP Perfora. + +### Экспериментальный статус + +Это **предварительный выпуск**, а не стабильная производственная сборка. Геометрия и установщик проверяются CI на macOS, Windows и Linux; Linux используется для тестирования и сборки, а не как платформа Fusion. Нативные CAD-сценарии отдельно проверяются в Fusion на macOS. Поведение CAD в Windows, сохранение и повторное открытие документов и сложные сборки ещё требуют проверки. + +Результат использует обычные эскизы и операции Extrude. Пользовательской параметрической операции для повторного открытия или восстановления всего узора отверстий нет. Только плоские грани и твёрдые тела. + +При переходе с Perforator остановите старый аддон и удалите его регистрацию до запуска Perfora. Не запускайте обе версии одновременно. + +[Документация](https://github.com/4FusionLab/Perfora#readme) · [Русская инструкция](https://github.com/4FusionLab/Perfora/blob/main/README.ru.md) + +Этот выпуск лицензирован по GPL-3.0-only. Независимый проект, не связанный с Autodesk. diff --git a/docs/releases/v0.2.0.md b/docs/releases/v0.2.0.md index 1924436..adbcd1a 100644 --- a/docs/releases/v0.2.0.md +++ b/docs/releases/v0.2.0.md @@ -1,5 +1,7 @@ ## Parametric Perfora features and Voronoi +[Русская версия](v0.2.0.ru.md) + Perfora 0.2.0 adds a **Feature** output that regenerates the hole pattern when its parameters or upstream geometry change, and **Voronoi** as the thirteenth hole shape. ### Highlights diff --git a/docs/releases/v0.2.0.ru.md b/docs/releases/v0.2.0.ru.md new file mode 100644 index 0000000..d6a1620 --- /dev/null +++ b/docs/releases/v0.2.0.ru.md @@ -0,0 +1,49 @@ +## Параметрические операции Perfora и Voronoi + +[English](v0.2.0.md) + +Perfora 0.2.0 добавляет результат **Feature**, который перестраивает узор отверстий при изменении его параметров или исходной геометрии, и **Voronoi** как тринадцатую форму отверстий. + +### Основные возможности + +- **Type → Feature** создаёт один узел Perfora в таймлайне. Дважды нажмите его или используйте **Edit Feature**, чтобы изменить узор, обрезку, размещение, тип профиля и толщину. +- Выражения параметров могут ссылаться на пользовательские параметры Fusion. Пересчёт может изменить число отверстий без добавления узлов в таймлайн. +- Voronoi поддерживает воспроизводимые Seed/New Pattern, Irregularity 0–100%, минимальную толщину перемычки, точную обрезку по границе и необязательное касательное скругление углов. +- Все 13 форм поддерживают Fast/Full Preview. Редактирование Feature поддерживает OK, Cancel и Undo/Redo. +- По-прежнему доступны эскиз и штатный Extrude, включая более широкий выбор протяжённости и операций Extrude. +- Создаваемая Fusion конфигурация редактора исключена из установки и ZIP-пакетов. + +### Установка и обновление + +Fusion предоставляет среду выполнения Python; отдельная установка Python не нужна. + +1. Скачайте **Perfora-0.2.0.zip** и распакуйте его в постоянную папку. +2. Остановите предыдущую копию Perfora и удалите её ссылку из **Utilities → Scripts and Add-Ins**. +3. Перезапустите Fusion перед использованием Feature из новой папки. При переключении связанных копий с одинаковым UUID в одном сеансе может сохраниться прежний владелец Custom Feature, что препятствует пересчёту. +4. Выберите **+ → Script or add-in from device**, укажите внутреннюю папку **Perfora** с `Perfora.py` и `Perfora.manifest` и нажмите **Run**. Не перемещайте папку и запускайте одну копию. +5. Найдите **Perfora** в **Design → Solid → Create** или нажмите **S** для поиска. Включите **Run on Startup**, если существующие узлы Feature должны пересчитываться при каждом открытии Fusion. + +Необязательный установщик `python3 install.py` (macOS) или `py -3 install.py` (Windows) копирует аддон в каталог Fusion API и создаёт резервные копии предыдущих установок. Автозапуск остаётся выключенным. Соседний файл **Perfora-0.2.0.zip.sha256** позволяет проверить именованный установочный пакет. + +### Проверка + +Нативная приёмка: **Autodesk Fusion 2706.1.14, macOS 27.0.1, Apple Silicon**. + +- 40 локальных тестов геометрии и установщика; 14 нативных дымовых сценариев; 34 сценария форм; 35 сценариев обрезки; 12 сценариев Voronoi; семь конфигураций измерения производительности предпросмотра. +- 45 сценариев Feature как в рабочем каталоге, так и в копии, установленной из ZIP после чистого запуска Fusion: все 13 форм, изменения параметров и исходных профилей, поддерживаемые операции и направления, пользовательские выражения, обрезка, повторное открытие архива F3D с последующим пересчётом. +- Реальные OK/Cancel в Sketch, Extrude и Feature; Edit Feature, откат Full Preview, Undo/Redo и редактирование штатного Extrude в стандартном диалоге Fusion. +- Локально проверены содержимое ZIP, контрольная сумма, установка и резервные копии при повторной установке. CI релиза отдельно проверяет Python и упаковку на Linux, macOS и Windows; эти задания не подтверждают нативное CAD-поведение в Windows. + +Для ориентира: Fast Preview создал 709 шестиугольников за 0,101 с и 1138 обрезанных скруглённых ячеек Voronoi за 0,663 с на проверенной машине. Время зависит от оборудования и сложности модели. + +### Экспериментальные ограничения + +Это **экспериментальный предварительный выпуск**. Используйте копии рабочих моделей. Нативное CAD-поведение в Windows и сложные сборки ещё требуют приёмочных испытаний. + +Feature требует включённого **Capture Design History** и работающего аддона Perfora. Используется Autodesk Preview Custom Feature API. Эта версия поддерживает прямую протяжённость **Distance** с нулевым уклоном, **One Side / Two Sides / Symmetric** и **Join / Cut / Intersect / New Body**. Источник, операция и целевые тела фиксированы при редактировании. Для **All**, **To Object**, уклона или **New Component** используйте штатный Extrude. + +Большие изменения топологии могут сделать недействительными последующие ссылки на грани и рёбра. Sketch и Extrude сохраняют фиксированный узор. Поддерживаются только плоская геометрия и твёрдые тела. + +[Документация](https://github.com/4FusionLab/Perfora#readme) · [Русская инструкция](https://github.com/4FusionLab/Perfora/blob/main/README.ru.md) + +Этот выпуск распространяется по GPL-3.0-only. Независимый проект 4FusionLab, не связанный с Autodesk. diff --git a/docs/releases/v1.0.0.md b/docs/releases/v1.0.0.md index 844cfb3..055de53 100644 --- a/docs/releases/v1.0.0.md +++ b/docs/releases/v1.0.0.md @@ -1,5 +1,7 @@ # Perfora 1.0.0 — First stable release +[Русская версия](v1.0.0.ru.md) + **Perforate the region you choose. Place the pattern where you need it. Keep it parametric.** Perfora 1.0 is the first stable release from 4FusionLab. It combines the existing thirteen hole shapes and parametric timeline Feature with circular patterns, point-based placement, bounded spread, direct sketch-profile regions, and faster previews. diff --git a/docs/releases/v1.0.0.ru.md b/docs/releases/v1.0.0.ru.md new file mode 100644 index 0000000..44d3512 --- /dev/null +++ b/docs/releases/v1.0.0.ru.md @@ -0,0 +1,102 @@ +# Perfora 1.0.0 — первый стабильный выпуск + +[English](v1.0.0.md) + +**Перфорируйте выбранную область. Размещайте узор там, где он нужен. Сохраняйте параметричность.** + +Perfora 1.0 — первый стабильный выпуск 4FusionLab. Он объединяет существующие тринадцать форм отверстий и параметрическую операцию Feature в таймлайне с круговыми узорами, размещением по точке, ограниченной областью, непосредственным выбором профиля эскиза и ускоренным предпросмотром. + +[Скачать Perfora-1.0.0.zip](https://github.com/4FusionLab/Perfora/releases/download/v1.0.0/Perfora-1.0.0.zip) · [SHA-256](https://github.com/4FusionLab/Perfora/releases/download/v1.0.0/Perfora-1.0.0.zip.sha256) · [Английское руководство](https://github.com/4FusionLab/Perfora/blob/v1.0.0/README.md) · [Русская инструкция](https://github.com/4FusionLab/Perfora/blob/v1.0.0/README.ru.md) + +## Что нового + +- **Круговое распределение:** концентрические кольца для всех двенадцати повторяемых форм. Выберите ориентацию Fixed, Radial или Tangential, задайте Start Radius первого кольца и добавьте Hole Angle. Web Thickness сохраняется на стыке каждого кольца. +- **Start Point для любого распределения:** выберите точку эскиза, вершину или конструкционную точку штатным элементом Fusion Select. Точки за пределами исходной плоскости проецируются на неё. X/Y Offset смещает узор от этой точки. +- **Spread Radius:** ограничьте отверстия круглой зоной вокруг выбранного начала. Ноль заполняет выбранную границу. Для простой локальной перфорации дополнительный профиль не нужен. Edge Offset и точный Trim to Boundary продолжают действовать. +- **Профили непосредственно на гранях тел:** завершите эскиз границы и выберите его заштрихованный профиль в Profiles. Узор остаётся внутри области, а поддерживающее тело выбирается для Cut/Intersect. Split Face не требуется. +- **Feature по умолчанию:** новые команды начинают с параметрического узла Perfora в таймлайне. Измените штатный параметр, исходную границу или Start Point и пересчитайте узор. Sketch и штатный Extrude по-прежнему доступны. +- **Восстановление значений по умолчанию:** пустое значение любого из 36 числовых полей восстанавливает значение по умолчанию. Явный ноль, параметры документа, единицы и ошибки проверки непустых значений сохраняют своё значение. +- **Preview Color:** по умолчанию Gold, также доступны Cyan, Magenta, Green, White и Black. Контуры Fast Preview стали толще, а изменение цвета повторно использует подготовленную раскладку. Full Preview сохраняет внешний вид модели Fusion. + +## Создано в Fusion + +Это реальные CAD-результаты, полученные в Fusion с тем же белым фоном и цветными деталями, что и в существующей галерее. + +| Круговые узоры | Radial и Tangential | +| --- | --- | +| ![Золотая круговая решётка с касательными прорезями](https://raw.githubusercontent.com/4FusionLab/Perfora/v1.0.0/docs/assets/examples/v1.0.0/circular-tangential.jpg) | ![Радиальные прорези слева и касательные справа](https://raw.githubusercontent.com/4FusionLab/Perfora/v1.0.0/docs/assets/examples/v1.0.0/radial-and-tangential.jpg) | +| Прорези следуют концентрическим кольцам вокруг центрального отверстия. | Меняется ориентация; круговое распределение сохраняется. | + +| Точка и радиус | Эскиз задаёт границу | +| --- | --- | +| ![Перфорация ограничена зоной вокруг точки](https://raw.githubusercontent.com/4FusionLab/Perfora/v1.0.0/docs/assets/examples/v1.0.0/point-scoped-perforation.jpg) | ![Перфорация внутри профиля без Split Face](https://raw.githubusercontent.com/4FusionLab/Perfora/v1.0.0/docs/assets/examples/v1.0.0/profile-region.jpg) | +| Смещённая круглая зона на существующей пластине; материал снаружи сохранён. | Скруглённые отверстия Voronoi внутри произвольного профиля, нарисованного на грани. | + +![Сравнение параметрического радиуса: 16 и 26 мм](https://raw.githubusercontent.com/4FusionLab/Perfora/v1.0.0/docs/assets/examples/v1.0.0/parametric-spread.jpg) + +**Измените радиус. Перестройте узор.** Обе панели начинаются с одинаковых настроек. Правая Feature пересчитана изменением параметра модели Spread Radius с 16 до 26 мм. + +## Измерения производительности + +Измерения сделаны **24 октября 2026 года на macOS arm64, Fusion 2706.1.14**. Сравнение до и после использует зафиксированный **снимок разработки до оптимизации с теми же возможностями раскладки**, а не опубликованный пакет 0.2.0. Алгоритмы сохраняют созданные ячейки и контуры: сравнительная матрица из 511 случаев не обнаружила расхождений. + +### Генерация раскладки на чистом Python + +Медиана трёх чередующихся измерений, включая подготовку индекса; нативный рендеринг, построение эскиза, обрезка BRep и Extrude исключены. + +| Сценарий | Отверстий | До | После | Ускорение | +| --- | ---: | ---: | ---: | ---: | +| Шестиугольники, прямоугольная граница | 709 | 34,005 мс | 10,588 мс | 3,21× | +| Шестиугольники, круглая граница | 253 | 1 282,353 мс | 96,812 мс | 13,25× | +| Эллипсы, круглая граница | 45 | 4 027,185 мс | 263,233 мс | 15,30× | +| Voronoi, прямоугольная граница | 1 041 | 269,651 мс | 125,366 мс | 2,15× | + +### Нативный Fusion: Fast Preview и последующее построение + +Одиночные парные измерения в одном сеансе Fusion. Построение следует за Fast Preview, поэтому оптимизированная версия может повторно использовать ячейки, при этом читая текущий источник и создавая нативную геометрию. + +| Сценарий | Отверстий | Fast Preview до → после | Построение до → после | +| --- | ---: | ---: | ---: | +| Шестиугольники внутри круга | 253 | 1,148 → 0,104 с | 2,453 → 2,193 с | +| Эллипсы внутри круга | 45 | 3,424 → 0,262 с | 3,683 → 0,263 с | +| Небольшая ограниченная касательная раскладка | 7 | 0,058 → 0,054 с | 0,105 → 0,107 с | + +В небольшом ограниченном случае заметного ускорения построения нет. Создание нативного эскиза всё ещё может занимать основное время при плотном узоре. Результаты зависят от задачи; **15,30× — измеренное ускорение генерации геометрии, а не универсальное ускорение команды**. + +Изменения фильтруют близкие рёбра границы перед точной проверкой, пропускают обрезку Voronoi без результата, разделяют неизменяемые подготовленные ячейки между Fast Preview и созданием, откладывают неиспользуемые булевы операции Panel и независимо кешируют подготовку источника, внутреннего отступа и зоны. Текущие настройки выдавливания применяются всегда, а изменение источника сбрасывает кеш. + +[Полная методика и сценарии](https://github.com/4FusionLab/Perfora/blob/v1.0.0/docs/BENCHMARKS.md) · [Исходные измерения и отпечатки исходников](https://github.com/4FusionLab/Perfora/blob/v1.0.0/docs/benchmarks/v1.0.0.json) · [Повторить измерение геометрии](https://github.com/4FusionLab/Perfora/blob/v1.0.0/scripts/benchmark_layout.py) + +## Установка и обновление + +1. Скачайте и распакуйте ZIP в постоянную папку. +2. В Fusion откройте **Utilities → Scripts and Add-Ins → + → Script or add-in from device**. +3. Выберите внутреннюю папку **Perfora** с `Perfora.py` и `Perfora.manifest`, затем нажмите **Run**. Run on Startup включается по желанию. +4. Откройте **Design → Solid → Create → Perfora** или нажмите **S** и найдите Perfora. + +Отдельная установка Python и сторонние пакеты среды выполнения не нужны. Необязательный установщик `install.py` сохраняет резервные копии предыдущих установок. + +При обновлении папки, уже подключённой в Fusion, остановите и повторно загрузите аддон. При подключении другой папки остановите и отключите старую копию, затем перезапустите Fusion перед использованием Feature: Fusion может сохранить прежнего владельца Custom Feature в том же сеансе. Не запускайте обе копии. UUID манифеста, ID команды и пространство имён атрибутов документа не меняются. + +Существующие узлы Feature версии 0.2 остаются редактируемыми. Новые штатные параметры Start Radius и Spread Radius присутствуют в новых узлах; старые узлы сохраняют редактируемые значения в настройках, но не могут получить эти дополнительные штатные параметры средствами текущего API. Если поля должны появиться в диалоге Parameters Fusion, создайте узел заново. + +## Проверка и практические ограничения + +- **67 тестов Python**, проверка компиляции, воспроизводимая сборка ZIP и установка с резервными копиями. GitHub Actions проверяет Python и упаковку на Linux, macOS и Windows перед публикацией именно этого коммита. +- **179 нативных CAD-сценариев** для форм, обрезки, Voronoi, кругового распределения, точек, операций и пересчёта Feature, профилей на гранях, поведения оптимизации и производительности предпросмотра. +- Приёмка реальных команд на **Fusion 2706.1.14 / macOS 27.0.1**: значения по умолчанию и выбор цвета, Fast/Full Preview, OK/Cancel, нативные Undo/Redo, редактирование параметров Feature и Extrude, локальное повторное открытие F3D и последующий пересчёт. Все тестовые документы временные; пользовательские документы не сохраняются. +- Нативный CAD Fusion на Windows, сохранение и повторное открытие через облако и сложные сборки **не заявлены как проверенные**. Windows CI не равнозначен нативной CAD-приёмке. +- Исходные объекты должны быть плоскими; криволинейные грани и сетки не поддерживаются. Edge Offset должен создавать корректный внутренний контур; Fusion может отклонить касающиеся или пересекающиеся петли смещения. +- Feature поддерживает прямую протяжённость **Distance** и **Join, Cut, Intersect, New Body**. Для All, To Object, уклона и New Component используйте штатный Extrude. Для редактирования и пересчёта Feature Perfora должна работать. Autodesk Custom Feature API по-прежнему имеет статус Preview; этот выпуск не меняет статус API Autodesk. +- Синяя подсветка выбора Fusion может окрашивать или перекрывать пользовательскую графику даже при выборе другого цвета предпросмотра. Более толстые контуры повышают контраст; Preview Color не переопределяет цвета выделения Fusion. +- Start Radius измеряется до центров отверстий и не гарантирует сплошную ступицу. Для некруглых колец применяется консервативный шаг; реальные перемычки могут быть шире заданных. + +## По-русски + +**Perfora 1.0.0 — первый стабильный релиз, без отметки prerelease.** В нём появились круговая раскладка с касательными и радиальными отверстиями, общая Start Point, ограничение Spread Radius, работа по профилю на грани без Split Face, восстановление пустых числовых полей и выбор цвета Fast Preview. Feature теперь выбирается по умолчанию. + +Бенчмарки выше разделяют генерацию геометрии и настоящее построение Fusion: например, Fast Preview для 45 эллиптических отверстий сократился с 3,424 до 0,262 с. Это конкретные парные замеры на macOS, а не обещание такого ускорения для любой модели. Нативная работа Windows отдельно не проверялась. + +[Подробная русская инструкция](https://github.com/4FusionLab/Perfora/blob/v1.0.0/README.ru.md) + +Этот выпуск Perfora распространяется свободно по GPL-3.0-only и является независимым. Создан **4FusionLab** с любовью к чистым кромкам и неприязнью к размещению отверстий по одному. diff --git a/docs/releases/v1.0.1.md b/docs/releases/v1.0.1.md index a590bf7..9cf2656 100644 --- a/docs/releases/v1.0.1.md +++ b/docs/releases/v1.0.1.md @@ -1,5 +1,7 @@ # Perfora 1.0.1 +[Русская версия](v1.0.1.ru.md) + Fix Feature Cut recompute when an upstream face shrinks with **Trim to Boundary** and a nonzero **Edge Offset**. [Download Perfora-1.0.1.zip](https://github.com/4FusionLab/Perfora/releases/download/v1.0.1/Perfora-1.0.1.zip) · [SHA-256](https://github.com/4FusionLab/Perfora/releases/download/v1.0.1/Perfora-1.0.1.zip.sha256) · [English guide](https://github.com/4FusionLab/Perfora/blob/v1.0.1/README.md) · [Русская инструкция](https://github.com/4FusionLab/Perfora/blob/v1.0.1/README.ru.md) diff --git a/docs/releases/v1.0.1.ru.md b/docs/releases/v1.0.1.ru.md new file mode 100644 index 0000000..97e1163 --- /dev/null +++ b/docs/releases/v1.0.1.ru.md @@ -0,0 +1,25 @@ +# Perfora 1.0.1 + +[English](v1.0.1.md) + +Исправлен пересчёт Feature Cut при уменьшении исходной грани с включённым **Trim to Boundary** и ненулевым **Edge Offset**. + +[Скачать Perfora-1.0.1.zip](https://github.com/4FusionLab/Perfora/releases/download/v1.0.1/Perfora-1.0.1.zip) · [SHA-256](https://github.com/4FusionLab/Perfora/releases/download/v1.0.1/Perfora-1.0.1.zip.sha256) · [Английское руководство](https://github.com/4FusionLab/Perfora/blob/v1.0.1/README.md) · [Русская инструкция](https://github.com/4FusionLab/Perfora/blob/v1.0.1/README.ru.md) + +## Исправления + +- Изменение высоты коробки с 70 до 20 мм могло сделать целевое тело Combine внутри Perfora Feature недействительным. Родительский узел при этом мог оставаться в состоянии Healthy, хотя тело не содержало геометрии. +- Edge Offset теперь использует точные смещения временных BRep-контуров. Пересчёт больше не редактирует вспомогательный эскиз на грани и сохраняет цель булевой операции. +- Нативная регрессионная проверка Fusion охватывает повторные изменения 70 → 20 → 70 → 20 мм, состояние вложенного Combine и видимое твёрдое тело. Проверяются скруглённые и нескруглённые ячейки Voronoi, включённая и выключенная обрезка, Circle и штатные Extrude/Cut. + +## Установка и обновление + +Распакуйте ZIP в постоянную папку. В Fusion остановите существующий аддон Perfora, затем подключите внутреннюю папку **Perfora** через **Utilities → Scripts and Add-Ins**. Одновременно запускайте только одну копию. UUID манифеста, ID команды и атрибуты документа не изменились. + +## Проверка + +Ранее в этом сеансе разработки на **Fusion 2706.1.14 / macOS** прошли **67 тестов Python**, **150 нативных CAD-сценариев** и набор проверок производительности предпросмотра. При подготовке данного выпуска локальные тесты и проверки Fusion повторно не запускались. Перед публикацией GitHub Actions проверяет Python и упаковку на Linux, macOS и Windows. Приёмка нативного CAD на Windows не заявляется. + +## По-русски + +Исправлена потеря целевого тела у **Feature Cut** при уменьшении исходной грани с **Trim to Boundary** и ненулевым **Edge Offset**. Например, высоту коробки теперь можно менять с 70 до 20 мм и обратно с пересчётом перфорации. Исправление проверено на обычных и скруглённых отверстиях Вороного; новых функций в этом выпуске нет. diff --git a/docs/releases/v1.1.0.md b/docs/releases/v1.1.0.md index 1996295..3ee7956 100644 --- a/docs/releases/v1.1.0.md +++ b/docs/releases/v1.1.0.md @@ -1,5 +1,7 @@ # Perfora 1.1.0 +[Русская версия](v1.1.0.ru.md) + Noise fields, more distributions, curved faces and reliable parametric rebuilding. [Download Perfora-1.1.0.zip](https://github.com/4FusionLab/Perfora/releases/download/v1.1.0/Perfora-1.1.0.zip) · [SHA-256](https://github.com/4FusionLab/Perfora/releases/download/v1.1.0/Perfora-1.1.0.zip.sha256) · [English guide](https://github.com/4FusionLab/Perfora/blob/v1.1.0/README.md) · [Русская инструкция](https://github.com/4FusionLab/Perfora/blob/v1.1.0/README.ru.md) diff --git a/docs/releases/v1.1.0.ru.md b/docs/releases/v1.1.0.ru.md new file mode 100644 index 0000000..cb80ff9 --- /dev/null +++ b/docs/releases/v1.1.0.ru.md @@ -0,0 +1,56 @@ +# Perfora 1.1.0 + +[English](v1.1.0.md) + +Шумовые поля, больше способов распределения, криволинейные грани и надёжное параметрическое перестроение. + +[Скачать Perfora-1.1.0.zip](https://github.com/4FusionLab/Perfora/releases/download/v1.1.0/Perfora-1.1.0.zip) · [SHA-256](https://github.com/4FusionLab/Perfora/releases/download/v1.1.0/Perfora-1.1.0.zip.sha256) · [Английское руководство](https://github.com/4FusionLab/Perfora/blob/v1.1.0/README.md) · [Русская инструкция](https://github.com/4FusionLab/Perfora/blob/v1.1.0/README.ru.md) + +## Noise и Pattern + +- **Pattern** содержит 12 повторяемых форм отверстий. **Noise** содержит Smooth Noise, Reaction Diffusion, Directional Fibers, Ridged Noise / Topographic, Gyroid Field, Blue Noise / Size Gradient и Voronoi последним пунктом. +- **Cell Size**, **Web Thickness**, **Edge Offset** и **Seed / New Pattern** определяют шум. Blue Noise использует Maximum Diameter; настройки полей предоставляют необязательные Add Bridges, вариацию размера и градиент, где это применимо. Процент заполнения скрыт; существующие Features сохраняют заданные пороги. +- Новые шумовые команды начинают с ячеек 8 мм и перемычки 0,8 мм. Для Fast Preview по умолчанию используется **Magenta**. Большие поля адаптируют дискретизацию в пределах фиксированного бюджета, сохраняя физический размер ячейки и безопасные частичные отверстия у границ. + +![Smooth Noise после Edit Feature в реальном Fusion](https://raw.githubusercontent.com/4FusionLab/Perfora/v1.1.0/docs/assets/examples/v1.1.0/smooth-noise-feature.png) + +Реальная операция Feature в Fusion после изменения Cell Size на 5,5 мм при перемычке 1,5 мм. Изображение сделано во время предшествующей CAD-приёмки и повторно использовано для этого выпуска. + +## Размещение, поверхности и несколько областей + +- **11 семейств Distribution:** Staggered, Rectangular, Circular, Along Path, Contour, Fan, Phyllotaxis, Poisson Disk, Wave, Chevron и Between Curves. Новые команды используют обновлённое общее ядро, включая ориентацию Follow Pattern и частичные варианты на границах. Сохранённые Features сохраняют версию алгоритма; старый Running Bond можно редактировать. +- Цилиндрические, конические и регулярные гладкие грани произвольной формы твёрдых тел используют те же сценарии Sketch, Extrude и Feature. Доступность Distribution зависит от типа источника. +- Можно выбрать до **32 областей одного типа поверхности** в одном компоненте с общими настройками и единым ограничением Maximum Holes. Плоские грани и плоские профили эскиза можно сочетать. +- Входящая в пакет **Pattern playground** запускает те же исходники Python для геометрии в браузере. Она включает все 19 форм, 11 семейств Distribution и связи параметров. О локальном запуске см. входящий в пакет `demo/README.md`; развёртывание размещённого демо в этот выпуск не входит. +- Концы строк исходников закреплены как LF, а сборщик демо явно читает UTF-8, что сохраняет согласованность хешей встроенного ядра, подписей и поставляемых исходников также в Windows. + +## Пересчёт и редактирование Feature + +Ссылки на объекты теперь привязываются к исходной геометрии до того, как её могут поглотить булевы операции. Это не позволяет Custom Feature зависеть от собственного результата. Edit Feature восстанавливает нужные тела и выделения, а после завершения команды восстанавливается таймлайн, поэтому Cancel сохраняет прежнюю модель и состояние узла. + +Для существующего проблемного Feature откройте **Edit Feature** и один раз нажмите **OK**, чтобы обновить ссылки Object. Существующие Features остаются читаемыми. Операции, созданные до новых штатных параметров пути, нужно создать заново для использования Along Path и зависимостей выражений. + +## Установка и обновление + +Распакуйте ZIP в постоянную папку. В Fusion остановите существующий аддон Perfora, затем выберите внутреннюю папку **Perfora** через **Utilities → Scripts and Add-Ins → Add-Ins → +** и запустите её. Одновременно используйте одну копию. Установщик необязателен и сохраняет резервную копию предыдущей установки. UUID манифеста, ID команды, пространство имён атрибутов документа и лицензия GPL-3.0-only этого выпуска не изменились. + +## Зафиксированные проверки и ограничения + +До подготовки релиза прошли **200 тестов Python** и **36 сценариев браузера**. Нативная приёмка выполнялась на **Fusion 2706.1.14 / macOS 27.0.1 (Apple Silicon)** и включала: + +- Создание Feature и пересчёт Cell Size для всех шести шумовых полей и Voronoi на копиях выбранной грани реальной модели Box. +- Реальные Fast/Full Preview, Edit Feature OK/Cancel, Undo/Redo создания и редактирования и восстановление старого откатанного узла. +- Cut, Join, Intersect и New Body для нескольких областей; изменение толщины исходного тела. +- Представительные случаи Smooth Noise на цилиндре, конусе и поверхности произвольной формы, а также локальный экспорт F3D, повторное открытие и новый пересчёт по параметру. + +При подготовке релиза локальные тесты и проверки Fusion **не повторялись**. Существующий workflow GitHub Actions собирает коммит релиза, выполняет обычную матрицу проверок Python, установки и упаковки на Linux, macOS и Windows и публикует ZIP и контрольную сумму из CI. + +Работа над производительностью включает ограниченную дискретизацию и общее кеширование; новый коэффициент ускорения CAD не заявляется. Существующие сценарии измерений различают генерацию раскладки на чистом Python, чтение исходников, предпросмотр и нативное построение. Регрессионная проверка шума на реальной грани использует ячейки 5 мм, перемычку 1,5 мм и отступ от края 3 мм до изменения Cell Size. + +Приёмка нативного CAD в Windows и облачного сохранения не заявляется. Custom Feature использует Preview API Autodesk и требует работающего Perfora. Feature поддерживает Distance с нулевым уклоном; для дополнительных вариантов протяжённости и New Component используйте штатный Extrude. Для криволинейных отверстий используются конечные прямые инструменты с консервативным разделением по швам и кривизне. Типы поверхностей смешивать нельзя; сферы, торы и сеточные тела не поддерживаются. Contour использует дискретизированные уровни расстояния, а Between Curves требует две поддерживаемые открытые плоские направляющие. + +## По-русски + +Выпуск добавляет шесть шумов, переносит Voronoi в раздел Noise и разделяет настройки Noise/Pattern. Вместо процента заполнения используются размер ячеек и толщина перемычек; цвет Fast Preview по умолчанию — Magenta. + +Доступны 11 Distribution, криволинейные грани и до 32 областей одного типа. Исправлены пересчёт Feature, восстановление Objects, Edit Feature OK/Cancel и Undo/Redo. Для старого проблемного узла достаточно один раз открыть **Edit Feature → OK**. ZIP собирается и публикуется существующим CI; локальные и CAD-проверки при подготовке релиза повторно не запускаются. From be5198b6333406097bf88f505bdf53027d1bc558 Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 15:53:17 +0300 Subject: [PATCH 02/10] docs: translate reference and release guides --- docs/BENCHMARKS.md | 2 ++ docs/BENCHMARKS.ru.md | 54 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+) create mode 100644 docs/BENCHMARKS.ru.md diff --git a/docs/BENCHMARKS.md b/docs/BENCHMARKS.md index 0071757..d047b26 100644 --- a/docs/BENCHMARKS.md +++ b/docs/BENCHMARKS.md @@ -1,5 +1,7 @@ # Perfora 1.0 benchmarks +[Русская версия](BENCHMARKS.ru.md) + Measured on 24 October 2026, macOS arm64, Fusion 2706.1.14 (macOS 27.0.1). These results compare the frozen pre-optimization development snapshot with the optimized geometry shipped in 1.0. Both snapshots already contain Circular, Start Point, Spread Radius, and Tangential placement. **The baseline is not the published 0.2.0 release.** Source fingerprints and raw samples are in [v1.0.0.json](benchmarks/v1.0.0.json). ## Pure Python geometry generation diff --git a/docs/BENCHMARKS.ru.md b/docs/BENCHMARKS.ru.md new file mode 100644 index 0000000..a43505e --- /dev/null +++ b/docs/BENCHMARKS.ru.md @@ -0,0 +1,54 @@ +# Измерения производительности Perfora 1.0 + +[English](BENCHMARKS.md) + +Измерено 24 октября 2026 года на macOS arm64, Fusion 2706.1.14 (macOS 27.0.1). Результаты сравнивают зафиксированный снимок разработки до оптимизации с оптимизированной геометрией, поставленной в 1.0. Оба снимка уже содержат Circular, Start Point, Spread Radius и размещение Tangential. **Базой не является опубликованный релиз 0.2.0.** Отпечатки исходников и исходные измерения находятся в [v1.0.0.json](benchmarks/v1.0.0.json). + +## Генерация геометрии на чистом Python + +Каждое значение — медиана трёх чередующихся измерений до и после со свежими Region и Settings. Подготовка индекса включена. Измеряется `geometry.generate`; рендеринг, создание нативного эскиза, обрезка BRep и Extrude исключены. Каждый образец проверяет совпадение ячеек и координат контуров. Отдельная матрица из 511 случаев не нашла различий в ячейках, координатах и соответствующих ошибках. + +| Сценарий | Отверстий | До, мс | После, мс | Ускорение | +| --- | ---: | ---: | ---: | ---: | +| `tiny_circle` | 1 | 0.041 | 0.036 | 1.14× | +| `tiny_triangle` | 1 | 0.060 | 0.052 | 1.17× | +| `rect_circle` | 709 | 6.330 | 3.409 | 1.86× | +| `rect_hexagon` | 709 | 34.005 | 10.588 | 3.21× | +| `disk_hexagon` | 253 | 1282.353 | 96.812 | 13.25× | +| `disk_ellipse` | 45 | 4027.185 | 263.233 | 15.30× | +| `annulus_circle` | 72 | 107.009 | 13.573 | 7.88× | +| `disk_circular_circle` | 223 | 176.663 | 15.299 | 11.55× | +| `dense_hexagon` | 3831 | 178.721 | 53.161 | 3.36× | +| `voronoi` | 1041 | 269.651 | 125.366 | 2.15× | +| `voronoi_rounded` | 1041 | 270.513 | 128.597 | 2.10× | +| `voronoi_disk` | 45 | 195.792 | 34.023 | 5.75× | +| `bounded_voronoi` | 45 | 33.425 | 16.700 | 2.00× | + +`rect_*` использует область 120 × 250 мм; `disk_hexagon` — диаметр 120 мм; `disk_ellipse` — диаметр 80 мм. Размер отверстия по умолчанию — 5 мм, зазор 1,5 мм, отступ от края 3 мм. Плотный случай шестиугольников использует отверстия 2,6 мм и зазор 0,3 мм. `bounded_voronoi` использует очень большую границу с ограничением зоны 16 мм, чтобы проверить локальную генерацию кандидатов. Определения сценариев можно повторно запустить с помощью [scripts/benchmark_layout.py](../scripts/benchmark_layout.py). + +Результат 15,30× для эллипсов относится только к этому пути генерации Python. Это **не** заявление об ускорении каждой команды или нативной операции с телом в 15 раз. В малых нагрузках есть шум на уровне микросекунд; семь дополнительных чередующихся серий по 1000 полных генераций показали 37,34 → 30,44 мкс для одной окружности и 55,70 → 47,44 мкс для одного треугольника. + +## Нативный Fusion: первый Fast Preview и последующее построение + +Одно парное измерение на сценарий в одном нативном сеансе Fusion. Построение измерялось после Fast Preview: базовая версия создаёт ячейки заново; оптимизированная повторно использует неизменяемые ячейки, но заново читает текущий источник и выполняет нативное построение. Число отверстий, площади профилей и координаты предпросмотра совпали (допуск координат 1e-7 см). + +| Сценарий | Отверстий | Fast до → после, с | Построение до → после, с | +| --- | ---: | ---: | ---: | +| Шестиугольники в круглой границе | 253 | 1.148 → 0.104 | 2.453 → 2.193 | +| Эллипсы в круглой границе | 45 | 3.424 → 0.262 | 3.683 → 0.263 | +| Малая ограниченная касательная раскладка | 7 | 0.058 → 0.054 | 0.105 → 0.107 | + +В последнем случае заметного ускорения построения нет. Создание нативных эскизов и кривых может занимать основное время при узорах из шестиугольников. Результаты зависят от оборудования, сложности границы, версии Fusion, поведения нативного API и кеширования. Время CAD в Windows и нормированные по оборудованию результаты не заявляются. + +## Проверки кеша и цвета + +Нативные регрессионные проверки подтверждают, что Fast → построение повторно использует ячейки, но текущие расстояния Extrude по-прежнему влияют на объём; Holes избегает булевых операций только для Panel; изменения ревизии источника и перемещение плоскостей сбрасывают соответствующие данные. Preview Color меняет только представление. Тест с 709 шестиугольниками проверяет все шесть нативных значений RGB без повторной генерации ячеек; измерение API меньше миллисекунды не включает обновление экрана и не гарантирует задержку взаимодействия. + +## Повторение измерений текущей генерации + +```sh +python3 scripts/benchmark_layout.py --repeat 3 --output /tmp/perfora-benchmark.json +python3 scripts/benchmark_layout.py --baseline /path/to/frozen/geometry.py --repeat 3 +``` + +Исторический базовый вариант имеет отпечаток в исходных данных и намеренно не поставляется как дополнительная реализация. Аргумент базовой версии должен указывать на совместимый снимок с той же схемой Settings и Region. Для нативных измерений требуются Fusion и `tests/fusion_optimization_regression.py` с совместимым `baseline_path`; одни замеры Python не подтверждают поведение CAD. From aea74411d3198d41bea2f4ca75b94bf2347cc209 Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 15:55:31 +0300 Subject: [PATCH 03/10] docs: translate release policy --- .github/RELEASE_POLICY.md | 2 ++ .github/RELEASE_POLICY.ru.md | 29 +++++++++++++++++++++++++++++ 2 files changed, 31 insertions(+) create mode 100644 .github/RELEASE_POLICY.ru.md diff --git a/.github/RELEASE_POLICY.md b/.github/RELEASE_POLICY.md index 59afd05..2a070b7 100644 --- a/.github/RELEASE_POLICY.md +++ b/.github/RELEASE_POLICY.md @@ -1,5 +1,7 @@ # 4FusionLab — automatic runtime release policy +[Русская версия](RELEASE_POLICY.ru.md) + ## Trigger - A direct push to `main` or a PR merge into `main` is the only normal release event. PR checks, manual CI dispatch and version-tag pushes **do not** initiate publication. diff --git a/.github/RELEASE_POLICY.ru.md b/.github/RELEASE_POLICY.ru.md new file mode 100644 index 0000000..676d7da --- /dev/null +++ b/.github/RELEASE_POLICY.ru.md @@ -0,0 +1,29 @@ +# 4FusionLab — политика автоматических релизов исполняемых компонентов + +[English](RELEASE_POLICY.md) + +## Запуск + +- Прямой push в `main` или объединение PR в `main` — единственное обычное событие релиза. Проверки PR, ручной запуск CI и отправка тегов версий **не** запускают публикацию. +- Перед публикацией сравнивайте `GITHUB_SHA` с последним **опубликованным** тегом GitHub Release, являющимся предком `main`. Если ZIP-релизов нет, используйте исходный диапазон push `github.event.before..GITHUB_SHA`. Удалённые и переименованные исполняемые файлы по-прежнему дают право на релиз. +- `.github/release-paths.txt` репозитория остаётся проверенным перечнем путей релиза. Изменения только README, руководств, тестов и CI **сами по себе не создают релиз**. Push только документации может восстановить ранее неудавшийся выпуск, если подходящие изменения после последнего опубликованного тега ещё не выпущены. +- Перед публикацией должны пройти все обязательные существующие проверки CI. При отказе проверки нет релиза, изменяемого тега и замены артефактов. + +## Версия и распространение + +- GitVersion.Tool **6.8.2** определяет числовую версию `MAJOR.MINOR.PATCH` по `GitVersion.yml` и полной истории Git. ZIP пакета, встроенный манифест Fusion (где применимо), автоматически созданный неизменяемый тег `vMAJOR.MINOR.PATCH` и GitHub Release соответствуют одному коммиту и версии. +- Конвейер создаёт тег **автоматически** при публикации GitHub Release. Участники никогда не создают и не отправляют теги релиза вручную. Существующий тег версии, указывающий на другой коммит, считается ошибкой; опубликованный релиз никогда не перезаписывается. +- При наличии используются проверенные заметки конкретной версии; иначе они автоматически создаются из истории Git. Подготовка файла заметок вручную только для выпуска изменения кода не требуется. +- Стабильные релизы становятся Latest. Предварительные выпуски никогда не становятся Latest. Проектные требования к нативной CAD-приёмке, тестам, подписанным архивам и контрольным суммам, совместимости ОС и публикации продолжают действовать. + +## Этот репозиторий + +Перечень исполняемых файлов: `Perfora/**`, `install.py`. Тесты Linux/macOS/Windows, манифест Fusion и SHA-256 ZIP остаются обязательными. Исторические выпуски 0.x остаются экспериментальными. + +Если после последнего опубликованного релиза не изменились подходящие входные исполняемые файлы, CI может запуститься, но публикация пропускается, даже если GitVersion вычислит другую версию. После сбоя следующая отправка в `main` повторяет публикацию после успешного прохождения обычных проверок CI; опубликованные теги и артефакты никогда не перезаписываются. + +## Общие Actions релизов + +Репозиторий использует работающие только на чтение Actions GitVersion, проверки влияния изменений, заметок и ZIP/манифеста/SHA-256 из `4FusionLab/.github`, закреплённые за `ad9d60ba4aabc494b4f2c85d6c566a50ca423751`. Perfora сохраняет собственные обширные CAD/геометрические тесты, установщик, контракт релиза, проверку загрузки черновика и издатель неизменяемых GitHub Releases. Устаревшие локальные копии помощников проверки изменений и создания заметок удалены. + +**Платформа восстановления:** классификатор опубликованных релизов отдельно закреплён за `2e961620a068c3ad754f6e1be05fb6e4ac68e843` с `recover-unpublished: 'true'` и `github.token` только для чтения. Остальные общие Actions сохраняют проверенное закрепление `ad9d60ba4aabc494b4f2c85d6c566a50ca423751`. From 01db78e94dc9e40bb43ece490f9b6793c18462e1 Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 16:00:32 +0300 Subject: [PATCH 04/10] docs: translate remaining guides --- CONTRIBUTING.md | 2 ++ CONTRIBUTING.ru.md | 78 +++++++++++++++++++++++++++++++++++++++++++ docs/PUBLISHING.md | 6 ++-- docs/PUBLISHING.ru.md | 32 ++++++++++++++++++ 4 files changed, 116 insertions(+), 2 deletions(-) create mode 100644 CONTRIBUTING.ru.md create mode 100644 docs/PUBLISHING.ru.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e2ad527..c652e18 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,7 @@ # Contributing to Perfora +[Русская версия](CONTRIBUTING.ru.md) + Keep geometry independent of Fusion. `Perfora/geometry.py` contains layout and clearance logic; `model.py` and `clipping.py` adapt it to Fusion; `preview.py` renders previews; `Perfora.py` owns the command and dialog. Curved sources use `surface_geometry.py` for dependency-free placement/finite-tool separation and `surface.py` for a shared temporary preparation consumed by preview, fixed output and Feature. Renderer-owned native sheets never enter a final-build cache. `cylindrical.py` retains the legacy fixed-cylinder adapter for older API callers. diff --git a/CONTRIBUTING.ru.md b/CONTRIBUTING.ru.md new file mode 100644 index 0000000..0d47442 --- /dev/null +++ b/CONTRIBUTING.ru.md @@ -0,0 +1,78 @@ +# Участие в разработке Perfora + +[English](CONTRIBUTING.md) + +Сохраняйте независимость геометрии от Fusion. `Perfora/geometry.py` содержит логику раскладки и зазоров; `model.py` и `clipping.py` адаптируют её к Fusion; `preview.py` рисует предпросмотры; `Perfora.py` отвечает за команду и диалог. + +Для криволинейных источников `surface_geometry.py` отвечает за независимое от внешних библиотек размещение и разделение конечных инструментов, а `surface.py` — за общую временную подготовку, используемую предпросмотром, фиксированным результатом и Feature. Нативные поверхности, принадлежащие рендереру, никогда не попадают в кеш окончательного построения. `cylindrical.py` сохраняет старый адаптер фиксированного цилиндра для прежних пользователей API. + +Выполните `python3 -m unittest discover -s tests -v` и `python3 install.py --zip`. В Fusion выполните `fusion_surface_regression.py`: все 13 форм, включённая и выключенная Trim, цилиндр/конус/поверхность произвольной формы, точные образцы кромки, 3D Sketch на перемещённой оси, существующие отверстия, круговое размещение/угол/смещение/зона, операции, ограниченные зоны, внутренние и наружные стенки и плотный кешируемый предпросмотр. `fusion_surface_feature_regression.py` использует реально загруженный аддон для проверки изменения числа отверстий, естественных зависимостей параметра/радиуса/высоты, локального повторного открытия F3D и последующего изменения зоны. Зависимости источника, операции и цели должны оставаться ацикличными. + +Выполните `fusion_surface_ui.py` из консоли Python Fusion с `mode='fast'` и `'full'`. После реального OK/Cancel вызовите возвращённую `finish(True/False)`; `stage='ready'` не означает приёмку транзакции. Проверьте общие плоские и криволинейные элементы, Seed/New Pattern, реальные Edit Feature OK/Cancel, Undo/Redo и изменение Distance во время Full Preview перед отменой. Команда проверяет данные по исходной захваченной карте поверхности во время предварительных вырезов. Изменение источника сбрасывает эту карту. Убедитесь, что геометрия исходного документа не изменена. Старая геометрия только для цилиндра проверяется отдельно в `fusion_cylindrical_regression.py`; её прежнюю UI-приёмку заменяет `fusion_surface_ui.py`. + +Выполните `tests/fusion_height_regression.py` с работающим проверяемым аддоном для изменения размера исходной грани: оболочка 2 мм с боковой перфорацией и изменение `h` 70 → 20 → 70 → 20 мм. Охватите скруглённый и нескруглённый Voronoi, Trim to Boundary в обоих состояниях, ненулевой Edge Offset, Circle и штатный Extrude/Cut. Проверьте каждую принадлежащую операцию (особенно Combine), корректность видимого тела, объём твёрдого тела и высоту, естественный пересчёт и `computeAll`; одного состояния Healthy Custom Feature недостаточно для подтверждения корректности результата. + +Изменения CAD также требуют реальной проверки Fusion. Установите аддон и запустите `PerforaSmokeTest` из Scripts and Add-Ins. Из консоли Python Fusion используйте абсолютный путь к рабочему каталогу или извлечённому ZIP: + +```python +import runpy +runpy.run_path('/absolute/path/to/Perfora/tests/fusion_shapes_regression.py') +``` + +Другие сценарии: `fusion_clipping_regression.py`, `fusion_preview_performance.py`, `fusion_voronoi_regression.py`, `fusion_dialog_regression.py` и `fusion_ui_contract.py`. Набор Voronoi проверяет точные контуры предпросмотра и эскиза, сброс кеша, перемещённую и повёрнутую плоскость, кольцевую область, вогнутую границу, площади и объёмы скруглённых отверстий, поглощение мелких фасок, касательные углы после обрезки и все пять операций со скруглением. Для проверок диалога аддон должен работать. Выполняйте `fusion_feature_regression.py` с зарегистрированным аддоном из того же рабочего каталога: определения Custom Feature требуют UUID его манифеста и не могут быть проверены импортом отдельного тестового пакета. Изучайте каждый сценарий перед запуском. CAD-сценарии создают отдельный несохранённый документ; отчёты сохраняются вне репозитория. + +Перед релизом проверьте запуск команды, все 13 форм, включая Voronoi, быстрый и полный предпросмотр, обрезку границ, Cancel без остаточной геометрии, Cut, Undo/Redo, сохранение и повторное открытие документа, а также редактирование штатного Extrude. Для Voronoi проверьте Seed/New Pattern, Irregularity 0% и 100%, минимальную перемычку, Round Corners в обоих состояниях, изменение радиуса и сброс кеша после изменения настройки. Для Feature проверьте изменения параметров и исходной границы, разное число отверстий, выражения пользовательских параметров, Edit Feature OK/Cancel, откат Full Preview, Undo/Redo и повторное открытие нативного архива с последующим пересчётом. Источник, операция и целевые тела фиксированы при редактировании; начальный режим поддерживает прямую протяжённость Distance и Join/Cut/Intersect/New Body. Запишите версию Fusion, ОС и фактические результаты; одни тесты геометрии не подтверждают корректность CAD. + +Регрессионный тест Feature также строит и пересчитывает все 13 форм, проверяет границы смещения и направления и отклоняет неподдерживаемую протяжённость, уклон и New Component. Для проверки установленной копии передайте её зарегистрированную папку через `init_globals={'addon_path': '/absolute/API/AddIns/Perfora'}`. Запустите новый сеанс Fusion и загрузите только эту копию: переключение связанных копий с одинаковым UUID манифеста в одном сеансе может сохранить регистрацию первого владельца Custom Feature и сообщить, что его расширение не работает. Повторная загрузка с того же пути и чистый запуск проверяются отдельно. + +Для UI-приёмки запускайте `fusion_ui_contract.py` с `init_globals={'result_mode': 'profiles'}` для Sketch, `'extrude'` для Extrude или `'feature'` для Feature. Добавьте `'registered_command': True`, чтобы проверить установленную команду `DiegoV_Perforator`. После нажатия реальной кнопки OK или Cancel вызовите `finish(True)` или `finish(False)` в возвращённом пространстве имён; одного отчёта `stage='ready'` недостаточно для подтверждения транзакции. Сохраняйте каждый отчёт до запуска следующего сценария. + +Сохраняйте ID команды, UUID аддона и пространство имён атрибутов документа стабильными, пока не реализована осознанная миграция. Используйте Conventional Commits, например `fix: preserve clearance around inner boundaries`. + +Для Distribution Circular также запустите `fusion_circular_regression.py`: все 12 повторяемых форм, размещение колец и совпадение контуров, сброс кеша, перемещённая/повёрнутая плоскость, обрезка кольцевой области с Edge Offset, объём панели и все пять нативных операций. В диалоге проверьте Start Radius, ориентацию Fixed/Radial и Tangential, выбор и очистку Start Point, смещения относительно выбранной точки, переключение на Voronoi и обратно, Fast/Full Preview, OK и Cancel без остаточной геометрии. Для некруглых колец используются консервативные ограничивающие контуры; Start Radius измеряется до центров отверстий и не гарантирует сплошную ступицу. + +Числовые поля используют штатные StringValueCommandInputs со скрытыми ValueCommandInputs, потому что ValueCommandInput скрывает пустой ввод последним корректным выражением. `fusion_ui_contract.py` проверяет восстановление значений по умолчанию всех числовых полей, безразмерные целые числа, явный ноль, неверный непустой текст, единицы и параметры документа. Также очистите видимое поле в интерфейсе и дождитесь возврата значения по умолчанию; затем очистите его и сразу введите замену. Проверьте отмену команды с ожидающим сбросом и убедитесь, что поздний обратный вызов не повлияет на другой документ. + +Для размещения Circular по точке выполните `fusion_center_regression.py`: совпадение предпросмотра и эскиза, замена и очистка привязки, повторное использование кеша, проецирование точек на перемещённую/повёрнутую плоскость, вершины и конструкционные точки, координаты сборки, касательная обрезка/выдавливание и пересчёт зависимости Feature, где поддерживается. В реальном диалоге выберите точку, переключите распределение и форму, проверьте Fast/Full Preview, OK и Cancel; в Edit Feature замените/очистите точку и проверьте подтверждение и отмену. + +Глобальные Start Point и Spread Radius должны работать для Staggered, Rectangular, Circular и Voronoi. Проверьте нулевой/неограниченный радиус, точку вне плоскости Profiles, положительный радиус с Trim to Boundary и Edge Offset и без них, пересчёт Feature по радиусу и ограниченную производительность на большом источнике. Проверка числовых значений по умолчанию следует текущим элементам диалога. + +Для оптимизации выполните `fusion_optimization_regression.py` с зарегистрированным аддоном. Он проверяет общие ячейки с текущими параметрами Extrude, ленивое переключение Panel, повтор после реального изменения цели булевой операции, раздельный сброс источника/внутреннего отступа/зоны, перемещённую исходную плоскость и кеш/пересчёт Feature. Необязательный `baseline_path` указывает на зафиксированный пакет Perfora до изменения для парного нативного сравнения геометрии и времени. Не включайте этот снимок в пакет. При необходимости выполните обычные регрессионные проверки форм, обрезки, Voronoi, кругового размещения, начала координат, предпросмотра, диалога и Feature; завершите реальными Full Preview, OK и Cancel. + +Между Fast Preview и финальным построением через `GeometryCache` передаются только неизменяемые двумерные ячейки. Нативные тела обрезки принадлежат рендереру; финальный CAD заново читает источник и выполняет собственную точную обрезку. Не кешируйте выходные тела, конфигурацию выдавливания и откатанные исходные эскизы. Кеш одного источника хранит одну успешную запись и очищается вместе с командой. + +Для нескольких областей добавлено до 32 локальных слотов кеша команды, каждый хранит одну успешную неизменяемую 2D-раскладку. При неизменных ревизиях источника и отступе можно повторно использовать принадлежащие рендереру исходные поверхности и внутренние контуры. Финальный CAD никогда не использует эти нативные поверхности повторно. Автономный `test_multi_region.py` проверяет правила систем координат/фазы, совместимость схемы 1, сопоставление, сброс кеша и очистку/восстановление с внедрёнными ошибками на инертных имитациях API; это не подтверждает корректность нативного ядра или транзакции команды. После явного разрешения использовать Fusion выполните `fusion_multi_region_regression.py` из этого точного зарегистрированного рабочего каталога, затем `fusion_multi_region_ui.py` для Sketch/Extrude/Feature с реальными OK и Cancel. Следуйте [полному списку приёмки нескольких областей](docs/MULTI_REGION.md), включая Edit Feature, общие цели Cut, сопоставленный Intersect, Undo/Redo, локальное сохранение и повторное открытие F3D и существующие проверки одного источника. Эти сценарии подготовлены автономно и не запускались в Fusion. + +Для профилей эскиза непосредственно на гранях твёрдых тел запустите `fusion_profile_face_regression.py`: горизонтальная/вертикальная опора, внутренние петли, Trim to Boundary в обоих состояниях, совпадение Fast Preview/профиля/Cut, восстановление таймлайна и пересчёт Feature после редактирования диаметра источника и размера отверстия. Выполните `fusion_ui_contract.py` с `source_profile=True` и `registered_command=True` для автоматического выбора Objects, Full Preview и реальных OK и Cancel без остаточной геометрии. + +Стабильная приёмка: выполните `fusion_release_acceptance.py` из консоли Python Fusion с `result_mode='feature'`, затем повторите с `'extrude'`. Используйте зарегистрированный аддон из этого рабочего каталога или передайте `addon_path`. После реального OK вызовите `verify_created()`, выполните штатный Undo и вызовите `verify_undo()`, выполните штатный Redo и вызовите `finish()`. Финальная проверка изменяет параметр модели, экспортирует и повторно открывает локальный F3D, снова выполняет пересчёт и восстанавливает исходный документ. Повторное открытие локального архива отличается от облачного сохранения и открытия. + +Выполните `scripts/benchmark_layout.py --repeat 3` для воспроизведения текущих геометрических сценариев. Исторические измерения до/после, методика, отпечатки базовой версии и оговорки находятся в [docs/BENCHMARKS.ru.md](docs/BENCHMARKS.ru.md). Скриншоты продукта создаются в реальном Fusion с помощью `scripts/capture_release_examples.py`; проверяйте каждое экспортированное изображение до публикации. + +Для импортированных/обрезанных криволинейных граней используйте evaluator грани и для границ UV, и для вычислений: отдельная аналитическая геометрия может иметь другое угловое начало. `fusion_surface_face_regression.py` копирует выбранное тело из открытой модели во временный документ, исключает грани, уже покрытые многими отверстиями, проверяет более десяти отверстий на каждой регулярной большой грани, принадлежность к предпросмотру и необязательное совпадение нативного Cut/кромок (`build=True`), а также неизменность исходной ревизии и таймлайна. Отчёты остаются вне репозитория. Регрессия включает проверку различий конических Rectangular/Staggered. Команда скрывает Circular и Pattern Angle на криволинейных источниках и глобально удаляет Spread Radius; сохранённые старые параметры Feature сохраняют совместимость пересчёта. + +`fusion_surface_spacing_regression.py` проверяет физическую длину рядов на больших гранях NURBS в открытой модели, не изменяя её. Независимые плотные полилинейные измерения должны различаться менее чем на 0,2% при равных приращениях координаты ряда. Чистые тесты `LengthMap` включают сильно неравномерные скорости параметризации и проверку обратного преобразования/экстраполяции. Конические ряды должны сохранять общие фазы образующих, помимо различия Rectangular и Staggered. `fusion_surface_ui.py` с `kind='selected'`, `source_body_name` и `source_face_id` копирует реальную конечную грань во временную модель и проверяет точную инициализацию углового диапазона, включая предварительный выбор. Никогда не округляйте конечный диапазон через `formatInternalValue` перед проверкой. + +`fusion_layout_ui.py` проверяет описанный квадрат 50×50 мм (отверстия 5 мм, перемычка 1,5 мм, отступ 3 мм) и заострённый конус с основанием 50 мм и высотой 90 мм во временном документе. Запустите из нативной консоли Python с `kind="plane"` или `kind="cone"`, вызовите `check_preview()`, используйте реальные кнопки OK/Cancel, затем вызовите `finish(created)`. Квадрат должен сохранять центральную симметрию и шесть позиций на первом кольце; плотность конуса должна адаптироваться к каждому ряду, а не наследовать минимальную окружность. `fusion_surface_regression.py` также проверяет плотность заострённого конуса, нативный Cut, совпадение числа объектов предпросмотра и результата и пересчёт конической Feature. + +Для грани NURBS со схлопнутой параметрической границей `fusion_surface_face_regression.py` принимает `chart_only=True` для воспроизведения конструктора, затем `hole_limit=5000, build=True` для полного размещения и нативного Cut. Проверьте регулярную внутреннюю область, исключение локальных оболочек полюса, совпадение предпросмотра и кромок и неизменность исходной ревизии/таймлайна. Сферы и торы остаются исключёнными. + +Для невыпущенных вариантов раскладки см. [LAYOUT_VARIANTS.md](docs/LAYOUT_VARIANTS.md). Автономно выполните `test_layout_variants.py` и `test_layout_contracts.py`; `scripts/benchmark_layout_variants.py` записывает время чистой геометрии. Нативные CAD-проверки — в `fusion_layout_variants_regression.py`. До `finish` выполните `fusion_ui_contract.py` с `layout_variant='contour'/'fan'/'phyllotaxis'/'poisson'/'wave'/'chevron'/'running_bond'/'between_curves'`, каждым режимом результата и реальными OK/Cancel. Нативные Edit Feature OK/Cancel, повторное открытие старого архива, пересчёт зависимостей направляющих, Undo/Redo и точная обрезка остаются обязательными условиями. Не выводите CAD-приёмку из автономных имитаций. + +Along Path доступен только в разработке; нативная приёмка зафиксирована в отчёте интеграции. Автономные контракты находятся в `test_curve_layout.py` и `test_curve_integration.py` (последний использует имитации API и не является CAD-приёмкой). Нативные проверки: `fusion_curve_regression.py` и `fusion_ui_contract.py` с `distribution='path'`, `registered_command=True` и каждым режимом результата, затем реальные OK/Cancel и `finish`. Полная ожидающая матрица, числовые пороги, ссылки на API, ограничения совместимости Feature и неразрешённые CAD-предположения приведены в [CURVE_LAYOUT.md](docs/CURVE_LAYOUT.md). Не запускайте эти сценарии, пока общий сеанс Fusion явно не доступен. В объединённом диалоге сейчас 58 числовых полей. + +## Объединённая ветка релиза + +Используйте `tests/fusion_release_integration.py` для матрицы поверхностей и распределений, отклонения смешанных источников, Cut нескольких поверхностей и пересчёта Feature цилиндра/конуса/произвольной поверхности по параметрам. Каждый случай использует временный документ. `tests/fusion_integration_archive.py` экспортирует временный локальный F3D с несколькими цилиндрическими областями и Along Path, повторно открывает его и снова изменяет их параметры. Это не подтверждает облачное сохранение или поведение CAD в Windows. + +Перезагружайте через штатный жизненный цикл stop/run зарегистрированного скрипта. Выполнение модуля входа из другого сценария может зарегистрировать Custom Feature под неверным владельцем и оставить исправный на вид узел без работающего пересчёта. Проверяйте фактическое изменение объёма, а не только состояние. При проверке изменений исходного эскиза откатите таймлайн до Feature, измените эскиз, затем верните маркер в конец, как при обычном Edit Sketch в Fusion. + +`fusion_layout_variants_regression.py` принимает подмножества `layouts` и `shapes` для ограниченных запусков. Сохраняйте полный отчёт до того, как следующий запуск его перезапишет. Для нативной UI-приёмки сохраняйте отдельные отчёты для реальных OK и Cancel; стадия `ready` не является приёмкой. + +`fusion_release_selection.py` проверяет нативный предварительный выбор: пара цилиндр/конус сохраняет один совместимый источник с уведомлением, а два цилиндра сохраняются оба. До `finish()` нажмите настоящий Cancel. `fusion_release_ui.py` принимает тип поверхности, число областей, раскладку и режим результата; после открытия через MCP используйте `prepare()` из нативной консоли Python, затем `preview()`, реальные OK/Cancel и `finish()`. Выполненная матрица описана в отчёте интеграции. + +## Органические поля (разработка) + +См. [ORGANIC_PATTERNS.md](docs/ORGANIC_PATTERNS.md). Запустите полный автономный набор, включая `test_organic.py`, `test_solid_topology.py` и реальные контракты методов диалога. В Fusion выполните `fusion_organic_regression.py` для зарегистрированного рабочего каталога с необязательными подмножествами `kinds`, `shapes`, `modes` и `trims`. `archive=True` проверяет локальный импорт F3D/пересчёт; `capture=True` экспортирует реальные изображения окна просмотра. Отчёты храните вне репозитория. Активный документ никогда не используется как тестовая заготовка: каждый случай создаёт временный документ и восстанавливает исходный. + +Для каждой формы и затронутого режима результата используйте `fusion_organic_ui.py` из нативной консоли Python. Вызовите `prepare()`, запросите Fast/Full через `preview()`, затем `check_preview()`. Нажмите настоящую кнопку OK/Cancel и вызовите `verify(created)`. Для Feature выполните `begin_edit()`, затем `edit_preview()`, нажмите настоящую OK/Cancel и вызовите `end_edit(accepted)`. После нативных Undo/Redo обязательно вызовите `verify_undo()` / `verify(True)`. `finish()` восстанавливает исходный документ пользователя. Стадия ready или успешная геометрия Python сами по себе не являются приёмкой нативной транзакции. Выполните `fusion_organic_boundaries.py` для связности с нулевым отступом при существующем внутреннем вырезе; также повторно проверьте разделение шва/глубины, несколько однородных областей и текущую упаковку. diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md index c35d34c..3e599f2 100644 --- a/docs/PUBLISHING.md +++ b/docs/PUBLISHING.md @@ -1,5 +1,7 @@ # Releasing Perfora +[Русская версия](PUBLISHING.ru.md) + Releases are built by [Check and release](https://github.com/4FusionLab/Perfora/actions/workflows/ci.yml). ## Prepare a version @@ -19,9 +21,9 @@ The maintainer chooses the release channel. Validation records describe the plat ## Automated publication -Pushes to `main` run compile, geometry, installation, and packaging checks on Linux, macOS, and Windows. Release publication is skipped if nonempty, reviewed `docs/releases/vX.Y.Z.md` notes are missing for the GitVersion-calculated version. Pull requests run the same checks without release permissions. +Pushes to `main` run compile, geometry, installation, and packaging checks on Linux, macOS, and Windows. Publication requires eligible runtime changes since the last published release (or the original push range if no ZIP release exists). A documentation-only push may retry an earlier missed runtime release; it does not create a release on its own. Pull requests run the same checks without release permissions. -The version job derives `MajorMinorPatch` using GitVersion once. All three OS jobs build versioned ZIPs with this identity, and the release job consumes the same identity after successful checks. Publication proceeds only if matching release notes exist. The generated ZIP and embedded Fusion manifest use this numeric version. `scripts/release.py` derives the channel from the numeric version (legacy 0.x experimental), uploads ZIP and SHA-256, downloads both to verify their bytes, then publishes with the correct prerelease/Latest flags. Only that job has `contents: write`; it uses the built-in GitHub Actions token. No personal token is stored in the project. +The version job derives `MajorMinorPatch` using GitVersion once. All three OS jobs build versioned ZIPs with this identity, and the release job consumes the same identity after successful checks. Reviewed version-specific release notes are used when present; otherwise the shared action generates notes from Git history. The generated ZIP and embedded Fusion manifest use this numeric version. `scripts/release.py` derives the channel from the numeric version (legacy 0.x experimental), uploads ZIP and SHA-256, downloads both to verify their bytes, then publishes with the correct prerelease/Latest flags. Only that job has `contents: write`; it uses the built-in GitHub Actions token. No personal token is stored in the project. An existing published version is immutable. Retrying a failed upload is allowed only for a draft belonging to the same exact commit. A draft targeting another commit stops publication for inspection. Before creating a release, the job also refuses to reuse a Git tag already pointing to a different commit. Never move a published tag or replace its assets to repair a code defect; publish a new patch version. diff --git a/docs/PUBLISHING.ru.md b/docs/PUBLISHING.ru.md new file mode 100644 index 0000000..65393b0 --- /dev/null +++ b/docs/PUBLISHING.ru.md @@ -0,0 +1,32 @@ +# Выпуск Perfora + +[English](PUBLISHING.md) + +Релизы собираются workflow [Check and release](https://github.com/4FusionLab/Perfora/actions/workflows/ci.yml). + +## Подготовка версии + +1. Определите следующую числовую версию `MAJOR.MINOR.PATCH` с помощью GitVersion 6.8.2 (`dotnet-gitversion /showvariable MajorMinorPatch`). Манифест Fusion в репозитории не переписывается: при упаковке релиза эта версия записывается в манифест внутри ZIP. +2. Обновите `CHANGELOG.md`, оба README и `docs/releases/vVERSION.md`. Укажите установку, фактические проверки, методику измерения производительности и существенные ограничения. +3. Выполните модульные тесты, проверку компиляции и `python3 install.py --zip --version X.Y.Z`. Проверьте соответствие манифеста в архиве, имени ZIP и контрольной суммы GitVersion; также проверьте две установки во временный `--api-root`, включая резервные копии. +4. Выполните необходимые CAD-проверки в отдельных несохранённых документах Fusion. Заполните матрицу приёмки из `CONTRIBUTING.md`, включая реальные OK/Cancel, Undo/Redo, редактирование штатного Extrude, пересчёт и редактирование Feature и локальное повторное открытие F3D. Запишите версии Fusion и ОС и различайте нативный CAD и CI Python. Никогда не заявляйте невыполненную CAD-приёмку Windows или проверку облачного сохранения. +5. Снимите изображения продукта в реальном Fusion с тем же нейтральным фоном, кадрированием и палитрой, что в существующей галерее. Проверьте реальную геометрию; не иллюстрируйте недоступные возможности. +6. Проверьте финальные изменения на наличие частных файлов, учётных данных, локальных путей, отчётов, кешей, резервных копий и ресурсов Autodesk, затем отправьте проверенный коммит в `main`. + +## Каналы релизов + +Серия 0.x остаётся экспериментальной и публикуется как предварительные выпуски. Версия 1.0.0 — первый стабильный выпуск. Версии с MAJOR >= 1 являются обычными GitHub Releases (`prerelease=false`) и явно помечаются Latest. Канал релиза аддона не меняет жизненный цикл используемых API Autodesk: Custom Feature API остаётся Autodesk Preview API. + +Сопровождающий выбирает канал релиза. Записи о проверках описывают фактически проверенные платформы; CI Windows не подтверждает нативную CAD-работу Fusion. Невыполненные проверки отдельных платформ остаются документированными, в том числе для стабильных версий. + +## Автоматическая публикация + +Push в `main` запускает проверки компиляции, геометрии, установки и упаковки на Linux, macOS и Windows. Для публикации нужны подходящие изменения поставляемых файлов после последнего опубликованного релиза (или исходный диапазон push, если ZIP-релиза ещё нет). Push только документации может повторить ранее пропущенный выпуск с изменениями продукта, но сам по себе релиз не создаёт. Pull requests выполняют те же проверки без прав публикации. + +Задание версии один раз определяет `MajorMinorPatch` через GitVersion. Все три задания ОС собирают ZIP с этой версией, а задание релиза использует её после успешных проверок. При наличии используются проверенные заметки конкретной версии; иначе общий Action создаёт заметки из истории Git. Созданный ZIP и встроенный манифест Fusion используют эту числовую версию. `scripts/release.py` определяет канал по числовой версии (старые 0.x — экспериментальные), загружает ZIP и SHA-256, скачивает оба для проверки байтов и публикует с нужными признаками prerelease/Latest. Только это задание имеет `contents: write`; оно использует встроенный токен GitHub Actions. Личный токен в проекте не хранится. + +Существующая опубликованная версия неизменяема. Повтор неудачной загрузки допустим только для черновика того же точного коммита. Черновик для другого коммита останавливает публикацию для проверки. Перед созданием релиза задание также отказывается повторно использовать тег Git, уже указывающий на другой коммит. Никогда не перемещайте опубликованный тег и не заменяйте его файлы для исправления дефекта; публикуйте новую версию патча. + +## Проверка публикации + +Проверьте задания всех трёх ОС и задание релиза. Сверьте тег релиза, целевой коммит, состояние черновика, канал и ссылку Latest. Скачайте `Perfora-VERSION.zip` и `.sha256`, сравните их байты с проверенным дистрибутивом, изучите манифест и содержимое и дважды установите пакет во временный API root для проверки резервных копий. Убедитесь, что оба README, заметки к релизу и все связанные скриншоты отображаются на GitHub. From 7e0eaf9cd61a666666f2d998bceea825941d3f3c Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 16:09:45 +0300 Subject: [PATCH 05/10] docs: fix reference guide links --- README.ru.md | 4 ++-- docs/README_REFERENCE.md | 30 +++++++++++++++--------------- docs/README_REFERENCE.ru.md | 30 +++++++++++++++--------------- 3 files changed, 32 insertions(+), 32 deletions(-) diff --git a/README.ru.md b/README.ru.md index 3547359..7c73332 100644 --- a/README.ru.md +++ b/README.ru.md @@ -49,9 +49,9 @@ ## Подробнее -[Подробное руководство](docs/README_REFERENCE.ru.md) · [Геометрия отверстий](docs/PERFORATIONS.md) · [Органические узоры](docs/ORGANIC_PATTERNS.md) · [Что нового в 1.1.0](docs/releases/v1.1.0.md) · [История изменений](CHANGELOG.md) +[Подробное руководство](docs/README_REFERENCE.ru.md) · [Геометрия отверстий](docs/PERFORATIONS.md) · [Органические узоры](docs/ORGANIC_PATTERNS.md) · [Что нового в 1.1.0](docs/releases/v1.1.0.ru.md) · [История изменений](CHANGELOG.ru.md) -[Участие в разработке](CONTRIBUTING.md) · [Лицензия](LICENSE) · [Сообщить о проблеме](https://github.com/4FusionLab/Perfora/issues) +[Участие в разработке](CONTRIBUTING.ru.md) · [Лицензия](LICENSE) · [Сообщить о проблеме](https://github.com/4FusionLab/Perfora/issues) **Другие аддоны Fusion 360 от 4FusionLab:** [Selectra — выбор похожей геометрии](https://github.com/4FusionLab/Selectra) · [Ejix — извлечение объёмов](https://github.com/4FusionLab/Ejix) · [RuEn — горячие клавиши при русской раскладке](https://github.com/4FusionLab/RuEn) · [Planara — будущая развёртка поверхностей](https://github.com/4FusionLab/Planara) diff --git a/docs/README_REFERENCE.md b/docs/README_REFERENCE.md index 17c30a9..d0daf73 100644 --- a/docs/README_REFERENCE.md +++ b/docs/README_REFERENCE.md @@ -16,15 +16,15 @@ ## Make the pattern. Keep the native model. -Shared-kernel visual bench: [the offline Distribution test](studies/README.md) renders the 11 Distribution families from the shared geometry kernel. New native commands use revision 2 for the revised families, including partial boundary candidates and Follow Pattern orientation. Existing Features retain their saved revision; legacy Running Bond remains editable. +Shared-kernel visual bench: [the offline Distribution test](../studies/README.md) renders the 11 Distribution families from the shared geometry kernel. New native commands use revision 2 for the revised families, including partial boundary candidates and Follow Pattern orientation. Existing Features retain their saved revision; legacy Running Bond remains editable. -[Pattern playground](demo/README.md) is the browser demo and fast visual test bench. It executes the same Python geometry sources as Fusion, with 11 Distribution families, 19 hole shapes, including six organic fields and shareable parameters. Build with `python3 scripts/build_web_demo.py`; serve the repository and open `/demo/`. It is prepared for static hosting; no deployment is performed by the build. +[Pattern playground](../demo/README.md) is the browser demo and fast visual test bench. It executes the same Python geometry sources as Fusion, with 11 Distribution families, 19 hole shapes, including six organic fields and shareable parameters. Build with `python3 scripts/build_web_demo.py`; serve the repository and open `/demo/`. It is prepared for static hosting; no deployment is performed by the build. Select a planar face, a closed sketch profile, or a construction plane. Choose a hole shape, set the spacing and edge clearance, and preview the result. Perfora creates ordinary sketch profiles, a native Fusion Extrude, or a parametric Perfora timeline feature. To perforate part of an existing face, draw a closed sketch on that face, finish the sketch, and select its shaded profile in **Profiles**. No Split Face is required. For **Cut** or **Intersect**, the supporting body is selected automatically in **Objects**; check the direction and extent before confirming. Profiles on construction planes still require explicit Objects. -**Perfora 1.1.0 adds six noise fields, 11 Distribution families, curved faces and multiple regions, with reliable Feature recompute and editing.** [Release notes →](docs/releases/v1.1.0.md) +**Perfora 1.1.0 adds six noise fields, 11 Distribution families, curved faces and multiple regions, with reliable Feature recompute and editing.** [Release notes →](releases/v1.1.0.md) **Curved faces:** cylindrical, conical and regular smooth freeform solid faces use the common Sketch/Extrude/Feature workflow, including Voronoi and boundary trimming. See the source-specific behavior and limitations below. @@ -82,7 +82,7 @@ To perforate part of an existing face, draw a closed sketch on that face, finish
View the twelve regular hole shapes -![Twelve supported regular hole shapes](docs/assets/hole-shapes.svg) +![Twelve supported regular hole shapes](assets/hole-shapes.svg)
@@ -95,7 +95,7 @@ To perforate part of an existing face, draw a closed sketch on that face, finish | Extent | One Side, Two Sides, Symmetric; distance, through-all, or to-object where supported | | Preview | Cached fast contours for layout; full CAD preview to inspect the extrusion | -See [hole dimensions and geometry notes](docs/PERFORATIONS.md). The interface is in English, using Fusion's native operation names. No third-party Python packages are required. +See [hole dimensions and geometry notes](PERFORATIONS.md). The interface is in English, using Fusion's native operation names. No third-party Python packages are required. Every numeric field has a default. Leaving a field empty restores its default after about a second, while allowing you to clear and immediately type a replacement. Explicit zero values are preserved, and nonempty invalid expressions are not replaced. Units, equations, and parameters from the current Fusion document are supported; integer fields retain their range limits. @@ -123,7 +123,7 @@ The first five use **Cell Size**, **Web Thickness**, **Edge Offset** and **Seed These shapes define their own bounded field; Distribution and Hole Angle are hidden. Pattern Angle rotates the field in sketch axes. On a curved face, 0° follows the circumferential chart axis and 90° follows the axial/meridian axis, including fibers. All six connect to Sketch, Extrude, Feature, Fast/Full Preview, Trim to Boundary and inner-cutout clearance on planar, cylindrical, conical and regular freeform sources. Multiple selections must still have one surface type. Curved openings are finite straight tools, with conservative seam/depth separation; the motif can become sparser at high curvature or a cone tip. -Material islands are joined before contour extraction. Overlong slots receive bridges; conflicting small fragments are omitted to protect the actual contour web. With a zero edge border, boundary fragments that would detach material are retained as solid material. Sampling and contour budgets give actionable errors instead of unbounded CAD work. See [algorithms, controls, surface behavior and validation](docs/ORGANIC_PATTERNS.md). +Material islands are joined before contour extraction. Overlong slots receive bridges; conflicting small fragments are omitted to protect the actual contour web. With a zero edge border, boundary fragments that would detach material are retained as solid material. Sampling and contour budgets give actionable errors instead of unbounded CAD work. See [algorithms, controls, surface behavior and validation](ORGANIC_PATTERNS.md). ## Multiple regions @@ -133,7 +133,7 @@ For several planar regions, the default origin is the component origin projected Repeated references are ignored. Positive-area overlaps are rejected before output is created; adjacent regions stay separate and each retains its own Edge Offset and internal openings. All regions must belong to one component occurrence. Cut/Intersect maps a face or face-backed profile to its supporting body, which must be included in Objects. Profiles without a supporting body require exactly one Object. Intersect requires one region per Object; unused or ambiguous Objects are rejected. Feature Join uses the same explicit mapping; native Extrude Join retains Fusion's automatic touching-body behavior. Multiple-region New Component is rejected; use New Body or a single source. Existing single-source operations remain available. -Feature stores all source dependencies and its Objects mapping; source set, operation, and Objects remain fixed in Edit Feature. Older single-source Features remain readable/editable. Full Preview/OK use fresh source geometry and the same canonical layout as Fast Preview; failures remove all new output, and recompute attempts to restore every changed base body if one update fails. **Current native CAD/UI and local F3D results are recorded in the [integration report](docs/RELEASE_INTEGRATION.md).** [Binding rules and acceptance checklist](docs/MULTI_REGION.md). +Feature stores all source dependencies and its Objects mapping; source set, operation, and Objects remain fixed in Edit Feature. Older single-source Features remain readable/editable. Full Preview/OK use fresh source geometry and the same canonical layout as Fast Preview; failures remove all new output, and recompute attempts to restore every changed base body if one update fails. **Current native CAD/UI and local F3D results are recorded in the [integration report](RELEASE_INTEGRATION.md).** [Binding rules and acceptance checklist](MULTI_REGION.md). ## Parametric Feature @@ -166,26 +166,26 @@ Spread Radius has been removed from the command. New patterns fill the selected ## Eleven Distribution families -**Validated in Fusion on macOS; exact coverage is in the [integration report](docs/RELEASE_INTEGRATION.md).** Eight additions — **Along Path, Contour, Fan, Phyllotaxis, Poisson Disk, Wave, Chevron and Between Curves** — bring the public list to 11 Distribution families for the 12 repeating shapes. Noise fields and Voronoi define their own distribution. Running Bond remains available only when editing legacy Features. +**Validated in Fusion on macOS; exact coverage is in the [integration report](RELEASE_INTEGRATION.md).** Eight additions — **Along Path, Contour, Fan, Phyllotaxis, Poisson Disk, Wave, Chevron and Between Curves** — bring the public list to 11 Distribution families for the 12 repeating shapes. Noise fields and Voronoi define their own distribution. Running Bond remains available only when editing legacy Features. -Native fields, shared Fast/Full Preview and Sketch/Extrude/Feature paths, stored parameters, guide dependencies and Edit Feature are included. Recorded Python and native macOS acceptance is in the [integration report](docs/RELEASE_INTEGRATION.md). +Native fields, shared Fast/Full Preview and Sketch/Extrude/Feature paths, stored parameters, guide dependencies and Edit Feature are included. Recorded Python and native macOS acceptance is in the [integration report](RELEASE_INTEGRATION.md). Along Spacing and Row Spacing use automatic enclosing-hole spacing at 0; smaller requested pitches are raised to the safe minimum. A spatial neighbour index omits candidates that could violate Web Thickness, including rotated shapes, fan centers, contour seams, and chevron vertices. Packing is conservative. Phyllotaxis has Density Ratio; saved Spread Radius parameters remain compatible; Poisson Disk has Seed/New Pattern; Wave uses length-based sampling, amplitude/wavelength/phase/row phase; Running Bond accepts cumulative shifts such as `1 / 3` and `1 / 4`. Contour follows approximate signed-distance levels, with explicit Contour Tolerance and a sampling budget; it is not an exact CAD offset, and sub-resolution details can disappear. Between Curves currently requires two separate open planar curves/edges in the Profiles component, matches normalized arc length and endpoints, and rejects crossed, collapsed, folded, closed, nonplanar, or cross-component guides. Arbitrary complex spline strips and curve chains are not promised. For Contour/Between Curves, Start Point and offsets affect only saved legacy Spread Radius scopes; Pattern Angle is hidden. -New Feature nodes expose the added model parameters. Older nodes keep missing values as stored snapshots when edited; recreate a Feature to obtain new model parameters and their expression dependencies. [Implementation limits, integration seam, and CAD/UI acceptance →](docs/LAYOUT_VARIANTS.md) +New Feature nodes expose the added model parameters. Older nodes keep missing values as stored snapshots when edited; recreate a Feature to obtain new model parameters and their expression dependencies. [Implementation limits, integration seam, and CAD/UI acceptance →](LAYOUT_VARIANTS.md) ## Along Path Perfora 1.1.0 adds **Distribution → Along Path** for all 12 repeating shapes: select one coplanar line, arc, circle or spline in the Profiles component. **Path Spacing** measures arc length; **Start Offset**, **End Offset**, **Position** and **Reverse Path** control placement. **Fixed** or **Tangent** orientation adds **Hole Angle**. Closed paths omit duplicate seam centers. Tight turns, nearby sections and the closing seam are checked against Web Thickness using conservative enclosing bounds; conflicts are reported rather than silently skipping holes. The implementation connects to Fast/Full Preview, existing trimming/inner cutouts/Edge Offset, Sketch, Extrude and Feature. Feature stores a live path dependency and new native path parameters; Edit Feature can replace the path or change distribution. Older nodes remain compatible with existing distributions; recreate them to use Along Path, because existing nodes cannot gain its native parameters. Chains, off-plane/cross-component paths and elliptical paths are unsupported. Start Point, Spread Radius, Pattern Angle and X/Y Offset are inactive in this distribution; Voronoi keeps its own distribution. -Native CAD/UI, recompute/edit, Undo/Redo and local F3D acceptance are recorded in the [integration report](docs/RELEASE_INTEGRATION.md). [Behavior, API rationale, tolerances, limitations and CAD acceptance →](docs/CURVE_LAYOUT.md) +Native CAD/UI, recompute/edit, Undo/Redo and local F3D acceptance are recorded in the [integration report](RELEASE_INTEGRATION.md). [Behavior, API rationale, tolerances, limitations and CAD acceptance →](CURVE_LAYOUT.md) ## Performance -Measured before/after results include **3.424 → 0.262 s** for a 45-hole elliptical Fast Preview and **1.148 → 0.104 s** for 253 hexagons in a circular region. These are paired measurements in Fusion on macOS, not universal speed guarantees. [Benchmark data, scenarios, and methodology →](docs/BENCHMARKS.md) +Measured before/after results include **3.424 → 0.262 s** for a 45-hole elliptical Fast Preview and **1.148 → 0.104 s** for 253 hexagons in a circular region. These are paired measurements in Fusion on macOS, not universal speed guarantees. [Benchmark data, scenarios, and methodology →](BENCHMARKS.md) Fast Preview and final creation reuse the current command's prepared hole layout. Changing extrusion settings still applies the current values to the final result. Changes to the source geometry, plane, point, radius, or layout invalidate the corresponding data. Clipped hole previews defer panel-only Boolean work until Perforated Panel is selected. Small simple patterns keep a direct clearance-check path. @@ -274,7 +274,7 @@ Voronoi retains its own distribution on all supported surface types. Conical Run Multiple regions support Sketch, Extrude and one parametric Feature node. Coplanar regions share one phase; curved regions follow their local normals. All regions are prepared before modifying the first body. Conservative finite-tool checks reject conflicts across neighboring curved regions without resizing holes. Intersect requires a separate target body for each region. New Component remains available for a single source. -Included in **1.1.0**. See [RELEASE_INTEGRATION.md](docs/RELEASE_INTEGRATION.md) and [noise/recompute acceptance](docs/ORGANIC_PATTERNS.md) for recorded validation and limitations. +Included in **1.1.0**. See [RELEASE_INTEGRATION.md](RELEASE_INTEGRATION.md) and [noise/recompute acceptance](ORGANIC_PATTERNS.md) for recorded validation and limitations. ## Development @@ -286,13 +286,13 @@ python3 install.py --zip The build produces `dist/Perfora-1.1.0.zip` and its `.sha256` file. Version comes from the add-in manifest. CI checks geometry and installation on macOS, Windows, and Linux, then publishes verified 1.x versions as stable releases marked Latest. The earlier 0.x versions remain prereleases. Native Fusion checks run separately. -[Contributing and CAD checks](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) · [Release process](docs/PUBLISHING.md) +[Contributing and CAD checks](../CONTRIBUTING.md) · [Changelog](../CHANGELOG.md) · [Release process](PUBLISHING.md) ## A little workshop mythology Perfora is the goddess of holes, guardian of clean edges, and sworn enemy of repeating the same pattern by hand — from **4FusionLab's own mythology**, with a playful nod to ancient Greece. -[PolyForm Noncommercial 1.0.0](LICENSE). An independent **4FusionLab** project, not affiliated with or endorsed by Autodesk. Native operation icons are resolved from the user's Fusion installation; Autodesk graphics are not bundled. +[PolyForm Noncommercial 1.0.0](../LICENSE). An independent **4FusionLab** project, not affiliated with or endorsed by Autodesk. Native operation icons are resolved from the user's Fusion installation; Autodesk graphics are not bundled. Large organic fields adapt their sampling within 8–16 samples per Cell Size and the fixed node budget. Previously accepted small regions retain their grid; physical Cell Size and Web Thickness stay explicit. diff --git a/docs/README_REFERENCE.ru.md b/docs/README_REFERENCE.ru.md index 4174af3..559d831 100644 --- a/docs/README_REFERENCE.ru.md +++ b/docs/README_REFERENCE.ru.md @@ -16,15 +16,15 @@ ## Задайте узор. Получите обычную модель Fusion. -Визуальный стенд общего ядра: [офлайн-тест Distribution](studies/README.md) показывает 11 семейств через общее геометрическое ядро. Новые нативные команды используют ревизию 2 доработанных Distribution, включая частичные отверстия и Follow Pattern. Существующие Feature сохраняют свою ревизию; старый Running Bond доступен при редактировании. +Визуальный стенд общего ядра: [офлайн-тест Distribution](../studies/README.md) показывает 11 семейств через общее геометрическое ядро. Новые нативные команды используют ревизию 2 доработанных Distribution, включая частичные отверстия и Follow Pattern. Существующие Feature сохраняют свою ревизию; старый Running Bond доступен при редактировании. -[Pattern playground](demo/README.md) — браузерное демо и стенд быстрых визуальных проверок. Он исполняет те же исходники Python-геометрии, что и Fusion: 11 семейств Distribution, 19 форм отверстий, ссылки с параметрами. Сборка: `python3 scripts/build_web_demo.py`; после запуска HTTP-сервера откройте `/demo/`. Страница подготовлена к статическому хостингу; сборка ничего не публикует. +[Pattern playground](../demo/README.md) — браузерное демо и стенд быстрых визуальных проверок. Он исполняет те же исходники Python-геометрии, что и Fusion: 11 семейств Distribution, 19 форм отверстий, ссылки с параметрами. Сборка: `python3 scripts/build_web_demo.py`; после запуска HTTP-сервера откройте `/demo/`. Страница подготовлена к статическому хостингу; сборка ничего не публикует. Выберите плоскую грань, замкнутый профиль эскиза или конструкционную плоскость. Настройте форму отверстий, перемычки и отступ от края, затем проверьте предпросмотр. Perfora создаст обычные профили эскиза, штатную операцию Extrude или параметрическую фичу Perfora в таймлайне. Чтобы перфорировать часть существующей грани, нарисуйте на ней замкнутый эскиз, завершите его и выберите закрашенную область профиля в **Profiles**. Split Face не требуется. Для **Cut** или **Intersect** тело опорной грани автоматически выбирается в **Objects**; перед подтверждением проверьте направление и протяжённость. Для профилей на конструкционных плоскостях Objects по-прежнему задаются явно. -**Perfora 1.1.0: шесть шумовых полей, 11 Distribution, криволинейные грани, несколько областей и исправленный пересчёт Feature.** [Что нового →](docs/releases/v1.1.0.md) +**Perfora 1.1.0: шесть шумовых полей, 11 Distribution, криволинейные грани, несколько областей и исправленный пересчёт Feature.** [Что нового →](releases/v1.1.0.ru.md) **Криволинейные грани:** цилиндрические, конические и регулярные гладкие грани свободной формы используют общие Sketch/Extrude/Feature, включая Voronoi и обрезку по границе. Поведение и ограничения описаны ниже. @@ -82,7 +82,7 @@
Посмотреть двенадцать регулярных форм отверстий -![Двенадцать регулярных форм отверстий](docs/assets/hole-shapes.svg) +![Двенадцать регулярных форм отверстий](assets/hole-shapes.svg)
@@ -95,7 +95,7 @@ | Протяжённость | One Side, Two Sides, Symmetric; расстояние, насквозь, до объекта в поддерживаемых режимах | | Предпросмотр | Быстрые кэшированные контуры для настройки; точный CAD-результат для проверки выдавливания | -[Размеры отверстий и особенности геометрии](docs/PERFORATIONS.md). Интерфейс на английском с привычными названиями операций Fusion. Сторонние пакеты Python не нужны. +[Размеры отверстий и особенности геометрии](PERFORATIONS.md). Интерфейс на английском с привычными названиями операций Fusion. Сторонние пакеты Python не нужны. У всех числовых полей есть начальные значения. Если оставить поле пустым, примерно через секунду оно вернётся к своему дефолту; при этом можно сразу набрать новое значение после очистки. Явный 0 сохраняется, непустые ошибочные выражения не заменяются. Поддерживаются единицы, вычисления и параметры текущего документа Fusion; для целочисленных значений сохраняются ограничения диапазона. @@ -123,7 +123,7 @@ Cell Spacing задаёт номинальный шаг исходных точ Эти формы определяют собственное ограниченное поле; Distribution и Hole Angle скрыты. Pattern Angle поворачивает поле в осях эскиза. На кривой грани 0° следует окружному направлению развёрнутой карты, а 90° — осевому направлению или меридиану, в том числе для волокон. Все шесть подключены к Sketch, Extrude, Feature, Fast/Full Preview, Trim to Boundary и отступам вокруг внутренних вырезов на плоскости, цилиндре, конусе и регулярной свободной поверхности. Несколько областей по-прежнему выбираются только одного типа. На кривых это конечные прямые инструменты с консервативной защитой перемычки по глубине и у шва; высокая кривизна и вершина конуса могут разрежать рисунок. -Островки материала соединяются до выделения контуров; длинные прорези получают мостики. Конфликтующие мелкие фрагменты пропускаются ради перемычки между готовыми контурами. При нулевом краевом отступе фрагменты отверстий, отрезающие материал, сохраняются сплошными. Бюджеты дискретизации и контуров ограничивают стоимость CAD и дают понятную ошибку. [Алгоритмы, поля, поведение поверхностей и проверки →](docs/ORGANIC_PATTERNS.md) +Островки материала соединяются до выделения контуров; длинные прорези получают мостики. Конфликтующие мелкие фрагменты пропускаются ради перемычки между готовыми контурами. При нулевом краевом отступе фрагменты отверстий, отрезающие материал, сохраняются сплошными. Бюджеты дискретизации и контуров ограничивают стоимость CAD и дают понятную ошибку. [Алгоритмы, поля, поведение поверхностей и проверки →](ORGANIC_PATTERNS.md) ## Несколько областей @@ -133,7 +133,7 @@ Cell Spacing задаёт номинальный шаг исходных точ Повторные ссылки исключаются. Перекрытие заполненных областей по площади отклоняется до создания результата. Соседние области остаются отдельными, каждая сохраняет свой Edge Offset и внутренние вырезы. Все источники должны относиться к одному экземпляру компонента. Cut/Intersect сопоставляет грань или профиль на грани с её опорным телом, которое должно присутствовать в Objects. Профили без опорного тела требуют ровно один Object. Intersect допускает одну область на Object; неиспользуемые и неоднозначные Objects отклоняются. Feature Join использует то же явное сопоставление; штатный Extrude Join сохраняет автоматический выбор соприкасающихся тел средствами Fusion. New Component при нескольких областях отклоняется: используйте New Body или один источник. Прежние одиночные операции сохраняются. -Feature хранит зависимости всех источников и сопоставление Objects; состав источников, операция и Objects фиксированы при Edit Feature. Старые одиночные Feature остаются читаемыми и редактируемыми. Full Preview/OK заново читает исходную геометрию и использует ту же привязку раскладки, что Fast Preview. Ошибка удаляет весь новый результат; при неудачном пересчёте код пытается восстановить каждое изменённое базовое тело. **Текущие результаты CAD/UI и локального F3D приведены в [отчёте интеграции](docs/RELEASE_INTEGRATION.md).** [Привязка и сценарии приёмки](docs/MULTI_REGION.md). +Feature хранит зависимости всех источников и сопоставление Objects; состав источников, операция и Objects фиксированы при Edit Feature. Старые одиночные Feature остаются читаемыми и редактируемыми. Full Preview/OK заново читает исходную геометрию и использует ту же привязку раскладки, что Fast Preview. Ошибка удаляет весь новый результат; при неудачном пересчёте код пытается восстановить каждое изменённое базовое тело. **Текущие результаты CAD/UI и локального F3D приведены в [отчёте интеграции](RELEASE_INTEGRATION.md).** [Привязка и сценарии приёмки](MULTI_REGION.md). ## Параметрический режим Feature Исправление пересчёта: пересчёт Feature фиксирует ссылки Objects до Boolean и использует upstream-грани, чтобы избежать зависимости от собственного результата. Edit Feature OK обновляет старые ссылки Objects; после Cancel таймлайн восстанавливается по завершении команды. Проверено в Fusion 2706.1.14 на macOS: все шесть шумов и Voronoi на копиях выбранной грани Box, настоящие Edit Feature OK/Cancel и Undo/Redo. @@ -164,26 +164,26 @@ Spread Radius удалён из диалога. Новая раскладка з ## Одиннадцать Distribution -**Проверено в Fusion на macOS; точный объём приёмки — в [отчёте интеграции](docs/RELEASE_INTEGRATION.md).** Восемь новых вариантов — **Along Path, Contour, Fan, Phyllotaxis, Poisson Disk, Wave, Chevron и Between Curves** — дополняют Staggered, Rectangular и Circular: всего 11 Distribution для 12 повторяемых форм. Шумы и Voronoi задают собственное распределение. Running Bond доступен только при редактировании старых Feature. +**Проверено в Fusion на macOS; точный объём приёмки — в [отчёте интеграции](RELEASE_INTEGRATION.md).** Восемь новых вариантов — **Along Path, Contour, Fan, Phyllotaxis, Poisson Disk, Wave, Chevron и Between Curves** — дополняют Staggered, Rectangular и Circular: всего 11 Distribution для 12 повторяемых форм. Шумы и Voronoi задают собственное распределение. Running Bond доступен только при редактировании старых Feature. -Подключены нативные поля, общие пути Fast/Full Preview и Sketch/Extrude/Feature, хранение параметров, зависимости направляющих и Edit Feature. Результаты Python- и CAD/UI-проверок на macOS записаны в [отчёте интеграции](docs/RELEASE_INTEGRATION.md). +Подключены нативные поля, общие пути Fast/Full Preview и Sketch/Extrude/Feature, хранение параметров, зависимости направляющих и Edit Feature. Результаты Python- и CAD/UI-проверок на macOS записаны в [отчёте интеграции](RELEASE_INTEGRATION.md). Along Spacing и Row Spacing при 0 выбирают автоматический шаг по описанному габариту отверстия; меньший заданный шаг повышается до безопасного минимума. Пространственный индекс соседей пропускает кандидатов, нарушающих Web Thickness, в том числе у центра веера, замыкания контуров и вершины шеврона. Упаковка консервативна и учитывает повёрнутые формы. Phyllotaxis имеет Density Ratio и Spread Radius; Poisson Disk — Seed/New Pattern; Wave — выборку по длине, амплитуду/длину волны/фазу/фазу соседних рядов; Running Bond — накопительный сдвиг, включая `1 / 3` и `1 / 4`. Contour использует приближённые уровни внутреннего расстояния, явный Contour Tolerance и бюджет дискретизации; это не точный CAD-offset, детали меньше разрешения могут исчезнуть. Between Curves пока требует две отдельные открытые плоские кривые/ребра в компоненте Profiles, сопоставляет нормированную длину и концы, отклоняет пересечения, схлопывание, складки, замкнутые, неплоские и межкомпонентные направляющие. Произвольные сложные сплайновые полосы и цепочки не заявлены. Для Contour/Between Curves Start Point и сдвиги двигают только положительную зону Spread Radius; Pattern Angle скрыт. -Новые Feature содержат дополнительные параметры модели. У старых узлов отсутствующие поля при редактировании сохраняются числовыми снимками; для новых model parameters и зависимостей выражений пересоздайте Feature. [Ограничения, точки интеграции и CAD/UI-приёмка →](docs/LAYOUT_VARIANTS.md) +Новые Feature содержат дополнительные параметры модели. У старых узлов отсутствующие поля при редактировании сохраняются числовыми снимками; для новых model parameters и зависимостей выражений пересоздайте Feature. [Ограничения, точки интеграции и CAD/UI-приёмка →](LAYOUT_VARIANTS.md) ## Вдоль кривой Ветка `codex/curve-layout` добавляет **Distribution → Along Path** для всех 12 повторяемых форм: выберите одну линию, дугу, окружность или сплайн в плоскости и компоненте Profiles. **Path Spacing** измеряет шаг по длине кривой; **Start Offset**, **End Offset**, **Position** и **Reverse Path** задают положение отверстий. Ориентация **Fixed** или **Tangent** дополняется **Hole Angle**. Замкнутый путь не дублирует отверстие на шве. На крутых поворотах, сближающихся участках и шве перемычка проверяется по консервативным описанным окружностям; конфликт выдаёт ошибку вместо скрытого пропуска отверстий. Код интегрирован с Fast/Full Preview, существующей обрезкой, внутренними вырезами и Edge Offset, Sketch, Extrude и Feature. Feature хранит зависимость от живого пути и новые параметры модели; Edit Feature позволяет заменить путь или распределение. Старые узлы сохраняют существующие распределения; для Along Path потребуется пересоздание узла, поскольку добавить в старый узел новые нативные параметры нельзя. Цепочки, неплоские пути, пути из другого компонента и эллиптические пути не поддерживаются. Start Point, Spread Radius, Pattern Angle и X/Y Offset в этом распределении неактивны; Voronoi использует своё распределение. -Нативные CAD-сценарии, настоящий диалог и локальное F3D проверены в общей релизной ветке; текущая приёмка записана в [отчёте интеграции](docs/RELEASE_INTEGRATION.md). [Поведение, обоснование API, допуски, ограничения и CAD-приёмка →](docs/CURVE_LAYOUT.md) +Нативные CAD-сценарии, настоящий диалог и локальное F3D проверены в общей релизной ветке; текущая приёмка записана в [отчёте интеграции](RELEASE_INTEGRATION.md). [Поведение, обоснование API, допуски, ограничения и CAD-приёмка →](CURVE_LAYOUT.md) ## Производительность -В парных замерах Fast Preview в Fusion: **3,424 → 0,262 с** для 45 эллиптических отверстий и **1,148 → 0,104 с** для 253 шестигранников в круглой области. Это измерения на macOS, а не универсальная гарантия ускорения. [Данные, сценарии и методика →](docs/BENCHMARKS.md) +В парных замерах Fast Preview в Fusion: **3,424 → 0,262 с** для 45 эллиптических отверстий и **1,148 → 0,104 с** для 253 шестигранников в круглой области. Это измерения на macOS, а не универсальная гарантия ускорения. [Данные, сценарии и методика →](BENCHMARKS.ru.md) Fast Preview и окончательное создание используют подготовленную раскладку текущей команды. Изменение выдавливания по-прежнему передаёт актуальные параметры в результат. Изменения исходной геометрии, плоскости, точки, радиуса или раскладки обновляют соответствующие данные. Для обрезанных отверстий операции, нужные только панели, выполняются при выборе Perforated Panel. Маленькие простые сетки сохраняют прямую проверку зазоров. @@ -275,7 +275,7 @@ Voronoi сохраняет собственное распределение д Несколько областей поддерживают Sketch, Extrude и один параметрический узел Feature. Плоские копланарные области используют общую фазу; криволинейные области — собственные локальные нормали. Все области готовятся до первого изменения тела. Для соседних кривых областей консервативная проверка конечных инструментов отклоняет конфликт, сохраняя размер отверстий. Intersect требует отдельное целевое тело для каждой области. New Component доступен для одиночной области. -Включено в **1.1.0**. Фактическая приёмка и ограничения: [RELEASE_INTEGRATION.md](docs/RELEASE_INTEGRATION.md) и [шумы и пересчёт](docs/ORGANIC_PATTERNS.md). +Включено в **1.1.0**. Фактическая приёмка и ограничения: [RELEASE_INTEGRATION.md](RELEASE_INTEGRATION.md) и [шумы и пересчёт](ORGANIC_PATTERNS.md). ## Разработка @@ -287,13 +287,13 @@ python3 install.py --zip Результат сборки — `dist/Perfora-1.1.0.zip` и файл `.sha256`. Версия берётся из manifest дополнения. CI проверяет геометрию и установку на macOS, Windows и Linux, затем публикует проверенные версии 1.x как стабильные релизы с отметкой Latest. Ранние версии 0.x остаются prerelease. CAD-проверки выполняются отдельно в Fusion. -[Участие в разработке и CAD-проверки](CONTRIBUTING.md) · [Изменения](CHANGELOG.md) · [Выпуск релизов](docs/PUBLISHING.md) +[Участие в разработке и CAD-проверки](../CONTRIBUTING.ru.md) · [Изменения](../CHANGELOG.ru.md) · [Выпуск релизов](PUBLISHING.ru.md) ## Немного мифологии мастерской Перфора — богиня отверстий, хранительница аккуратных кромок и противница ручного повторения одного узора. Она принадлежит **авторской мифологии 4FusionLab** с шуточной отсылкой к Древней Греции. -[PolyForm Noncommercial 1.0.0](LICENSE). Независимый проект **4FusionLab**, не связанный с Autodesk. Нативные значки операций загружаются из установки Fusion пользователя; графика Autodesk в дистрибутив не включена. +[PolyForm Noncommercial 1.0.0](../LICENSE). Независимый проект **4FusionLab**, не связанный с Autodesk. Нативные значки операций загружаются из установки Fusion пользователя; графика Autodesk в дистрибутив не включена. Большие шумовые поля адаптируют дискретизацию в пределах 8–16 отсчётов на Cell Size при прежнем лимите узлов. У ранее допустимых малых областей сетка сохраняется; физический масштаб и Web Thickness задаются явно. From 86a68ae9ac48499f4988e9235a71e22eb7df86a3 Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 16:10:12 +0300 Subject: [PATCH 06/10] docs: fix reference image paths --- docs/README_REFERENCE.md | 24 ++++++++++++------------ docs/README_REFERENCE.ru.md | 24 ++++++++++++------------ 2 files changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/README_REFERENCE.md b/docs/README_REFERENCE.md index d0daf73..4bb832e 100644 --- a/docs/README_REFERENCE.md +++ b/docs/README_REFERENCE.md @@ -1,5 +1,5 @@

- Perfora — goddess of holes + Perfora — goddess of holes

Perfora for Autodesk Fusion

@@ -8,10 +8,10 @@

Build and release checks Release - PolyForm Noncommercial 1.0.0 license + PolyForm Noncommercial 1.0.0 license

-

Download v1.1.0 · Русский · Report a problem

+

Download v1.1.0 · Русский · Report a problem

## Make the pattern. Keep the native model. @@ -33,47 +33,47 @@ To perforate part of an existing face, draw a closed sketch on that face, finish diff --git a/docs/README_REFERENCE.ru.md b/docs/README_REFERENCE.ru.md index 559d831..f8d1aad 100644 --- a/docs/README_REFERENCE.ru.md +++ b/docs/README_REFERENCE.ru.md @@ -1,5 +1,5 @@

- Перфора — богиня отверстий + Перфора — богиня отверстий

Perfora для Autodesk Fusion

@@ -8,10 +8,10 @@

Проверки и релизы Версия - Лицензия PolyForm Noncommercial 1.0.0 + Лицензия PolyForm Noncommercial 1.0.0

-

Скачать v1.1.0 · English · Сообщить о проблеме

+

Скачать v1.1.0 · English · Сообщить о проблеме

## Задайте узор. Получите обычную модель Fusion. @@ -33,47 +33,47 @@
- Blue rectangular grille with hexagonal perforation and four mounting holes + Blue rectangular grille with hexagonal perforation and four mounting holes

Honeycomb grille
Hexagonal cells, an outer frame, and mounting holes.

- Green rectangular panel with rounded Voronoi perforation + Green rectangular panel with rounded Voronoi perforation

Rounded Voronoi
An irregular pattern with rounded corners and a defined edge.

- Orange circular plate with diagonal slots and a central opening + Orange circular plate with diagonal slots and a central opening

Slots on a circular boundary
Partial slots follow the outer edge and central opening.

- Six colored panels showing circular, triangular, star, elliptical, diamond, and cross perforations + Six colored panels showing circular, triangular, star, elliptical, diamond, and cross perforations

A shape for every pattern
Circles, triangles, stars, ellipses, diamonds, and crosses.

- Gold circular grille with tangential slots on concentric rings + Gold circular grille with tangential slots on concentric rings

Slots that follow the circle
Circular distribution, Tangential orientation, and a clean center opening.

- Two circular grilles comparing radial and tangential slots + Two circular grilles comparing radial and tangential slots

Choose the direction
Radial on the left, Tangential on the right. Fixed orientation is available too.

- Green plate perforated only inside an off-center circular zone + Green plate perforated only inside an off-center circular zone

Start here. Stop at this radius.
Pick a point and limit the spread without drawing a boundary profile.

- Blue plate with rounded Voronoi perforation confined to a sketch profile + Blue plate with rounded Voronoi perforation confined to a sketch profile

Your sketch is the boundary
Perforate a profile directly on a solid face. No Split Face.

- Two panels showing a parametric spread radius change from 16 to 26 millimeters + Two panels showing a parametric spread radius change from 16 to 26 millimeters

Change the parameter. Rebuild the pattern.
Spread Radius 16 mm and 26 mm; the right-hand Feature recomputes after editing its model parameter.

From d1628a4fff6c59524f7556542ba7fb077f31b436 Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 16:17:25 +0300 Subject: [PATCH 07/10] docs: provide bilingual perforation references --- CONTRIBUTING.ru.md | 2 +- README.ru.md | 2 +- docs/ORGANIC_PATTERNS.md | 101 ++++++++++++-------------- docs/ORGANIC_PATTERNS.ru.md | 90 ++++++++++++++++++++++++ docs/PERFORATIONS.md | 136 ++++++++++++++++++------------------ docs/PERFORATIONS.ru.md | 115 ++++++++++++++++++++++++++++++ docs/README_REFERENCE.ru.md | 6 +- 7 files changed, 324 insertions(+), 128 deletions(-) create mode 100644 docs/ORGANIC_PATTERNS.ru.md create mode 100644 docs/PERFORATIONS.ru.md diff --git a/CONTRIBUTING.ru.md b/CONTRIBUTING.ru.md index 0d47442..120fe62 100644 --- a/CONTRIBUTING.ru.md +++ b/CONTRIBUTING.ru.md @@ -73,6 +73,6 @@ Along Path доступен только в разработке; нативна ## Органические поля (разработка) -См. [ORGANIC_PATTERNS.md](docs/ORGANIC_PATTERNS.md). Запустите полный автономный набор, включая `test_organic.py`, `test_solid_topology.py` и реальные контракты методов диалога. В Fusion выполните `fusion_organic_regression.py` для зарегистрированного рабочего каталога с необязательными подмножествами `kinds`, `shapes`, `modes` и `trims`. `archive=True` проверяет локальный импорт F3D/пересчёт; `capture=True` экспортирует реальные изображения окна просмотра. Отчёты храните вне репозитория. Активный документ никогда не используется как тестовая заготовка: каждый случай создаёт временный документ и восстанавливает исходный. +См. [ORGANIC_PATTERNS.md](docs/ORGANIC_PATTERNS.ru.md). Запустите полный автономный набор, включая `test_organic.py`, `test_solid_topology.py` и реальные контракты методов диалога. В Fusion выполните `fusion_organic_regression.py` для зарегистрированного рабочего каталога с необязательными подмножествами `kinds`, `shapes`, `modes` и `trims`. `archive=True` проверяет локальный импорт F3D/пересчёт; `capture=True` экспортирует реальные изображения окна просмотра. Отчёты храните вне репозитория. Активный документ никогда не используется как тестовая заготовка: каждый случай создаёт временный документ и восстанавливает исходный. Для каждой формы и затронутого режима результата используйте `fusion_organic_ui.py` из нативной консоли Python. Вызовите `prepare()`, запросите Fast/Full через `preview()`, затем `check_preview()`. Нажмите настоящую кнопку OK/Cancel и вызовите `verify(created)`. Для Feature выполните `begin_edit()`, затем `edit_preview()`, нажмите настоящую OK/Cancel и вызовите `end_edit(accepted)`. После нативных Undo/Redo обязательно вызовите `verify_undo()` / `verify(True)`. `finish()` восстанавливает исходный документ пользователя. Стадия ready или успешная геометрия Python сами по себе не являются приёмкой нативной транзакции. Выполните `fusion_organic_boundaries.py` для связности с нулевым отступом при существующем внутреннем вырезе; также повторно проверьте разделение шва/глубины, несколько однородных областей и текущую упаковку. diff --git a/README.ru.md b/README.ru.md index 7c73332..1519d50 100644 --- a/README.ru.md +++ b/README.ru.md @@ -49,7 +49,7 @@ ## Подробнее -[Подробное руководство](docs/README_REFERENCE.ru.md) · [Геометрия отверстий](docs/PERFORATIONS.md) · [Органические узоры](docs/ORGANIC_PATTERNS.md) · [Что нового в 1.1.0](docs/releases/v1.1.0.ru.md) · [История изменений](CHANGELOG.ru.md) +[Подробное руководство](docs/README_REFERENCE.ru.md) · [Геометрия отверстий](docs/PERFORATIONS.ru.md) · [Органические узоры](docs/ORGANIC_PATTERNS.ru.md) · [Что нового в 1.1.0](docs/releases/v1.1.0.ru.md) · [История изменений](CHANGELOG.ru.md) [Участие в разработке](CONTRIBUTING.ru.md) · [Лицензия](LICENSE) · [Сообщить о проблеме](https://github.com/4FusionLab/Perfora/issues) diff --git a/docs/ORGANIC_PATTERNS.md b/docs/ORGANIC_PATTERNS.md index c9d4236..a724c01 100644 --- a/docs/ORGANIC_PATTERNS.md +++ b/docs/ORGANIC_PATTERNS.md @@ -1,88 +1,77 @@ -# Органические паттерны Perfora +# Perfora organic patterns -Perfora 1.1.0 объединяет шесть шумовых полей и Voronoi в разделе Noise. Прежние идентификаторы форм, command ID, manifest UUID, атрибуты и схемы Feature 1/2 сохранены. +[Русская версия](ORGANIC_PATTERNS.ru.md) -## Формы и алгоритмы +Perfora 1.1.0 groups six noise fields and Voronoi under Noise. Existing shape identifiers, command ID, manifest UUID, attributes, and Feature schemas 1/2 are preserved. -| Field | Поле и характер рисунка | Основные поля | +## Shapes and algorithms + +| Field | Pattern and behavior | Main controls | | --- | --- | --- | -| Smooth Noise | Двумерный градиентный шум с квинтической интерполяцией и дополнительной октавой; нерегулярные округлые отверстия | Cell Size, Pattern Angle, Seed | -| Reaction Diffusion | Настоящая итерационная реакция–диффузия Gray–Scott; коралловые и лабиринтные прорези | Cell Size, Pattern Angle, Seed | -| Directional Fibers | Анизотропный градиентный шум с плавным искривлением; вытянутые прорези с поперечными мостиками | Cell Size, Pattern Angle, Seed | -| Ridged Noise / Topographic | Периодические уровни низкочастотного рельефа с модулем шума; вложенные дуги и полосы, соединённые материалом | Cell Size, Pattern Angle, Seed | -| Gyroid Field | Сечение поля `sin(x)cos(y) + sin(y)cos(z) + sin(z)cos(x)` плоскостью с нормалью (1,1,1), с фазой, определяемой Seed | Cell Size, Pattern Angle, Seed | -| Blue Noise / Size Gradient | Воспроизводимая упаковка кругов переменного радиуса с проверкой суммы обоих радиусов и Web Thickness | Maximum Diameter, Size Variation, Size Gradient, Direction, Seed | +| Smooth Noise | Two-dimensional gradient noise with quintic interpolation and an additional octave; irregular rounded openings | Cell Size, Pattern Angle, Seed | +| Reaction Diffusion | Actual iterative Gray–Scott reaction–diffusion; coral-like and maze-like slots | Cell Size, Pattern Angle, Seed | +| Directional Fibers | Anisotropic gradient noise with smooth warping; elongated slots with cross bridges | Cell Size, Pattern Angle, Seed | +| Ridged Noise / Topographic | Periodic levels of low-frequency terrain with an absolute-value noise field; nested arcs and strips joined by material | Cell Size, Pattern Angle, Seed | +| Gyroid Field | Cross-section of `sin(x)cos(y) + sin(y)cos(z) + sin(z)cos(x)` by a plane normal to (1,1,1), with phase determined by Seed | Cell Size, Pattern Angle, Seed | +| Blue Noise / Size Gradient | Reproducible packing of variable-radius circles, checking the sum of both radii and Web Thickness | Maximum Diameter, Size Variation, Size Gradient, Direction, Seed | -Gyroid Field создаёт плоские контуры для прямых инструментов. Это не объёмная TPMS-решётка. Blue Noise дополняет существующий Poisson Disk: тот сохраняет одинаковую форму и размер, а новый режим меняет радиусы. Спектральная оптимизация синего шума не заявляется. +Gyroid Field produces planar contours for straight tools, not a volumetric TPMS lattice. Blue Noise complements the existing Poisson Disk: the latter retains equal shape and size, while the new mode varies radii. Spectral blue-noise optimization is not claimed. -Gray–Scott рассчитывается на периодической сетке 128×128: 1000 шагов, dt=1, Du=1, Dv=0.5, feed=0.04, kill=0.06. Девятиточечный лапласиан использует веса −1 в центре, 0.2 по сторонам и 0.05 по диагоналям. Seed задаёт начальные возмущения. Неизменяемые поля последних трёх Seed кэшируются; это ограниченный кэш чисел без объектов Fusion. Базовый период решателя составляет 128/12 Cell Size. Плавное непериодическое искривление координат убирает буквальное повторение плитки; на большой области сходные мотивы всё ещё могут быть узнаваемы. Изменение масштаба, порога или направления использует уже рассчитанное поле того же Seed. +Gray–Scott is calculated on a periodic 128×128 grid: 1,000 steps, dt=1, Du=1, Dv=0.5, feed=0.04, kill=0.06. The nine-point Laplacian uses weights −1 at the center, 0.2 at the sides, and 0.05 on diagonals. Seed determines the initial disturbances. Immutable fields for the last three Seeds are cached in a bounded numeric cache without Fusion objects. The solver's base period is 128/12 Cell Size. Smooth nonperiodic coordinate warping removes literal tile repetition; similar motifs may still be recognizable over a large area. Changes to scale, threshold, or direction reuse the field already calculated for the same Seed. -Алгоритмические ориентиры: [градиентный шум Ken Perlin](https://cs.nyu.edu/~perlin/noise/) и [модель Gray–Scott в изложении Karl Sims](https://www.karlsims.com/rd.html). Реализация самостоятельная, на стандартном Python, без сторонних зависимостей выполнения. +Algorithm references: [Ken Perlin's gradient noise](https://cs.nyu.edu/~perlin/noise/) and [Karl Sims' explanation of Gray–Scott](https://www.karlsims.com/rd.html). The implementation is independent, in standard Python, without third-party runtime dependencies. -## Значение полей +## Controls -**Add Bridges** — отдельная галочка, по умолчанию выключенная. Она добавляет локальные поперечные связи в длинных прорезях; без неё сохраняется естественный рисунок поля. Обязательная защита связности материала и Web Thickness остаются активными. Галочка скрыта для Blue Noise, сохраняется в Feature, восстанавливается в Edit Feature и при открытии F3D. +**Add Bridges** is a separate checkbox, off by default. It adds local cross connections to long slots; without it the field's natural pattern remains. Mandatory material-connectivity and Web Thickness protection remains active. The checkbox is hidden for Blue Noise, stored in Feature, and restored in Edit Feature and when opening F3D. -Cell Size — физический масштаб поля в единицах длины, а не одинаковая ширина каждого отверстия. Web Thickness задаёт минимальную перемычку. Внутренний порог поля выбирается по форме; прежний Field Fill сохраняется только для совместимости существующих Feature. Утолщение перемычек, мостики, скругление концов, отступ и обрезка уменьшают итоговую открытую площадь. +Cell Size is the physical field scale in length units, not the uniform width of every opening. Web Thickness sets the minimum web. The internal field threshold depends on the shape; the old Field Fill is retained only for existing Feature compatibility. Thickened webs, bridges, rounded ends, offsets, and trimming reduce the final open area. -Для Blue Noise Maximum Diameter — наибольший диаметр. Size Variation 65% разрешает диаметры от 35% до 100% этого значения; при 0% размеры одинаковые. Size Gradient от −100% до +100% задаёт направленное изменение размера: 0% — случайные размеры, +100% — увеличение вдоль Direction, −100% — обратное направление. Значения между ними смешивают градиент и случайную вариацию. +For Blue Noise, Maximum Diameter is the largest diameter. Size Variation of 65% permits diameters from 35% to 100% of that value; at 0% sizes are equal. Size Gradient from −100% to +100% controls directional size variation: 0% gives random sizes, +100% increases along Direction, and −100% reverses that direction. Intermediate values mix the gradient with random variation. -Pattern Angle поворачивает весь мотив; Seed / New Pattern воспроизводимы при одинаковом источнике и настройках. Distribution и Hole Angle скрыты: эти формы определяют собственное поле и не совмещаются с Circular, Along Path или восемью дополнительными Distribution. Переключение обратно на повторяемую форму восстанавливает выбранную раскладку. Вызов через API с несовместимым сочетанием отклоняется явно, без подмены алгоритма. +Pattern Angle rotates the complete motif; Seed / New Pattern are reproducible for the same source and settings. Distribution and Hole Angle are hidden: these shapes define their own field and do not combine with Circular, Along Path, or the eight additional Distributions. Switching back to a repeating shape restores the selected layout. An API call with an incompatible combination is rejected explicitly, without substituting an algorithm. -Start Point и X/Y Offset сохраняют фазу поля в его осях. Для нескольких плоских областей используются общие оси компонента и начало, как в общей команде. Порог, топология мостиков и конечная упаковка разрешаются отдельно в окне каждой области; соседние окна не являются вырезками одной бесконечной готовой сетки. Изменение габаритов источника может изменить отверстия и их количество. Перекрывающиеся области запрещены. +Start Point and X/Y Offset preserve the field phase in its own axes. Multiple planar regions use common component axes and origin, as in the shared command. Threshold, bridge topology, and final packing are resolved separately within each region's window; neighboring windows are not crops of one infinite completed grid. Changing source bounds may change openings and their count. Overlapping regions are prohibited. -## Перемычки, контуры и стоимость +## Webs, contours, and cost -Материал на сетке соединяется минимальным остовным лесом кратчайших растровых путей. При включённой Add Bridges длинные прорези дополнительно делятся мостиками; поперечные разрезы не накладывают на всю панель одну регулярную решётку. Затем евклидово расстояние утолщает материал с запасом на диагонали сетки и аппроксимацию. Ограниченное знаковое поле расстояния сглаживается, скругляя концы и убирая игольчатые выступы. Мостик пересекает только одну локальную ветвь прорези, а не весь ряд отверстий. Контуры равномерно пересэмплируются и адаптивно аппроксимируются кубическими кривыми с согласованными касательными. В Fusion это точные кубические NURBS; одни и те же кривые поступают в Fast Preview, обрезку, Sketch и прямое выдавливание. +Material on the grid is connected using a minimum spanning forest of shortest raster paths. With Add Bridges enabled, long slots are further divided by bridges; cross cuts do not impose one regular grid on the entire panel. Euclidean distance then thickens the material with allowance for grid diagonals and approximation. A bounded signed distance field is smoothed, rounding ends and removing needle-like protrusions. A bridge crosses only one local slot branch, not an entire row of openings. Contours are uniformly resampled and adaptively approximated with cubic curves with matched tangents. In Fusion these are exact cubic NURBS; the same curves feed Fast Preview, trimming, Sketch, and straight extrusion. -Проверяются замкнутость, самопересечения и расстояние между готовыми контурами. При распаде узкой прорези на несколько отверстий новые перемычки проверяются отдельно: узкая связка локально утолщается с повторным выделением контуров. Только остаточные конфликтующие мелкие фрагменты после ограниченного числа уточнений пропускаются. Описанные габариты не заменяют эту плоскую проверку. Целые отверстия учитывают внешний край и внутренние вырезы; их отбор консервативен в пределах допуска дискретизации кривой. Trim to Boundary сохраняет безопасные частичные отверстия с действующим точным Edge Offset. При выборе органической формы в новой команде обрезка включается автоматически; возврат к повторяемой форме восстанавливает прежний переключатель. Сохранённые Feature не переопределяются этим начальным поведением. +Closure, self-intersections, and distances between final contours are checked. When a narrow slot splits into multiple openings, the new webs are checked separately: a narrow connection is thickened locally and contours are extracted again. Only remaining conflicting small fragments are omitted after a bounded number of refinements. Enclosing bounds do not replace this planar check. Whole openings account for the outer edge and inner cutouts; their selection is conservative within curve-sampling tolerance. Trim to Boundary retains safe partial openings with the active exact Edge Offset. Selecting an organic shape in a new command automatically enables trimming; returning to a repeating shape restores the previous toggle. This initial behavior does not override saved Features. -При Edge Offset около нуля точная проверка материала отклоняет локальный фрагмент отверстия, который создавал бы отдельный островок: он остаётся материалом. Положительный отступ не увеличивается скрыто до Web Thickness. Соединённость — геометрическая защита, не расчёт прочности, усталости или технологичности изготовления. +With Edge Offset near zero, an exact material check rejects a local opening fragment that would create a separate island: it remains material. A positive offset is not silently increased to Web Thickness. Connectivity is a geometric safeguard, not a strength, fatigue, or manufacturing calculation. -Шаг дискретизации — Cell Size / 16 для ранее допустимых областей; на больших областях он адаптируется до Cell Size / 8, сохраняя лимит узлов и физический масштаб поля; допуск аппроксимации кривых — 0.22 шага. Детали меньше разрешения могут исчезнуть. Бюджет поля — 120000 узлов с защитным ореолом; бюджет принятых контуров — 16000 рёбер, плюс ограниченный предварительный бюджет. Maximum Holes остаётся 1–5000 и считается суммарно для нескольких областей. Слишком плотный запрос завершается понятной ошибкой с предложением увеличить масштаб или уменьшить область. Время CAD зависит и от числа рёбер, сложности границы и кривизны. +Sampling step is Cell Size / 16 for previously permitted regions; on large regions it adapts up to Cell Size / 8, retaining the node limit and physical field scale. Curve approximation tolerance is 0.22 of a step. Details smaller than the resolution may disappear. The field budget is 120,000 nodes including a protective halo; accepted contours have a budget of 16,000 edges plus a bounded preliminary budget. Maximum Holes remains 1–5,000, counted across regions. An overly dense request ends with an actionable error suggesting a larger scale or smaller region. CAD time also depends on edge count, boundary complexity, and curvature. -## Поверхности и результат +## Surfaces and results -| Источник | Размещение и ограничения | +| Source | Placement and limitations | | --- | --- | -| Плоская грань, плоский профиль, Construction Plane | Все шесть полей в физических координатах плоскости; точная обрезка с внутренними контурами | -| Цилиндр | Карта окружность/ось; центры переносятся периодически, дубли шва удаляются; конечные инструменты разделяются по глубине | -| Конус | Центры адаптируются к местной окружности; инструменты сохраняют размер; участки у оси/вершины и слишком длинные для Distance пропускаются локально | -| Freeform | Физическая карта существующего адаптера, локальные нормали и та же точная маска; сингулярности и непригодные локальные участки не исключают остальную грань | +| Planar face, planar profile, Construction Plane | All six fields in physical plane coordinates; exact trimming with inner contours | +| Cylinder | Circumference/axis map; centers wrap periodically, seam duplicates are removed; finite tools are separated through depth | +| Cone | Centers adapt to local circumference; tools retain size; areas near the axis/apex and slots too long for Distance are skipped locally | +| Freeform | Existing adapter's physical map, local normals, and the same exact mask; singularities and unsuitable local areas do not exclude the rest of the face | + +On a curved face, Direction 0° corresponds to the circumferential/first map axis; 90° corresponds to the cylinder axis, cone meridian, or second freeform-map axis. Fibers can run along or across the axis. Separating planes can shorten organic contours and make the pattern sparser at high curvature. A web is preserved at the seam; continuous random-field continuation across an arbitrary circumference is not guaranteed. These are straight finite tools, not geodesic slots or a planar sketch wrapped onto the surface. -На кривой грани Direction 0° соответствует окружной/первой оси карты, 90° — оси цилиндра, меридиану конуса или второй оси карты freeform. Волокна можно направлять вдоль или поперёк оси. Разделяющие плоскости могут укорачивать органические контуры и делать рисунок более редким на сильной кривизне. На шве обеспечивается перемычка, а не непрерывное продолжение случайного поля через произвольную длину окружности. Это прямые конечные инструменты, не геодезические прорези и не оборачивание плоского эскиза по поверхности. +Slots too long for local projection are omitted. If no openings remain, build or recompute fails. Reduce Cell Size, enable Add Bridges, or increase Distance within permitted limits. -Слишком длинные для локальной проекции прорези пропускаются. Если после этого не осталось отверстий, построение или пересчёт завершается ошибкой. Уменьшите Cell Size, включите Add Bridges либо увеличьте Distance в допустимых пределах. +Sketch produces fixed contours, using the existing 3D-contour path on curved surfaces. Extrude produces a fixed native Extrude on a plane or Base Feature/Combine on a curved surface. Feature retains settings and native parameters, dependencies, Edit Feature, and recompute. Existing restrictions on Distance, zero Taper, operations, and fixed sources/Objects remain. New fields on old nodes receive defaults; if a node predates those native parameters, editable numeric values are kept in a snapshot. Recreate Feature to obtain new expression dependencies. -Sketch создаёт фиксированные контуры; на кривых — существующий путь 3D-контуров. Extrude создаёт фиксированный штатный Extrude на плоскости либо Base Feature/Combine на кривой. Feature сохраняет настройки и нативные параметры, зависимости, Edit Feature и пересчёт. Ограничения Distance/нулевого Taper/операций и неизменяемых источников/Objects остаются прежними. Новые поля старых узлов получают значения по умолчанию; если узел создан до появления этих нативных параметров, редактируемые числовые значения сохраняются в снимке. Для новых зависимостей выражений пересоздайте Feature. +Selection of up to 32 regions remains homogeneous by surface type. Planes, cylinders, cones, and freeform surfaces cannot be mixed. The existing conservative finite-tool check applies between curved regions. -Выбор до 32 областей остаётся однородным по типу поверхности. Плоскость, цилиндр, конус и freeform не смешиваются. Между кривыми областями действует существующая консервативная проверка конечных инструментов. +## Validation -## Проверки +UI validation recorded on 2026-10-25: Pattern/Noise sections, all 19 shapes, Voronoi last in Noise, and default Magenta were checked in the loaded copy of Fusion 2706.1.14 on macOS. Thirty-six browser scenarios passed, including switching sections with settings restored and a 360 px mobile width. A Feature recompute failure was fixed: Objects are retained through upstream faces and references are bound before a Boolean can remove the selected face. The timeline after Edit Feature is restored through `commandTerminated`. -Текущая проверка интерфейса 2026-10-25: разделы Pattern/Noise, все 19 форм, -Voronoi последним в Noise и Magenta по умолчанию проверены в загруженной -копии Fusion 2706.1.14 на macOS. В браузере прошли 36 сценариев, включая -переключение разделов с восстановлением настроек и мобильную ширину 360 px. -Сбой пересчёта Feature исправлен: Objects сохраняются через upstream-грани, -а ссылки фиксируются до Boolean, способного удалить выбранную грань. -Таймлайн после Edit Feature восстанавливается через commandTerminated. -В загруженной копии проверены создание и изменение Cell Size всех шести -полей и Voronoi на копиях выбранной грани Box. Smooth Noise также проверен -на цилиндре, конусе и freeform; плоская Feature пересчитана после повторного -открытия локального F3D. Настоящие Edit Feature OK/Cancel, Undo/Redo всей -команды и редактирования прошли. Несколько областей проверены с Cut, Join, -Intersect и New Body. Старый узел с воспроизведённой циклической зависимостью -восстановлен и проверен изменением размера и исходной толщины. -Исходные пользовательские документы не изменялись. Это проверка macOS; -облачное сохранение и Windows CAD ей не подтверждаются. +The loaded copy was used to check creation and Cell Size changes for all six fields and Voronoi on copies of a selected Box face. Smooth Noise was also checked on a cylinder, cone, and freeform face; a planar Feature recomputed after reopening a local F3D. Real Edit Feature OK/Cancel and Undo/Redo for both the complete command and editing passed. Multiple regions were checked with Cut, Join, Intersect, and New Body. An old node with a reproduced cyclic dependency was recovered and checked by changing size and source thickness. Original user documents were not modified. This was macOS validation; it does not establish cloud-save or Windows CAD behavior. -Локальные инварианты: `python3 -m unittest discover -s tests -v`. `test_organic.py` проверяет шесть разных воспроизводимых полей, реальные зазоры контуров, граф соединения материала, евклидово расстояние, радиусы/градиент, направления/фазу, отступы/внутренние вырезы, бюджеты, кэш и версионированные параметры. `test_solid_topology.py` проверяет совпадение копий точек ядра возле границ округления; сшивание дополнительно проверяется в настоящем Fusion. +Local invariants: `python3 -m unittest discover -s tests -v`. `test_organic.py` checks six different reproducible fields, actual contour clearances, the material-connection graph, Euclidean distance, radii/gradient, directions/phase, offsets/inner cutouts, budgets, cache, and versioned parameters. `test_solid_topology.py` checks matching kernel-point copies near rounding boundaries; stitching is additionally checked in real Fusion. -`fusion_organic_regression.py` использует реально загруженную копию: плоскость/цилиндр/конус/freeform, все шесть форм, Sketch/Extrude/Feature, Trim on/off, совпадение количества Fast/final, валидность тел и отсутствие новых lumps, изменение реального объёма при пересчёте. Опция `archive=True` экспортирует отдельные локальные F3D, открывает и пересчитывает их вновь; `capture=True` сохраняет реальные изображения. +`fusion_organic_regression.py` uses the actually loaded copy: plane/cylinder/cone/freeform, all six shapes, Sketch/Extrude/Feature, Trim on/off, matching Fast/final counts, body validity and no new lumps, and actual volume change after recompute. `archive=True` exports separate local F3Ds, reopens them, and recomputes again; `capture=True` saves real images. -`fusion_organic_ui.py` проверяет видимость нативных полей, Fast/Full Preview, реальные OK/Cancel, Edit Feature OK/Cancel и Undo/Redo в отдельном документе. Только успешная проверка после нажатия кнопки считается приёмкой транзакции. Временные отчёты, снимки, архивы и замеры остаются вне репозитория и ZIP. Облачное сохранение, Windows CAD и произвольные импортированные поверхности этой проверкой не подтверждаются. +`fusion_organic_ui.py` checks native control visibility, Fast/Full Preview, real OK/Cancel, Edit Feature OK/Cancel, and Undo/Redo in a separate document. Only a successful check after pressing the button counts as transaction acceptance. Temporary reports, images, archives, and timings stay outside the repository and ZIP. This validation does not establish cloud-save, Windows CAD, or arbitrary imported-surface behavior. -В интерфейсе **Pattern Type → Noise** объединены эти шесть полей и последним **Voronoi**. Основные настройки новых шумов — Cell Size (8 mm), Web Thickness (0.8 mm), Edge Offset и Seed. Процент заполнения скрыт; прежнее значение сохраняется только для совместимости существующих Feature. Дополнительные настройки сгруппированы в Field Options. Цвет Fast Preview по умолчанию — Magenta. +In the interface, **Pattern Type → Noise** groups these six fields with **Voronoi** last. The main controls for new noise fields are Cell Size (8 mm), Web Thickness (0.8 mm), Edge Offset, and Seed. Fill percentage is hidden; the previous value is retained only for compatibility with existing Features. Additional settings are grouped under Field Options. Fast Preview defaults to Magenta. -`fusion_feature_dependency_regression.py` воспроизводит старую позднюю привязку BRepBody, проверяет восстановление узла и изменения исходной толщины. `fusion_selected_noise_regression.py` проверяет настоящие Feature на копиях выбранного тела: здоровое состояние, восстановление Objects и изменение объёма после изменения Cell Size. +`fusion_feature_dependency_regression.py` reproduces the old late BRepBody binding, checks node recovery and source-thickness changes. `fusion_selected_noise_regression.py` checks real Features on copies of a selected body: healthy status, restored Objects, and volume change after changing Cell Size. diff --git a/docs/ORGANIC_PATTERNS.ru.md b/docs/ORGANIC_PATTERNS.ru.md new file mode 100644 index 0000000..23ad9f8 --- /dev/null +++ b/docs/ORGANIC_PATTERNS.ru.md @@ -0,0 +1,90 @@ +# Органические паттерны Perfora + +[English](ORGANIC_PATTERNS.md) + +Perfora 1.1.0 объединяет шесть шумовых полей и Voronoi в разделе Noise. Прежние идентификаторы форм, command ID, manifest UUID, атрибуты и схемы Feature 1/2 сохранены. + +## Формы и алгоритмы + +| Field | Поле и характер рисунка | Основные поля | +| --- | --- | --- | +| Smooth Noise | Двумерный градиентный шум с квинтической интерполяцией и дополнительной октавой; нерегулярные округлые отверстия | Cell Size, Pattern Angle, Seed | +| Reaction Diffusion | Настоящая итерационная реакция–диффузия Gray–Scott; коралловые и лабиринтные прорези | Cell Size, Pattern Angle, Seed | +| Directional Fibers | Анизотропный градиентный шум с плавным искривлением; вытянутые прорези с поперечными мостиками | Cell Size, Pattern Angle, Seed | +| Ridged Noise / Topographic | Периодические уровни низкочастотного рельефа с модулем шума; вложенные дуги и полосы, соединённые материалом | Cell Size, Pattern Angle, Seed | +| Gyroid Field | Сечение поля `sin(x)cos(y) + sin(y)cos(z) + sin(z)cos(x)` плоскостью с нормалью (1,1,1), с фазой, определяемой Seed | Cell Size, Pattern Angle, Seed | +| Blue Noise / Size Gradient | Воспроизводимая упаковка кругов переменного радиуса с проверкой суммы обоих радиусов и Web Thickness | Maximum Diameter, Size Variation, Size Gradient, Direction, Seed | + +Gyroid Field создаёт плоские контуры для прямых инструментов. Это не объёмная TPMS-решётка. Blue Noise дополняет существующий Poisson Disk: тот сохраняет одинаковую форму и размер, а новый режим меняет радиусы. Спектральная оптимизация синего шума не заявляется. + +Gray–Scott рассчитывается на периодической сетке 128×128: 1000 шагов, dt=1, Du=1, Dv=0.5, feed=0.04, kill=0.06. Девятиточечный лапласиан использует веса −1 в центре, 0.2 по сторонам и 0.05 по диагоналям. Seed задаёт начальные возмущения. Неизменяемые поля последних трёх Seed кэшируются; это ограниченный кэш чисел без объектов Fusion. Базовый период решателя составляет 128/12 Cell Size. Плавное непериодическое искривление координат убирает буквальное повторение плитки; на большой области сходные мотивы всё ещё могут быть узнаваемы. Изменение масштаба, порога или направления использует уже рассчитанное поле того же Seed. + +Алгоритмические ориентиры: [градиентный шум Ken Perlin](https://cs.nyu.edu/~perlin/noise/) и [модель Gray–Scott в изложении Karl Sims](https://www.karlsims.com/rd.html). Реализация самостоятельная, на стандартном Python, без сторонних зависимостей выполнения. + +## Значение полей + +**Add Bridges** — отдельная галочка, по умолчанию выключенная. Она добавляет локальные поперечные связи в длинных прорезях; без неё сохраняется естественный рисунок поля. Обязательная защита связности материала и Web Thickness остаются активными. Галочка скрыта для Blue Noise, сохраняется в Feature, восстанавливается в Edit Feature и при открытии F3D. + +Cell Size — физический масштаб поля в единицах длины, а не одинаковая ширина каждого отверстия. Web Thickness задаёт минимальную перемычку. Внутренний порог поля выбирается по форме; прежний Field Fill сохраняется только для совместимости существующих Feature. Утолщение перемычек, мостики, скругление концов, отступ и обрезка уменьшают итоговую открытую площадь. + +Для Blue Noise Maximum Diameter — наибольший диаметр. Size Variation 65% разрешает диаметры от 35% до 100% этого значения; при 0% размеры одинаковые. Size Gradient от −100% до +100% задаёт направленное изменение размера: 0% — случайные размеры, +100% — увеличение вдоль Direction, −100% — обратное направление. Значения между ними смешивают градиент и случайную вариацию. + +Pattern Angle поворачивает весь мотив; Seed / New Pattern воспроизводимы при одинаковом источнике и настройках. Distribution и Hole Angle скрыты: эти формы определяют собственное поле и не совмещаются с Circular, Along Path или восемью дополнительными Distribution. Переключение обратно на повторяемую форму восстанавливает выбранную раскладку. Вызов через API с несовместимым сочетанием отклоняется явно, без подмены алгоритма. + +Start Point и X/Y Offset сохраняют фазу поля в его осях. Для нескольких плоских областей используются общие оси компонента и начало, как в общей команде. Порог, топология мостиков и конечная упаковка разрешаются отдельно в окне каждой области; соседние окна не являются вырезками одной бесконечной готовой сетки. Изменение габаритов источника может изменить отверстия и их количество. Перекрывающиеся области запрещены. + +## Перемычки, контуры и стоимость + +Материал на сетке соединяется минимальным остовным лесом кратчайших растровых путей. При включённой Add Bridges длинные прорези дополнительно делятся мостиками; поперечные разрезы не накладывают на всю панель одну регулярную решётку. Затем евклидово расстояние утолщает материал с запасом на диагонали сетки и аппроксимацию. Ограниченное знаковое поле расстояния сглаживается, скругляя концы и убирая игольчатые выступы. Мостик пересекает только одну локальную ветвь прорези, а не весь ряд отверстий. Контуры равномерно пересэмплируются и адаптивно аппроксимируются кубическими кривыми с согласованными касательными. В Fusion это точные кубические NURBS; одни и те же кривые поступают в Fast Preview, обрезку, Sketch и прямое выдавливание. + +Проверяются замкнутость, самопересечения и расстояние между готовыми контурами. При распаде узкой прорези на несколько отверстий новые перемычки проверяются отдельно: узкая связка локально утолщается с повторным выделением контуров. Только остаточные конфликтующие мелкие фрагменты после ограниченного числа уточнений пропускаются. Описанные габариты не заменяют эту плоскую проверку. Целые отверстия учитывают внешний край и внутренние вырезы; их отбор консервативен в пределах допуска дискретизации кривой. Trim to Boundary сохраняет безопасные частичные отверстия с действующим точным Edge Offset. При выборе органической формы в новой команде обрезка включается автоматически; возврат к повторяемой форме восстанавливает прежний переключатель. Сохранённые Feature не переопределяются этим начальным поведением. + +При Edge Offset около нуля точная проверка материала отклоняет локальный фрагмент отверстия, который создавал бы отдельный островок: он остаётся материалом. Положительный отступ не увеличивается скрыто до Web Thickness. Соединённость — геометрическая защита, не расчёт прочности, усталости или технологичности изготовления. + +Шаг дискретизации — Cell Size / 16 для ранее допустимых областей; на больших областях он адаптируется до Cell Size / 8, сохраняя лимит узлов и физический масштаб поля; допуск аппроксимации кривых — 0.22 шага. Детали меньше разрешения могут исчезнуть. Бюджет поля — 120000 узлов с защитным ореолом; бюджет принятых контуров — 16000 рёбер, плюс ограниченный предварительный бюджет. Maximum Holes остаётся 1–5000 и считается суммарно для нескольких областей. Слишком плотный запрос завершается понятной ошибкой с предложением увеличить масштаб или уменьшить область. Время CAD зависит и от числа рёбер, сложности границы и кривизны. + +## Поверхности и результат + +| Источник | Размещение и ограничения | +| --- | --- | +| Плоская грань, плоский профиль, Construction Plane | Все шесть полей в физических координатах плоскости; точная обрезка с внутренними контурами | +| Цилиндр | Карта окружность/ось; центры переносятся периодически, дубли шва удаляются; конечные инструменты разделяются по глубине | +| Конус | Центры адаптируются к местной окружности; инструменты сохраняют размер; участки у оси/вершины и слишком длинные для Distance пропускаются локально | +| Freeform | Физическая карта существующего адаптера, локальные нормали и та же точная маска; сингулярности и непригодные локальные участки не исключают остальную грань | + +На кривой грани Direction 0° соответствует окружной/первой оси карты, 90° — оси цилиндра, меридиану конуса или второй оси карты freeform. Волокна можно направлять вдоль или поперёк оси. Разделяющие плоскости могут укорачивать органические контуры и делать рисунок более редким на сильной кривизне. На шве обеспечивается перемычка, а не непрерывное продолжение случайного поля через произвольную длину окружности. Это прямые конечные инструменты, не геодезические прорези и не оборачивание плоского эскиза по поверхности. + +Слишком длинные для локальной проекции прорези пропускаются. Если после этого не осталось отверстий, построение или пересчёт завершается ошибкой. Уменьшите Cell Size, включите Add Bridges либо увеличьте Distance в допустимых пределах. + +Sketch создаёт фиксированные контуры; на кривых — существующий путь 3D-контуров. Extrude создаёт фиксированный штатный Extrude на плоскости либо Base Feature/Combine на кривой. Feature сохраняет настройки и нативные параметры, зависимости, Edit Feature и пересчёт. Ограничения Distance/нулевого Taper/операций и неизменяемых источников/Objects остаются прежними. Новые поля старых узлов получают значения по умолчанию; если узел создан до появления этих нативных параметров, редактируемые числовые значения сохраняются в снимке. Для новых зависимостей выражений пересоздайте Feature. + +Выбор до 32 областей остаётся однородным по типу поверхности. Плоскость, цилиндр, конус и freeform не смешиваются. Между кривыми областями действует существующая консервативная проверка конечных инструментов. + +## Проверки + +Текущая проверка интерфейса 2026-10-25: разделы Pattern/Noise, все 19 форм, +Voronoi последним в Noise и Magenta по умолчанию проверены в загруженной +копии Fusion 2706.1.14 на macOS. В браузере прошли 36 сценариев, включая +переключение разделов с восстановлением настроек и мобильную ширину 360 px. +Сбой пересчёта Feature исправлен: Objects сохраняются через upstream-грани, +а ссылки фиксируются до Boolean, способного удалить выбранную грань. +Таймлайн после Edit Feature восстанавливается через commandTerminated. +В загруженной копии проверены создание и изменение Cell Size всех шести +полей и Voronoi на копиях выбранной грани Box. Smooth Noise также проверен +на цилиндре, конусе и freeform; плоская Feature пересчитана после повторного +открытия локального F3D. Настоящие Edit Feature OK/Cancel, Undo/Redo всей +команды и редактирования прошли. Несколько областей проверены с Cut, Join, +Intersect и New Body. Старый узел с воспроизведённой циклической зависимостью +восстановлен и проверен изменением размера и исходной толщины. +Исходные пользовательские документы не изменялись. Это проверка macOS; +облачное сохранение и Windows CAD ей не подтверждаются. + +Локальные инварианты: `python3 -m unittest discover -s tests -v`. `test_organic.py` проверяет шесть разных воспроизводимых полей, реальные зазоры контуров, граф соединения материала, евклидово расстояние, радиусы/градиент, направления/фазу, отступы/внутренние вырезы, бюджеты, кэш и версионированные параметры. `test_solid_topology.py` проверяет совпадение копий точек ядра возле границ округления; сшивание дополнительно проверяется в настоящем Fusion. + +`fusion_organic_regression.py` использует реально загруженную копию: плоскость/цилиндр/конус/freeform, все шесть форм, Sketch/Extrude/Feature, Trim on/off, совпадение количества Fast/final, валидность тел и отсутствие новых lumps, изменение реального объёма при пересчёте. Опция `archive=True` экспортирует отдельные локальные F3D, открывает и пересчитывает их вновь; `capture=True` сохраняет реальные изображения. + +`fusion_organic_ui.py` проверяет видимость нативных полей, Fast/Full Preview, реальные OK/Cancel, Edit Feature OK/Cancel и Undo/Redo в отдельном документе. Только успешная проверка после нажатия кнопки считается приёмкой транзакции. Временные отчёты, снимки, архивы и замеры остаются вне репозитория и ZIP. Облачное сохранение, Windows CAD и произвольные импортированные поверхности этой проверкой не подтверждаются. + +В интерфейсе **Pattern Type → Noise** объединены эти шесть полей и последним **Voronoi**. Основные настройки новых шумов — Cell Size (8 mm), Web Thickness (0.8 mm), Edge Offset и Seed. Процент заполнения скрыт; прежнее значение сохраняется только для совместимости существующих Feature. Дополнительные настройки сгруппированы в Field Options. Цвет Fast Preview по умолчанию — Magenta. + +`fusion_feature_dependency_regression.py` воспроизводит старую позднюю привязку BRepBody, проверяет восстановление узла и изменения исходной толщины. `fusion_selected_noise_regression.py` проверяет настоящие Feature на копиях выбранного тела: здоровое состояние, восстановление Objects и изменение объёма после изменения Cell Size. diff --git a/docs/PERFORATIONS.md b/docs/PERFORATIONS.md index f250b26..912ce5d 100644 --- a/docs/PERFORATIONS.md +++ b/docs/PERFORATIONS.md @@ -1,111 +1,113 @@ -# Формы перфорации +# Perforation shapes -По каталогам производителей, проверено 23 октября 2026 года. +[Русская версия](PERFORATIONS.ru.md) -Перфорация задаётся не только формой отверстия: важны размер, перемычка, шаг, прямое, шахматное или круговое расположение, поворот, отступ и доля открытой площади. В плагине форма ячейки отделена от расположения сетки и операции Extrude. +> **Historical development reference.** This document combines Perfora 1.0.0 behavior with development notes; statements that features are unreleased or untested describe their original stage. For the released 1.1.0 scope and recorded acceptance, see the [release notes](releases/v1.1.0.md) and [integration report](RELEASE_INTEGRATION.md). -| Тип | Варианты | Поддержка в Perfora 1.0.0 | -|---|---|---| -| Базовые отверстия | Круг, квадрат, шестигранник | Диаметр, сторона или размер между гранями | -| Щелевые | Прямоугольная щель и прорезь с круглыми концами | Прямоугольник и прорезь; ширина и полная длина | -| Геометрические | Треугольник, ромб, эллипс, пятиугольник, восьмиугольник | Отдельные формы с поворотом | -| Декоративные | Звёзды, кресты, клевер, цветочные и смешанные узоры | Крест с шириной луча; звезда с 3–12 лучами и внутренним радиусом | -| Формованные | Жалюзийные, вытяжные и рельефные отверстия | Требуют отдельной трёхмерной операции; плоский контур и Extrude не воспроизводят такую геометрию | -| Рисунки и переменная плотность | Несколько размеров/форм, изображения из отверстий | Отдельное возможное расширение; текущая команда повторяет одну форму и размер | +Based on manufacturer catalogs checked on 23 October 2026. -## Круговая раскладка +Perforation is determined by more than hole shape: size, web, pitch, straight, staggered or circular arrangement, rotation, offset, and open-area ratio all matter. In the add-in, cell shape is separate from grid placement and the Extrude operation. -Distribution → Circular доступна для 12 повторяемых форм; Voronoi использует собственное распределение. Отверстия размещаются концентрическими кольцами, число отверстий на каждом кольце подбирается по хорде. В ветке разработки кольца содержат противоположные пары; нечётная вместимость округляется вниз до чётной, сохраняя минимальную перемычку. Первое обычное кольцо содержит шесть отверстий независимо от формы границы. Центральный круг остаётся одиночным. Расстояние между кольцами равно диаметру описанного вокруг отверстия круга плюс Web Thickness. Это сохраняет минимальную перемычку при Fixed, Radial и Tangential Orientation, но для вытянутых и угловатых форм упаковка консервативна. +| Type | Variants | Support in Perfora 1.0.0 | +| --- | --- | --- | +| Basic openings | Circle, square, hexagon | Diameter, side length, or across-flats size | +| Slotted | Rectangular slot and slot with rounded ends | Rectangle and slot; width and full length | +| Geometric | Triangle, diamond, ellipse, pentagon, octagon | Separate rotatable shapes | +| Decorative | Stars, crosses, clover, floral and mixed patterns | Cross with arm width; star with 3–12 points and inner radius | +| Formed | Louvered, drawn and embossed openings | Require a separate 3D operation; a planar outline and Extrude do not reproduce this geometry | +| Patterns and variable density | Multiple sizes/shapes, images made of holes | A possible separate extension; the current command repeats one shape and size | -Start Radius измеряется до центров первого кольца; 0 добавляет одно центральное отверстие. Отверстия могут выступать внутрь этого радиуса. Radial поворачивает отверстия по радиусу, Tangential — вдоль окружности. Hole Angle задаёт дополнительный поворот во всех режимах. Pattern Angle поворачивает рисунок вокруг центра габаритов внешней границы, X/Y Offset сдвигают этот центр в осях эскиза без периодичности. Trim to Boundary и Edge Offset действуют и на внутренние вырезы; радиусы колец задаются до обрезки. На плоскости точное равенство отступу допустимо: скрытый запас 0,001 mm к Edge Offset не добавляется. Касание смещённой границы сохраняет целую ячейку, а действительное пересечение требует обрезки. +## Circular layout -## Размеры новых ячеек +Distribution → Circular is available for the 12 repeating shapes; Voronoi uses its own distribution. Holes are placed in concentric rings, with each ring's count chosen by chord spacing. In the development branch, rings contain opposite pairs; odd capacity is rounded down to an even number while preserving the minimum web. The first ordinary ring contains six holes regardless of boundary shape. The central circle remains single. Ring spacing equals the diameter of the circle enclosing a hole plus Web Thickness. This preserves the minimum web with Fixed, Radial, and Tangential Orientation, but packing is conservative for elongated and angular shapes. -В разрабатываемом режиме нескольких плоских областей размеры и формы остаются общими для всех источников. Раскладка привязана к проекции начала и осей компонента: копланарные области используют одинаковую фазу, включая Voronoi и Circular. Start Point проецируется на каждую плоскость. Возле каждой отдельной границы и её внутренних вырезов действует Edge Offset; соседние области не сливаются. Перекрывающиеся заполненные области отклоняются. Лимит Maximum Holes считается суммарно, включая отдельные обрезанные фрагменты одной ячейки в разных областях. Прежние описания автоматического центра относятся к одному источнику. Функция не выпущена и не прошла CAD-приёмку; подробности — [MULTI_REGION.md](MULTI_REGION.md). +Start Radius is measured to centers of the first ring; 0 adds one central hole. Holes may extend inside that radius. Radial rotates holes along the radius; Tangential follows the circumference. Hole Angle adds rotation in all modes. Pattern Angle rotates the pattern around the outer boundary's bounding-box center; X/Y Offset shifts that center in sketch axes without periodicity. Trim to Boundary and Edge Offset also apply to inner cutouts; ring radii are set before trimming. On a plane, exact equality with the offset is allowed: no hidden 0.001 mm allowance is added to Edge Offset. A cell touching the offset boundary is retained whole; an actual intersection requires trimming. -- Треугольник: сторона равностороннего треугольника. -- Прямоугольник: ширина и длина. -- Ромб: вертикальная и горизонтальная диагонали до поворота. -- Эллипс: полная малая и большая оси, большая должна быть больше малой. Это точный эллипс, а не прорезь с полукруглыми концами. -- Пятиугольник: диаметр описанной окружности. -- Восьмиугольник: расстояние между противоположными гранями. -- Крест: полная ширина/высота и ширина луча. -- Звезда: диаметр по внешним вершинам, число лучей, внутренний радиус в процентах от внешнего. +## Dimensions of new cells -Для дополнительных форм шаг сетки выбирается по габаритам повёрнутой фигуры, чтобы перемычка не стала меньше заданной. Это безопасная раскладка; плотнейшая упаковка треугольников с чередованием ориентации и смешанные мозаики не реализованы. При проверке отступов эллипса используется описанный многоугольник; это консервативный отбор целых ячеек. Выходной эскиз содержит точные эллипсы и эллиптические дуги. +In the developing multi-planar-region mode, dimensions and shapes are shared across sources. The layout is anchored to the projection of the component origin and axes: coplanar regions share a phase, including Voronoi and Circular. Start Point is projected onto each plane. Edge Offset applies near each separate boundary and its inner cutouts; neighboring regions are not merged. Overlapping filled regions are rejected. Maximum Holes is counted across all regions, including separate trimmed fragments of one cell in different regions. Earlier descriptions of the automatic center apply to a single source. At that stage the feature was unreleased and had not passed CAD acceptance; see [MULTI_REGION.md](MULTI_REGION.md). -## Voronoi +- Triangle: side of the equilateral triangle. +- Rectangle: width and length. +- Diamond: vertical and horizontal diagonals before rotation. +- Ellipse: full minor and major axes; the major axis must exceed the minor. This is an exact ellipse, not a slot with semicircular ends. +- Pentagon: diameter of the circumscribed circle. +- Octagon: distance between opposite faces. +- Cross: overall width/height and arm width. +- Star: diameter through outer vertices, number of points, and inner radius as a percentage of the outer radius. -Нерегулярные выпуклые многоугольники строятся по диаграмме Вороного. Исходные точки смещаются относительно квадратной решётки; плотность по области постоянна. Эта тринадцатая форма доступна с версии 0.2.0. +For additional shapes, grid pitch is selected from the rotated shape's bounds so the web does not fall below the specified value. This is a safe layout; densest alternating-orientation triangle packing and mixed tilings are not implemented. Ellipse clearance checks use a circumscribed polygon, conservatively selecting whole cells. The resulting sketch contains exact ellipses and elliptical arcs. -- **Cell Spacing** — номинальный шаг исходных точек, а не диаметр отверстия. Меньший шаг даёт больше ячеек; их реальные размеры различаются. -- **Irregularity (%)** — нерегулярность от 0 до 100%. При 0% получаются квадратные ячейки, при увеличении значения — более разнообразные многоугольники. -- **Seed** — целое число от 0 до 2147483647. Одинаковые источник, Seed и настройки дают одинаковую раскладку в превью и готовой модели. -- **New Pattern** — увеличивает Seed на единицу, сохраняя остальные настройки. -- **Round Corners** — включает скругление углов ячеек касательными круговыми дугами; по умолчанию выключено. **Corner Radius** — максимальный радиус, по умолчанию 0,5 мм. Слишком короткие фаски поглощаются скруглением вместо микроскопических дуг; радиус уменьшается только при недостаточной ширине отверстия. Контур строится смещением многоугольника внутрь и расширением кругом того же радиуса. Он остаётся внутри исходной ячейки и не уменьшает перемычку. -- **Web Thickness** — минимальная перемычка. Каждая ячейка отступает внутрь от своих границ на половину этого значения. Толстая перемычка может полностью поглотить маленькие ячейки. -- **Edge Offset**, **Trim to Boundary**, **Pattern Angle** и сдвиги X/Y действуют так же, как для остальных форм. Отдельный **Hole Angle** и обычный **Distribution** скрыты: многоугольники определяются общей диаграммой. +## Voronoi -Положение решётки отсчитывается от центра габаритов области в системе Pattern Angle. Сдвиги периодичны с периодом Cell Spacing. Изменение границы может переместить центр раскладки; Seed сам по себе не фиксирует её в мировых координатах. +Irregular convex polygons are constructed using a Voronoi diagram. Seed points are displaced relative to a square grid; density across the area is constant. This thirteenth shape has been available since 0.2.0. -Поддерживаются Fast/Full Preview, обычные профили, все операции Extrude, рамка и существующие внутренние вырезы. Контуры имеют прямые стороны и, при включённом Round Corners, точные круговые дуги. После обрезки новые выпуклые углы на стыках прямых и круговых дуг скругляются дополнительно. Радиус ограничивается локально, а временная BRep-проверка подтверждает, что отверстие не расширилось. Исходные вогнутые углы, внутренние замкнутые контуры, эллиптические и сплайновые участки границы сохраняются. В режиме целых отверстий отбор остаётся консервативным по исходному многоугольнику. При слишком плотной раскладке расчёт отклоняется до построения CAD; лимит отверстий остаётся общим для всех форм. +- **Cell Spacing** is nominal seed-point pitch, not hole diameter. Smaller spacing creates more cells; their actual sizes vary. +- **Irregularity (%)** ranges from 0 to 100%. At 0% cells are square; higher values produce more varied polygons. +- **Seed** is an integer from 0 to 2147483647. Identical source, Seed and settings produce the same layout in preview and final model. +- **New Pattern** increments Seed by one while retaining the other settings. +- **Round Corners** rounds cell corners with tangent circular arcs; off by default. **Corner Radius** is the maximum radius, 0.5 mm by default. Very short chamfers are absorbed by rounding instead of producing microscopic arcs; radius is reduced only when hole width is insufficient. The contour is built by offsetting the polygon inward and expanding it with a circle of the same radius. It remains inside the original cell and does not reduce the web. +- **Web Thickness** is the minimum web. Each cell is inset by half this value; a thick web can absorb small cells entirely. +- **Edge Offset**, **Trim to Boundary**, **Pattern Angle**, and X/Y offsets work as with the other shapes. Separate **Hole Angle** and ordinary **Distribution** are hidden because polygons are defined by the overall diagram. -## Источники производителей +The grid position is measured from the region's bounding-box center in the Pattern Angle frame. Offsets are periodic with Cell Spacing. Changing the boundary can move the layout center; Seed alone does not fix it in world coordinates. -- [Graepels — Standard Perforations](https://www.graepels.com/wp-content/uploads/2024/10/standard-perforation-sizes.pdf): круглые, квадратные, два типа щелей, ромбические, шестигранные и треугольные отверстия. -- [SCHÄFER — Perforation patterns](https://www.schaefer-lochbleche.com/en/offer/perforated-metal-from-stock/perforation-pattern/): форма, шаг, перемычка, ориентация, открытая площадь и прямое/шахматное расположение. -- [Hengda — Perforated metal](https://perforated-metal.net/perforatedmetal/aboutus.html): среди предлагаемых форм указаны ромбы, прямоугольники, кресты, восьмиугольники, треугольники, звёзды и овалы. -- [Dillinger — Special perforations](https://www.df-perforatedsheets.com/en/embossed-panels-special-perforations/special-perforations-embossed-plates): звёздные, цветочные и клеверные орнаменты, формованные отверстия. -- [Perfopol — Other perforation](https://www.perfopol.com/Other_perforation): клевер, жалюзийные, смешанные и другие специальные варианты. +Fast/Full Preview, ordinary profiles, all Extrude operations, the border, and existing inner cutouts are supported. Contours have straight sides and, with Round Corners, exact circular arcs. After trimming, new convex corners at straight/circular-arc junctions are additionally rounded. Radius is limited locally, and a temporary BRep check confirms the opening has not expanded. Original concave corners, inner closed contours, and elliptical and spline boundary segments are preserved. In whole-hole mode selection remains conservative against the original polygon. An overly dense layout is rejected before CAD construction; the hole limit remains shared across all shapes. -Каталожные сведения описывают промышленные изделия. Параметры плагина — геометрические настройки модели, а не рекомендация по прочности, акустике или технологии производства. +## Manufacturer sources -### Start Point и ориентация +- [Graepels — Standard Perforations](https://www.graepels.com/wp-content/uploads/2024/10/standard-perforation-sizes.pdf): round, square, two slot types, diamond, hexagonal and triangular holes. +- [SCHÄFER — Perforation patterns](https://www.schaefer-lochbleche.com/en/offer/perforated-metal-from-stock/perforation-pattern/): shape, pitch, web, orientation, open area and straight/staggered arrangement. +- [Hengda — Perforated metal](https://perforated-metal.net/perforatedmetal/aboutus.html): offered shapes include diamonds, rectangles, crosses, octagons, triangles, stars and ovals. +- [Dillinger — Special perforations](https://www.df-perforatedsheets.com/en/embossed-panels-special-perforations/special-perforations-embossed-plates): star, floral and clover ornaments and formed openings. +- [Perfopol — Other perforation](https://www.perfopol.com/Other_perforation): clover, louvered, mixed and other special variants. -**Start Point** выбирает точку эскиза, вершину или конструкционную точку штатным Select. Точка вне плоскости проецируется на Profiles. Без выбранной точки используется автоматический центр. X/Y Offset добавляют сдвиг: в осях раскладки для сеток/Voronoi и в осях эскиза для Circular. **Fixed**, **Radial** и **Tangential** задают ориентацию отверстий; Hole Angle добавляет поворот. Ориентация скрыта для кругов, а настройки колец — для Voronoi. Start Point доступен для всех раскладок. +Catalog information describes industrial products. Add-in parameters are geometric model settings, not recommendations for strength, acoustics or manufacturing processes. -### Ограничение области +### Start Point and orientation -Spread Radius удалён из диалога. Новые раскладки заполняют выбранную границу; область задаётся выбранной гранью, профилем или Boundary. Старые Feature сохраняют параметр Spread Radius и пересчёт для совместимости. +**Start Point** selects a sketch point, vertex, or construction point with native Select. A point outside the plane is projected onto Profiles. Without a selected point, the automatic center is used. X/Y Offset adds a shift in layout axes for grids/Voronoi and sketch axes for Circular. **Fixed**, **Radial**, and **Tangential** set hole orientation; Hole Angle adds rotation. Orientation is hidden for circles and ring settings for Voronoi. Start Point is available for all layouts. -### Криволинейные грани (разработка) +### Limiting the area -Размеры форм относятся к плоскому сечению прямого инструмента по нормали к поверхности. На цилиндре X следует окружности, Y — оси; на конусе Y следует образующей с физическим шагом, а число отверстий каждого ряда зависит от местной окружности и глубины инструмента. Rectangular сохраняет начальное угловое направление, Staggered сдвигает через ряд половину местного углового шага. К основанию добавляются отверстия; отдельные колонки разветвляются при изменении числа ячеек. На свободной поверхности используются локальные касательные оси, физическая длина сечений и обратное отображение длины в UV. Шаг повторяемых форм консервативно учитывает сближение инструментов по глубине; на двойной кривизне равномерность сразу по всем направлениям не гарантируется. Hole Angle поворачивает сечение. Например, Diameter 5 mm означает диаметр инструмента, а не постоянную длину дуги отверстия на поверхности. +Spread Radius was removed from the dialog. New layouts fill the selected boundary; the area is specified by a selected face, profile, or Boundary. Old Features retain the Spread Radius parameter and recompute for compatibility. -Voronoi сохраняет Cell Spacing, Irregularity, Seed/New Pattern и Round Corners. На цилиндре точки периодичны через 360°. Разделяющие плоскости между конечными инструментами защищают Web Thickness по глубине, включая сближение у почти замкнутого сектора. У повторяющихся форм размеры не уменьшаются: конфликтующие точки пропускаются. Это прямые инструменты, а не геодезическая диаграмма на поверхности. +### Curved faces (development) -Trim to Boundary сохраняет частичные отверстия; Edge Offset действует на исходную границу, зону и существующие вырезы. Точные проекции кривых сохраняются в маске. Вогнутое/вырождающееся смещение использует консервативное вычитание полос вдоль границы с дополнительным зазором 0,002 mm. Смещение в локальной проекции не является геодезическим. Circular и Pattern Angle доступны только для плоских источников; X/Y Offset сохраняются на кривых как фаза рисунка. +Shape dimensions refer to the planar cross-section of a straight tool along the surface normal. On a cylinder X follows the circumference and Y the axis; on a cone Y follows the generator with physical spacing, and each row's hole count depends on local circumference and tool depth. Rectangular retains the initial angular direction; Staggered shifts alternate rows by half the local angular pitch. Holes are added toward the base; individual columns branch as the cell count changes. On a freeform surface, local tangent axes, physical cross-section length, and inverse length-to-UV mapping are used. Repeating-shape pitch conservatively accounts for tools approaching through depth; uniformity in every direction is not guaranteed on double curvature. Hole Angle rotates the section. For example, Diameter 5 mm means tool diameter, not a constant hole arc length on the surface. -Distance, Offset, Flip Direction, One Side, Two Sides и Symmetric задают ограниченный прямой инструмент. Дно глухого отверстия плоское, а не на постоянной глубине от поверхности. Для сквозного отверстия задайте Distance немного больше толщины стенки и проверьте Full Preview. Цилиндрический/конический инструмент не должен пересекать ось. All, To Object, Taper и Perforated Panel на криволинейной грани недоступны. +Voronoi retains Cell Spacing, Irregularity, Seed/New Pattern, and Round Corners. On a cylinder points are periodic across 360°. Separating planes between finite tools protect Web Thickness through depth, including convergence near an almost closed sector. Repeating shapes are not reduced in size: conflicting points are skipped. These are straight tools, not a geodesic surface diagram. -Sketch создаёт фиксированные 3D-контуры, Extrude — фиксированные Base Feature/Combine, Feature — параметрический узел с зависимостями, пересчётом и Edit Feature. Подробнее — обе README. Сферы, торы, mesh и переходы между несколькими гранями исключены. +Trim to Boundary retains partial openings; Edge Offset applies to the original boundary, zone, and existing cutouts. Exact curve projections are preserved in the mask. A concave/degenerate offset uses conservative subtraction of strips along the boundary with an additional 0.002 mm clearance. Offset in the local projection is not geodesic. Circular and Pattern Angle are available only for planar sources; X/Y Offset remains on curved surfaces as pattern phase. -NURBS-грани с вырожденной границей в виде одной точки проверяются по внутренним параметрам. Участки с неопределённым локальным базисом и зоны обрезки, включающие эту точку, пропускаются отдельно; остальная грань остаётся доступной. Лимит Maximum Holes сохраняется: для больших площадей его требуется увеличить явно. +Distance, Offset, Flip Direction, One Side, Two Sides, and Symmetric define a bounded straight tool. The bottom of a blind hole is flat, not at constant depth from the surface. For a through hole, set Distance slightly greater than wall thickness and inspect Full Preview. A cylindrical/conical tool must not cross the axis. All, To Object, Taper, and Perforated Panel are unavailable on a curved face. -## Новые Distribution в рабочей ветке +Sketch creates fixed 3D contours, Extrude creates fixed Base Feature/Combine, and Feature creates a parametric node with dependencies, recompute, and Edit Feature. See both READMEs for details. Spheres, tori, mesh, and transitions across multiple faces are excluded. -Contour, Fan, Phyllotaxis, Poisson Disk, Wave, Chevron, Running Bond и Between Curves используют существующие 12 повторяемых форм и их размеры. Voronoi с ними не совмещается. Минимальная перемычка проверяется по описанным окружностям реальных форм, независимо от поворота; это консервативная упаковка с возможными пропусками кандидатов. Along Spacing/Row Spacing при 0 автоматические, меньший шаг повышается до безопасного минимума. Новые генераторы подключены к общим путям обрезки и Edge Offset. +NURBS faces with a degenerate boundary at a single point are checked using interior parameters. Areas with an undefined local basis and trim regions containing that point are skipped separately; the remainder of the face stays available. Maximum Holes still applies and must be explicitly increased for large areas. -Contour — приближённые уровни внутреннего расстояния с явным допуском, не точный CAD-offset. Between Curves — ограниченный контракт двух открытых плоских направляющих одного компонента; сложные/пересекающиеся/неплоские полосы не заявлены. **Текущая CAD/UI-приёмка записана в [RELEASE_INTEGRATION.md](RELEASE_INTEGRATION.md).** Полная семантика полей, допуски и проверки: [LAYOUT_VARIANTS.md](LAYOUT_VARIANTS.md). +## New Distributions in the working branch -## Раскладка вдоль кривой — в разработке +Contour, Fan, Phyllotaxis, Poisson Disk, Wave, Chevron, Running Bond, and Between Curves use the existing 12 repeating shapes and their dimensions. They do not combine with Voronoi. Minimum web is checked against the circumscribed circles of actual shapes regardless of rotation; this is conservative packing and may skip candidates. Along Spacing/Row Spacing at 0 are automatic; smaller spacing is raised to a safe minimum. The new generators are connected to shared trimming and Edge Offset paths. -Along Path использует одну линию, дугу, окружность или сплайн в плоскости источника. Path Spacing — расстояние между центрами по длине кривой, независимо от размера отверстия и Web Thickness. Минимальная перемычка проверяется между всеми сближенными отверстиями, включая повороты и шов: для кругов точно, для остальных форм по описанным окружностям. Поэтому некруглые формы могут требовать большего шага, чем при проверке точных контуров. Конфликт выдаёт ошибку; автоматического прореживания нет. +Contour uses approximate inner-distance levels with an explicit tolerance, not an exact CAD offset. Between Curves is a bounded contract for two open planar guides in one component; complex, intersecting, or nonplanar strips are not claimed. **Current CAD/UI acceptance is recorded in [RELEASE_INTEGRATION.md](RELEASE_INTEGRATION.md).** Full control semantics, tolerances, and checks: [LAYOUT_VARIANTS.md](LAYOUT_VARIANTS.md). -Start Offset, End Offset и Position измеряются до центров, а не до края отверстия. Closed Path не дублирует шов; фиксированный шаг не перераспределяется, поэтому короткий остаток у шва может потребовать изменения параметров. Полная область, её внутренние вырезы, Edge Offset и точная Trim to Boundary сохраняют существующий смысл. Функция не выпущена и не проверялась в Fusion; [подробный контракт и будущая приёмка](CURVE_LAYOUT.md). +## Along Path layout — in development +Along Path uses one line, arc, circle, or spline in the source plane. Path Spacing is center-to-center distance along the curve, independent of hole size and Web Thickness. Minimum web is checked between all nearby holes, including turns and the seam: exactly for circles, and using circumscribed circles for other shapes. Noncircular shapes may therefore require greater spacing than with exact contour checks. Conflicts produce an error; holes are not automatically thinned. -## Совместимость раскладок и нескольких поверхностей +Start Offset, End Offset, and Position are measured to centers, not hole edges. Closed Path does not duplicate the seam; fixed spacing is not redistributed, so a short seam remainder may require parameter changes. The complete region, its inner cutouts, Edge Offset, and exact Trim to Boundary retain their existing meaning. At this stage the feature was unreleased and had not been tested in Fusion; [detailed contract and planned acceptance](CURVE_LAYOUT.md). -Актуальная матрица — в обеих README и [RELEASE_INTEGRATION.md](RELEASE_INTEGRATION.md). На цилиндре добавлены Running Bond и Poisson Disk; на конусе — Running Bond с местной вместимостью ряда; на свободной поверхности — Running Bond, Poisson Disk, Wave и Chevron. Центрические раскладки и плоские направляющие остаются для плоских источников. Неподдержанное сочетание отклоняется явно, без подмены другой сеткой. +## Compatibility of layouts and multiple surfaces -Несколько областей выбираются только одного типа: плоские, цилиндрические, конические или свободные. Проверка действует и при выборе, и при построении/пересчёте Feature. Предел Maximum Holes общий. Все области подготавливаются до изменения тела; перемычки между кривыми областями проверяются по конечным инструментам. Отверстия при конфликте не уменьшаются. +The current matrix is in both READMEs and [RELEASE_INTEGRATION.md](RELEASE_INTEGRATION.md). Running Bond and Poisson Disk were added on cylinders; Running Bond with local row capacity on cones; and Running Bond, Poisson Disk, Wave, and Chevron on freeform surfaces. Centered layouts and planar guides remain limited to planar sources. Unsupported combinations are rejected explicitly without substituting another grid. +Multiple regions must have one surface type: planar, cylindrical, conical, or freeform. This is checked during selection and Feature construction/recompute. Maximum Holes is shared. All regions are prepared before modifying the body; webs between curved regions are checked using finite tools. Conflicting holes are not reduced in size. -## Органические поля в рабочей ветке +## Organic fields in the working branch -Smooth Noise, Reaction Diffusion, Directional Fibers, Ridged Noise / Topographic, Gyroid Field и Blue Noise / Size Gradient расположены в Hole Shape перед последним Voronoi. Первые пять создают ограниченные плавные поля с Pattern Scale, Field Fill, Direction и Seed; Blue Noise — круги разных радиусов с Maximum Diameter, Size Variation и знаковым Size Gradient. Field Fill задаёт исходный квантиль, а не измеренную открытую площадь готового тела. +Smooth Noise, Reaction Diffusion, Directional Fibers, Ridged Noise / Topographic, Gyroid Field, and Blue Noise / Size Gradient are in Hole Shape before the final Voronoi. The first five create bounded smooth fields with Pattern Scale, Field Fill, Direction, and Seed; Blue Noise produces circles of different radii with Maximum Diameter, Size Variation, and signed Size Gradient. Field Fill sets the initial quantile, not the measured open area of the finished body. -Это самостоятельные поля: Circular, Along Path и дополнительные Distribution с ними не совмещаются. Все шесть используют общие пути Fast/Full Preview, обрезки/Edge Offset, Sketch/Extrude/Feature на плоскости, цилиндре, конусе и регулярных частях freeform. Островки материала соединяются мостиками; реальная перемычка готовых контуров проверяется отдельно. На кривых сохраняется перемычка между конечными прямыми инструментами, возможны местные пропуски и разрежение у швов, вершины и высокой кривизны. Несколько областей — только одного типа. +These are independent fields: Circular, Along Path, and additional Distributions do not combine with them. All six use shared Fast/Full Preview, trimming/Edge Offset, and Sketch/Extrude/Feature paths on planes, cylinders, cones, and regular freeform areas. Material islands are joined with bridges; the actual web between finished contours is checked separately. On curved surfaces a web is maintained between finite straight tools, with possible local omissions and thinning near seams, the apex, and high curvature. Multiple regions must have one surface type. -[Полный контракт алгоритмов, размеров, допусков, стоимости, совместимости и проверок](ORGANIC_PATTERNS.md). Возможности не опубликованы в 1.0.1. +[Full contract for algorithms, dimensions, tolerances, cost, compatibility, and validation](ORGANIC_PATTERNS.md). These features were not published in 1.0.1. diff --git a/docs/PERFORATIONS.ru.md b/docs/PERFORATIONS.ru.md new file mode 100644 index 0000000..8792d9b --- /dev/null +++ b/docs/PERFORATIONS.ru.md @@ -0,0 +1,115 @@ +# Формы перфорации + +[English](PERFORATIONS.md) + +> **Исторический справочный материал разработки.** Документ сочетает поведение Perfora 1.0.0 с заметками разработки; утверждения о невыпущенных или непроверенных функциях относятся к исходному этапу. Состав выпущенной 1.1.0 и фактическая приёмка — в [заметках к выпуску](releases/v1.1.0.ru.md) и [отчёте интеграции](RELEASE_INTEGRATION.md). + +По каталогам производителей, проверено 23 октября 2026 года. + +Перфорация задаётся не только формой отверстия: важны размер, перемычка, шаг, прямое, шахматное или круговое расположение, поворот, отступ и доля открытой площади. В плагине форма ячейки отделена от расположения сетки и операции Extrude. + +| Тип | Варианты | Поддержка в Perfora 1.0.0 | +|---|---|---| +| Базовые отверстия | Круг, квадрат, шестигранник | Диаметр, сторона или размер между гранями | +| Щелевые | Прямоугольная щель и прорезь с круглыми концами | Прямоугольник и прорезь; ширина и полная длина | +| Геометрические | Треугольник, ромб, эллипс, пятиугольник, восьмиугольник | Отдельные формы с поворотом | +| Декоративные | Звёзды, кресты, клевер, цветочные и смешанные узоры | Крест с шириной луча; звезда с 3–12 лучами и внутренним радиусом | +| Формованные | Жалюзийные, вытяжные и рельефные отверстия | Требуют отдельной трёхмерной операции; плоский контур и Extrude не воспроизводят такую геометрию | +| Рисунки и переменная плотность | Несколько размеров/форм, изображения из отверстий | Отдельное возможное расширение; текущая команда повторяет одну форму и размер | + +## Круговая раскладка + +Distribution → Circular доступна для 12 повторяемых форм; Voronoi использует собственное распределение. Отверстия размещаются концентрическими кольцами, число отверстий на каждом кольце подбирается по хорде. В ветке разработки кольца содержат противоположные пары; нечётная вместимость округляется вниз до чётной, сохраняя минимальную перемычку. Первое обычное кольцо содержит шесть отверстий независимо от формы границы. Центральный круг остаётся одиночным. Расстояние между кольцами равно диаметру описанного вокруг отверстия круга плюс Web Thickness. Это сохраняет минимальную перемычку при Fixed, Radial и Tangential Orientation, но для вытянутых и угловатых форм упаковка консервативна. + +Start Radius измеряется до центров первого кольца; 0 добавляет одно центральное отверстие. Отверстия могут выступать внутрь этого радиуса. Radial поворачивает отверстия по радиусу, Tangential — вдоль окружности. Hole Angle задаёт дополнительный поворот во всех режимах. Pattern Angle поворачивает рисунок вокруг центра габаритов внешней границы, X/Y Offset сдвигают этот центр в осях эскиза без периодичности. Trim to Boundary и Edge Offset действуют и на внутренние вырезы; радиусы колец задаются до обрезки. На плоскости точное равенство отступу допустимо: скрытый запас 0,001 mm к Edge Offset не добавляется. Касание смещённой границы сохраняет целую ячейку, а действительное пересечение требует обрезки. + +## Размеры новых ячеек + +В разрабатываемом режиме нескольких плоских областей размеры и формы остаются общими для всех источников. Раскладка привязана к проекции начала и осей компонента: копланарные области используют одинаковую фазу, включая Voronoi и Circular. Start Point проецируется на каждую плоскость. Возле каждой отдельной границы и её внутренних вырезов действует Edge Offset; соседние области не сливаются. Перекрывающиеся заполненные области отклоняются. Лимит Maximum Holes считается суммарно, включая отдельные обрезанные фрагменты одной ячейки в разных областях. Прежние описания автоматического центра относятся к одному источнику. Функция не выпущена и не прошла CAD-приёмку; подробности — [MULTI_REGION.md](MULTI_REGION.md). + +- Треугольник: сторона равностороннего треугольника. +- Прямоугольник: ширина и длина. +- Ромб: вертикальная и горизонтальная диагонали до поворота. +- Эллипс: полная малая и большая оси, большая должна быть больше малой. Это точный эллипс, а не прорезь с полукруглыми концами. +- Пятиугольник: диаметр описанной окружности. +- Восьмиугольник: расстояние между противоположными гранями. +- Крест: полная ширина/высота и ширина луча. +- Звезда: диаметр по внешним вершинам, число лучей, внутренний радиус в процентах от внешнего. + +Для дополнительных форм шаг сетки выбирается по габаритам повёрнутой фигуры, чтобы перемычка не стала меньше заданной. Это безопасная раскладка; плотнейшая упаковка треугольников с чередованием ориентации и смешанные мозаики не реализованы. При проверке отступов эллипса используется описанный многоугольник; это консервативный отбор целых ячеек. Выходной эскиз содержит точные эллипсы и эллиптические дуги. + +## Voronoi + +Нерегулярные выпуклые многоугольники строятся по диаграмме Вороного. Исходные точки смещаются относительно квадратной решётки; плотность по области постоянна. Эта тринадцатая форма доступна с версии 0.2.0. + +- **Cell Spacing** — номинальный шаг исходных точек, а не диаметр отверстия. Меньший шаг даёт больше ячеек; их реальные размеры различаются. +- **Irregularity (%)** — нерегулярность от 0 до 100%. При 0% получаются квадратные ячейки, при увеличении значения — более разнообразные многоугольники. +- **Seed** — целое число от 0 до 2147483647. Одинаковые источник, Seed и настройки дают одинаковую раскладку в превью и готовой модели. +- **New Pattern** — увеличивает Seed на единицу, сохраняя остальные настройки. +- **Round Corners** — включает скругление углов ячеек касательными круговыми дугами; по умолчанию выключено. **Corner Radius** — максимальный радиус, по умолчанию 0,5 мм. Слишком короткие фаски поглощаются скруглением вместо микроскопических дуг; радиус уменьшается только при недостаточной ширине отверстия. Контур строится смещением многоугольника внутрь и расширением кругом того же радиуса. Он остаётся внутри исходной ячейки и не уменьшает перемычку. +- **Web Thickness** — минимальная перемычка. Каждая ячейка отступает внутрь от своих границ на половину этого значения. Толстая перемычка может полностью поглотить маленькие ячейки. +- **Edge Offset**, **Trim to Boundary**, **Pattern Angle** и сдвиги X/Y действуют так же, как для остальных форм. Отдельный **Hole Angle** и обычный **Distribution** скрыты: многоугольники определяются общей диаграммой. + +Положение решётки отсчитывается от центра габаритов области в системе Pattern Angle. Сдвиги периодичны с периодом Cell Spacing. Изменение границы может переместить центр раскладки; Seed сам по себе не фиксирует её в мировых координатах. + +Поддерживаются Fast/Full Preview, обычные профили, все операции Extrude, рамка и существующие внутренние вырезы. Контуры имеют прямые стороны и, при включённом Round Corners, точные круговые дуги. После обрезки новые выпуклые углы на стыках прямых и круговых дуг скругляются дополнительно. Радиус ограничивается локально, а временная BRep-проверка подтверждает, что отверстие не расширилось. Исходные вогнутые углы, внутренние замкнутые контуры, эллиптические и сплайновые участки границы сохраняются. В режиме целых отверстий отбор остаётся консервативным по исходному многоугольнику. При слишком плотной раскладке расчёт отклоняется до построения CAD; лимит отверстий остаётся общим для всех форм. + +## Источники производителей + +- [Graepels — Standard Perforations](https://www.graepels.com/wp-content/uploads/2024/10/standard-perforation-sizes.pdf): круглые, квадратные, два типа щелей, ромбические, шестигранные и треугольные отверстия. +- [SCHÄFER — Perforation patterns](https://www.schaefer-lochbleche.com/en/offer/perforated-metal-from-stock/perforation-pattern/): форма, шаг, перемычка, ориентация, открытая площадь и прямое/шахматное расположение. +- [Hengda — Perforated metal](https://perforated-metal.net/perforatedmetal/aboutus.html): среди предлагаемых форм указаны ромбы, прямоугольники, кресты, восьмиугольники, треугольники, звёзды и овалы. +- [Dillinger — Special perforations](https://www.df-perforatedsheets.com/en/embossed-panels-special-perforations/special-perforations-embossed-plates): звёздные, цветочные и клеверные орнаменты, формованные отверстия. +- [Perfopol — Other perforation](https://www.perfopol.com/Other_perforation): клевер, жалюзийные, смешанные и другие специальные варианты. + +Каталожные сведения описывают промышленные изделия. Параметры плагина — геометрические настройки модели, а не рекомендация по прочности, акустике или технологии производства. + +### Start Point и ориентация + +**Start Point** выбирает точку эскиза, вершину или конструкционную точку штатным Select. Точка вне плоскости проецируется на Profiles. Без выбранной точки используется автоматический центр. X/Y Offset добавляют сдвиг: в осях раскладки для сеток/Voronoi и в осях эскиза для Circular. **Fixed**, **Radial** и **Tangential** задают ориентацию отверстий; Hole Angle добавляет поворот. Ориентация скрыта для кругов, а настройки колец — для Voronoi. Start Point доступен для всех раскладок. + +### Ограничение области + +Spread Radius удалён из диалога. Новые раскладки заполняют выбранную границу; область задаётся выбранной гранью, профилем или Boundary. Старые Feature сохраняют параметр Spread Radius и пересчёт для совместимости. + +### Криволинейные грани (разработка) + +Размеры форм относятся к плоскому сечению прямого инструмента по нормали к поверхности. На цилиндре X следует окружности, Y — оси; на конусе Y следует образующей с физическим шагом, а число отверстий каждого ряда зависит от местной окружности и глубины инструмента. Rectangular сохраняет начальное угловое направление, Staggered сдвигает через ряд половину местного углового шага. К основанию добавляются отверстия; отдельные колонки разветвляются при изменении числа ячеек. На свободной поверхности используются локальные касательные оси, физическая длина сечений и обратное отображение длины в UV. Шаг повторяемых форм консервативно учитывает сближение инструментов по глубине; на двойной кривизне равномерность сразу по всем направлениям не гарантируется. Hole Angle поворачивает сечение. Например, Diameter 5 mm означает диаметр инструмента, а не постоянную длину дуги отверстия на поверхности. + +Voronoi сохраняет Cell Spacing, Irregularity, Seed/New Pattern и Round Corners. На цилиндре точки периодичны через 360°. Разделяющие плоскости между конечными инструментами защищают Web Thickness по глубине, включая сближение у почти замкнутого сектора. У повторяющихся форм размеры не уменьшаются: конфликтующие точки пропускаются. Это прямые инструменты, а не геодезическая диаграмма на поверхности. + +Trim to Boundary сохраняет частичные отверстия; Edge Offset действует на исходную границу, зону и существующие вырезы. Точные проекции кривых сохраняются в маске. Вогнутое/вырождающееся смещение использует консервативное вычитание полос вдоль границы с дополнительным зазором 0,002 mm. Смещение в локальной проекции не является геодезическим. Circular и Pattern Angle доступны только для плоских источников; X/Y Offset сохраняются на кривых как фаза рисунка. + +Distance, Offset, Flip Direction, One Side, Two Sides и Symmetric задают ограниченный прямой инструмент. Дно глухого отверстия плоское, а не на постоянной глубине от поверхности. Для сквозного отверстия задайте Distance немного больше толщины стенки и проверьте Full Preview. Цилиндрический/конический инструмент не должен пересекать ось. All, To Object, Taper и Perforated Panel на криволинейной грани недоступны. + +Sketch создаёт фиксированные 3D-контуры, Extrude — фиксированные Base Feature/Combine, Feature — параметрический узел с зависимостями, пересчётом и Edit Feature. Подробнее — обе README. Сферы, торы, mesh и переходы между несколькими гранями исключены. + +NURBS-грани с вырожденной границей в виде одной точки проверяются по внутренним параметрам. Участки с неопределённым локальным базисом и зоны обрезки, включающие эту точку, пропускаются отдельно; остальная грань остаётся доступной. Лимит Maximum Holes сохраняется: для больших площадей его требуется увеличить явно. + +## Новые Distribution в рабочей ветке + +Contour, Fan, Phyllotaxis, Poisson Disk, Wave, Chevron, Running Bond и Between Curves используют существующие 12 повторяемых форм и их размеры. Voronoi с ними не совмещается. Минимальная перемычка проверяется по описанным окружностям реальных форм, независимо от поворота; это консервативная упаковка с возможными пропусками кандидатов. Along Spacing/Row Spacing при 0 автоматические, меньший шаг повышается до безопасного минимума. Новые генераторы подключены к общим путям обрезки и Edge Offset. + +Contour — приближённые уровни внутреннего расстояния с явным допуском, не точный CAD-offset. Between Curves — ограниченный контракт двух открытых плоских направляющих одного компонента; сложные/пересекающиеся/неплоские полосы не заявлены. **Текущая CAD/UI-приёмка записана в [RELEASE_INTEGRATION.md](RELEASE_INTEGRATION.md).** Полная семантика полей, допуски и проверки: [LAYOUT_VARIANTS.md](LAYOUT_VARIANTS.md). + +## Раскладка вдоль кривой — в разработке + +Along Path использует одну линию, дугу, окружность или сплайн в плоскости источника. Path Spacing — расстояние между центрами по длине кривой, независимо от размера отверстия и Web Thickness. Минимальная перемычка проверяется между всеми сближенными отверстиями, включая повороты и шов: для кругов точно, для остальных форм по описанным окружностям. Поэтому некруглые формы могут требовать большего шага, чем при проверке точных контуров. Конфликт выдаёт ошибку; автоматического прореживания нет. + +Start Offset, End Offset и Position измеряются до центров, а не до края отверстия. Closed Path не дублирует шов; фиксированный шаг не перераспределяется, поэтому короткий остаток у шва может потребовать изменения параметров. Полная область, её внутренние вырезы, Edge Offset и точная Trim to Boundary сохраняют существующий смысл. Функция не выпущена и не проверялась в Fusion; [подробный контракт и будущая приёмка](CURVE_LAYOUT.md). + + +## Совместимость раскладок и нескольких поверхностей + +Актуальная матрица — в обеих README и [RELEASE_INTEGRATION.md](RELEASE_INTEGRATION.md). На цилиндре добавлены Running Bond и Poisson Disk; на конусе — Running Bond с местной вместимостью ряда; на свободной поверхности — Running Bond, Poisson Disk, Wave и Chevron. Центрические раскладки и плоские направляющие остаются для плоских источников. Неподдержанное сочетание отклоняется явно, без подмены другой сеткой. + +Несколько областей выбираются только одного типа: плоские, цилиндрические, конические или свободные. Проверка действует и при выборе, и при построении/пересчёте Feature. Предел Maximum Holes общий. Все области подготавливаются до изменения тела; перемычки между кривыми областями проверяются по конечным инструментам. Отверстия при конфликте не уменьшаются. + + +## Органические поля в рабочей ветке + +Smooth Noise, Reaction Diffusion, Directional Fibers, Ridged Noise / Topographic, Gyroid Field и Blue Noise / Size Gradient расположены в Hole Shape перед последним Voronoi. Первые пять создают ограниченные плавные поля с Pattern Scale, Field Fill, Direction и Seed; Blue Noise — круги разных радиусов с Maximum Diameter, Size Variation и знаковым Size Gradient. Field Fill задаёт исходный квантиль, а не измеренную открытую площадь готового тела. + +Это самостоятельные поля: Circular, Along Path и дополнительные Distribution с ними не совмещаются. Все шесть используют общие пути Fast/Full Preview, обрезки/Edge Offset, Sketch/Extrude/Feature на плоскости, цилиндре, конусе и регулярных частях freeform. Островки материала соединяются мостиками; реальная перемычка готовых контуров проверяется отдельно. На кривых сохраняется перемычка между конечными прямыми инструментами, возможны местные пропуски и разрежение у швов, вершины и высокой кривизны. Несколько областей — только одного типа. + +[Полный контракт алгоритмов, размеров, допусков, стоимости, совместимости и проверок](ORGANIC_PATTERNS.ru.md). Возможности не опубликованы в 1.0.1. diff --git a/docs/README_REFERENCE.ru.md b/docs/README_REFERENCE.ru.md index f8d1aad..6a6ade2 100644 --- a/docs/README_REFERENCE.ru.md +++ b/docs/README_REFERENCE.ru.md @@ -95,7 +95,7 @@ | Протяжённость | One Side, Two Sides, Symmetric; расстояние, насквозь, до объекта в поддерживаемых режимах | | Предпросмотр | Быстрые кэшированные контуры для настройки; точный CAD-результат для проверки выдавливания | -[Размеры отверстий и особенности геометрии](PERFORATIONS.md). Интерфейс на английском с привычными названиями операций Fusion. Сторонние пакеты Python не нужны. +[Размеры отверстий и особенности геометрии](PERFORATIONS.ru.md). Интерфейс на английском с привычными названиями операций Fusion. Сторонние пакеты Python не нужны. У всех числовых полей есть начальные значения. Если оставить поле пустым, примерно через секунду оно вернётся к своему дефолту; при этом можно сразу набрать новое значение после очистки. Явный 0 сохраняется, непустые ошибочные выражения не заменяются. Поддерживаются единицы, вычисления и параметры текущего документа Fusion; для целочисленных значений сохраняются ограничения диапазона. @@ -123,7 +123,7 @@ Cell Spacing задаёт номинальный шаг исходных точ Эти формы определяют собственное ограниченное поле; Distribution и Hole Angle скрыты. Pattern Angle поворачивает поле в осях эскиза. На кривой грани 0° следует окружному направлению развёрнутой карты, а 90° — осевому направлению или меридиану, в том числе для волокон. Все шесть подключены к Sketch, Extrude, Feature, Fast/Full Preview, Trim to Boundary и отступам вокруг внутренних вырезов на плоскости, цилиндре, конусе и регулярной свободной поверхности. Несколько областей по-прежнему выбираются только одного типа. На кривых это конечные прямые инструменты с консервативной защитой перемычки по глубине и у шва; высокая кривизна и вершина конуса могут разрежать рисунок. -Островки материала соединяются до выделения контуров; длинные прорези получают мостики. Конфликтующие мелкие фрагменты пропускаются ради перемычки между готовыми контурами. При нулевом краевом отступе фрагменты отверстий, отрезающие материал, сохраняются сплошными. Бюджеты дискретизации и контуров ограничивают стоимость CAD и дают понятную ошибку. [Алгоритмы, поля, поведение поверхностей и проверки →](ORGANIC_PATTERNS.md) +Островки материала соединяются до выделения контуров; длинные прорези получают мостики. Конфликтующие мелкие фрагменты пропускаются ради перемычки между готовыми контурами. При нулевом краевом отступе фрагменты отверстий, отрезающие материал, сохраняются сплошными. Бюджеты дискретизации и контуров ограничивают стоимость CAD и дают понятную ошибку. [Алгоритмы, поля, поведение поверхностей и проверки →](ORGANIC_PATTERNS.ru.md) ## Несколько областей @@ -275,7 +275,7 @@ Voronoi сохраняет собственное распределение д Несколько областей поддерживают Sketch, Extrude и один параметрический узел Feature. Плоские копланарные области используют общую фазу; криволинейные области — собственные локальные нормали. Все области готовятся до первого изменения тела. Для соседних кривых областей консервативная проверка конечных инструментов отклоняет конфликт, сохраняя размер отверстий. Intersect требует отдельное целевое тело для каждой области. New Component доступен для одиночной области. -Включено в **1.1.0**. Фактическая приёмка и ограничения: [RELEASE_INTEGRATION.md](RELEASE_INTEGRATION.md) и [шумы и пересчёт](ORGANIC_PATTERNS.md). +Включено в **1.1.0**. Фактическая приёмка и ограничения: [RELEASE_INTEGRATION.md](RELEASE_INTEGRATION.md) и [шумы и пересчёт](ORGANIC_PATTERNS.ru.md). ## Разработка From baee4796aaaf46a6cff21d85a37cf6a4c367b8a9 Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 16:18:22 +0300 Subject: [PATCH 08/10] docs: provide bilingual playground guide --- demo/README.md | 90 +++++++++++-------------------------- demo/README.ru.md | 85 +++++++++++++++++++++++++++++++++++ docs/README_REFERENCE.ru.md | 2 +- 3 files changed, 112 insertions(+), 65 deletions(-) create mode 100644 demo/README.ru.md diff --git a/demo/README.md b/demo/README.md index 02c15a4..186fd24 100644 --- a/demo/README.md +++ b/demo/README.md @@ -1,83 +1,45 @@ # Perfora — Pattern playground -Публичное браузерное демо и штатный стенд быстрой визуальной проверки паттернов. -Fusion и браузер используют **одно геометрическое ядро Perfora**. Исходники -`Perfora/geometry.py`, `organic.py`, `distributions.py`, `distribution_fields.py`, `curves.py` -и `curve_layout.py` встраиваются в страницу без изменения и исполняются в -Python через Pyodide 0.27.7, в отдельном Web Worker. В JavaScript остаются ввод, -отображение готовых контуров и ссылки. Экспорт по решению пользователя отсутствует. Отдельной реализации раскладок -на JavaScript нет. Состав и SHA-256 модулей доступны в `perforaDemo.source`. +[Русская версия](README.ru.md) -## Возможности +A public browser demo and standard bench for quick visual pattern checks. Fusion and the browser use **the same Perfora geometry kernel**. The sources `Perfora/geometry.py`, `organic.py`, `distributions.py`, `distribution_fields.py`, `curves.py`, and `curve_layout.py` are embedded in the page unchanged and executed in Python via Pyodide 0.27.7 in a separate Web Worker. JavaScript handles input, display of completed contours, and links. Export was excluded by user decision. There is no separate JavaScript implementation of layouts. Module composition and SHA-256 values are available in `perforaDemo.source`. -- Pattern: 12 повторяемых форм и 11 семейств Distribution. -- Noise: Smooth Noise, Reaction Diffusion, Directional Fibers, Topographic, - Gyroid Field, Blue Noise и последним Voronoi. Distribution скрыта. -- Running Bond объединён с Staggered; отдельного управления Row Shift нет. -- Граница Rectangle/Rounded/Circle, размеры панели, размеры отверстий, - Web Thickness, Edge Offset, ориентация и параметры выбранного рисунка. -- Cell Size и Web Thickness вместо процента заполнения; у Voronoi сохраняются - Cell Spacing, Irregularity и Round Corners. Seed/New Pattern и ссылки с параметрами. -- Геометрия пересчитывается в браузере; сервер вычислений и API-ключи не нужны. - Первый запуск требует интернета для загрузки закреплённой версии Pyodide с - jsDelivr. Страница содержит готовый первый рисунок, поэтому не открывается - пустой во время загрузки. Контуры панели не отправляются на сервер. +## Features -Все шесть шумовых форм используют общее Python-ядро. Add Bridges относится -к первым пяти полям и включается отдельно от Web Thickness. У обычных Distribution -дополнительных мостиков нет. +- Pattern: 12 repeating shapes and 11 Distribution families. +- Noise: Smooth Noise, Reaction Diffusion, Directional Fibers, Topographic, Gyroid Field, Blue Noise, and Voronoi last. Distribution is hidden. +- Running Bond is combined with Staggered; there is no separate Row Shift control. +- Rectangle/Rounded/Circle boundary, panel and hole dimensions, Web Thickness, Edge Offset, orientation, and selected-pattern parameters. +- Cell Size and Web Thickness instead of fill percentage; Voronoi retains Cell Spacing, Irregularity, and Round Corners. Seed/New Pattern and links with parameters are supported. +- Geometry is recalculated in the browser; no compute server or API keys are needed. The first run requires internet access to load the pinned Pyodide version from jsDelivr. The page contains a ready first pattern, so it does not open empty during loading. Panel contours are not sent to a server. -## Сборка и локальный запуск +All six noise shapes use the shared Python kernel. Add Bridges applies to the first five fields and is enabled separately from Web Thickness. Ordinary Distributions have no additional bridges. + +## Build and run locally ```sh python3 scripts/build_web_demo.py python3 -m http.server 8768 --bind 127.0.0.1 ``` -Откройте `http://127.0.0.1:8768/demo/`. Единственный файл для хостинга — -`demo/index.html`: оформление, логотип, Python-модули и стартовые образцы уже -встроены. Его можно разместить в артефакте GitHub Pages либо другом статическом -хостинге с HTTPS. Для локального запуска предпочтителен HTTP-сервер; ограничения -`file://`, Web Worker и буфера обмена зависят от браузера. Подготовка страницы -не является публикацией: push, настройка Pages и запуск deployment выполняются -только по отдельному указанию пользователя. +Open `http://127.0.0.1:8768/demo/`. The only file needed for hosting is `demo/index.html`: styling, logo, Python modules, and initial examples are already embedded. It can be hosted in a GitHub Pages artifact or another static HTTPS host. An HTTP server is preferred locally; `file://`, Web Worker, and clipboard restrictions vary by browser. Preparing the page is not publication: push, Pages setup, and deployment are performed only on separate user instruction. -Сборщик не меняет установку Fusion, не требует сторонних Python-пакетов и не -загружает зависимости. Версия Pyodide закреплена в `worker.js`; при её смене -повторите реальную проверку браузера. [Pyodide](https://github.com/pyodide/pyodide) -загружается отдельно и сохраняет собственные условия лицензирования. +The builder does not modify the Fusion installation, require third-party Python packages, or download dependencies. The Pyodide version is pinned in `worker.js`; repeat real browser validation when changing it. [Pyodide](https://github.com/pyodide/pyodide) is loaded separately and retains its own license terms. -## Проверка изменений +## Checking changes -1. Изменяйте алгоритмы в общем Python-ядре. Новую версию рисунка сохраняйте - явно; прежние Feature продолжают использовать прежнюю ревизию. -2. Выполните `python3 -m unittest discover -s tests -v`, пересоберите страницу. - `tests/test_web_demo.py` проверяет реальные контуры, все формы и семейства, - скрытые поля, ограничения и точное встраивание исходников. -3. Откройте свежую страницу. `browser-smoke.js` содержит сценарий для Playwright: - все Distribution, все формы, изменение параметров, восстановление - ссылки, ошибочный ввод, Reset и узкий экран. Он создаёт отдельную вкладку и - возвращает параметры и хеши полученных контуров. Сравните хеши/координаты с - результатом `demo.engine.compute()` на тех же входных данных. Визуально - просмотрите затронутые паттерны, обычный и узкий экраны. -4. Затем выполните относящуюся к изменению CAD-приёмку из `CONTRIBUTING.md`. - Веб-проверка не подтверждает BRep, операции, швы криволинейных поверхностей, - нативный диалог, транзакции или пересчёт Custom Feature в Fusion. +1. Change algorithms in the shared Python kernel. Explicitly version a new pattern; existing Features continue using their previous revision. +2. Run `python3 -m unittest discover -s tests -v` and rebuild the page. `tests/test_web_demo.py` checks real contours, every shape and family, hidden fields, limits, and exact source embedding. +3. Open the freshly built page. `browser-smoke.js` contains a Playwright scenario covering every Distribution and shape, parameter changes, link restoration, invalid input, Reset, and a narrow screen. It creates a separate tab and returns parameters and hashes of the resulting contours. Compare hashes/coordinates with `demo.engine.compute()` for the same inputs. Visually inspect affected patterns and both ordinary and narrow screens. +4. Then perform the CAD acceptance relevant to the change from [CONTRIBUTING.md](../CONTRIBUTING.md). A web check does not establish BRep, operations, curved-surface seams, native dialog behavior, transactions, or Custom Feature recompute in Fusion. -Планарная версия 2 сейчас поддерживает целые отверстия; частичная BRep-обрезка -и криволинейное отображение остаются этапом нативной интеграции. Для остальных -форм зазор в версии 2 консервативно контролируется описанными окружностями; -у кругов/щелей используется точное расстояние капсул. Демо является визуальным -стендом; производственные файлы оно не создаёт. Open area — геометрическая -оценка для показанных отверстий. При скруглении Voronoi оценка использует -исходный многоугольник и может быть немного завышена. +Planar version 2 currently supports whole holes; partial BRep trimming and curved-surface display remain native integration stages. For other shapes, version 2 conservatively checks clearance using circumscribed circles; circles and slots use exact capsule distance. The demo is a visual bench and does not create production files. Open area is a geometric estimate for the displayed holes. With rounded Voronoi, the estimate uses the original polygon and may be slightly high. -## Исходники страницы +## Page sources -- `engine.py` — адаптация входа и отображения над общим ядром. -- `app.html`, `style.css`, `app.js` — интерфейс. -- `worker.js` — изолированное исполнение Python. -- `scripts/build_web_demo.py` — сборка, образцы и контроль происхождения. +- `engine.py` — input and display adaptation over the shared kernel. +- `app.html`, `style.css`, `app.js` — interface. +- `worker.js` — isolated Python execution. +- `scripts/build_web_demo.py` — build, examples, and provenance checks. -Лицензия кода проекта — PolyForm Noncommercial 1.0.0. Производные HTML-страницы сохраняют -лицензию проекта; встроенные исходники доступны внутри файла. +The project code is licensed under PolyForm Noncommercial 1.0.0. Derived HTML pages retain the project license; embedded source code is available within the file. diff --git a/demo/README.ru.md b/demo/README.ru.md new file mode 100644 index 0000000..3a1e078 --- /dev/null +++ b/demo/README.ru.md @@ -0,0 +1,85 @@ +# Perfora — Pattern playground + +[English](README.md) + +Публичное браузерное демо и штатный стенд быстрой визуальной проверки паттернов. +Fusion и браузер используют **одно геометрическое ядро Perfora**. Исходники +`Perfora/geometry.py`, `organic.py`, `distributions.py`, `distribution_fields.py`, `curves.py` +и `curve_layout.py` встраиваются в страницу без изменения и исполняются в +Python через Pyodide 0.27.7, в отдельном Web Worker. В JavaScript остаются ввод, +отображение готовых контуров и ссылки. Экспорт по решению пользователя отсутствует. Отдельной реализации раскладок +на JavaScript нет. Состав и SHA-256 модулей доступны в `perforaDemo.source`. + +## Возможности + +- Pattern: 12 повторяемых форм и 11 семейств Distribution. +- Noise: Smooth Noise, Reaction Diffusion, Directional Fibers, Topographic, + Gyroid Field, Blue Noise и последним Voronoi. Distribution скрыта. +- Running Bond объединён с Staggered; отдельного управления Row Shift нет. +- Граница Rectangle/Rounded/Circle, размеры панели, размеры отверстий, + Web Thickness, Edge Offset, ориентация и параметры выбранного рисунка. +- Cell Size и Web Thickness вместо процента заполнения; у Voronoi сохраняются + Cell Spacing, Irregularity и Round Corners. Seed/New Pattern и ссылки с параметрами. +- Геометрия пересчитывается в браузере; сервер вычислений и API-ключи не нужны. + Первый запуск требует интернета для загрузки закреплённой версии Pyodide с + jsDelivr. Страница содержит готовый первый рисунок, поэтому не открывается + пустой во время загрузки. Контуры панели не отправляются на сервер. + +Все шесть шумовых форм используют общее Python-ядро. Add Bridges относится +к первым пяти полям и включается отдельно от Web Thickness. У обычных Distribution +дополнительных мостиков нет. + +## Сборка и локальный запуск + +```sh +python3 scripts/build_web_demo.py +python3 -m http.server 8768 --bind 127.0.0.1 +``` + +Откройте `http://127.0.0.1:8768/demo/`. Единственный файл для хостинга — +`demo/index.html`: оформление, логотип, Python-модули и стартовые образцы уже +встроены. Его можно разместить в артефакте GitHub Pages либо другом статическом +хостинге с HTTPS. Для локального запуска предпочтителен HTTP-сервер; ограничения +`file://`, Web Worker и буфера обмена зависят от браузера. Подготовка страницы +не является публикацией: push, настройка Pages и запуск deployment выполняются +только по отдельному указанию пользователя. + +Сборщик не меняет установку Fusion, не требует сторонних Python-пакетов и не +загружает зависимости. Версия Pyodide закреплена в `worker.js`; при её смене +повторите реальную проверку браузера. [Pyodide](https://github.com/pyodide/pyodide) +загружается отдельно и сохраняет собственные условия лицензирования. + +## Проверка изменений + +1. Изменяйте алгоритмы в общем Python-ядре. Новую версию рисунка сохраняйте + явно; прежние Feature продолжают использовать прежнюю ревизию. +2. Выполните `python3 -m unittest discover -s tests -v`, пересоберите страницу. + `tests/test_web_demo.py` проверяет реальные контуры, все формы и семейства, + скрытые поля, ограничения и точное встраивание исходников. +3. Откройте свежую страницу. `browser-smoke.js` содержит сценарий для Playwright: + все Distribution, все формы, изменение параметров, восстановление + ссылки, ошибочный ввод, Reset и узкий экран. Он создаёт отдельную вкладку и + возвращает параметры и хеши полученных контуров. Сравните хеши/координаты с + результатом `demo.engine.compute()` на тех же входных данных. Визуально + просмотрите затронутые паттерны, обычный и узкий экраны. +4. Затем выполните относящуюся к изменению CAD-приёмку из [CONTRIBUTING.ru.md](../CONTRIBUTING.ru.md). + Веб-проверка не подтверждает BRep, операции, швы криволинейных поверхностей, + нативный диалог, транзакции или пересчёт Custom Feature в Fusion. + +Планарная версия 2 сейчас поддерживает целые отверстия; частичная BRep-обрезка +и криволинейное отображение остаются этапом нативной интеграции. Для остальных +форм зазор в версии 2 консервативно контролируется описанными окружностями; +у кругов/щелей используется точное расстояние капсул. Демо является визуальным +стендом; производственные файлы оно не создаёт. Open area — геометрическая +оценка для показанных отверстий. При скруглении Voronoi оценка использует +исходный многоугольник и может быть немного завышена. + +## Исходники страницы + +- `engine.py` — адаптация входа и отображения над общим ядром. +- `app.html`, `style.css`, `app.js` — интерфейс. +- `worker.js` — изолированное исполнение Python. +- `scripts/build_web_demo.py` — сборка, образцы и контроль происхождения. + +Лицензия кода проекта — PolyForm Noncommercial 1.0.0. Производные HTML-страницы сохраняют +лицензию проекта; встроенные исходники доступны внутри файла. diff --git a/docs/README_REFERENCE.ru.md b/docs/README_REFERENCE.ru.md index 6a6ade2..b26bd89 100644 --- a/docs/README_REFERENCE.ru.md +++ b/docs/README_REFERENCE.ru.md @@ -18,7 +18,7 @@ Визуальный стенд общего ядра: [офлайн-тест Distribution](../studies/README.md) показывает 11 семейств через общее геометрическое ядро. Новые нативные команды используют ревизию 2 доработанных Distribution, включая частичные отверстия и Follow Pattern. Существующие Feature сохраняют свою ревизию; старый Running Bond доступен при редактировании. -[Pattern playground](../demo/README.md) — браузерное демо и стенд быстрых визуальных проверок. Он исполняет те же исходники Python-геометрии, что и Fusion: 11 семейств Distribution, 19 форм отверстий, ссылки с параметрами. Сборка: `python3 scripts/build_web_demo.py`; после запуска HTTP-сервера откройте `/demo/`. Страница подготовлена к статическому хостингу; сборка ничего не публикует. +[Pattern playground](../demo/README.ru.md) — браузерное демо и стенд быстрых визуальных проверок. Он исполняет те же исходники Python-геометрии, что и Fusion: 11 семейств Distribution, 19 форм отверстий, ссылки с параметрами. Сборка: `python3 scripts/build_web_demo.py`; после запуска HTTP-сервера откройте `/demo/`. Страница подготовлена к статическому хостингу; сборка ничего не публикует. Выберите плоскую грань, замкнутый профиль эскиза или конструкционную плоскость. Настройте форму отверстий, перемычки и отступ от края, затем проверьте предпросмотр. Perfora создаст обычные профили эскиза, штатную операцию Extrude или параметрическую фичу Perfora в таймлайне. From a3a9e43eb43c7e3c3a91859678e82afb5ed4c82b Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 16:53:09 +0300 Subject: [PATCH 09/10] docs: provide bilingual agent instructions --- AGENTS.md | 179 ++++++++++++++++++++++++++------------------------- AGENTS.ru.md | 105 ++++++++++++++++++++++++++++++ 2 files changed, 195 insertions(+), 89 deletions(-) create mode 100644 AGENTS.ru.md diff --git a/AGENTS.md b/AGENTS.md index 19dc9b9..b18e8c8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,103 +1,104 @@ -# Работа над Perfora +# Working on Perfora -Perfora — дополнение Autodesk Fusion от 4FusionLab для перфорации плоских областей. MVP реализован; развивай текущий инструмент, сохраняя существующие сценарии и производительность. +[Русская версия](AGENTS.ru.md) -## Общение и документация +Perfora is a 4FusionLab Autodesk Fusion add-in for perforating planar regions. The MVP is implemented; develop the existing tool while preserving current workflows and performance. -- Общайся с пользователем на русском. Планы, в том числе в режиме планирования, составляй на русском. -- Интерфейс дополнения, сообщения об ошибках и названия создаваемых элементов модели — на английском, в терминах Fusion: Profiles, Extrude, Join, Cut, Intersect, New Body, New Component, OK, Cancel. -- Перед изменениями прочитай соответствующий модуль и проверь рабочее дерево. Сохраняй изменения пользователя и параллельных задач. -- За актуальными возможностями и ограничениями обращайся к `README.md` и `README.ru.md`; при изменении поведения обновляй обе версии. -- Для размеров и типов отверстий используй `docs/PERFORATIONS.md`; для проверок — `CONTRIBUTING.md`; перед публикацией — `docs/PUBLISHING.md`. +## Communication and documentation -## Границы MVP +- Communicate with the user in Russian. Write plans, including in plan mode, in Russian. Write documents in English and maintain separate Russian versions of documentation; intermediate working notes do not require translation. +- Add-in UI, error messages and names of created model elements are English, using Fusion terminology: Profiles, Extrude, Join, Cut, Intersect, New Body, New Component, OK, Cancel. +- Read the relevant module and inspect the working tree before changes. Preserve user changes and parallel work. +- Consult `README.md` and `README.ru.md` for current capabilities and limits; update both when behavior changes. +- Use `docs/PERFORATIONS.md` for hole dimensions and types, `CONTRIBUTING.md` for checks, and `docs/PUBLISHING.md` before publication. -- Источник: плоская грань, замкнутый профиль эскиза или конструкционная плоскость с заданной областью. -- Результат: обычные профили эскиза либо штатный Extrude с выбором операции, направления, протяжённости и целевых тел. -- Сохраняй все существующие формы и параметры раскладки. При добавлении формы обеспечь её поддержку в профилях, Fast/Full Preview, обрезке и Extrude. -- **Trim to Boundary** сохраняет частичные отверстия. **Edge Offset** остаётся активным: обрезка идёт по границе с учётом отступа, включая существующие внутренние вырезы. -- Одинаковые параметры должны давать совпадающие контуры в предпросмотре и готовой модели. -- В режимах Sketch и Extrude сетка фиксируется при создании; штатный Extrude редактируется средствами Fusion. Режим Feature создаёт параметрическую Custom Feature: сохраняй её параметры, зависимости, пересчёт и Edit Feature. Ограничения режима перечислены в обеих README. +## MVP boundaries -## Архитектура +- Source: a planar face, closed sketch profile, or construction plane with a specified region. +- Result: ordinary sketch profiles or native Extrude with operation, direction, extent and target-body choices. +- Preserve existing shapes and layout parameters. When adding a shape, support it in profiles, Fast/Full Preview, trimming and Extrude. +- **Trim to Boundary** retains partial openings. **Edge Offset** remains active: trim against the boundary with the offset, including existing inner cutouts. +- Identical parameters must produce matching contours in preview and final model. +- Sketch and Extrude fix the grid at creation; native Extrude is edited using Fusion. Feature creates a parametric Custom Feature: preserve its parameters, dependencies, recompute and Edit Feature. Both READMEs describe mode limitations. -| Файл | Ответственность | +## Architecture + +| File | Responsibility | | --- | --- | -| `Perfora/geometry.py` | Независимая 2D-геометрия, формы, шаг, раскладка и зазоры; без импорта `adsk` | -| `Perfora/model.py` | Работа с источниками, эскизами, профилями и штатным Extrude | -| `Perfora/feature.py` | Параметры, зависимости, жизненный цикл и пересчёт Custom Feature | -| `Perfora/solid.py` | Точное временное тело прямого выдавливания без создания узлов таймлайна | -| `Perfora/clipping.py` | Точная обрезка временными BRep-операциями и смещение границы | -| `Perfora/preview.py` | Кэш раскладки, система координат и пакетная графика Fast Preview | -| `Perfora/Perfora.py` | Команда, диалог, обработчики событий и жизненный цикл сессии | -| `Perfora/ui_resources.py` | Поиск нативных значков в текущей установке Fusion с запасным текстовым представлением | -| `PerforaSmokeTest/` | Проверки внутри настоящего Fusion | -| `install.py` | Локальная установка с резервной копией и сборка ZIP | - -- Геометрическое ядро использует внутренние единицы Fusion: сантиметры. Преобразования единиц и пользовательские выражения обрабатывай явно на границе с API. -- Дополнение работает на Python, поставляемом Fusion, без сторонних зависимостей времени выполнения. -- Сохраняй совместимость: command ID `DiegoV_Perforator`, UUID из manifest и пространство атрибутов `DiegoV.Perforator` намеренно оставлены после переименования. Их изменение требует продуманной миграции. -- В релизных ZIP числовую версию рассчитывай GitVersion; checked-in `Perfora/Perfora.manifest` не переписывай ради релиза. Сохраняй лицензию PolyForm Noncommercial 1.0.0 и соответствующие SPDX-заголовки. - -## Fusion API и интерфейс - -- Для вопросов о SDK/API, его синтаксиса, настройки и специфичных для API ошибок используй Context7: сначала `resolve-library-id`, затем `query-docs` по выбранному ID и конкретному вопросу. Если документация Fusion отсутствует или неполна, проверь официальную документацию Autodesk и определения API установленного Fusion. Отмечай непроверенные предположения. -- Для чистого рефакторинга, алгоритмов геометрии и редактирования документации запрос к Context7 не требуется. -- Строй диалог на нативных CommandInputs. Сравнивай изменения с настоящими Extrude и Pattern: подписи, пиктограммы, группировка, видимость полей и кнопки подтверждения. -- Нативную графику разрешай через `ui_resources.py` из текущей установки; сохраняй текстовый fallback. Ресурсы Autodesk в дистрибутив не копируй. -- `CommandInput.name` доступно только для чтения: для меняющихся подписей используй существующие связанные поля с переключением видимости и синхронизацией выражений. -- Не переноси сворачивание вложенных групп без проверки в Fusion: оно уже вызывало ошибку `the group cannot be folded`. -- Храни ссылки на обработчики событий до завершения сессии. Учитывай исчезновение выбранной сущности при отмене команды и освобождай временные ресурсы. - -## Производительность и геометрия - -- **Единое ядро:** Fusion и веб-демо исполняют одни исходники геометрии Perfora для всех форм и Distribution. Браузерный слой отвечает за ввод и отображение; алгоритмы раскладки и проверки зазоров остаются в Python-ядре. Образцы и миниатюры также генерируй этим ядром. Веб-версия предназначена для быстрой проверки, экспорт ей не требуется. -- **Быстрая визуальная проверка:** веб-демо — штатный стенд перед CAD-приёмкой. При изменении паттерна пересобери демо и проверь соответствие браузерного результата общему ядру: параметры, координаты/контуры, зазоры, seed и ревизия алгоритма. Порядок сборки и проверки — в `demo/README.md`. Проверка веб-демо дополняет обязательную приёмку Fusion. - -- Fast Preview использует кэш и пакетную Custom Graphics. Открытие раздела или изменение видимости поля не должно запускать полное CAD-построение. -- Инвалидируй геометрический кэш при изменении источника или параметров, влияющих на раскладку. Full Preview и окончательное построение должны учитывать актуальные параметры Extrude. -- Не добавляй атрибуты каждому ребру отверстия: это уже приводило к большим задержкам на шестигранниках из-за отслеживания сущностей Fusion. Сохраняй существующее разделение атрибутов границы и ячеек. -- Преобразование контуров в мировые координаты проверяй на смещённой и повёрнутой плоскости. Используй явный базис через `sketchToModelSpace`; замена на обратную матрицу без проверки уже приводила к смещённому превью. -- Проецируй и размечай границу до включения `sketch.isComputeDeferred`; иначе результат проекции может оказаться пустым при последующем появлении кривых. -- При обрезке сохраняй точные дуги и внутренние контуры. Проверяй минимальную перемычку и отступ с учётом допуска, поворота и частичных ячеек. - -## Проверка результата - -Выбирай проверки по затронутому поведению. Локальные тесты и успешная сборка ZIP не подтверждают работу CAD или интерфейса Fusion. +| `Perfora/geometry.py` | Independent 2D geometry, shapes, pitch, layout and clearances; no `adsk` import | +| `Perfora/model.py` | Sources, sketches, profiles and native Extrude | +| `Perfora/feature.py` | Custom Feature parameters, dependencies, lifecycle and recompute | +| `Perfora/solid.py` | Exact temporary straight-extrusion body without creating timeline nodes | +| `Perfora/clipping.py` | Exact trimming with temporary BRep operations and boundary offset | +| `Perfora/preview.py` | Layout cache, coordinate system and batched Fast Preview graphics | +| `Perfora/Perfora.py` | Command, dialog, event handlers and session lifecycle | +| `Perfora/ui_resources.py` | Locate native icons in the current Fusion installation with text fallback | +| `PerforaSmokeTest/` | Checks inside real Fusion | +| `install.py` | Local installation with backup and ZIP build | + +- The geometry kernel uses Fusion internal units: centimeters. Handle unit conversion and user expressions explicitly at the API boundary. +- The add-in runs on Python supplied by Fusion without third-party runtime dependencies. +- Preserve compatibility: command ID `DiegoV_Perforator`, manifest UUID and attribute namespace `DiegoV.Perforator` were intentionally retained after renaming. Changing them requires a considered migration. +- Compute the numeric version of release ZIPs using GitVersion; do not rewrite checked-in `Perfora/Perfora.manifest` for a release. Preserve PolyForm Noncommercial 1.0.0 and corresponding SPDX headers. + +## Fusion API and UI + +- For SDK/API questions, syntax, configuration and API-specific errors use Context7: first `resolve-library-id`, then `query-docs` for the selected ID and specific question. If Fusion documentation is absent or incomplete, check official Autodesk documentation and installed Fusion API definitions. Mark unverified assumptions. +- Context7 is not required for pure refactoring, geometry algorithms or documentation edits. +- Build the dialog with native CommandInputs. Compare changes with real Extrude and Pattern: labels, icons, grouping, field visibility and confirmation buttons. +- Resolve native graphics through `ui_resources.py` from the current installation; retain the text fallback. Do not copy Autodesk resources into the distribution. +- `CommandInput.name` is read-only: for changing labels use existing paired fields with visibility switching and synchronized expressions. +- Do not relocate nested-group folding without Fusion validation: it previously caused `the group cannot be folded`. +- Retain event-handler references until session end. Account for selected entities disappearing during cancellation and release temporary resources. + +## Performance and geometry + +- **Shared kernel:** Fusion and the web demo execute the same Perfora geometry sources for all shapes and Distributions. Browser code handles input and display; layout and clearance algorithms remain in the Python kernel. Generate examples and thumbnails with that kernel too. The web version is for quick checks and does not require export. +- **Fast visual checks:** the web demo is the standard bench before CAD acceptance. When changing a pattern, rebuild the demo and check browser results against the shared kernel: parameters, coordinates/contours, clearances, seed and algorithm revision. Build and verification steps are in `demo/README.md`. Web checks supplement mandatory Fusion acceptance. +- Fast Preview uses caching and batched Custom Graphics. Opening a section or changing field visibility must not trigger a complete CAD build. +- Invalidate geometry cache when the source or layout-affecting parameters change. Full Preview and final construction must use current Extrude parameters. +- Do not add attributes to every hole edge: this previously caused large delays on hexagons due to Fusion entity tracking. Preserve the existing separation of boundary and cell attributes. +- Verify contour conversion to world coordinates on a translated and rotated plane. Use an explicit basis via `sketchToModelSpace`; replacing it with an inverse matrix without validation previously displaced preview. +- Project and annotate the boundary before enabling `sketch.isComputeDeferred`; otherwise projection can appear empty even though curves appear later. +- Preserve exact arcs and inner contours during trimming. Check minimum web and offset with tolerance, rotation and partial cells accounted for. + +## Result verification + +Choose checks for the affected behavior. Local tests and a successful ZIP build do not establish CAD or Fusion UI behavior. ```sh python3 -m unittest discover -s tests -v python3 install.py --zip ``` -- Изменение геометрии: локальные тесты плюс соответствующие сценарии `tests/fusion_shapes_regression.py` и `tests/fusion_clipping_regression.py` внутри Fusion. -- Изменение превью или кэша: `tests/fusion_preview_performance.py`; проверь плотную сетку шестигранников, положение контуров и отзывчивость диалога. Запиши число ячеек и измеренное время. -- Изменение команды или диалога: `tests/fusion_dialog_regression.py`, `tests/fusion_ui_contract.py` и визуальная проверка. Проверь переключение затронутых режимов, настоящий OK и Cancel без остаточной геометрии. -- Установка или упаковка: собери ZIP, проверь состав и установку в отдельный временный `--api-root`, включая резервную копию при повторной установке. -- Изменение иконки: сохрани оригинал пользователя и прозрачность, подготовь размеры 16/32/64. Fusion кэширует ресурсы; при необходимости используй новый каталог и перезапусти только дополнение. Проверь кнопку на настоящей панели. -- Перед выпуском выполни приёмку из `CONTRIBUTING.md`, включая Undo/Redo, сохранение и повторное открытие, редактирование штатного Extrude. Указывай фактическую версию Fusion и ОС; результаты macOS не подтверждают Windows. -- В отчёте различай локальную проверку, проверку установленной копии и наблюдение в интерфейсе. Исторические отчёты не считай проверкой текущей сборки. - -## Работа с приложениями пользователя - -- Для CAD-проверок по умолчанию создавай отдельный несохранённый документ. Текущий пользовательский документ используй, когда это разрешено задачей; сохраняй его геометрию и не сохраняй файл без запроса. -- Проверяй, какая копия дополнения действительно загружена. Установка файлов сама по себе не обновляет исполняемый модуль и кэш значков. -- Для работы с Fusion, браузером и другими приложениями сначала используй доступные MCP-инструменты. Переходи к Computer Use только тогда, когда возможностей MCP недостаточно для нужного действия или проверки. После действий проверяй фактический результат; состояние переключателя само по себе не доказывает запуск дополнения. -- При зависшем расчёте сначала пробуй штатную отмену. Принудительное завершение и перезапуск Fusion с пользовательскими документами требуют отдельного согласования. -- Для сайтов предпочитай подключённый DevTools или конкретную вкладку с узкими запросами. Проверяй реальное подключение; для визуальной проверки используй скриншоты. Не включай удалённую отладку и не перезапускай браузер только ради экономии токенов без согласования. - -## Git и публикация - -- Используй Conventional Commits; для новой ветки по умолчанию — префикс `codex/`. -- Изменения исходников и workflow выполняй только в рамках поставленной задачи и через проверяемую историю Git. Прямая публикация ZIP и создание тегов вручную запрещены; автоматический GitHub Release после изменения runtime в `main` уже согласован. Подробности — в `.github/RELEASE_POLICY.md` и `docs/PUBLISHING.md`. -- Не включай в коммиты и дистрибутив кэши, локальные отчёты, секреты и резервные копии установок. Упаковку выполняй штатным `install.py`. - -## Общий инженерный контракт 4FusionLab - -- Корпоративные правила и общие CI-компоненты описаны в [4FusionLab/.github](https://github.com/4FusionLab/.github/blob/main/AGENTS.md) и [Release Platform](https://github.com/4FusionLab/.github/blob/main/RELEASE_PLATFORM.md). Настоящие правила конкретного продукта действуют дополнительно. -- Перед правками проверь существующие Git-изменения, документацию, автоматические проверки и совместимость с Autodesk Fusion. Не удаляй пользовательские данные, не меняй существующие IDs команд, UUID manifest или структуру аддона без миграционного плана. -- Для обычной разработки используй Conventional Commits; предпочтителен небольшой PR с CI, но прямой push в `main` допускается политикой репозитория. Не переписывай историю и не изменяй опубликованные теги/артефакты. -- Включён **автоматический выпуск только при изменении распространяемого продукта**: push или merge в `main` → проверка `.github/release-paths.txt` → тесты → GitVersion 6.8.2 → новый неизменяемый тег и GitHub Release. Теги вручную не создавай; изменения README, документации, тестов, workflow, `AGENTS.md` не должны публиковать релиз. -- Общие GitHub Actions подключай только по **точному SHA** проверенного коммита `4FusionLab/.github`, а не по `@main`. Пакет, manifest, SHA-256, release notes и version согласованы; существующие релизы не перезаписывай. -- Выполнение unit-тестов и успешная сборка ZIP **не доказывают** работоспособность в установленном Autodesk Fusion. Для изменений Fusion API и пользовательского интерфейса фиксируй фактическую CAD-приёмку и ОС отдельно. -- Сохраняй существующие английскую и русскую версии документации, лицензии, ограничения и уникальные сценарии проекта. Не публикуй секреты, персональные CAD-документы, токены или артефакты с локальной машины. +- Geometry change: local tests plus relevant `tests/fusion_shapes_regression.py` and `tests/fusion_clipping_regression.py` scenarios inside Fusion. +- Preview or cache change: `tests/fusion_preview_performance.py`; check a dense hexagon grid, contour positions and dialog responsiveness. Record cell count and measured time. +- Command or dialog change: `tests/fusion_dialog_regression.py`, `tests/fusion_ui_contract.py` and visual inspection. Check switching affected modes and real OK and Cancel without residual geometry. +- Installation or packaging: build the ZIP and verify contents and installation to a separate temporary `--api-root`, including backup on repeat installation. +- Icon change: preserve the user's original and transparency; prepare 16/32/64 sizes. Fusion caches resources; when needed use a new directory and restart only the add-in. Check the button on the real panel. +- Before release perform acceptance from `CONTRIBUTING.md`, including Undo/Redo, save and reopen, and native Extrude editing. State actual Fusion version and OS; macOS results do not establish Windows behavior. +- Distinguish local verification, installed-copy verification and UI observation in reports. Do not treat historical reports as validation of the current build. + +## Working with user applications + +- By default create a separate unsaved document for CAD tests. Use the current user document when the task authorizes it; preserve its geometry and do not save it without a request. +- Verify which add-in copy is actually loaded. Installing files alone does not update the executing module or icon cache. +- Use available MCP tools first for Fusion, browsers and other applications. Move to Computer Use only when MCP cannot perform the required action or verification. Verify actual outcomes after actions; a toggle state alone does not prove the add-in started. +- If computation hangs, first try normal cancellation. Force-quitting and restarting Fusion with user documents require separate agreement. +- For websites prefer connected DevTools or a specific tab with narrow requests. Verify real connectivity; use screenshots for visual checks. Do not enable remote debugging or restart a browser solely to save tokens without agreement. + +## Git and publication + +- Use Conventional Commits; default new-branch prefix is `codex/`. +- Change sources and workflows only within task scope and through reviewable Git history. Direct ZIP publication and manual tag creation are prohibited; automatic GitHub Release after runtime changes in `main` is already authorized. Details: `.github/RELEASE_POLICY.md` and `docs/PUBLISHING.md`. +- Keep caches, local reports, secrets and installation backups out of commits and distributions. Package with the standard `install.py`. + +## Shared 4FusionLab engineering contract + +- Organization rules and shared CI components are documented in [4FusionLab/.github](https://github.com/4FusionLab/.github/blob/main/AGENTS.md) and [Release Platform](https://github.com/4FusionLab/.github/blob/main/RELEASE_PLATFORM.md). These product-specific rules apply in addition. +- Before edits inspect existing Git changes, documentation, automated checks and Autodesk Fusion compatibility. Do not delete user data or change existing command IDs, manifest UUID or add-in structure without a migration plan. +- Use Conventional Commits for ordinary development; a small PR with CI is preferred, though direct push to `main` is allowed by repository policy. Do not rewrite history or modify published tags/artifacts. +- **Automatic releases occur only for shipped product changes**: push or merge to `main` → check `.github/release-paths.txt` → tests → GitVersion 6.8.2 → new immutable tag and GitHub Release. Do not create tags manually; changes to README, documentation, tests, workflows or `AGENTS.md` must not independently publish a release. +- Pin shared GitHub Actions to the **exact SHA** of a reviewed `4FusionLab/.github` commit, not `@main`. Package, manifest, SHA-256, release notes and version must agree; do not overwrite existing releases. +- Passing unit tests and building a ZIP **does not prove** operation in installed Autodesk Fusion. Record actual CAD acceptance and OS separately for Fusion API and UI changes. +- Preserve existing English and Russian documentation, licenses, limitations and project-specific workflows. Do not publish secrets, personal CAD documents, tokens or local-machine artifacts. diff --git a/AGENTS.ru.md b/AGENTS.ru.md new file mode 100644 index 0000000..11d0505 --- /dev/null +++ b/AGENTS.ru.md @@ -0,0 +1,105 @@ +# Работа над Perfora + +[English](AGENTS.md) + +Perfora — дополнение Autodesk Fusion от 4FusionLab для перфорации плоских областей. MVP реализован; развивай текущий инструмент, сохраняя существующие сценарии и производительность. + +## Общение и документация + +- Общайся с пользователем на русском. Планы, в том числе в режиме планирования, составляй на русском. Документы веди на английском; для документации поддерживай отдельные русские версии, промежуточные рабочие заметки переводить не требуется. +- Интерфейс дополнения, сообщения об ошибках и названия создаваемых элементов модели — на английском, в терминах Fusion: Profiles, Extrude, Join, Cut, Intersect, New Body, New Component, OK, Cancel. +- Перед изменениями прочитай соответствующий модуль и проверь рабочее дерево. Сохраняй изменения пользователя и параллельных задач. +- За актуальными возможностями и ограничениями обращайся к `README.md` и `README.ru.md`; при изменении поведения обновляй обе версии. +- Для размеров и типов отверстий используй `docs/PERFORATIONS.md`; для проверок — `CONTRIBUTING.md`; перед публикацией — `docs/PUBLISHING.md`. + +## Границы MVP + +- Источник: плоская грань, замкнутый профиль эскиза или конструкционная плоскость с заданной областью. +- Результат: обычные профили эскиза либо штатный Extrude с выбором операции, направления, протяжённости и целевых тел. +- Сохраняй все существующие формы и параметры раскладки. При добавлении формы обеспечь её поддержку в профилях, Fast/Full Preview, обрезке и Extrude. +- **Trim to Boundary** сохраняет частичные отверстия. **Edge Offset** остаётся активным: обрезка идёт по границе с учётом отступа, включая существующие внутренние вырезы. +- Одинаковые параметры должны давать совпадающие контуры в предпросмотре и готовой модели. +- В режимах Sketch и Extrude сетка фиксируется при создании; штатный Extrude редактируется средствами Fusion. Режим Feature создаёт параметрическую Custom Feature: сохраняй её параметры, зависимости, пересчёт и Edit Feature. Ограничения режима перечислены в обеих README. + +## Архитектура + +| Файл | Ответственность | +| --- | --- | +| `Perfora/geometry.py` | Независимая 2D-геометрия, формы, шаг, раскладка и зазоры; без импорта `adsk` | +| `Perfora/model.py` | Работа с источниками, эскизами, профилями и штатным Extrude | +| `Perfora/feature.py` | Параметры, зависимости, жизненный цикл и пересчёт Custom Feature | +| `Perfora/solid.py` | Точное временное тело прямого выдавливания без создания узлов таймлайна | +| `Perfora/clipping.py` | Точная обрезка временными BRep-операциями и смещение границы | +| `Perfora/preview.py` | Кэш раскладки, система координат и пакетная графика Fast Preview | +| `Perfora/Perfora.py` | Команда, диалог, обработчики событий и жизненный цикл сессии | +| `Perfora/ui_resources.py` | Поиск нативных значков в текущей установке Fusion с запасным текстовым представлением | +| `PerforaSmokeTest/` | Проверки внутри настоящего Fusion | +| `install.py` | Локальная установка с резервной копией и сборка ZIP | + +- Геометрическое ядро использует внутренние единицы Fusion: сантиметры. Преобразования единиц и пользовательские выражения обрабатывай явно на границе с API. +- Дополнение работает на Python, поставляемом Fusion, без сторонних зависимостей времени выполнения. +- Сохраняй совместимость: command ID `DiegoV_Perforator`, UUID из manifest и пространство атрибутов `DiegoV.Perforator` намеренно оставлены после переименования. Их изменение требует продуманной миграции. +- В релизных ZIP числовую версию рассчитывай GitVersion; checked-in `Perfora/Perfora.manifest` не переписывай ради релиза. Сохраняй лицензию PolyForm Noncommercial 1.0.0 и соответствующие SPDX-заголовки. + +## Fusion API и интерфейс + +- Для вопросов о SDK/API, его синтаксиса, настройки и специфичных для API ошибок используй Context7: сначала `resolve-library-id`, затем `query-docs` по выбранному ID и конкретному вопросу. Если документация Fusion отсутствует или неполна, проверь официальную документацию Autodesk и определения API установленного Fusion. Отмечай непроверенные предположения. +- Для чистого рефакторинга, алгоритмов геометрии и редактирования документации запрос к Context7 не требуется. +- Строй диалог на нативных CommandInputs. Сравнивай изменения с настоящими Extrude и Pattern: подписи, пиктограммы, группировка, видимость полей и кнопки подтверждения. +- Нативную графику разрешай через `ui_resources.py` из текущей установки; сохраняй текстовый fallback. Ресурсы Autodesk в дистрибутив не копируй. +- `CommandInput.name` доступно только для чтения: для меняющихся подписей используй существующие связанные поля с переключением видимости и синхронизацией выражений. +- Не переноси сворачивание вложенных групп без проверки в Fusion: оно уже вызывало ошибку `the group cannot be folded`. +- Храни ссылки на обработчики событий до завершения сессии. Учитывай исчезновение выбранной сущности при отмене команды и освобождай временные ресурсы. + +## Производительность и геометрия + +- **Единое ядро:** Fusion и веб-демо исполняют одни исходники геометрии Perfora для всех форм и Distribution. Браузерный слой отвечает за ввод и отображение; алгоритмы раскладки и проверки зазоров остаются в Python-ядре. Образцы и миниатюры также генерируй этим ядром. Веб-версия предназначена для быстрой проверки, экспорт ей не требуется. +- **Быстрая визуальная проверка:** веб-демо — штатный стенд перед CAD-приёмкой. При изменении паттерна пересобери демо и проверь соответствие браузерного результата общему ядру: параметры, координаты/контуры, зазоры, seed и ревизия алгоритма. Порядок сборки и проверки — в `demo/README.md`. Проверка веб-демо дополняет обязательную приёмку Fusion. + +- Fast Preview использует кэш и пакетную Custom Graphics. Открытие раздела или изменение видимости поля не должно запускать полное CAD-построение. +- Инвалидируй геометрический кэш при изменении источника или параметров, влияющих на раскладку. Full Preview и окончательное построение должны учитывать актуальные параметры Extrude. +- Не добавляй атрибуты каждому ребру отверстия: это уже приводило к большим задержкам на шестигранниках из-за отслеживания сущностей Fusion. Сохраняй существующее разделение атрибутов границы и ячеек. +- Преобразование контуров в мировые координаты проверяй на смещённой и повёрнутой плоскости. Используй явный базис через `sketchToModelSpace`; замена на обратную матрицу без проверки уже приводила к смещённому превью. +- Проецируй и размечай границу до включения `sketch.isComputeDeferred`; иначе результат проекции может оказаться пустым при последующем появлении кривых. +- При обрезке сохраняй точные дуги и внутренние контуры. Проверяй минимальную перемычку и отступ с учётом допуска, поворота и частичных ячеек. + +## Проверка результата + +Выбирай проверки по затронутому поведению. Локальные тесты и успешная сборка ZIP не подтверждают работу CAD или интерфейса Fusion. + +```sh +python3 -m unittest discover -s tests -v +python3 install.py --zip +``` + +- Изменение геометрии: локальные тесты плюс соответствующие сценарии `tests/fusion_shapes_regression.py` и `tests/fusion_clipping_regression.py` внутри Fusion. +- Изменение превью или кэша: `tests/fusion_preview_performance.py`; проверь плотную сетку шестигранников, положение контуров и отзывчивость диалога. Запиши число ячеек и измеренное время. +- Изменение команды или диалога: `tests/fusion_dialog_regression.py`, `tests/fusion_ui_contract.py` и визуальная проверка. Проверь переключение затронутых режимов, настоящий OK и Cancel без остаточной геометрии. +- Установка или упаковка: собери ZIP, проверь состав и установку в отдельный временный `--api-root`, включая резервную копию при повторной установке. +- Изменение иконки: сохрани оригинал пользователя и прозрачность, подготовь размеры 16/32/64. Fusion кэширует ресурсы; при необходимости используй новый каталог и перезапусти только дополнение. Проверь кнопку на настоящей панели. +- Перед выпуском выполни приёмку из `CONTRIBUTING.md`, включая Undo/Redo, сохранение и повторное открытие, редактирование штатного Extrude. Указывай фактическую версию Fusion и ОС; результаты macOS не подтверждают Windows. +- В отчёте различай локальную проверку, проверку установленной копии и наблюдение в интерфейсе. Исторические отчёты не считай проверкой текущей сборки. + +## Работа с приложениями пользователя + +- Для CAD-проверок по умолчанию создавай отдельный несохранённый документ. Текущий пользовательский документ используй, когда это разрешено задачей; сохраняй его геометрию и не сохраняй файл без запроса. +- Проверяй, какая копия дополнения действительно загружена. Установка файлов сама по себе не обновляет исполняемый модуль и кэш значков. +- Для работы с Fusion, браузером и другими приложениями сначала используй доступные MCP-инструменты. Переходи к Computer Use только тогда, когда возможностей MCP недостаточно для нужного действия или проверки. После действий проверяй фактический результат; состояние переключателя само по себе не доказывает запуск дополнения. +- При зависшем расчёте сначала пробуй штатную отмену. Принудительное завершение и перезапуск Fusion с пользовательскими документами требуют отдельного согласования. +- Для сайтов предпочитай подключённый DevTools или конкретную вкладку с узкими запросами. Проверяй реальное подключение; для визуальной проверки используй скриншоты. Не включай удалённую отладку и не перезапускай браузер только ради экономии токенов без согласования. + +## Git и публикация + +- Используй Conventional Commits; для новой ветки по умолчанию — префикс `codex/`. +- Изменения исходников и workflow выполняй только в рамках поставленной задачи и через проверяемую историю Git. Прямая публикация ZIP и создание тегов вручную запрещены; автоматический GitHub Release после изменения runtime в `main` уже согласован. Подробности — в `.github/RELEASE_POLICY.md` и `docs/PUBLISHING.md`. +- Не включай в коммиты и дистрибутив кэши, локальные отчёты, секреты и резервные копии установок. Упаковку выполняй штатным `install.py`. + +## Общий инженерный контракт 4FusionLab + +- Корпоративные правила и общие CI-компоненты описаны в [4FusionLab/.github](https://github.com/4FusionLab/.github/blob/main/AGENTS.md) и [Release Platform](https://github.com/4FusionLab/.github/blob/main/RELEASE_PLATFORM.md). Настоящие правила конкретного продукта действуют дополнительно. +- Перед правками проверь существующие Git-изменения, документацию, автоматические проверки и совместимость с Autodesk Fusion. Не удаляй пользовательские данные, не меняй существующие IDs команд, UUID manifest или структуру аддона без миграционного плана. +- Для обычной разработки используй Conventional Commits; предпочтителен небольшой PR с CI, но прямой push в `main` допускается политикой репозитория. Не переписывай историю и не изменяй опубликованные теги/артефакты. +- Включён **автоматический выпуск только при изменении распространяемого продукта**: push или merge в `main` → проверка `.github/release-paths.txt` → тесты → GitVersion 6.8.2 → новый неизменяемый тег и GitHub Release. Теги вручную не создавай; изменения README, документации, тестов, workflow, `AGENTS.md` не должны публиковать релиз. +- Общие GitHub Actions подключай только по **точному SHA** проверенного коммита `4FusionLab/.github`, а не по `@main`. Пакет, manifest, SHA-256, release notes и version согласованы; существующие релизы не перезаписывай. +- Выполнение unit-тестов и успешная сборка ZIP **не доказывают** работоспособность в установленном Autodesk Fusion. Для изменений Fusion API и пользовательского интерфейса фиксируй фактическую CAD-приёмку и ОС отдельно. +- Сохраняй существующие английскую и русскую версии документации, лицензии, ограничения и уникальные сценарии проекта. Не публикуй секреты, персональные CAD-документы, токены или артефакты с локальной машины. From 4c14e3702151dbe8c6a25e4c21c4bcc7b7e1f15b Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sun, 8 Nov 2026 10:13:53 +0300 Subject: [PATCH 10/10] docs: add English distribution study guide --- studies/README.md | 138 +++++++++++++------------------------------ studies/README.ru.md | 106 +++++++++++++++++++++++++++++++++ 2 files changed, 146 insertions(+), 98 deletions(-) create mode 100644 studies/README.ru.md diff --git a/studies/README.md b/studies/README.md index 2f112e0..f129e70 100644 --- a/studies/README.md +++ b/studies/README.md @@ -1,104 +1,46 @@ -# Визуальное принятие Distribution v2 - -**Статус: офлайн-кандидат, ожидает визуального принятия пользователем.** -Исходная база — `07e7184`, отдельная ветка `codex/distribution-visual-acceptance`. -Загруженная копия Fusion и параллельная ветка органических форм не изменялись. -Установленное дополнение нельзя переводить на новые режимы до принятия демо. -Алгоритмы кандидата находятся в `Perfora/distribution_fields.py`; публичный -`geometry.generate()` выбирает их по `distribution_revision=2`. По умолчанию -сохраняется revision 1. Демо и будущий адаптер Fusion получают один список Cell; -новые поля сериализуются обычным Feature payload. - -## Решения для оценки - -- Сохранять ритм целого поля. Конфликт зазоров меняет шаг/число рядов всего - поля, а не удаляет отдельное отверстие из регулярного ряда. По границе - отбираются только целые отверстия с Edge Offset. -- Contour: замыкать ряд равномерным целым числом отверстий, проверять хорды, - завершать заполнение до узких остатков у медиальной оси. Внутри остаётся - осмысленное сплошное ядро. Геометрия уровней — прежнее приближённое поле - расстояний, не подмена точным CAD-offset. -- Fan: общий внутренний радиус и общий радиальный шаг всех лучей. Рядом с - вершиной нет россыпи пропущенных отверстий. Пустая дуга у вершины намеренна. -- Phyllotaxis: сохранять каждый индекс спирали Фогеля. При тесноте менять - масштаб всего поля, сохраняя золотой угол и узнаваемые парастихи. -- Poisson Disk: существующий алгоритм сохранён. Нерегулярность здесь является - смыслом раскладки; делать его регулярным нет оснований. -- Wave: отсчёт длины дуги от центра поля, одинаковые фазы соседних рядов, - устойчивость при изменении границы, необязательная касательная ориентация щелей. -- Chevron: зеркальные пары, а не конфликтующие отверстия в общей вершине. - Касательная ориентация даёт аккуратный центральный шов. -- **Running Bond не является самостоятельной семьёй.** По замечанию пользователя - он объединён в демо с Staggered как Row Shift. 1/2 совпадает с шахматкой - при равных шагах; 1/3 — параметр сдвига рядов. Установленный runtime не менялся. -- Between Curves: общие станции между направляющими вместо независимого числа - отверстий в каждом ряду. При тесноте меняется число целых колонок/рядов. - -## Как читать демо - -Показаны точные круги Ø 2.5 mm и щели 1.7 × 5.2 mm. Web Thickness — 1.2 mm, -Edge Offset — 1.8 mm. Размер основной панели — 120 × 100 mm. Contour имеет -скруглённый некруглый источник; Phyllotaxis — круг Ø 93 mm. Физический масштаб -на растровых листах одинаковый. Растровые листы показывают щели по касательной, -а Phyllotaxis и Poisson Disk — круги; переключатель позволяет честно сравнить -одинаковые формы во всех раскладках. - -«Прежний алгоритм» исполняет настоящий генератор из базы при тех же размерах -отверстий, границе, зазоре и параметрах мотива. Ориентация у прежних вариантов -фиксированная, поскольку следования касательной там нет. У кандидата шаг может -увеличиваться при решении коллизий; это отражается на количестве отверстий. -Это не обещание сохранения плотности. Линии построения не являются прорезями. - -Файл включает все 12 пунктов из реестра LAYOUTS команды: четыре прежних режима -и восемь новых. Реестр читается без adsk; неизвестный режим останавливает сборку -вместо молчаливого пропуска. Along Path вызывает настоящие sample_path и -generate_path с аналитической дугой. Voronoi — Hole Shape, а не Distribution. - -Версия 2 ещё не является готовой CAD-функцией: демонстрационные источники заданы -явно; нет Trim частичных отверстий, CAD, перевода на поверхности или новых -полей нативного диалога. Круги/щели проверяются точным -расстоянием между капсулами; у остальных повторяемых форм версия 2 проверяет -описанные окружности, сохраняя консервативную упаковку. Нативные пути для этих -форм требуют отдельной проверки после принятия визуального направления. Повороты криволинейных отверстий, -совместимость старых Feature и сохранение seed потребуют отдельного этапа. -Старые Feature нельзя молча пересчитывать новым алгоритмом. - -Circular в общем тесте заполняется от центра: Start Radius = 0, ровно одно -центральное отверстие для круга и щели. Начальный демонстрационный отступ 8 mm -убран после замечания пользователя. Ненулевой Start Radius остаётся штатной -настройкой существующего кругового генератора, а не новым ограничением. - -## Воспроизведение +# Distribution v2 visual acceptance study + +English | [Русский](README.ru.md) + +**Status: offline candidate awaiting user visual acceptance.** The original base is `07e7184` on the separate `codex/distribution-visual-acceptance` branch. The loaded Fusion copy and the parallel organic-shapes branch were not changed. Do not switch the installed add-in to the new modes before accepting the demo. Candidate algorithms are in `Perfora/distribution_fields.py`; the public `geometry.generate()` selects them with `distribution_revision=2`. Revision 1 remains the default. The demo and future Fusion adapter receive the same list of Cell objects; new fields are serialized through the usual Feature payload. + +## Decisions to assess + +- Preserve the rhythm of the entire field. A spacing conflict changes the pitch or number of rows for the whole field instead of removing individual holes from a regular row. Only whole holes satisfying Edge Offset are selected at the boundary. +- Contour: close each row with an evenly spaced whole number of holes, check chords, and finish filling before reaching narrow remnants near the medial axis. A meaningful solid core remains. The level geometry is the earlier approximate distance field, not an exact CAD offset. +- Fan: use a shared inner radius and radial pitch for all rays. There is no scattering of omitted holes near the apex; the empty arc at the apex is intentional. +- Phyllotaxis: preserve every index of the Vogel spiral. When space is tight, scale the whole field while preserving the golden angle and recognizable parastichies. +- Poisson Disk: retain the existing algorithm. Irregularity is the purpose of this distribution; there is no basis for making it regular. +- Wave: measure arc length from the center of the field, use equal phases for neighboring rows, remain stable when the boundary changes, and optionally orient slots tangentially. +- Chevron: use mirrored pairs instead of conflicting holes at a shared apex. Tangential orientation gives a neat center seam. +- **Running Bond is not an independent family.** Following user feedback, the demo combines it with Staggered as Row Shift. A 1/2 shift matches a checkerboard at equal pitches; 1/3 is a row-shift setting. The installed runtime was not changed. +- Between Curves: use common stations between guides instead of an independent number of holes in each row. When space is tight, change the number of whole columns or rows. + +## Reading the demo + +The demo shows exact circles Ø 2.5 mm and slots 1.7 × 5.2 mm. Web Thickness is 1.2 mm and Edge Offset is 1.8 mm. The main panel is 120 × 100 mm. Contour uses a rounded noncircular source; Phyllotaxis uses a circle Ø 93 mm. Raster sheets share the same physical scale. The raster sheets show tangential slots, except circles for Phyllotaxis and Poisson Disk; a switch permits direct comparison of the same shapes in every distribution. + +The “previous algorithm” runs the actual baseline generator using the same hole sizes, boundary, spacing and motif settings. Its orientation is fixed because it does not follow tangents. The candidate may increase pitch to resolve collisions, affecting hole counts; this is not a promise to retain density. Construction lines are not cuts. + +The file includes all 12 entries in the command's LAYOUTS registry: four previous modes and eight new ones. The registry is read without adsk; an unknown mode stops the build instead of being silently skipped. Along Path calls the actual sample_path and generate_path with an analytical arc. Voronoi is a Hole Shape, not a Distribution. + +Version 2 is not yet a finished CAD feature: demo sources are explicit; there is no partial-hole Trim, CAD, surface mapping, or new native dialog fields. Circles and slots are checked using exact capsule distances; for other repeating shapes, version 2 checks circumscribed circles and retains conservative packing. Native paths for those shapes need separate validation after the visual direction is accepted. Curved-hole rotation, old Feature compatibility, and seed persistence need a separate stage. Old Features must not silently recompute with the new algorithm. + +Circular fills from the center in the shared test: Start Radius = 0, exactly one center hole for a circle or slot. The initial 8 mm demo offset was removed after user feedback. A nonzero Start Radius remains a normal setting of the existing circular generator, not a new restriction. + +## Reproduction ```sh python3 -m unittest discover -s tests -p test_distribution_study.py -v python3 scripts/visual_distribution_test.py --output /absolute/path/distributions.html ``` -Основной результат — **один автономный HTML** со всеми координатами, хешами -исходных модулей и оформлением. Сеть и сервер не нужны. Есть общий обзор, -отдельная раскладка, круги/фиксированные/следующие рисунку щели, сравнение -прежней версии и кандидата, линии построения, сдвиг 1/2 либо 1/3. - -Геометрия, тесты и HTML-экспорт не имеют сторонних зависимостей. Если вместо -`.html` передать каталог, создаётся дополнительный комплект. Только экспорт PNG использует -локально установленный Pillow и шрифт Helvetica macOS; это не зависимости -дополнения. Экспорт создаёт `distribution-demo.html` (интерактивный фрагмент), -три PNG, точные координаты `data.json` и измерения `metrics.json`. Результаты -экспорта хранятся вне Git/дистрибутива. Шаблон и генератор находятся в этой папке. - -Проверки включают независимую полную попарную проверку реального зазора всех -36 базовых комбинаций, совпадение с публичным ядром, детерминизм, непрерывность лучей Fan, сохранение индексов -Phyllotaxis, неподвижность Wave при обрезке области, общие колонки Between Curves -и два дополнительных уровня плотности для каждой раскладки. Локальная -производительность не является временем Fusion. - -## Проверка 25 октября 2026 - -172 локальных теста проходят, включая 12 проверок этого стенда. Для 36 базовых -сочетаний всех Distribution с кругами и щелями выполнен независимый полный -перебор пар реальных контуров; выдержаны Web Thickness и Edge Offset. Проверены -перенос/поворот источника, сохранение ревизии в метаданных, прежняя ревизия по -умолчанию и центр Circular. Браузерная проверка подтверждает 12 панелей, -сравнение, смену форм, линии построения и Row Shift; на ширине 360 px нет -горизонтального переполнения. Реальные CAD/UI-проверки намеренно не запускались. +The main output is **one standalone HTML file** with all coordinates, source-module hashes and styling. No network or server is needed. It includes an overview, individual distributions, circles/fixed slots/pattern-following slots, comparison of the previous version and candidate, construction lines, and 1/2 or 1/3 row shift. + +Geometry, tests and HTML export have no third-party dependencies. Passing a directory instead of `.html` produces an additional set. Only PNG export uses locally installed Pillow and the macOS Helvetica font; these are not add-in dependencies. Export produces `distribution-demo.html` (an interactive fragment), three PNGs, exact coordinates in `data.json`, and measurements in `metrics.json`. Exported results are outside Git and the distribution. The template and generator are in this folder. + +Checks include an independent exhaustive pairwise test of actual spacing across all 36 basic combinations, agreement with the public core, determinism, Fan ray continuity, preservation of Phyllotaxis indices, Wave stability when the region is trimmed, shared Between Curves columns, and two additional density levels per distribution. Local performance is not Fusion timing. + +## Validation on 25 October 2026 + +172 local tests passed, including 12 for this study. For 36 basic combinations of all Distributions with circles and slots, an independent exhaustive pairwise comparison of actual contours confirmed Web Thickness and Edge Offset. Source translation/rotation, revision persistence in metadata, the previous default revision and the Circular center were checked. Browser validation confirmed 12 panels, comparison, shape switching, construction lines and Row Shift; there was no horizontal overflow at 360 px. Real CAD/UI checks were intentionally not run. diff --git a/studies/README.ru.md b/studies/README.ru.md new file mode 100644 index 0000000..74f55f2 --- /dev/null +++ b/studies/README.ru.md @@ -0,0 +1,106 @@ +# Визуальное принятие Distribution v2 + +[English](README.md) | Русский + +**Статус: офлайн-кандидат, ожидает визуального принятия пользователем.** +Исходная база — `07e7184`, отдельная ветка `codex/distribution-visual-acceptance`. +Загруженная копия Fusion и параллельная ветка органических форм не изменялись. +Установленное дополнение нельзя переводить на новые режимы до принятия демо. +Алгоритмы кандидата находятся в `Perfora/distribution_fields.py`; публичный +`geometry.generate()` выбирает их по `distribution_revision=2`. По умолчанию +сохраняется revision 1. Демо и будущий адаптер Fusion получают один список Cell; +новые поля сериализуются обычным Feature payload. + +## Решения для оценки + +- Сохранять ритм целого поля. Конфликт зазоров меняет шаг/число рядов всего + поля, а не удаляет отдельное отверстие из регулярного ряда. По границе + отбираются только целые отверстия с Edge Offset. +- Contour: замыкать ряд равномерным целым числом отверстий, проверять хорды, + завершать заполнение до узких остатков у медиальной оси. Внутри остаётся + осмысленное сплошное ядро. Геометрия уровней — прежнее приближённое поле + расстояний, не подмена точным CAD-offset. +- Fan: общий внутренний радиус и общий радиальный шаг всех лучей. Рядом с + вершиной нет россыпи пропущенных отверстий. Пустая дуга у вершины намеренна. +- Phyllotaxis: сохранять каждый индекс спирали Фогеля. При тесноте менять + масштаб всего поля, сохраняя золотой угол и узнаваемые парастихи. +- Poisson Disk: существующий алгоритм сохранён. Нерегулярность здесь является + смыслом раскладки; делать его регулярным нет оснований. +- Wave: отсчёт длины дуги от центра поля, одинаковые фазы соседних рядов, + устойчивость при изменении границы, необязательная касательная ориентация щелей. +- Chevron: зеркальные пары, а не конфликтующие отверстия в общей вершине. + Касательная ориентация даёт аккуратный центральный шов. +- **Running Bond не является самостоятельной семьёй.** По замечанию пользователя + он объединён в демо с Staggered как Row Shift. 1/2 совпадает с шахматкой + при равных шагах; 1/3 — параметр сдвига рядов. Установленный runtime не менялся. +- Between Curves: общие станции между направляющими вместо независимого числа + отверстий в каждом ряду. При тесноте меняется число целых колонок/рядов. + +## Как читать демо + +Показаны точные круги Ø 2.5 mm и щели 1.7 × 5.2 mm. Web Thickness — 1.2 mm, +Edge Offset — 1.8 mm. Размер основной панели — 120 × 100 mm. Contour имеет +скруглённый некруглый источник; Phyllotaxis — круг Ø 93 mm. Физический масштаб +на растровых листах одинаковый. Растровые листы показывают щели по касательной, +а Phyllotaxis и Poisson Disk — круги; переключатель позволяет честно сравнить +одинаковые формы во всех раскладках. + +«Прежний алгоритм» исполняет настоящий генератор из базы при тех же размерах +отверстий, границе, зазоре и параметрах мотива. Ориентация у прежних вариантов +фиксированная, поскольку следования касательной там нет. У кандидата шаг может +увеличиваться при решении коллизий; это отражается на количестве отверстий. +Это не обещание сохранения плотности. Линии построения не являются прорезями. + +Файл включает все 12 пунктов из реестра LAYOUTS команды: четыре прежних режима +и восемь новых. Реестр читается без adsk; неизвестный режим останавливает сборку +вместо молчаливого пропуска. Along Path вызывает настоящие sample_path и +generate_path с аналитической дугой. Voronoi — Hole Shape, а не Distribution. + +Версия 2 ещё не является готовой CAD-функцией: демонстрационные источники заданы +явно; нет Trim частичных отверстий, CAD, перевода на поверхности или новых +полей нативного диалога. Круги/щели проверяются точным +расстоянием между капсулами; у остальных повторяемых форм версия 2 проверяет +описанные окружности, сохраняя консервативную упаковку. Нативные пути для этих +форм требуют отдельной проверки после принятия визуального направления. Повороты криволинейных отверстий, +совместимость старых Feature и сохранение seed потребуют отдельного этапа. +Старые Feature нельзя молча пересчитывать новым алгоритмом. + +Circular в общем тесте заполняется от центра: Start Radius = 0, ровно одно +центральное отверстие для круга и щели. Начальный демонстрационный отступ 8 mm +убран после замечания пользователя. Ненулевой Start Radius остаётся штатной +настройкой существующего кругового генератора, а не новым ограничением. + +## Воспроизведение + +```sh +python3 -m unittest discover -s tests -p test_distribution_study.py -v +python3 scripts/visual_distribution_test.py --output /absolute/path/distributions.html +``` + +Основной результат — **один автономный HTML** со всеми координатами, хешами +исходных модулей и оформлением. Сеть и сервер не нужны. Есть общий обзор, +отдельная раскладка, круги/фиксированные/следующие рисунку щели, сравнение +прежней версии и кандидата, линии построения, сдвиг 1/2 либо 1/3. + +Геометрия, тесты и HTML-экспорт не имеют сторонних зависимостей. Если вместо +`.html` передать каталог, создаётся дополнительный комплект. Только экспорт PNG использует +локально установленный Pillow и шрифт Helvetica macOS; это не зависимости +дополнения. Экспорт создаёт `distribution-demo.html` (интерактивный фрагмент), +три PNG, точные координаты `data.json` и измерения `metrics.json`. Результаты +экспорта хранятся вне Git/дистрибутива. Шаблон и генератор находятся в этой папке. + +Проверки включают независимую полную попарную проверку реального зазора всех +36 базовых комбинаций, совпадение с публичным ядром, детерминизм, непрерывность лучей Fan, сохранение индексов +Phyllotaxis, неподвижность Wave при обрезке области, общие колонки Between Curves +и два дополнительных уровня плотности для каждой раскладки. Локальная +производительность не является временем Fusion. + +## Проверка 25 октября 2026 + +172 локальных теста проходят, включая 12 проверок этого стенда. Для 36 базовых +сочетаний всех Distribution с кругами и щелями выполнен независимый полный +перебор пар реальных контуров; выдержаны Web Thickness и Edge Offset. Проверены +перенос/поворот источника, сохранение ревизии в метаданных, прежняя ревизия по +умолчанию и центр Circular. Браузерная проверка подтверждает 12 панелей, +сравнение, смену форм, линии построения и Row Shift; на ширине 360 px нет +горизонтального переполнения. Реальные CAD/UI-проверки намеренно не запускались.
- Синяя прямоугольная решётка с шестигранной перфорацией и четырьмя крепёжными отверстиями + Синяя прямоугольная решётка с шестигранной перфорацией и четырьмя крепёжными отверстиями

Сотовая решётка
Шестигранные ячейки, рамка и крепёжные отверстия.

- Зелёная прямоугольная панель со скруглённой перфорацией Вороного + Зелёная прямоугольная панель со скруглённой перфорацией Вороного

Вороной со скруглением
Нерегулярный узор со скруглёнными углами и рамкой.

- Оранжевая круглая пластина с диагональными прорезями и центральным отверстием + Оранжевая круглая пластина с диагональными прорезями и центральным отверстием

Щели в круглой области
Частичные прорези обрезаны по внешнему и внутреннему контурам.

- Шесть цветных панелей с круглыми, треугольными, звёздчатыми, эллиптическими, ромбическими и крестообразными отверстиями + Шесть цветных панелей с круглыми, треугольными, звёздчатыми, эллиптическими, ромбическими и крестообразными отверстиями

Разные формы отверстий
Круги, треугольники, звёзды, эллипсы, ромбы и кресты.

- Gold circular grille with tangential slots on concentric rings + Gold circular grille with tangential slots on concentric rings

Слоты вдоль окружности
Круговая раскладка, касательная ориентация и центральное отверстие.

- Two circular grilles comparing radial and tangential slots + Two circular grilles comparing radial and tangential slots

Выберите направление
Слева Radial, справа Tangential. Доступна и фиксированная ориентация.

- Green plate perforated only inside an off-center circular zone + Green plate perforated only inside an off-center circular zone

Начните в точке. Ограничьте радиусом.
Выберите точку и радиус заполнения без дополнительного профиля.

- Blue plate with rounded Voronoi perforation confined to a sketch profile + Blue plate with rounded Voronoi perforation confined to a sketch profile

Ваш эскиз — граница
Перфорация по профилю прямо на грани тела. Без Split Face.

- Two panels showing a parametric spread radius change from 16 to 26 millimeters + Two panels showing a parametric spread radius change from 16 to 26 millimeters

Измените параметр. Перестройте узор.
Spread Radius 16 и 26 мм; правая Feature пересчитана после изменения параметра модели.