Skip to content

feat(scene): keep linked Revit placements and split them into models - #242

Merged
mahach666 merged 6 commits into
mainfrom
fix/scene-linked-models
Nov 16, 2026
Merged

mahach666 merged 6 commits into
mainfrom
fix/scene-linked-models

Conversation

@mahach666

Copy link
Copy Markdown
Collaborator

Partially fixes #182. Stacked on #241 (fix/scene-multi-model). This adds linked Revit model handling.

What changed

  • HierarchyParser no longer throws when one element index appears under different parents or in a shared subtree. It keeps the placement, points Element at the first placement, and marks the node with the new NwcNode.IsLinkPlacement.
  • NwcSceneReader creates a separate SceneModel for every linked placement:
    • the placement becomes that model's root (Kind = Model, ParentId = null);
    • its geometry and SourceId are preserved, so the same source element can appear once per model;
    • descendants inherit the link model id; link model ids come from scene.Models.Count + 1 and use unique keys from the node name (Link_N fallback);
    • SceneDocument.Validate() passes for the synthetic link scene.
  • The geometry placer now marks the link placement itself as placed, not only node.Element, so link geometry is counted and attached to the link model.
  • Updated the old tests that expected NotSupportedException; added parser and scene regressions.
  • Docs and changelog updated: linked models are supported, class-32 .nwd partition trees remain the unsupported case.

Files

  • src/NwcIO/Model/NwcNode.cs
  • src/NwcIO/Internal/Parsing/HierarchyParser.cs
  • src/NwcIO/NwcDocument.cs
  • src/NwcIO.Scene/NwcSceneReader.cs
  • src/NwcIO.Scene/NwcSceneReader.Geometry.cs
  • tests/NwcIO.Tests/HierarchyParserTests.cs
  • tests/NwcIO.Tests/ElementIdentityTests.cs
  • tests/NwcIO.Scene.Tests/NwcSceneReaderTests.cs
  • docs/scene.md, docs/format-notes.md, docs/public-api.md, docs/getting-started.md, CHANGELOG.md

Tests

  • dotnet build NwcIO.slnx -c Release — success, 0 warnings, 0 errors.
  • dotnet test NwcIO.slnx -c Release --no-build — full suite passes (exit 0).
  • ElementIdentityTests: 24 passed.
  • New Read_DuplicateElementUnderDifferentParents_KeepsBothAsLinkedPlacement.
  • New Read_LinkedPlacement_BecomesItsOwnSceneModel, including two models, two instances, distinct model ids, preserved SourceId, and SceneDocument.Validate().

Remaining limitations

  • A linked model's levels are not cloned: link elements start with LevelId = null rather than a level from the main model.
  • Link model keys come from the placement node name, not from the linked file path (the hierarchy stores no reliable path).
  • Nested links create nested SceneModels.
  • Class-32 .nwd partition trees remain unsupported; the saved-view FOV/height and far distance remain undecoded.

HierarchyParser no longer throws for a repeated element under another parent: the node is kept, marked NwcNode.IsLinkPlacement, and points at the first placement. NwcSceneReader starts a new SceneModel for each linked placement, uses the placement as the model root, preserves its geometry and SourceId, and gives its descendants the link model id. Update docs and the old throw-based tests; add parser and scene regressions with SceneDocument.Validate().
@mahach666

Copy link
Copy Markdown
Collaborator Author

Код-ревью — feat(scene): keep linked Revit placements and split them into models (стек на #241)

Вердикт: approve-with-comments

Резюме ревьюеров

  • correctness: PR вместо NotSupportedException сохраняет повторные размещения элемента как NwcNode.IsLinkPlacement, а NwcSceneReader выносит каждое такое размещение в отдельную SceneModel. Идея разумна и узкая по объёму, но пометка IsLinkPlacement ставится на каждый узел с уже встречавшимся X, а не только на корень повторного поддерева, поэтому реальная связь с несколькими элементами дробится на множество моделей. Тесты используют только листовые размещения без потомков и не проверяют заявленное наследование модели потомками. Часть документации (README, справка CLI) осталась с прежним утверждением, что связанные модели не поддерживаются.
  • robustness: PR вместо NotSupportedException сохраняет повторное размещение элемента (тот же X под другим родителем) как NwcNode.IsLinkPlacement, а NwcSceneReader превращает каждое такое размещение в отдельную SceneModel. С точки зрения устойчивости и совместимости изменение рискованное: единственная защита от размножения элементов через DAG (отказ с исключением) снята, при этом число моделей не ограничено, а уникализация ключей квадратична. Признак «ссылка» ставится по слабому правилу (повтор X под другим родителем), из-за чего повторные элементы общего поддерева, вторые узлы пар и вложенные узлы с тем же X дают лишние или неверные модели. Тесты синтетические и проверяют только один элемент с мешем прямо на узле-ссылке, а README, справка CLI и XML-доки по-прежнему утверждают, что связанные модели не поддерживаются.
  • tests-claims: PR feat(scene): keep linked Revit placements and split them into models #242 перестаёт бросать NotSupportedException на втором размещении элемента под другим родителем: HierarchyParser ставит NwcNode.IsLinkPlacement, а NwcSceneReader делает из каждого такого узла отдельную SceneModel. С точки зрения тестов и заявлений качество слабое. Единственный сценарий на уровне сцены — один плоский узел-«ссылка» без потомков. Не проверены ElementCount/ElementsWithGeometry, потомки размещения, вложенность, ключи Link_N/feat: Add Clash Detective 3D engine, XML Clash Reports, BCF 2.1 exporter, and NWF manifests (v0.5.0) #2 и общее поддерево из нескольких элементов, а именно оно даёт реальное поведение парсера. Часть документации и контрактов (README, справка CLI, XML-doc, docs/scene.md) продолжает утверждать, что ссылки не поддерживаются или что «одна модель на документ».

Подтверждённые замечания (4)

1. [СРЕДНЯЯ] Квадратичная уникализация ключей и неограниченное число SceneModel на недоверенном входе — src/NwcIO.Scene/NwcSceneReader.cs:174 (security-dos; уверенность high; проверка: trace:подтвердил, intent:подтвердил)

Для каждого узла IsLinkPlacement вызывается UniqueModelKey, который при каждом вызове заново строит HashSet из ключей всех уже созданных моделей, а при совпадении имён перебирает суффиксы #2, #3, ... Число link-моделей ничем не ограничено. До PR любой элемент в общем поддереве приводил к NotSupportedException, и это была единственная защита от размножения элементов через DAG; README прямо заявляет, что читатель ограничивает crafted-вход (8 388 608 узлов), а теперь все эти узлы могут стать моделями.

Уточнение проверяющего: Уточнение: квадратичность есть всегда (перестройка HashSet на каждый link-узел, NwcSceneReader.cs:174), а дополнительный перебор суффиксов добавляется только при совпадающих именах узлов. Утверждение, что раньше «любой элемент в общем поддереве приводил к NotSupportedException», верно только для общего поддерева с X>0 под разными родителями. Остальные детали (отсутствие лимита на число link-моделей, рост SceneModel до миллионов при крупных DAG) соответствуют коду.

Сценарий: Небольшой NWC: общий (back-referenced) узел S с листом X=1 (в таблице GUID одна запись, проверяется только X <= guids.Count) и 100 000 родителей, ссылающихся на S. HierarchyParser укладывается в лимит 2^23 узлов и помечает 99 999 повторов как IsLinkPlacement. NwcSceneReader.Read делает 99 999 вызовов UniqueModelKey: i-й вызов строит множество из i ключей и, при одинаковом имени листа, перебирает i суффиксов. Это порядка 10^10 операций и аллокаций строк, то есть чтение зависает на минуты и раздувает память SceneModel (до миллионов при большем числе ссылок). Тестов на большое число link-моделей нет.

var used = new HashSet<string>(scene.Models.Select(m => m.Key), StringComparer.Ordinal);
string unique = candidate;
int suffix = 2;
while (!used.Add(unique))

Исправление: Держать один HashSet ключей на весь ConvertInto, а не пересоздавать его, и счётчик суффиксов на базовое имя. Добавить явный лимит числа link-моделей (по аналогии с MaxExpandedNodes) и диагностику или исключение при превышении. Добавить тест на тысячи повторов одного имени.

2. [СРЕДНЯЯ] Модель создаётся на каждый повторный элемент, а не на каждую связанную модель — src/NwcIO.Scene/NwcSceneReader.cs:281 (correctness; уверенность high; проверка: trace:подтвердил, intent:подтвердил)

HierarchyParser помечает IsLinkPlacement любой узел с X, уже встречавшимся под другим родителем, а сканер создаёт SceneModel на каждый такой узел. Корня ссылки в иерархии нет, поэтому общее поддерево S (или скопированная иерархия) с N элементами порождает N моделей из одного элемента, а не одну модель ссылки. Вложенные элементы (X>0 внутри элемента) становятся вложенными моделями. Группы вроде S' остаются в основной модели без детей: их дети ушли в другие модели с ParentId=null. Заявление PR «каждое размещение связанной модели становится отдельной SceneModel» этим кодом не выполняется.

Уточнение проверяющего: Для общего поддерева S из N элементов, размещённого под двумя родителями, NwcSceneReader создаёт N моделей по одному корню-элементу (ParentId=null) вместо одной модели на размещение. Группа S под вторым родителем остаётся пустой в основной модели. Причина в том, что HierarchyParser помечает IsLinkPlacement каждый повторный X и не отмечает корень повторно размещённого поддерева. Реальную частоту такого паттерна в корпусе по коду определить нельзя, а тесты покрывают только один лист-элемент.

Сценарий: Иерархия: A -> S -> [E1(X=1), E2(X=2), ... E500(X=500)] и B -> S (тот же общий узел, это именно случай теста Open_ElementInASharedSubtree). Для B все 500 элементов оказываются повторами и получают IsLinkPlacement. В результате SceneDocument содержит 1 + 500 моделей, каждая с одним элементом (ключи по именам элементов, например «Basic Wall#2», «Basic Wall#3»), а группа S под B остаётся пустой в модели 1. Сценовый тест Read_LinkedPlacement_BecomesItsOwnSceneModel покрывает один лист-элемент и не показывает этого.

if (node.IsLinkPlacement && parent is not null)
{
    nodeModelId = scene.Models.Count + 1;

Исправление: Определять границу ссылки детерминированно (корень повторно размещённого поддерева, а не каждый повторный X) и создавать модель один раз на такой корень. Либо оставить NotSupportedException для случаев, где корень ссылки не определяется однозначно. Добавить тест с поддеревом из нескольких элементов под двумя родителями.

3. [СРЕДНЯЯ] UniqueModelKey на каждую ссылку заново строит HashSet всех ключей: квадратичное время на недоверенном входе — src/NwcIO.Scene/NwcSceneReader.cs:174 (security-performance; уверенность high; проверка: trace:подтвердил, intent:подтвердил)

Раньше ключи собирались в общий usedKeys за O(1) на документ. Теперь UniqueModelKey создаёт new HashSet по всем scene.Models при каждом вызове, а он вызывается на каждый IsLinkPlacement (строка 284). Цикл суффиксов #2, #3, … каждый раз начинается заново. Число размещений определяется входным NWC (см. предыдущую находку: по одному на повторный элемент), а лимит чтения — 8,388,608 узлов.

Уточнение проверяющего: Находка верна по механизму: UniqueModelKey пересоздаёт HashSet всех ключей моделей на каждое link-размещение, поэтому чтение сцены с M размещениями стоит O(M^2), а при повторяющихся именах цикл суффиксов добавляет ещё O(k) на вызов. На обычных файлах (единицы или десятки связей) это незаметно. Проблема проявляется только на специально собранных или патологических NWC с десятками тысяч повторных размещений, поэтому severity medium (DoS-замедление), а не high. Тестов на много размещений и на повторяющиеся имена нет.

Сценарий: Файл с общим поддеревом на 200 000 элементов, названных одинаково (например, «Basic Wall»), даёт 200 000 моделей. Каждый вызов строит множество до 200 000 строк, а цикл подбирает суффикс до k попыток с выделением строки на каждой. Это порядка 10^10 операций: NwcSceneReader.Read практически зависает и выделяет сотни тысяч SceneModel. Тестов на много ссылок или на повторяющиеся имена нет.

var used = new HashSet<string>(scene.Models.Select(m => m.Key), StringComparer.Ordinal);

Исправление: Хранить HashSet ключей и словарь «имя → следующий суффикс» на время ConvertInto (или на сцену), а не пересоздавать их на каждый вызов. Добавить тест на несколько размещений с одним именем и проверку ключей #2, #3.

4. [НИЗКАЯ] Заявленный учёт геометрии ссылки не проверяется тестом и неполон для потомков размещения — src/NwcIO.Scene/NwcSceneReader.Geometry.cs:69 (test-quality; уверенность high; проверка: trace:подтвердил, intent:подтвердил)

PR заявляет, что «геометрия ссылки учитывается». Тест Read_LinkedPlacement_BecomesItsOwnSceneModel не проверяет ни ElementCount, ни ElementsWithGeometry: если удалить placed.Add(node), он всё равно пройдёт, потому что инстансы добавляются независимо от placed. Исправление покрывает только случай, когда меш висит на самом узле-размещении. Потомки размещения получают Element = first (HierarchyParser.cs:162 при X == 0), и для меша на потомке в placed попадает first, а не узел-размещение. В реальных Revit-файлах меши лежат на листьях внутри элемента (инвариант leaf-in-element в RealFileInvariantTests), а тест кладёт меш прямо на узел.

Уточнение проверяющего: Исправление placed.Add(node) учитывает геометрию размещения только когда меш висит на самом узле-размещении. Для меша на потомке размещения (типичный случай реальных Revit-файлов) в placed попадает first, а не L. Из-за этого ElementsWithGeometry занижается для L и завышается для first. Тест не ловит дефект: он не утверждает ElementCount и ElementsWithGeometry и не имеет потомков у ссылки. Влияет только на статистику отчёта, не на инстансы и не на модели сцены, поэтому серьёзность medium, а не high.

Сценарий: Элемент E (first) имеет дочерний лист C1 с мешем, размещение L (X равен X у E) имеет дочерний лист C2 с мешем. После AddGeometry placed = {E, C1, C2}, L в нём нет. В обходе elementCount увеличивается для E и L, а elementsWithGeometry — только для E. Результат ElementsWithGeometry = 1 вместо 2, при том что в модели ссылки есть инстанс C2. Если у E геометрии нет, а есть только у L, E ошибочно считается имеющим геометрию. Тест такого не ловит: он не утверждает счётчики и не имеет потомков у ссылки.

placed.Add(node.Element ?? node);
placed.Add(node);

Исправление: Отмечать как размещённое ближайшее размещение-предок меша (с учётом IsLinkPlacement), а не только node.Element. В тест добавить Assert на ElementCount/ElementsWithGeometry, потомка-лист с мешем под ссылкой и проверку, что инстанс принадлежит элементу модели 2.

sim added 2 commits November 16, 2026 12:53
Share one key set and suffix map per conversion, cap linked models, and create one model per top-level link placement so repeat elements inside a linked subtree stay in that model.
HierarchyParser now marks the highest group below a linking element (or the element itself) as IsLinkRoot; NwcSceneReader creates one model for that root and reuses it for every repeated element inside. Cover a shared subtree with three elements and a single linked group.
@mahach666
mahach666 changed the base branch from fix/scene-multi-model to main November 16, 2026 19:44
@mahach666
mahach666 merged commit f3f4686 into main Nov 16, 2026
5 checks passed
@mahach666
mahach666 deleted the fix/scene-linked-models branch November 17, 2026 23:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

NwcIO.Scene cannot convert .nwd trees, linked models, viewpoints, level elevations, .nwf

1 participant