Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ All notable changes to the `NwcIO` library, the CLI and the `NwcIO.Scene` adapte
## [Unreleased]

### Added
- `HierarchyParser` keeps linked Revit placements instead of throwing: a repeated element under another parent is marked `NwcNode.IsLinkPlacement` and points at the first placement. `NwcSceneReader` writes each placement as its own `SceneModel`, so its geometry and `SourceId` are preserved without duplicate ids inside one model.
- `NwcIO.Scene` converts an `NwcAssembly` into one scene with one `SceneModel` per component document, unique keys from file names, and scene-wide element, geometry and material ids. The `.nwf` document itself is skipped when components exist.
- `NwcIO.Scene` writes Revit level elevations in metres from the level's `LcRevitData_Parameter` length property; a missing, non-finite or unknown-unit value stays null.
- `NwcIO.Scene` converts saved viewpoints to `SceneViewpoint`s (camera position, target, up, field of view in radians, near/far in metres and projection).
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,13 +155,13 @@ The documentation site with API references and guides is at <https://ioextend.gi

## Supported files

Reads binary Navisworks Cache (`.nwc`), Navisworks Document (`.nwd`), and Navisworks Federated (`.nwf`) files. Tested against models saved across Navisworks 2016 through 2026. Scene trees of `.nwd` files with partition nodes are not decoded yet, and linked Revit models (a tree that places one element under two parents) are not supported: open both with `BuildSceneTree = false`.
Reads binary Navisworks Cache (`.nwc`), Navisworks Document (`.nwd`), and Navisworks Federated (`.nwf`) files. Tested against models saved across Navisworks 2016 through 2026. Scene trees of `.nwd` files with partition nodes are not decoded yet: open them with `BuildSceneTree = false`. Linked Revit models (a tree that places one element under two parents) are read; the repeated placements are marked `NwcNode.IsLinkPlacement`.

## Limitations

- Version 0.12.1 is a preview. The API can evolve before 1.0.
- Geometry extraction decodes triangle strips, polylines (including two-vertex line records) and stored normals from `.nwc`/`.nwd` geometry records; point records and quantised positions are not supported. On the lenient path, records above `NwcReaderOptions.MaxMeshVertices` (200,000 by default) are skipped; raise the option for exceptionally large records. Vertex positions are stored as 32-bit floats, so double-precision values are rounded on save, and the writer rejects coordinates with magnitude above 1e8 (the reader's limit) before writing.
- `.nwd` scene trees with partition nodes are not decoded yet, and linked Revit models (a tree that places one element under two parents) are not supported: open them with `BuildSceneTree = false` (CLI: `--no-tree`), also for `.nwf` federations that reference such files.
- `.nwd` scene trees with partition nodes are not decoded yet: open them with `BuildSceneTree = false` (CLI: `--no-tree`), also for `.nwf` federations that reference such files.
- The `.nwc` writer stores vertex positions, triangle indices, mesh ids and names, and rotation/translation; it rejects scaled transforms, line meshes and indices outside the vertex buffer. Transform ids are preserved and each mesh keeps its own transform through a writer-side link stream; transforms referenced only by a mesh are written too. Saved viewpoints keep their camera parameters (including FOV, far distance and projection), comments, id, section planes and section box in a writer-specific trailer; redlines are not written. A tree passed as `RootNode` keeps its names, hierarchy and property value types through a writer-specific parent marker; node-level GUID, transform, material and mesh links are not written. When `PropertyRecords` is non-empty it is the source of truth for the scene tree.
- Scene trees of files without a DbCache directory come from the lenient tag 52/53 scan: the Category/Family/Type nesting is recognized by the stored marker names (the common localized spellings are covered), a repeated marker keeps its level, and other collection names are derived from record order. Node classes other than the observed `LcRevit*` names are recognized by suffix; `LcRevitElement` material definitions stay properties. Model files read through their DbCache hierarchy are not affected by these heuristics.
- The document length unit is not stored in a stream NwcIO decodes. `NwcFileInfo.LengthUnit` is feet for the exact Revit loader/exporter (`LcNwcLoaderPlugin:lcldrevit`/`nwexportrevit`) and unknown otherwise; set `NwcReaderOptions.LengthUnit` when the source unit is known. Clash, grouping and diff tolerances (and the CLI `--clash-tolerance`, `--clash-radius`, `--diff-tolerance`) are in **document units**. IFC export keeps its own `NwcIfcExportOptions.LengthUnit` and does not inherit the document unit yet.
Expand Down
2 changes: 1 addition & 1 deletion docs/format-notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ Once inflated, streams serve dedicated roles identified by their signature prefi
- **Classes**:
- `53` group: `[str name][ptr 52 username][i32 flags][i32 X][i32 Y][Y x attribute ptr][i32 c][c x child ptr]`. Children are class 22 or 53 and are never null.
- `22` leaf: the same layout without `c` and children.
- `X` (element index): 0 on every node that is not a Revit element; on an element node, `X - 1` indexes the GUID table (§2.3). The exporter writes some elements (for example grids) as two sibling nodes with the same `X`, not always adjacent; NwcIO makes the first the element and points the second to it. Such a pair takes two equal GUID table entries (`X - 1` and `X`), so the table size is the number of stored nodes with `X > 0` and the next element's index is `X + 2`. The same `X` under different parents, including a node and its descendant, is rejected as a placed model (`NotSupportedException`).
- `X` (element index): 0 on every node that is not a Revit element; on an element node, `X - 1` indexes the GUID table (§2.3). The exporter writes some elements (for example grids) as two sibling nodes with the same `X`, not always adjacent; NwcIO makes the first the element and points the second to it. Such a pair takes two equal GUID table entries (`X - 1` and `X`), so the table size is the number of stored nodes with `X > 0` and the next element's index is `X + 2`. The same `X` under different parents, including a node and its descendant, is a linked placement: NwcIO keeps it with `NwcNode.IsLinkPlacement`, points `Element` at the first placement, and `NwcIO.Scene` writes it as its own `SceneModel`.
- `32` (`LcOaPartition`, `.nwd` only): `[i32 0]`, a class-53 body, then a trailer that is not decoded. Class 32 nodes are the top-level children of a `.nwd`; class 53 nodes are the top-level children of a `.nwc`.
- `52` display/internal name pair: `[str name][str internal]`. It is the node username, the property tab username and every property key.
- **Attributes** (slots may be null): `86` property tab `[str name][ptr 52][i32 flags][i32 n] n x ([ptr 52 key][i32 type][value])` with value by type `0` none, `1,5,6,7,10,11` `f64`, `2,3` `i32`, `4` and `9` string (type 9 was never seen; it is read as a string), `8` class-52 pointer; `31` material; `40` translation; `41` translation and quaternion (`x -> R(q)x + t`); `39` 3x3 column-major matrix and translation; `79` hyperlinks; `200` and `185` material JSON.
Expand Down
7 changes: 4 additions & 3 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,9 +39,10 @@ dotnet tool install --global NwcIO.Cli
```csharp
using NwcIO;

// Open a .nwc file directly from disk. A .nwd whose scene tree holds partition nodes, and a linked
// Revit model (a tree that places one element under two parents), need
// new NwcReaderOptions { BuildSceneTree = false }, because such trees are not decoded yet.
// Open a .nwc file directly from disk. A .nwd whose scene tree holds partition nodes needs
// new NwcReaderOptions { BuildSceneTree = false }, because those nodes are not decoded yet.
// A linked Revit model (a tree that places one element under two parents) is kept and
// converted into separate scene models.
var doc = NwcDocument.Open("model.nwc");

Console.WriteLine($"Source: {doc.FileInfo?.SourcePath}");
Expand Down
2 changes: 1 addition & 1 deletion docs/public-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ The supported surface is the `NwcIO` and `NwcIO.Model.*` namespaces listed here

| Type | Description |
|---|---|
| `NwcDocument` | Primary document container holding the root scene graph node, meshes, materials, viewpoints, selection sets, and TimeLiner schedules. Opens `.nwc`, `.nwd`, and `.nwf` files via `NwcDocument.Open`; `.nwd` scene trees with partition nodes, and trees that place one Revit element under two parents (linked models), throw `NotSupportedException` unless `BuildSceneTree` is false. `IsRevitSource` is true when the loader plugin is exactly the Revit loader `LcNwcLoaderPlugin:lcldrevit` (Navisworks reading a `.rvt`) or the Revit NWC exporter `nwexportrevit`. `LengthUnit` and `MetresPerUnit` give the length unit of coordinates and length values: feet (0.3048 m) for those two loaders, otherwise `Unknown` and null. |
| `NwcDocument` | Primary document container holding the root scene graph node, meshes, materials, viewpoints, selection sets, and TimeLiner schedules. Opens `.nwc`, `.nwd`, and `.nwf` files via `NwcDocument.Open`; `.nwd` scene trees with partition nodes throw `NotSupportedException` unless `BuildSceneTree` is false. Trees that place one Revit element under two parents (linked models) are decoded: the repeated node is marked `IsLinkPlacement`. `IsRevitSource` is true when the loader plugin is exactly the Revit loader `LcNwcLoaderPlugin:lcldrevit` (Navisworks reading a `.rvt`) or the Revit NWC exporter `nwexportrevit`. `LengthUnit` and `MetresPerUnit` give the length unit of coordinates and length values: feet (0.3048 m) for those two loaders, otherwise `Unknown` and null. |
| `NwcDocumentBuilder` | Fluent builder API for creating Navisworks documents and geometry programmatically from code. |
| `NwcWriter` | Direct `#LcUStream-V1.1` binary container serializer and continuous zlib chunk writer. Throws `ArgumentException` before writing for input it cannot store faithfully: an unrecognised header, scaled transforms, line meshes, triangle indices outside the vertex buffer, out-of-range vertex counts or coordinates, records or nodes without a name/class, and viewpoint names the reader would rename. Mesh ids, names and triangle indices are stored; normals and materials are not. `Materials`, `XRefs`, `DbCache`, `AppearanceProfiler`, `ClashTests` and `GridSystem` are not written; the output is read back by NwcIO but has not been verified in Autodesk Navisworks. |
| `NwcReaderOptions` | Per-open options: which streams to read (property records, GUIDs, transforms, meshes, viewpoints, selection sets, TimeLiner), whether to read materials (`ReadMaterials`: decoded from the file on the strict path, named in property records elsewhere, with a neutral inferred colour unless a `revit_Color` record gives one), whether to build the scene tree (`BuildSceneTree`), catalog retention. |
Expand Down
4 changes: 2 additions & 2 deletions docs/scene.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ The scene has one model per input document. Geometry and instance positions are
| `SceneModel.Key`, `Name` | `NwcSceneOptions.ModelKey`, else the file name with its extension. |
| `SceneModel` fields | `SourceFormat` is `nwc`; `Path` is set only when the scene is read from a path; `CreatedAt` is the source timestamp as `yyyy-MM-ddTHH:mm:ssZ`; `Application` is the loader plugin after its last `:` (for example `lcldrevit`, or `nwexportrevit` for the Revit NWC exporter); `SourceLengthUnit` is `ft` when the unit used is feet. |
| Elements | One `SceneElement` per tree node, `Id` = the node's preorder index with the root as 0, `Name` = the node name. Kind: the root is `Model`; on Revit files a depth-1 node holding a Revit level is `Level`; every node that is a Revit element or lies inside one (its parts, and the second node of a sibling pair) is `Element`; a leaf outside elements (no children, tag other than 53) is `Element` too; every other node is `Group`. |
| Sibling pair | A Revit export may write one element twice under one parent. The first in stored order is the element; the second maps as a part: its `ParentId` is the first, and it has no `SourceId`. The same element under different parents (a linked model) is not supported. |
| Sibling pair | A Revit export may write one element twice under one parent. The first in stored order is the element; the second maps as a part: its `ParentId` is the first, and it has no `SourceId`. The same element under different parents is a linked placement: it becomes its own `SceneModel`, rooted at the placement or, for a shared subtree, at the highest group below the linking element or the root, with the same `SourceId` in that model. |
| `SourceId` | The element's export GUID (`NwcNode.ElementGuid`) in format `D`, on element nodes only. This derivation does not change; a golden test pins it. |
| `IfcGuid` | The element's IFC GlobalId (`NwcNode.IfcGlobalId`), on element nodes only. This derivation does not change; a golden test pins it. |
| `Category`, `TypeName` | Revit files only, on `Element`-kind nodes only, by tree position: the category is the name at depth 2 on the path from the root, the type name the name at depth 4 when the element is at depth 5; otherwise empty. |
Expand Down Expand Up @@ -89,7 +89,7 @@ A property with no text, a non-finite number, numeric text that does not parse,

## Limits

- `.nwd` partition trees and linked Revit models are not supported: `Read` throws `NotSupportedException`.
- `.nwd` partition trees (class 32) are not supported: `Read` throws `NotSupportedException`. Linked Revit placements are supported: each placement becomes its own `SceneModel`.
- A `.nwf` file is read like a `.nwc` by `Read(string)`: the models it refers to are not loaded, so the scene holds only the content of the file itself (`xrefs-skipped`), and its `SourceFormat` is still `nwc`. Use `Read(NwcAssembly, ...)` with `NwcAssembly.OpenNwf` to convert the component models into one scene.
- Level elevations are written in metres when the level carries its length parameter and the unit is known; otherwise they stay null. Saved viewpoints are written when their camera is finite and the document unit is known; otherwise they are reported with `viewpoints-skipped`. File viewpoints without the writer trailer (every Navisworks file) use an approximated projection, field of view and far distance (`viewpoint-camera-approximated`), and their section planes, section box, redlines and comments are not part of the scene (`viewpoint-content-skipped`).
- Selection sets and search sets, the TimeLiner schedule and clash tests are not converted (`selection-sets-skipped`, `timeliner-skipped`, `clash-tests-skipped`).
Expand Down
4 changes: 2 additions & 2 deletions src/NwcIO.Cli/Program.cs
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ Reads Autodesk Navisworks files (.nwc, .nwd, .nwf) or assemblies of models
--no-materials Disable material and surface color extraction
--catalog Include raw container stream catalog (offsets, sizes, kinds)
--no-transforms Exclude 3D transform matrices from JSON export
--no-tree Skip reading the scene tree and exclude it from JSON export (required to open a .nwd with partition nodes or a linked Revit model)
--no-tree Skip reading the scene tree and exclude it from JSON export (required to open a .nwd with partition nodes)
--no-indent Write compact JSON instead of pretty-printed indented JSON
--bvh-stats Include Bounding Volume Hierarchy (BVH) spatial index statistics
--raycast <coords> Perform 3D raycast test: "originX,originY,originZ,dirX,dirY,dirZ"
Expand All @@ -97,7 +97,7 @@ 2 File or folder not found
3 Data format error or parsing failure
""";

// The reader throws NotSupportedException only for a scene tree it cannot convert (class-32 partition nodes, linked Revit models); --no-tree reads around both.
// The reader throws NotSupportedException only for a scene tree it cannot convert (class-32 partition nodes); --no-tree reads around it.
private const string NoTreeHint = " Use --no-tree to read geometry and placement without the scene tree.";

public static int Main(string[] args) => Run(args, null, null, null);
Expand Down
21 changes: 20 additions & 1 deletion src/NwcIO.Scene/NwcSceneReader.Geometry.cs
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,25 @@ public static partial class NwcSceneReader
{
private const int MaxLineColourGroups = 64; // shortcut: segments of colours past 64 per record are drawn with the material colour; the corpus has 10 palette entries in all (spike-look (a)); raise it if a real file shows more

// The node a mesh counts for: the nearest linked placement at or above it inside its element, else its element, else the node itself.
private static NwcNode Owner(NwcNode node)
{
if (node.Element is not { } element)
{
return node;
}

for (var n = node; n is not null; n = n.Parent)
{
if (ReferenceEquals(n, element) || n.IsLinkPlacement)
{
return n;
}
}

return element; // the second node of a sibling pair: its element is a sibling, not an ancestor
}

// Writes the geometries, materials and instances of the document's meshes in their order, each made at first use; returns
// the element of every placed mesh (its node's Element, or the node itself outside elements).
private static HashSet<NwcNode> AddGeometry(NwcDocument document, SceneDocument scene, double metresPerUnit, Dictionary<NwcNode, long> ids, List<SceneDiagnostic> diagnostics)
Expand Down Expand Up @@ -65,7 +84,7 @@ private static HashSet<NwcNode> AddGeometry(NwcDocument document, SceneDocument
scene.Instances.Add(new SceneInstance { ElementId = elementId, GeometryId = geometryId, Transform = transform, MaterialId = materialId, Color = colour });
}

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

if (unplaced > 0)
Expand Down
Loading
Loading