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
- `meshes-skipped` reader diagnostic: `NwcDocument.Diagnostics` reports geometry records that the lenient reader path skipped (vertex count out of range, truncated or malformed record). `nwcio --report` prints `NwcDocument.Diagnostics` and `NwcAssembly.Diagnostics` for a single file, a folder and an `.nwf`.
- `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.
Expand Down
2 changes: 1 addition & 1 deletion docs/public-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ The supported surface is the `NwcIO` and `NwcIO.Model.*` namespaces listed here
| `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. |
| `NwcAssembly` | Federated multi-model assembly: `Create`, `LoadFromDirectory` (several patterns, recursion), `OpenManifest` (`.nwf.xml`), `OpenNwf` (with `UnresolvedXRefs`/`SkippedXRefs` reporting), combined meshes/materials/bounds, per-assembly exports and clash runs. |
| `NwcDiagnostic` / `NwcDiagnosticSeverity` | Reader warning for skipped or substituted data (`Severity`, stable `Code`, `Message`, optional `StreamIndex` and `ByteOffset`), listed in `NwcDocument.Diagnostics` and `NwcAssembly.Diagnostics`. Codes: `ContainerTrailingGap` (bytes after the last container stream, including a truncated zlib stream), `NwfUnresolvedXref` and `NwfSkippedXref` (from `NwcAssembly.OpenNwf`). |
| `NwcDiagnostic` / `NwcDiagnosticSeverity` | Reader warning for skipped or substituted data (`Severity`, stable `Code`, `Message`, optional `StreamIndex` and `ByteOffset`), listed in `NwcDocument.Diagnostics` and `NwcAssembly.Diagnostics`. Codes: `meshes-skipped` (geometry records dropped because their vertex count is out of range or they are truncated or malformed; not raised on the strict DbCache path), `ContainerTrailingGap` (bytes after the last container stream, including a truncated zlib stream), `NwfUnresolvedXref` and `NwfSkippedXref` (from `NwcAssembly.OpenNwf`). `nwcio --report` prints them. |
| `NwcNode` | Scene graph tree node representing layers, categories, composite elements, and geometry instances with optional transformations and properties. For Navisworks model files read through their DbCache directory (the strict path), `Meshes` lists every mesh placed on a leaf and `Mesh` the first, ids are depth-first preorder indices, `Transform` is null; `IsElement` marks Revit element nodes, `ElementGuid` is their export GUID from `LcOpGuidStore`, `IfcGlobalId` is the GlobalId the Revit IFC export gives the element: its valid `IFC_GUID` parameter, else its export GUID in the IFC base-64 form (the rule of `RvtIO.Scene`), and `Element` points every node inside an element (and the second node of a sibling pair that repeats one element) to its element node; properties include the tabs stored in `LcOaPartitionProps`; other files leave `Meshes` empty and `Mesh` null. |
| `NwcPropertyRecord` | Property record (`Class`, `Name`, `Value`, `ValueType`, `Tag`, `FirstInt`; typed `IntValue`, `DoubleValue`, `ReferenceId`, `ReferenceTag`, `ReferenceClass`). On node properties of the strict path, `Class` is the property tab name (category, for example `Element`), `Name` the property name and `FirstInt` the key object id. Records scanned from property streams (`NwcDocument.PropertyRecords`, and node properties of other files) keep their internal class names. `TabInternalName` and `InternalName` are the internal names of the tab and the key on strict-path node properties, null on scanned records. |
| `NwcPropertyTab` | One property tab of a strict-path node (`NwcNode.PropertyTabs`, in stored slot order): display `Name`, `InternalName`, `Properties`. A tab object shared by several nodes is one instance. |
Expand Down
19 changes: 19 additions & 0 deletions src/NwcIO.Cli/Program.cs
Original file line number Diff line number Diff line change
Expand Up @@ -1170,6 +1170,7 @@ int ProcessLoadedAssembly(NwcAssembly preloaded, string displayPath, string? out
int totalTriangles = doc.Meshes.Sum(m => m.TriangleCount);

@err.WriteLine("=== NwcIO Execution Report ===");
PrintDiagnostics(doc.Diagnostics, @err);
@err.WriteLine($"Input: {inputPath}");
@err.WriteLine($"Source document: {doc.FileInfo.SourcePath ?? "<unknown>"}");
@err.WriteLine($"Loader plugin: {doc.FileInfo.LoaderPlugin ?? "<unknown>"}");
Expand Down Expand Up @@ -1493,6 +1494,7 @@ private static int ProcessAssemblyDirectory(
if (printReport)
{
@err.WriteLine("=== NwcIO Assembly Report ===");
PrintDiagnostics(assembly.Diagnostics, @err);
@err.WriteLine($"Assembly: {assembly.Name}");
@err.WriteLine($"Models: {assembly.Models.Count}");
@err.WriteLine($"Total Meshes: {assembly.AllMeshes.Count}");
Expand Down Expand Up @@ -1800,6 +1802,7 @@ private static int ProcessNwfAssembly(
@err.WriteLine($"Assembly: {assembly.Name}");
@err.WriteLine($"Models: {assembly.Models.Count}");
}
PrintDiagnostics(assembly.Diagnostics, @err);
@err.WriteLine($"Total Meshes: {assembly.AllMeshes.Count}");
@err.WriteLine($"Total Materials: {assembly.AllMaterials.Count}");
@err.WriteLine($"Saved viewpoints: {assembly.SavedViewpoints.Count}");
Expand Down Expand Up @@ -1924,6 +1927,22 @@ private static void ApplyClashGrouping(Model.Clash.NwcClashTest test, string? mo
}
}

private static void PrintDiagnostics(IReadOnlyList<NwcDiagnostic> diagnostics, TextWriter err)
{
// Unresolved and skipped references already have their own "Warning:" lines in the NWF report.
var shown = diagnostics.Where(d => d.Code is not ("NwfUnresolvedXref" or "NwfSkippedXref")).ToList();
if (shown.Count == 0)
{
return;
}

err.WriteLine($"Diagnostics: {shown.Count}");
foreach (var diagnostic in shown)
{
err.WriteLine($" [{diagnostic.Severity}] {diagnostic.Code}: {diagnostic.Message}");
}
}

private static void EnsureParentDirectory(string path)
{
var dir = Path.GetDirectoryName(path);
Expand Down
40 changes: 36 additions & 4 deletions src/NwcIO/Internal/Parsing/MeshParser.cs
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,18 @@ public static IReadOnlyList<NwcMesh> Parse(
IReadOnlyList<NwcTransform>? transforms = null,
int maxVertices = MaxPlausibleVertices,
IReadOnlyList<int>? transformIndices = null)
=> Parse(container, transforms, maxVertices, transformIndices, out _);

/// <summary>
/// Parses all 3D meshes and reports how many geometry records were recognised but skipped
/// (vertex count out of range, record truncated or malformed).
/// </summary>
public static IReadOnlyList<NwcMesh> Parse(
NwcContainer container,
IReadOnlyList<NwcTransform>? transforms,
int maxVertices,
IReadOnlyList<int>? transformIndices,
out int skippedRecords)
{
ArgumentNullException.ThrowIfNull(container);
if (maxVertices < MinMeshVertices)
Expand All @@ -32,20 +44,24 @@ public static IReadOnlyList<NwcMesh> Parse(
}

var meshes = new List<NwcMesh>();
int tocSkipped = 0;
int scanSkipped = 0;

// 1. Primary path: parse via Table of Contents (TOC) stream and chunked geometry block.
var tocStream = container.Streams.FirstOrDefault(s => s.Kind == NwcStreamKind.Toc);
if (tocStream is not null)
{
ParseViaToc(container, tocStream, meshes, transforms, maxVertices, transformIndices);
ParseViaToc(container, tocStream, meshes, transforms, maxVertices, transformIndices, ref tocSkipped);
}

// 2. Secondary fallback: if TOC yielded no meshes, scan individual streams for vertex buffers.
if (meshes.Count == 0)
{
ParseViaHeuristicScan(container, meshes, transforms, maxVertices, transformIndices);
ParseViaHeuristicScan(container, meshes, transforms, maxVertices, transformIndices, ref scanSkipped);
}

// The fallback replaces the TOC attempt; take the larger count so neither path hides a skipped record.
skippedRecords = Math.Max(tocSkipped, scanSkipped);
return meshes;
}

Expand Down Expand Up @@ -81,7 +97,8 @@ private static void ParseViaToc(
List<NwcMesh> meshes,
IReadOnlyList<NwcTransform>? transforms,
int maxVertices,
IReadOnlyList<int>? transformIndices)
IReadOnlyList<int>? transformIndices,
ref int skippedRecords)
{
var tocData = tocStream.Data;
if (tocData.Length < 16)
Expand Down Expand Up @@ -192,6 +209,14 @@ private static void ParseViaToc(

meshes.Add(mesh);
}
else
{
skippedRecords++;
}
}
else
{
skippedRecords++;
}
}
}
Expand All @@ -205,7 +230,8 @@ private static void ParseViaHeuristicScan(
List<NwcMesh> meshes,
IReadOnlyList<NwcTransform>? transforms,
int maxVertices,
IReadOnlyList<int>? transformIndices)
IReadOnlyList<int>? transformIndices,
ref int skippedRecords)
{
foreach (var stream in container.Streams)
{
Expand All @@ -228,12 +254,14 @@ private static void ParseViaHeuristicScan(
int minVertices = lines ? 2 : MinMeshVertices;
if (vCount < minVertices || vCount > maxVertices)
{
skippedRecords++;
continue;
}

// vCount can reach int.MaxValue through MaxMeshVertices: compare without multiplying.
if (vCount > (data.Length - (i + 16)) / 12)
{
skippedRecords++;
continue;
}

Expand All @@ -245,6 +273,10 @@ private static void ParseViaHeuristicScan(
meshes.Add(mesh);
i += 12 + vCount * 12;
}
else
{
skippedRecords++;
}
}
}
}
Expand Down
28 changes: 19 additions & 9 deletions src/NwcIO/NwcDocument.cs
Original file line number Diff line number Diff line change
Expand Up @@ -183,6 +183,7 @@ public static NwcDocument Open(Stream stream, NwcReaderOptions? options = null,

var transforms = new List<NwcTransform>();
var meshes = new List<NwcMesh>();
int skippedMeshRecords = 0;
var materials = new List<NwcMaterial>();
NwcNode? rootNode = null;
if (segments is not null)
Expand Down Expand Up @@ -216,7 +217,7 @@ public static NwcDocument Open(Stream stream, NwcReaderOptions? options = null,
transformIndices = TransformLinkParser.TryParse(linksStream);
}

meshes.AddRange(MeshParser.Parse(container, transforms, options.MaxMeshVertices, transformIndices));
meshes.AddRange(MeshParser.Parse(container, transforms, options.MaxMeshVertices, transformIndices, out skippedMeshRecords));
}

if (options.BuildSceneTree)
Expand Down Expand Up @@ -279,18 +280,27 @@ public static NwcDocument Open(Stream stream, NwcReaderOptions? options = null,
}

var document = new NwcDocument(fileInfo, records, guids, transforms, meshes, materials, rootNode, xRefs, dbCache, savedViewpoints, selectionSets, timeLiner, container);
var diagnostics = new List<NwcDiagnostic>();
if (skippedMeshRecords > 0)
{
diagnostics.Add(new NwcDiagnostic(
NwcDiagnosticSeverity.Warning,
"meshes-skipped",
$"{skippedMeshRecords} geometry records were skipped: their vertex count is outside " +
$"{MeshParser.MinMeshVertices}..{options.MaxMeshVertices} or the record is malformed."));
}

if (container.TrailingGap > 0)
{
document.Diagnostics =
[
new NwcDiagnostic(
NwcDiagnosticSeverity.Warning,
"ContainerTrailingGap",
$"Unrecognized {container.TrailingGap} byte tail after the last stream.",
ByteOffset: container.FileLength - container.TrailingGap),
];
diagnostics.Add(new NwcDiagnostic(
NwcDiagnosticSeverity.Warning,
"ContainerTrailingGap",
$"Unrecognized {container.TrailingGap} byte tail after the last stream.",
ByteOffset: container.FileLength - container.TrailingGap));
}

document.Diagnostics = diagnostics;

return document;
}

Expand Down
93 changes: 93 additions & 0 deletions tests/NwcIO.Tests/CliArgumentValidationTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -740,4 +740,97 @@ public void ManifestInput_IsAnAssembly()
Directory.Delete(dir, true);
}
}

private static void AppendTail(string path)
{
using var stream = new FileStream(path, FileMode.Append, FileAccess.Write);
stream.Write(new byte[8]);
}

[Fact]
public void Report_PrintsDocumentDiagnostics_OnlyWhenPresent()
{
string model = TempModel();
string clean = Path.Combine(Path.GetTempPath(), "cli-diag-" + Guid.NewGuid().ToString("N") + ".json");
string output = Path.Combine(Path.GetTempPath(), "cli-diag-" + Guid.NewGuid().ToString("N") + ".json");
try
{
var (cleanExit, _, cleanErr) = Run([model, clean, "--report"]);
Assert.Equal(0, cleanExit);
Assert.DoesNotContain("Diagnostics:", cleanErr);

AppendTail(model);
var (exit, _, err) = Run([model, output, "--report"]);

Assert.Equal(0, exit);
Assert.Contains("Diagnostics: 1", err);
Assert.Contains("[Warning] ContainerTrailingGap", err);
}
finally
{
foreach (var f in new[] { model, clean, output })
{
if (File.Exists(f)) File.Delete(f);
}
}
}

[Fact]
public void Report_PrintsAssemblyDiagnostics_ForFolderAndManifest()
{
string dir = Path.Combine(Path.GetTempPath(), "cli-diag-" + Guid.NewGuid().ToString("N"));
Directory.CreateDirectory(dir);
try
{
string a = Path.Combine(dir, "a.nwc");
WriteModel(a);
AppendTail(a);
WriteModel(Path.Combine(dir, "b.nwc"));

var (folderExit, _, folderErr) = Run([dir, "--report"]);
Assert.True(folderExit == 0, folderErr);
Assert.Contains("Diagnostics: 1", folderErr);
Assert.Contains("ContainerTrailingGap", folderErr);

string manifest = Path.Combine(dir, "fed.nwf.xml");
var m = new NwcIO.Model.Clash.NwcNwfManifest("Fed");
m.ModelPaths.Add("a.nwc");
m.ModelPaths.Add("b.nwc");
m.Save(manifest);

var (exit, _, err) = Run([manifest, "--report"]);
Assert.True(exit == 0, err);
Assert.Contains("Diagnostics: 1", err);
Assert.Contains("ContainerTrailingGap", err);
}
finally
{
Directory.Delete(dir, true);
}
}

[Fact]
public void Report_UnresolvedReference_IsReportedOnce()
{
string dir = Path.Combine(Path.GetTempPath(), "cli-diag-" + Guid.NewGuid().ToString("N"));
Directory.CreateDirectory(dir);
try
{
WriteModel(Path.Combine(dir, "a.nwc"));
string manifest = Path.Combine(dir, "fed.nwf.xml");
var m = new NwcIO.Model.Clash.NwcNwfManifest("Fed");
m.ModelPaths.Add("a.nwc");
m.ModelPaths.Add("missing.nwc");
m.Save(manifest);

var (exit, _, err) = Run([manifest, "--report"]);

Assert.True(exit == 0, err);
Assert.Equal(1, err.Split("missing.nwc").Length - 1);
}
finally
{
Directory.Delete(dir, true);
}
}
}
Loading
Loading