From 75d82ce0871ade3878d4e4a11d92f33fc5ad2ccb Mon Sep 17 00:00:00 2001 From: mie Date: Mon, 16 Nov 2026 09:54:36 +0300 Subject: [PATCH] feat(diagnostics): report skipped meshes and print diagnostics in --report Add a MeshParser overload that counts skipped geometry records, turn that count into the NwcDocument meshes-skipped diagnostic, and merge it with the container trailing-gap diagnostic. Print NwcDocument/NwcAssembly diagnostics in the single-file, folder and .nwf --report paths. Add parser, document and CLI regression tests. --- CHANGELOG.md | 1 + docs/public-api.md | 1 + src/NwcIO.Cli/Program.cs | 17 +++++++++ src/NwcIO/Internal/Parsing/MeshParser.cs | 35 ++++++++++++++++--- src/NwcIO/NwcDocument.cs | 34 +++++++++++------- .../NwcIO.Tests/CliArgumentValidationTests.cs | 25 +++++++++++++ tests/NwcIO.Tests/MeshParserTests.cs | 27 ++++++++++++++ 7 files changed, 124 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c818189..d4bac12 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ All notable changes to the `NwcIO` library, the CLI and the `NwcIO.Scene` adapte ## [Unreleased] ### Added +- Reader diagnostics are printed by `nwcio --report`: skipped geometry records (`meshes-skipped`), an unrecognized container tail (`ContainerTrailingGap`), and unresolved/skipped NWF references. `NwcDocument.Diagnostics` and `NwcAssembly.Diagnostics` expose the same entries to callers. - `NwcIO.Scene` diagnostics for document content the conversion leaves out: `xrefs-skipped` (Warning, with the number of external references, for example the models of a `.nwf` file), `selection-sets-skipped`, `timeliner-skipped` and `clash-tests-skipped` (Warning, each only when the document has that content), and `properties-skipped` (Info, the number of property values left out for a reason other than an unknown unit). A document with none of this content gets none of them. ### Changed diff --git a/docs/public-api.md b/docs/public-api.md index d9edcb8..fea762e 100644 --- a/docs/public-api.md +++ b/docs/public-api.md @@ -11,6 +11,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. | +| `NwcDiagnostic` / `NwcDiagnosticSeverity` | Reader diagnostics on `NwcDocument.Diagnostics` and `NwcAssembly.Diagnostics`: skipped geometry records (`meshes-skipped`), an unrecognized container tail (`ContainerTrailingGap`), and unresolved or skipped NWF references (`NwfUnresolvedXref`, `NwfSkippedXref`). `nwcio --report` prints them. | | `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, triangles other than the single strip the reader rebuilds, out-of-range vertex counts or coordinates, records or nodes without a name/class, and viewpoint names the reader would rename. Normals, materials and mesh names are not stored. | | `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, assigned by heuristics elsewhere), whether to build the scene tree (`BuildSceneTree`), catalog retention. | diff --git a/src/NwcIO.Cli/Program.cs b/src/NwcIO.Cli/Program.cs index 1788d90..502bf78 100644 --- a/src/NwcIO.Cli/Program.cs +++ b/src/NwcIO.Cli/Program.cs @@ -944,6 +944,7 @@ internal static int Run( 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 ?? ""}"); @err.WriteLine($"Loader plugin: {doc.FileInfo.LoaderPlugin ?? ""}"); @@ -1268,6 +1269,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}"); @@ -1567,6 +1569,7 @@ private static int ProcessNwfAssembly( if (printReport) { @err.WriteLine("=== NwcIO NWF Assembly Report ==="); + PrintDiagnostics(assembly.Diagnostics, @err); @err.WriteLine($"NWF File: {nwfPath}"); // Models[0] is the .nwf document itself; report the component files separately. @err.WriteLine($"Loaded Models: {assembly.Models.Count} (component files: {assembly.Models.Count - 1})"); @@ -1678,6 +1681,20 @@ private static void ApplyClashGrouping(Model.Clash.NwcClashTest test, string? mo } } + private static void PrintDiagnostics(IReadOnlyList diagnostics, TextWriter err) + { + if (diagnostics.Count == 0) + { + return; + } + + err.WriteLine($"Diagnostics: {diagnostics.Count}"); + foreach (var diagnostic in diagnostics) + { + err.WriteLine($" [{diagnostic.Severity}] {diagnostic.Code}: {diagnostic.Message}"); + } + } + private static void EnsureParentDirectory(string path) { var dir = Path.GetDirectoryName(path); diff --git a/src/NwcIO/Internal/Parsing/MeshParser.cs b/src/NwcIO/Internal/Parsing/MeshParser.cs index 5f66d72..38312ab 100644 --- a/src/NwcIO/Internal/Parsing/MeshParser.cs +++ b/src/NwcIO/Internal/Parsing/MeshParser.cs @@ -17,22 +17,34 @@ public static class MeshParser /// Parses all 3D meshes found in the container streams. /// public static IReadOnlyList Parse(NwcContainer container, IReadOnlyList? transforms = null) + => Parse(container, transforms, out _); + + /// + /// Parses all 3D meshes found in the container streams and reports how many geometry records were skipped. + /// + public static IReadOnlyList Parse( + NwcContainer container, + IReadOnlyList? transforms, + out int skippedRecords) { ArgumentNullException.ThrowIfNull(container); var meshes = new List(); + skippedRecords = 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); + ParseViaToc(container, tocStream, meshes, transforms, ref skippedRecords); } // 2. Secondary fallback: if TOC yielded no meshes, scan individual streams for vertex buffers. if (meshes.Count == 0) { - ParseViaHeuristicScan(container, meshes, transforms); + // The fallback replaces the TOC attempt, so do not count the same record twice. + skippedRecords = 0; + ParseViaHeuristicScan(container, meshes, transforms, ref skippedRecords); } return meshes; @@ -42,7 +54,8 @@ private static void ParseViaToc( NwcContainer container, LcRawStream tocStream, List meshes, - IReadOnlyList? transforms) + IReadOnlyList? transforms, + ref int skippedRecords) { var tocData = tocStream.Data; if (tocData.Length < 16) @@ -150,6 +163,14 @@ private static void ParseViaToc( meshes.Add(mesh); } + else + { + skippedRecords++; + } + } + else + { + skippedRecords++; } } } @@ -161,7 +182,8 @@ private static void ParseViaToc( private static void ParseViaHeuristicScan( NwcContainer container, List meshes, - IReadOnlyList? transforms) + IReadOnlyList? transforms, + ref int skippedRecords) { foreach (var stream in container.Streams) { @@ -182,6 +204,7 @@ private static void ParseViaHeuristicScan( int vCount = BinaryPrimitives.ReadInt32LittleEndian(data.AsSpan(i + 8)); if (vCount < MinMeshVertices || vCount > MaxPlausibleVertices) { + skippedRecords++; continue; } @@ -202,6 +225,10 @@ private static void ParseViaHeuristicScan( meshes.Add(mesh); i += 12 + vBytes; } + else + { + skippedRecords++; + } } } } diff --git a/src/NwcIO/NwcDocument.cs b/src/NwcIO/NwcDocument.cs index 02a3e92..c2efb9c 100644 --- a/src/NwcIO/NwcDocument.cs +++ b/src/NwcIO/NwcDocument.cs @@ -181,6 +181,7 @@ public static NwcDocument Open(Stream stream, NwcReaderOptions? options = null, var transforms = new List(); var meshes = new List(); var materials = new List(); + int skippedMeshRecords = 0; NwcNode? rootNode = null; if (segments is not null) { @@ -206,7 +207,7 @@ public static NwcDocument Open(Stream stream, NwcReaderOptions? options = null, if (options.ReadMeshes) { - meshes.AddRange(MeshParser.Parse(container, transforms)); + meshes.AddRange(MeshParser.Parse(container, transforms, out skippedMeshRecords)); } if (options.BuildSceneTree) @@ -268,7 +269,26 @@ public static NwcDocument Open(Stream stream, NwcReaderOptions? options = null, container = container with { Streams = [] }; } - return new NwcDocument(fileInfo, records, guids, transforms, meshes, materials, rootNode, xRefs, dbCache, savedViewpoints, selectionSets, timeLiner, container); + var diagnostics = new List(); + if (skippedMeshRecords > 0) + { + diagnostics.Add(new NwcDiagnostic( + NwcDiagnosticSeverity.Warning, + "meshes-skipped", + $"{skippedMeshRecords} geometry records were skipped: their vertex count is outside " + + $"{MeshParser.MinMeshVertices}..{MeshParser.MaxPlausibleVertices} or the record is malformed.")); + } + if (container.TrailingGap > 0) + { + diagnostics.Add(new NwcDiagnostic( + NwcDiagnosticSeverity.Warning, + "ContainerTrailingGap", + $"Unrecognized {container.TrailingGap} byte tail after the last stream.")); + } + + var doc = new NwcDocument(fileInfo, records, guids, transforms, meshes, materials, rootNode, xRefs, dbCache, savedViewpoints, selectionSets, timeLiner, container); + doc.Diagnostics = diagnostics; + return doc; } /// @@ -307,16 +327,6 @@ public static NwcDocument Create( }; var doc = new NwcDocument(fi, pList, gList, tList, mList, matList, rootNode, xRefs, dbCache, vList, sList, timeLiner, container); - if (container.TrailingGap > 0) - { - doc.Diagnostics = - [ - new NwcDiagnostic( - NwcDiagnosticSeverity.Warning, - "ContainerTrailingGap", - $"Unrecognized {container.TrailingGap} byte tail after the last stream."), - ]; - } if (appearanceProfiler is not null) { doc.ApplyAppearanceProfiler(appearanceProfiler); diff --git a/tests/NwcIO.Tests/CliArgumentValidationTests.cs b/tests/NwcIO.Tests/CliArgumentValidationTests.cs index ef8471b..da1e81e 100644 --- a/tests/NwcIO.Tests/CliArgumentValidationTests.cs +++ b/tests/NwcIO.Tests/CliArgumentValidationTests.cs @@ -220,6 +220,31 @@ public void FolderOrNwfAssembly_WithUnsupportedOptions_Exits1() } } + [Fact] + public void Report_PrintsDocumentDiagnostics() + { + string model = TempModel(); + string output = Path.Combine(Path.GetTempPath(), "cli-diag-" + Guid.NewGuid().ToString("N") + ".json"); + try + { + using (var stream = new FileStream(model, FileMode.Append, FileAccess.Write)) + { + stream.Write(new byte[8]); + } + + var (exit, _, err) = Run([model, output, "--report"]); + + Assert.Equal(0, exit); + Assert.Contains("Diagnostics:", err); + Assert.Contains("ContainerTrailingGap", err); + } + finally + { + if (File.Exists(model)) File.Delete(model); + if (File.Exists(output)) File.Delete(output); + } + } + [Fact] public void IfcSchema_InvalidVersion_Exits1() { diff --git a/tests/NwcIO.Tests/MeshParserTests.cs b/tests/NwcIO.Tests/MeshParserTests.cs index f7bfc15..fb3f222 100644 --- a/tests/NwcIO.Tests/MeshParserTests.cs +++ b/tests/NwcIO.Tests/MeshParserTests.cs @@ -69,6 +69,33 @@ public void Parse_OverflowingTocRecordCount_SkipsMesh(int recordCount) Assert.Empty(MeshParser.Parse(container)); } + [Fact] + public void Parse_OutOfRangeVertexCount_ReportsSkippedRecord() + { + var chunk = Int32Bytes(0, 94, 0, 60, 1, 0, 0, 0); + var toc = Int32Bytes(1, 1, chunk.Length, 24); + var container = NwcContainerReader.Read(NwcContainerWriter.Write([chunk, toc])); + container.Streams[1].Kind = NwcStreamKind.Toc; + + var meshes = MeshParser.Parse(container, null, out int skipped); + + Assert.Empty(meshes); + Assert.Equal(1, skipped); + } + + [Fact] + public void Open_OutOfRangeVertexCount_ReportsMeshesSkippedDiagnostic() + { + var chunk = Int32Bytes(0, 94, 0, 60, 1, 0, 0, 0); + var toc = Int32Bytes(1, 1, chunk.Length, 24); + using var file = new MemoryStream(NwcContainerWriter.Write([chunk, toc])); + + var document = NwcDocument.Open(file); + + var diagnostic = Assert.Single(document.Diagnostics, d => d.Code == "meshes-skipped"); + Assert.Contains("geometry records were skipped", diagnostic.Message); + } + private static byte[] Int32Bytes(params int[] values) { var data = new byte[values.Length * 4];