diff --git a/CHANGELOG.md b/CHANGELOG.md index 96c9423..a3086a4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,8 @@ All notable changes to the `NwcIO` library, the CLI and the `NwcIO.Scene` adapte ## [Unreleased] ### Added -- Cancellation and progress overloads for `NwcDocument.Open`, `NwcAssembly.LoadFromDirectory` (also with several patterns and recursion) and `NwcAssembly.OpenNwf` and `NwcAssembly.OpenManifest`, plus `OpenAsync`, `LoadFromDirectoryAsync`, `OpenNwfAsync` and `SaveAsync` (`.nwc`) wrappers on `Task.Run`. `NwcProgress` reports `read-container`, `read-geometry`, `open` and per-model `load-models` counts (`OpenNwf` counts every reference, so `Completed` reaches `Total`). The token is checked between phases and models; a running container read is not interrupted, and `SaveAsync` checks it only before it starts. +- Cancellation and progress overloads for `.nwc` and JSON export: `NwcDocument.Save`, `NwcDocument.SaveJson` and `NwcAssembly.SaveJson` (path and stream). Existing signatures are unchanged; the new overloads report `export-nwc` and `export-json` phases and check the token before and after the exporter. `NwcDocument.SaveAsync` passes the token into the `.nwc` overloads. `NwcAssembly.SaveJson(path, ...)` writes a temporary file and moves it over the target, so a cancelled export keeps an existing file. +- Cancellation and progress overloads for `NwcDocument.Open`, `NwcAssembly.LoadFromDirectory` (also with several patterns and recursion) and `NwcAssembly.OpenNwf` and `NwcAssembly.OpenManifest`, plus `OpenAsync`, `LoadFromDirectoryAsync`, `OpenNwfAsync` and `SaveAsync` (`.nwc`) wrappers on `Task.Run`. `NwcProgress` reports `read-container`, `read-geometry`, `open` and per-model `load-models` counts (`OpenNwf` counts every reference, so `Completed` reaches `Total`). The token is checked between phases and models; a running container read is not interrupted. - `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`. - Reader diagnostics also cover property-scanner failures (`property-scan-failed`, Warning: the first malformed string a property scan met, with its stream index and byte offset; not raised on the strict DbCache path) and are written to document and assembly JSON as a `diagnostics` array. `NwcReaderOptions.Strict` throws `InvalidDataException` when an error-level diagnostic is recorded. - `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. diff --git a/docs/public-api.md b/docs/public-api.md index 21e9015..bd247f4 100644 --- a/docs/public-api.md +++ b/docs/public-api.md @@ -11,7 +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 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. | -| `NwcProgress` | Progress payload for the cancellation-aware overloads: a phase name, completed units, and total units (0 when unknown). | +| `NwcProgress` | Progress payload for the cancellation-aware reader overloads and the `.nwc` and JSON export overloads (`export-nwc`, `export-json`): a phase name, completed units, and total units (0 when unknown). | | `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, and `Strict` (throw `InvalidDataException` when an error-level diagnostic is recorded). | diff --git a/src/NwcIO/Model/NwcAssembly.cs b/src/NwcIO/Model/NwcAssembly.cs index 1a353f5..f92495f 100644 --- a/src/NwcIO/Model/NwcAssembly.cs +++ b/src/NwcIO/Model/NwcAssembly.cs @@ -910,6 +910,20 @@ public int AssignGridLocations(Grids.NwcGridSystem? gridSystem = null) /// Exports a structured summary of the federated assembly to a stream in JSON format. public void SaveJson(Stream stream, NwcJsonExportOptions? options = null) + => SaveJson(stream, options, null, default); + + /// Exports the assembly JSON to a stream with cancellation and progress. + public void SaveJson(Stream stream, NwcJsonExportOptions? options, IProgress? progress, CancellationToken cancellationToken) + { + cancellationToken.ThrowIfCancellationRequested(); + progress?.Report(new NwcProgress("export-json", 0, 1)); + cancellationToken.ThrowIfCancellationRequested(); + SaveJsonCore(stream, options); + cancellationToken.ThrowIfCancellationRequested(); + progress?.Report(new NwcProgress("export-json", 1, 1)); + } + + private void SaveJsonCore(Stream stream, NwcJsonExportOptions? options) { ArgumentNullException.ThrowIfNull(stream); options ??= NwcJsonExportOptions.Default; @@ -988,9 +1002,29 @@ public void SaveJson(Stream stream, NwcJsonExportOptions? options = null) /// Exports a structured summary of the federated assembly to a JSON file. public void SaveJson(string path, NwcJsonExportOptions? options = null) + => SaveJson(path, options, null, default); + + /// Exports the assembly JSON to a file with cancellation and progress. + public void SaveJson(string path, NwcJsonExportOptions? options, IProgress? progress, CancellationToken cancellationToken) { ArgumentException.ThrowIfNullOrEmpty(path); - using var fs = File.Create(path); - SaveJson(fs, options); + cancellationToken.ThrowIfCancellationRequested(); + string temp = $"{path}.{Guid.NewGuid():N}.tmp"; + try + { + using (var fs = File.Create(temp)) + { + SaveJson(fs, options, progress, cancellationToken); + } + + File.Move(temp, path, overwrite: true); + } + finally + { + if (File.Exists(temp)) + { + File.Delete(temp); + } + } } } diff --git a/src/NwcIO/NwcDocument.cs b/src/NwcIO/NwcDocument.cs index b1b8afa..d876727 100644 --- a/src/NwcIO/NwcDocument.cs +++ b/src/NwcIO/NwcDocument.cs @@ -610,14 +610,30 @@ public void ExportClashBcf(Stream stream, string? testName = null) /// tree of an opened document are not persisted unless the records are cleared first. /// public void Save(string path, string? header = null) + => Save(path, header, null, default); + + /// Saves the document to an .nwc file with cancellation and progress. + public void Save(string path, string? header, IProgress? progress, CancellationToken cancellationToken) { + cancellationToken.ThrowIfCancellationRequested(); + progress?.Report(new NwcProgress("export-nwc", 0, 1)); NwcWriter.Write(this, path, header); + cancellationToken.ThrowIfCancellationRequested(); + progress?.Report(new NwcProgress("export-nwc", 1, 1)); } /// Saves the document to an output stream in NwcIO's .nwc layout. public void Save(Stream stream, string? header = null) + => Save(stream, header, null, default); + + /// Saves the document to an .nwc stream with cancellation and progress. + public void Save(Stream stream, string? header, IProgress? progress, CancellationToken cancellationToken) { + cancellationToken.ThrowIfCancellationRequested(); + progress?.Report(new NwcProgress("export-nwc", 0, 1)); NwcWriter.Write(this, stream, header); + cancellationToken.ThrowIfCancellationRequested(); + progress?.Report(new NwcProgress("export-nwc", 1, 1)); } /// @@ -699,16 +715,34 @@ public string ToViewpointsXml(string units = "m") /// Exports the document to a JSON file. public void SaveJson(string path, NwcJsonExportOptions? options = null) + => SaveJson(path, options, null, default); + + /// Exports the document to JSON with cancellation and progress. + public void SaveJson(string path, NwcJsonExportOptions? options, IProgress? progress, CancellationToken cancellationToken) { options ??= NwcJsonExportOptions.Default; + cancellationToken.ThrowIfCancellationRequested(); + progress?.Report(new NwcProgress("export-json", 0, 1)); + cancellationToken.ThrowIfCancellationRequested(); Internal.Json.JsonExporter.WriteFile(this, path, options); + cancellationToken.ThrowIfCancellationRequested(); + progress?.Report(new NwcProgress("export-json", 1, 1)); } /// Exports the document to a JSON stream. public void SaveJson(Stream stream, NwcJsonExportOptions? options = null) + => SaveJson(stream, options, null, default); + + /// Exports the document to a JSON stream with cancellation and progress. + public void SaveJson(Stream stream, NwcJsonExportOptions? options, IProgress? progress, CancellationToken cancellationToken) { options ??= NwcJsonExportOptions.Default; + cancellationToken.ThrowIfCancellationRequested(); + progress?.Report(new NwcProgress("export-json", 0, 1)); + cancellationToken.ThrowIfCancellationRequested(); Internal.Json.JsonExporter.Write(this, stream, options); + cancellationToken.ThrowIfCancellationRequested(); + progress?.Report(new NwcProgress("export-json", 1, 1)); } /// Serializes the document to a JSON string. @@ -752,11 +786,11 @@ public static Task OpenAsync( /// Saves the document asynchronously. The current implementation wraps the synchronous writer. public Task SaveAsync(string path, string? header = null, CancellationToken cancellationToken = default) - => Task.Run(() => Save(path, header), cancellationToken); + => Task.Run(() => Save(path, header, null, cancellationToken), cancellationToken); /// Saves the document to a stream asynchronously. public Task SaveAsync(Stream stream, string? header = null, CancellationToken cancellationToken = default) - => Task.Run(() => Save(stream, header), cancellationToken); + => Task.Run(() => Save(stream, header, null, cancellationToken), cancellationToken); /// /// Populates clash grid location tags across all clash detective tests in this document using the provided or attached grid system. diff --git a/tests/NwcIO.Tests/ExportCancellationTests.cs b/tests/NwcIO.Tests/ExportCancellationTests.cs new file mode 100644 index 0000000..23b20a8 --- /dev/null +++ b/tests/NwcIO.Tests/ExportCancellationTests.cs @@ -0,0 +1,164 @@ +using NwcIO.Model; +using Xunit; + +namespace NwcIO.Tests; + +public sealed class ExportCancellationTests +{ + [Fact] + public void DocumentExports_CanceledToken_ThrowOperationCanceled() + { + var document = Document(); + using var cancellation = new CancellationTokenSource(); + cancellation.Cancel(); + + Assert.Throws(() => + document.Save(Path.GetTempFileName(), null, null, cancellation.Token)); + Assert.Throws(() => + document.SaveJson(Path.GetTempFileName(), null, null, cancellation.Token)); + } + + [Fact] + public void DocumentExports_ReportProgress() + { + var document = Document(); + var json = new CollectingProgress(); + using var jsonStream = new MemoryStream(); + document.SaveJson(jsonStream, null, json, CancellationToken.None); + Assert.Contains(json.Reports, p => p.Phase == "export-json" && p.Completed == 1 && p.Total == 1); + + var nwc = new CollectingProgress(); + using var nwcStream = new MemoryStream(); + document.Save(nwcStream, null, nwc, CancellationToken.None); + Assert.Contains(nwc.Reports, p => p.Phase == "export-nwc" && p.Completed == 1 && p.Total == 1); + } + + [Fact] + public void AssemblyExports_CancelAndReportProgress() + { + var document = Document(); + var assembly = NwcAssembly.Create("Fed", document); + using var cancellation = new CancellationTokenSource(); + cancellation.Cancel(); + string path = Path.Combine(Path.GetTempPath(), $"nwcio-{Guid.NewGuid():N}.json"); + Assert.Throws(() => + assembly.SaveJson(path, null, null, cancellation.Token)); + Assert.False(File.Exists(path)); + + var progress = new CollectingProgress(); + using var stream = new MemoryStream(); + assembly.SaveJson(stream, null, progress, CancellationToken.None); + Assert.Contains(progress.Reports, p => p.Phase == "export-json" && p.Completed == 1 && p.Total == 1); + } + + [Fact] + public void AssemblySaveJson_CanceledToken_DoesNotTruncateExistingFile() + { + var assembly = NwcAssembly.Create("Fed", Document()); + string path = Path.Combine(Path.GetTempPath(), $"nwcio-{Guid.NewGuid():N}.json"); + File.WriteAllText(path, "keep me"); + try + { + using var cancellation = new CancellationTokenSource(); + cancellation.Cancel(); + + Assert.Throws(() => + assembly.SaveJson(path, null, null, cancellation.Token)); + + Assert.Equal("keep me", File.ReadAllText(path)); + } + finally + { + if (File.Exists(path)) File.Delete(path); + } + } + + [Fact] + public void AssemblySaveJson_ProgressCanCancelMidExport() + { + var assembly = NwcAssembly.Create("Fed", Document()); + string path = Path.Combine(Path.GetTempPath(), $"nwcio-{Guid.NewGuid():N}.json"); + File.WriteAllText(path, "keep me"); + using var cancellation = new CancellationTokenSource(); + var progress = new CancellingProgress(cancellation); + try + { + Assert.Throws(() => + assembly.SaveJson(path, null, progress, cancellation.Token)); + + Assert.Equal("keep me", File.ReadAllText(path)); + } + finally + { + if (File.Exists(path)) File.Delete(path); + } + } + + [Fact] + public void AssemblySaveJson_ProgressCancelsBeforeWrite_WritesNothing() + { + var assembly = NwcAssembly.Create("Fed", Document()); + using var cancellation = new CancellationTokenSource(); + using var stream = new MemoryStream(); + + Assert.Throws(() => + assembly.SaveJson(stream, null, new CancellingProgress(cancellation), cancellation.Token)); + + Assert.Equal(0, stream.Length); + } + + [Fact] + public async Task SaveAsync_CanceledWhileWriting_IsCanceled() + { + var document = Document(); + using var cancellation = new CancellationTokenSource(); + using var stream = new CancelOnWriteStream(cancellation); + + await Assert.ThrowsAnyAsync(() => + document.SaveAsync(stream, cancellationToken: cancellation.Token)); + + Assert.True(stream.Written); + } + + private static NwcDocument Document() => NwcDocument.Create(meshes: + [ + new NwcMesh + { + Id = 1, + Vertices = [new(0, 0, 0), new(1, 0, 0), new(0, 1, 0)], + Indices = [0, 1, 2], + BoundingBox = new BoundingBox3d(new(0, 0, 0), new(1, 1, 0)), + }, + ]); + + private sealed class CollectingProgress : IProgress + { + public List Reports { get; } = []; + + public void Report(NwcProgress value) => Reports.Add(value); + } + + private sealed class CancellingProgress(CancellationTokenSource cancellation) : IProgress + { + public void Report(NwcProgress value) => cancellation.Cancel(); + } + + private sealed class CancelOnWriteStream(CancellationTokenSource cancellation) : MemoryStream + { + public bool Written { get; private set; } + + public override void Write(byte[] buffer, int offset, int count) + { + Written = true; + cancellation.Cancel(); + base.Write(buffer, offset, count); + } + + public override void Write(ReadOnlySpan buffer) + { + Written = true; + cancellation.Cancel(); + base.Write(buffer); + } + } +}