Skip to content

NwcIO 0.12.0: element identity, property tabs, units and file materials; new NwcIO.Scene adapter - #168

Merged
mahach666 merged 29 commits into
mainfrom
feat/nwcio-scene
Nov 14, 2026
Merged

mahach666 merged 29 commits into
mainfrom
feat/nwcio-scene

Conversation

@mahach666

Copy link
Copy Markdown
Collaborator

NwcIO 0.11 gave a scene adapter no stable element id, no length unit, no colours from the file, and only two thirds of an element's properties: the rest live in LcOaPartitionProps, which it did not read. This PR adds those facts to the core public API and ships a new package, NwcIO.Scene, that turns a Navisworks model into an IOScene scene document. It is the step that lets IOViewer open a .nwc and show the selection tree with its properties.

Release order. IOExtend/IOScene#5 registers the nwc: key namespace and must be merged before this PR and the v0.12.0 tag.

Core (NwcIO 0.12.0).

  • Element identity: NwcNode.IsElement, Element (the element a part or the second node of a sibling pair belongs to), ElementGuid (the Revit export GUID from LcOpGuidStore, indexed by the node's element index) and IfcGlobalId (the valid IFC_GUID parameter, otherwise the export GUID in IFC base-64, the rule of RvtIO.Scene).
  • Properties: NwcPropertyTab and NwcNode.PropertyTabs keep tab identity; records carry TabInternalName and InternalName. The tabs and element ids stored in LcOaPartitionProps are attached to their nodes; that segment is checked only while the scene tree is built, so BuildSceneTree = false never touches it and a .nwd still fails first on its partition nodes.
  • NwcLengthUnit, NwcDocument.LengthUnit and MetresPerUnit (feet for the Revit loader). The partition header is read with its alignment pads, so the timestamp and loader plugin are read from every model file.
  • Materials are decoded from the fragment appearance (diffuse colour, alpha, class-31 name) instead of name heuristics; Roughness and Metallic keep their defaults. NwcMesh.GeometryIndex and per-vertex NwcMesh.LineColors (palette order ABGR).
  • NwcSavedViewpoint.Id is Guid?: files store no viewpoint id, so 0.11's random id per read is gone.

Adapter (NwcIO.Scene 0.12.0). NwcSceneReader.Read(path) and Read(document, options):

  • the full tree through ParentId in preorder, with elements, parts and Revit levels (found by element id, language-free);
  • SourceId (export GUID) and IfcGuid on element nodes;
  • one property set per tab object, with nwc: keys only for internal names that do not change with language or a rename, and value text identical to RvtIO.Scene;
  • geometry in metres shared per geometry record, instances with mirrors kept, file materials, line colours, and Revit grid lines.

Packaged like IfcIO.Scene: exact NwcIO pin, IOScene [0.1.0, 0.2.0-0.0); release.yml publishes NuGet before the GitHub release; pack-release.ps1 asserts the adapter nuspec and now builds the solution first. docs/scene.md documents the mapping, the frozen derivations (SourceId, IfcGuid, keys and value text, pinned by a golden test), diagnostics and limits.

Behaviour changes (all **Breaking:** bullets in the CHANGELOG): element GUIDs on strict-path nodes; linked Revit models (one element under two parents) throw NotSupportedException unless BuildSceneTree is false; node properties include LcOaPartitionProps; decoded materials replace the heuristics on the strict path; nullable viewpoint ids; the aligned partition header (files written by NwcIO 0.11 whose path or plugin needed a pad lose those fields).

Crafted input. The new reads stay strict and bounded: LcOpGuidStore, LcOaPartitionProps (directory shape, table of contents, root classes, class-66 body) and class-54 floats are checked exactly; tab references count toward the expanded-property cap. The adapter stays linear in time and output on untrusted files: line segments are grouped by colour through a dictionary, each line geometry carries only its own vertices, there are at most 64 colour groups per geometry record, and per-node set deduplication and category lookup are linear.

Tests.

  • dotnet build NwcIO.slnx -c Release: 0 warnings. NwcIO.Tests: 822 passed, 3 skipped (env-gated). NwcIO.Scene.Tests: 48 passed, 1 skipped on net8.0 and net10.0. docfx --warningsAsErrors: 0 warnings. pack-release.ps1 under Windows PowerShell 5.1: three 0.12.0 packages, adapter nuspec checked.
  • Synthetic fixtures only (SyntheticTree, SyntheticFragments, RevitSample, new line vectors); a golden identity test pins SourceId, IfcGuid, keys and value text.
  • Checked locally against a private set of 54 Revit-exported .nwc files and one .nwd (not committed; env-gated tests report aggregates and file indices only): every file converts with an empty Validate(); 151,302 elements plus 334 sibling pairs, equal to the GUID tables; 562 levels; 101 grid lines; the decoded material colour equals the Revit material colour in 184,676 of 184,676 comparisons; the only diagnostic is viewpoints-skipped.

Not verified / limits.

  • .nwd partition trees and linked models are still not converted (use BuildSceneTree = false in the core).
  • The props of .nwd files were seen on one sample only.
  • Saved viewpoints are not converted: the core still recognises views in only some real files and keeps the 60° default field of view.
  • Not compared with Navisworks itself; the pack script was checked on a simulated clean state, not a fresh clone.

Follow-ups, not in this PR. Reading saved viewpoints of real files (projection and field of view); .nwd partition nodes; .nwc input with a hierarchical tree and lines in IOViewer 0.4.0.

Fix review findings for task 5. Locate now only records the
LcOaPartitionProps directory entries. The duplicate-entry, segment shape
and table-of-contents checks run when the hierarchy reader first needs a
root, so a .nwd still throws NotSupportedException at its first class-32
node, and BuildSceneTree = false never checks the props. A segment that
holds only its table of contents is no longer taken for a missing
segment: it fails the root-stream count check.
NwcMesh.GeometryIndex is the 0-based geometry record index (-1 outside
model files); NwcMesh.LineColors holds one colour per vertex for line
meshes, decoded from the class-95 palette in ABGR order.
…ng one

NwcSavedViewpoint.Id is Guid?: null when read from a file or from Navisworks
XML without a valid guid, generated for viewpoints made in code. BCF export
uses one new GUID per viewpoint without id, JSON writes null, XML omits guid.
… number

A code-built record of value type 1, 6, 7, 10 or 11 whose text does not
parse with the invariant culture made the conversion throw. Design 6.3
leaves out a value that cannot be shown exactly, so it is now left out
like a non-finite double.
…ch group only its own vertices

Fix review findings for task 14: line segments are grouped through a colour dictionary plus one bucket for mixed segments,
in first-seen order, and each line geometry carries only the vertices its segments use, with its indices remapped,
so many line colours no longer cost quadratic time or output.
A Revit element of category OST_Grids with one single-segment horizontal
line mesh becomes a grid line in one "Grids" system; other grids stay
elements. Files with saved views get a viewpoints-skipped warning, and no
viewpoint is written.
Golden lines for RevitSample (model key, SourceId and IfcGuid, keyed sets and
values), a Validate and SceneJson round trip of the sample, and hostile
strings (quotes, control characters, non-BMP, Cyrillic) through SceneJson.
Add the IOScene type aliases to the golden tests so the file matches its sibling test files.
Add docs/scene.md (usage, what the scene holds, property text, diagnostics, limits), link it in the docs table of contents and the README, update the README feature and scope text, and record the adapter in the changelog.
Cap the line colour groups of a geometry record at 64 (further colours are
drawn with the material colour and reported as line-colours-capped), so the
instances of a shared record stay linear in the fragments; dedup a node's
property sets through a hash set; number elements by a preorder pre-pass
instead of NwcNode.Id, which repeats on files read without their DbCache
directory, and report meshes whose node is outside the tree as unplaced;
carry the depth-2 and depth-4 names on the walk's stack instead of walking
the parent chain per element; word unit-unknown so it is also true when
NwcSceneOptions.LengthUnit is Unknown.
…models for --no-tree

Drop the freeze claims on Category, TypeName and Levels (only the model key,
SourceId, IfcGuid and the keyed values are frozen) and pin the family and
type element keys in the golden through RevitSample; state the Kind rule as
the code applies it (every node inside an element is an Element); make the
README link to the scene page absolute for nuget.org; name linked Revit
models next to .nwd partition trees wherever BuildSceneTree = false and
--no-tree are explained; cover NwcIO.Scene in the changelog header and list
the export options a 0.11-written header with a pad loses.
…, test the gaps

Add the non-finite class-54 rule to the materials Breaking bullet and check
it with and without the tree and ReadMaterials, also for a float the reader
drops; say that ReadGuids controls NwcDocument.Guids and that element GUIDs
come from LcOpGuidStore whenever the tree is built, what ElementGuid and
IsElement hold on the strict path, and how the class-66 element-id tab is
named. Test a line palette in token form, the children of a pair's second
node, IFC GlobalId fallbacks for another parameter, another value type and
a character outside the alphabet, and the boolean value text.
…lean checkout

pack runs with --no-build, and the publish steps build only NwcIO and
NwcIO.Cli, so NwcIO.Scene failed with NU5026 unless something had built it.

@mahach666 mahach666 left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed 734a77d. No actionable findings; ready after IOExtend/IOScene#5 is merged.

Read the core parser/identity/material/unit changes, adapter mappings and callers, tests, namespace contract and packaging/release changes. Release solution build and DocFX warnings-as-errors both passed with zero warnings/errors. Full solution tests were run separately with each of two private real NWC fixtures: core 825 passed and adapter 49 passed on each of net8.0/net10.0, zero skips/failures. CI Windows/Linux/Docs is green.

Ran the complete pack-release.ps1 under Windows PowerShell 5.1 at the reviewed commit: all three 0.12.0 packages, archives/checksums and adapter nuspec assertions passed. Verified NwcIO.Scene's exact NwcIO [0.12.0] dependency, IOScene [0.1.0, 0.2.0-0.0) range and dependency-free core. Built an isolated package consumer from this local feed on net8.0 and net10.0. Both real files produced valid scenes and JSON roundtrips; SourceId/IfcGuid were stable across independent reads and preserved on roundtrip. Independently checked every triangle index and 428,239 placed triangle vertices against core world coordinates converted to metres: maximum absolute difference 4.656612873077393e-10 m. Aggregate output: 5,187 source elements, 8,056 instances, 4,181 shared geometries, 25 levels; the only conversion diagnostic was viewpoints-skipped.

Limits: two real NWC files only; no real NWD/NWF or non-Revit conversion, no visual comparison with Navisworks/IOViewer and no NuGet publication. The documented skipped-viewpoint and unsupported linked-model/partition-tree limitations remain. No product source edits or merge/tag/publication performed. Submitted as COMMENT because the authenticated account is also this PR's author.

@mahach666
mahach666 merged commit 485e5c6 into main Nov 14, 2026
4 checks passed
@mahach666
mahach666 deleted the feat/nwcio-scene branch November 14, 2026 13:39
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.

1 participant