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`. 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-документы, токены или артефакты с локальной машины. 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/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..120fe62 --- /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.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 3547359..1519d50 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.ru.md) · [Органические узоры](docs/ORGANIC_PATTERNS.ru.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/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/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. 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/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. diff --git a/docs/README_REFERENCE.md b/docs/README_REFERENCE.md index 17c30a9..4bb832e 100644 --- a/docs/README_REFERENCE.md +++ b/docs/README_REFERENCE.md @@ -1,5 +1,5 @@
-
+
Download v1.1.0 · Русский · Report a problem
+Download v1.1.0 · Русский · Report a problem
## 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. @@ -33,47 +33,47 @@ To perforate part of an existing face, draw a closed sketch on that face, finish
-
+
Honeycomb grille |
-
+
Rounded Voronoi |
-
+
Slots on a circular boundary |
-
+
A shape for every pattern |
-
+
Slots that follow the circle |
-
+
Choose the direction |
-
+
Start here. Stop at this radius. |
-
+
Your sketch is the boundary |
-
+
Change the parameter. Rebuild the pattern. |
|