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);
+ }
+ }
+}