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
3 changes: 2 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/public-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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). |
Expand Down
38 changes: 36 additions & 2 deletions src/NwcIO/Model/NwcAssembly.cs
Original file line number Diff line number Diff line change
Expand Up @@ -910,6 +910,20 @@ public int AssignGridLocations(Grids.NwcGridSystem? gridSystem = null)

/// <summary>Exports a structured summary of the federated assembly to a stream in JSON format.</summary>
public void SaveJson(Stream stream, NwcJsonExportOptions? options = null)
=> SaveJson(stream, options, null, default);

/// <summary>Exports the assembly JSON to a stream with cancellation and progress.</summary>
public void SaveJson(Stream stream, NwcJsonExportOptions? options, IProgress<NwcProgress>? 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;
Expand Down Expand Up @@ -988,9 +1002,29 @@ public void SaveJson(Stream stream, NwcJsonExportOptions? options = null)

/// <summary>Exports a structured summary of the federated assembly to a JSON file.</summary>
public void SaveJson(string path, NwcJsonExportOptions? options = null)
=> SaveJson(path, options, null, default);

/// <summary>Exports the assembly JSON to a file with cancellation and progress.</summary>
public void SaveJson(string path, NwcJsonExportOptions? options, IProgress<NwcProgress>? 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);
}
}
}
}
38 changes: 36 additions & 2 deletions src/NwcIO/NwcDocument.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
/// </summary>
public void Save(string path, string? header = null)
=> Save(path, header, null, default);

/// <summary>Saves the document to an .nwc file with cancellation and progress.</summary>
public void Save(string path, string? header, IProgress<NwcProgress>? 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));
}

/// <summary>Saves the document to an output stream in NwcIO's .nwc layout.</summary>
public void Save(Stream stream, string? header = null)
=> Save(stream, header, null, default);

/// <summary>Saves the document to an .nwc stream with cancellation and progress.</summary>
public void Save(Stream stream, string? header, IProgress<NwcProgress>? 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));
}

/// <summary>
Expand Down Expand Up @@ -699,16 +715,34 @@ public string ToViewpointsXml(string units = "m")

/// <summary>Exports the document to a JSON file.</summary>
public void SaveJson(string path, NwcJsonExportOptions? options = null)
=> SaveJson(path, options, null, default);

/// <summary>Exports the document to JSON with cancellation and progress.</summary>
public void SaveJson(string path, NwcJsonExportOptions? options, IProgress<NwcProgress>? 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));
}

/// <summary>Exports the document to a JSON stream.</summary>
public void SaveJson(Stream stream, NwcJsonExportOptions? options = null)
=> SaveJson(stream, options, null, default);

/// <summary>Exports the document to a JSON stream with cancellation and progress.</summary>
public void SaveJson(Stream stream, NwcJsonExportOptions? options, IProgress<NwcProgress>? 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));
}

/// <summary>Serializes the document to a JSON string.</summary>
Expand Down Expand Up @@ -752,11 +786,11 @@ public static Task<NwcDocument> OpenAsync(

/// <summary>Saves the document asynchronously. The current implementation wraps the synchronous writer.</summary>
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);

/// <summary>Saves the document to a stream asynchronously.</summary>
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);

/// <summary>
/// Populates clash grid location tags across all clash detective tests in this document using the provided or attached grid system.
Expand Down
164 changes: 164 additions & 0 deletions tests/NwcIO.Tests/ExportCancellationTests.cs
Original file line number Diff line number Diff line change
@@ -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<OperationCanceledException>(() =>
document.Save(Path.GetTempFileName(), null, null, cancellation.Token));
Assert.Throws<OperationCanceledException>(() =>
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<OperationCanceledException>(() =>
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<OperationCanceledException>(() =>
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<OperationCanceledException>(() =>
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<OperationCanceledException>(() =>
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<OperationCanceledException>(() =>
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<NwcProgress>
{
public List<NwcProgress> Reports { get; } = [];

public void Report(NwcProgress value) => Reports.Add(value);
}

private sealed class CancellingProgress(CancellationTokenSource cancellation) : IProgress<NwcProgress>
{
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<byte> buffer)
{
Written = true;
cancellation.Cancel();
base.Write(buffer);
}
}
}
Loading