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 @@ -21,6 +21,7 @@ API between minor releases.
- Preview distance measurement points and snap to visible vertices, edge midpoints and edges near the pointer.
- Use each instance's projected size for orbit detail when the measured frame budget has room.
- Fill cut faces of closed meshes on demand and rotate the section box around Z with a ring or slider.
- Compute hard clashes and surface clearances between categories in the CLI with IOCoord, and export the results to HTML or JSON.

### Fixed

Expand Down
1 change: 1 addition & 0 deletions Directory.Packages.props
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
<!-- Patch = adds or fixes, minor = breaking while IOScene is 0.x; the -0.0 keeps out previews of the next breaking line
(nuget.org refuses the shorter bound -0 in a dependency). -->
<PackageVersion Include="IOScene" Version="[0.1.0, 0.2.0-0.0)" />
<PackageVersion Include="IOCoord" Version="0.1.0-preview.1" />
<PackageVersion Include="IfcIO.Scene" Version="0.11.1" />
<PackageVersion Include="NwcIO.Scene" Version="0.13.0" />
<PackageVersion Include="RvtIO.Scene" Version="0.4.0" />
Expand Down
11 changes: 11 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,17 @@ The archive limit is 64 MiB and 4,096 entries, with 2 MiB per XML file and 32 Mi
The importer reads topic and viewpoint XML. Snapshots, attachments, markup lines and component
colours are outside this import.

Builds from this repository can check two categories for clashes after placing all source models. Use the exact
category names displayed in the model tree:

```sh
ioviewer coordination.ifc --clash IFCWALL IFCSLAB -o review.html
ioviewer building.rvt --clash Walls Floors --clash-clearance 0.05 -o clearance.html
```

The new test is appended to existing clash results. Open it in the HTML **Clashes** panel or save it in viewer JSON.
See [clash check options and distance semantics](docs/getting-started.md#check-for-clashes).

Export structured JSON snapshots:

```sh
Expand Down
3 changes: 2 additions & 1 deletion THIRD-PARTY-NOTICES.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,12 +38,13 @@ THE SOFTWARE.

## IOViewer.Cli tool package

The `IOViewer.Cli` tool package reads IFC, Revit and Navisworks cache files through the engine adapters, so besides
The `IOViewer.Cli` tool package reads IFC, Revit and Navisworks cache files and computes clash results. Besides
`IOViewer` and `IOScene` (MIT, copyright (c) 2026 mahach666) it ships the assemblies listed below. The `IOViewer`
library package references none of them.

| Component | Use | License |
|---|---|---|
| [IOCoord](https://github.com/IOExtend/IOScene) 0.1.0-preview.1 | hard clash and clearance checks | MIT, copyright (c) 2026 mahach666 |
| [IfcIO](https://github.com/IOExtend/IfcIO) 0.11.1 and IfcIO.Scene 0.11.1 | read IFC files into a scene | MIT, copyright (c) 2026 IfcIO contributors |
| [NwcIO](https://github.com/IOExtend/NwcIO) 0.13.0 and NwcIO.Scene 0.13.0 | read Navisworks caches into a scene | MIT, copyright (c) 2026 mahach666 |
| [RvtIO](https://github.com/IOExtend/RvtIO) 0.4.0 and RvtIO.Scene 0.4.0 | read Revit files into a scene | MIT, copyright (c) 2026 mahach666 |
Expand Down
20 changes: 20 additions & 0 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,26 @@ The direct `.nwc` command is available in CLI builds from this repository. Publi
[IOScene JSON handoff](#navisworks-cache) for Navisworks models.
The CLI reports `.nwd` and `.nwf` as unsupported input formats and exits with code 3.

### Check for clashes

In builds from this repository, pass one `--clash <category-a> <category-b>` rule to check triangle surfaces after
all input models have been placed. Use the exact category names from the model tree and quote names with spaces.
You can use the same category on both sides to check distinct elements within it.

```sh
ioviewer building.ifc --clash IFCWALL IFCSLAB -o hard-clashes.html
ioviewer building.rvt --clash Walls Floors --clash-clearance 0.05 -o clearances.html
```

Hard checks report a surface contact point and use the overlap of the contacting mesh bounds to estimate
penetration depth. The distance is negative for estimated penetration and zero for contacts with zero depth.
Clearance mode reports the nearest gap at or below the limit in metres, with its midpoint as the result point.
Touching surfaces report zero gap. For enclosed solids, use the separate `SceneClash.FindSolidContainments`
query in [IOCoord](https://github.com/IOExtend/IOScene/blob/main/docs/tools.md#clash-checks-revision-comparison-grids-and-bcf).

Open the **Clashes** panel in the HTML, or use `--json` to save the same results in a viewer snapshot. If a
category is absent, the CLI reports a usage error before writing the output.

## C# API usage

The model data is a `SceneDocument` from the [IOScene](https://github.com/IOExtend/IOScene) package: models, elements,
Expand Down
19 changes: 19 additions & 0 deletions docs/public-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,25 @@ and visibility.
- `HtmlViewerOptions`: Title, which data to include (properties, viewpoints, grids, 4D schedule, clashes), the initial display mode (`InitialWireframe`, `InitialWhiteMode`), and `MaxMeshVertices`, which is unlimited by default; when a lower limit leaves meshes out, the viewer shows how many were written.
- `JsonViewerExporter`: Writes a `ViewerDocument` as viewer JSON (`"Kind": "ioviewer"`, `"Format": 2`). A scene alone is written with IOScene's `SceneJson`.

### Compute and export clash results

Add [IOCoord](https://www.nuget.org/packages/IOCoord/0.1.0-preview.1) to the application alongside `IOViewer`. The
queries take an IOScene document and two sets of scene element IDs and return a `SceneClashTest`.

```csharp
using IOCoord;
using IOScene;
using IOViewer.Exporters;

var scene = SceneJson.Load("building.scene.json");
long[] walls = scene.Elements.Where(e => e.Category == "Walls").Select(e => e.Id).ToArray();
long[] floors = scene.Elements.Where(e => e.Category == "Floors").Select(e => e.Id).ToArray();

scene.ClashTests.Add(SceneClash.FindHardClashes(scene, walls, floors));
scene.ClashTests.Add(SceneClash.FindSurfaceClearances(scene, walls, floors, maxClearanceMetres: 0.05));
HtmlViewerExporter.Save(scene, "clashes.html");
```

### Importers (`IOViewer.Importers`)

- `GlbViewerImporter`: Reads binary glTF 2.0 (`.glb`) files into a `ViewerDocument` with one model. Each glTF mesh primitive becomes one `SceneGeometry`, and each node that uses it a `SceneInstance` per primitive with the node's world transform, converted from glTF's Y-up to the viewer's Z-up. Each such node also becomes a `SceneElement` (category `GLB`, named after the node, else the mesh) that all its instances belong to. A material's base colour factor is linear in glTF and becomes an sRGB colour with the same alpha. A node hierarchy that is not a tree (a node referenced twice or a cycle) is rejected with `InvalidDataException`.
Expand Down
1 change: 1 addition & 0 deletions src/IOViewer.Cli/IOViewer.Cli.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@

<ItemGroup>
<ProjectReference Include="..\IOViewer\IOViewer.csproj" />
<PackageReference Include="IOCoord" />
<PackageReference Include="IfcIO.Scene" />
<PackageReference Include="NwcIO.Scene" />
<PackageReference Include="RvtIO.Scene" />
Expand Down
72 changes: 72 additions & 0 deletions src/IOViewer.Cli/Program.cs
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
using System.Reflection;
using System.Text;
using IfcIO.Scene;
using IOCoord;
using IOScene;
using IOViewer.Exporters;
using IOViewer.Importers;
Expand Down Expand Up @@ -38,6 +39,10 @@ Add another model. Translation is in metres and yaw in degrees about +Z.
Repeat the pair for each model. Use 0,0,0,0 for an already aligned source.
--title <title> Page title shown in the browser tab.
--bcf <file> Import topics from a local BCF 2.1 archive in the scene's coordinates.
--clash <category-a> <category-b>
Check two exact category names for hard clashes after placing all models.
--clash-clearance <metres>
Check gaps up to this distance instead. Requires --clash.
--wireframe Enable wireframe display mode by default.
--white-mode Enable white/clay architectural rendering mode by default.
--no-properties Exclude element properties to reduce the file size.
Expand Down Expand Up @@ -81,6 +86,8 @@ public static int Main(string[] args)
string? customTitle = null;
string? explicitJsonPath = null;
string? bcfPath = null;
(string First, string Second)? clashCategories = null;
double? clashClearance = null;
var additional = new List<(string Path, Transform3d Placement)>();
bool wireframe = false;
bool whiteMode = false;
Expand Down Expand Up @@ -120,6 +127,28 @@ public static int Main(string[] args)
}
bcfPath = args[++i];
break;
case "--clash":
if (clashCategories is not null || i + 2 >= args.Length
|| string.IsNullOrWhiteSpace(args[i + 1]) || args[i + 1].StartsWith('-')
|| string.IsNullOrWhiteSpace(args[i + 2]) || args[i + 2].StartsWith('-'))
{
Console.Error.WriteLine("Error: Specify two category names once with --clash <category-a> <category-b>.");
return 1;
}
clashCategories = (args[i + 1], args[i + 2]);
i += 2;
break;
case "--clash-clearance":
if (clashClearance is not null || i + 1 >= args.Length
|| !double.TryParse(args[i + 1], NumberStyles.Float, CultureInfo.InvariantCulture, out var metres)
|| !double.IsFinite(metres) || metres < 0)
{
Console.Error.WriteLine("Error: Specify one finite, nonnegative distance in metres with --clash-clearance.");
return 1;
}
clashClearance = metres;
i++;
break;
case "--add":
if (i + 3 >= args.Length || args[i + 1].StartsWith('-') || args[i + 2] != "--placement"
|| !SceneFederation.TryParsePlacement(args[i + 3], out var placement))
Expand Down Expand Up @@ -178,6 +207,12 @@ public static int Main(string[] args)
}
}

if (clashClearance is not null && clashCategories is null)
{
Console.Error.WriteLine("Error: --clash-clearance requires --clash <category-a> <category-b>.");
return 1;
}

if (string.IsNullOrEmpty(inputPath))
{
Console.Error.WriteLine("Error: Input file must be specified.");
Expand Down Expand Up @@ -235,6 +270,12 @@ public static int Main(string[] args)
return 3;
}

if (clashCategories is { } categories)
{
int clashCode = CheckClashes(doc.Scene, categories, clashClearance);
if (clashCode != 0) return clashCode;
}

if (!string.IsNullOrEmpty(customTitle))
{
doc.Title = customTitle;
Expand Down Expand Up @@ -352,6 +393,37 @@ internal static ViewerDocument FromScene(string path, SceneDocument scene, IRead

// Messages can quote names from the model file: control characters (escape sequences, line breaks) and format
// characters (bidirectional overrides, invisible tag characters) become '?'. Runes, so characters above U+FFFF count too.
private static int CheckClashes(SceneDocument scene, (string First, string Second) categories, double? clearance)
{
long[] Select(string category) => scene.Elements.Where(element => element.Category == category)
.Select(element => element.Id).ToArray();

var first = Select(categories.First);
var second = Select(categories.Second);
if (first.Length == 0 || second.Length == 0)
{
string missing = first.Length == 0 ? categories.First : categories.Second;
Console.Error.WriteLine($"Error: The scene has no elements in clash category '{Printable(missing)}'.");
return 1;
}

try
{
var test = clearance is double metres
? SceneClash.FindSurfaceClearances(scene, first, second, metres)
: SceneClash.FindHardClashes(scene, first, second);
test.Name += $" ({categories.First} / {categories.Second})";
scene.ClashTests.Add(test);
Console.Error.WriteLine($"Clash check found {test.Clashes.Count} element pairs.");
return 0;
}
catch (InvalidDataException ex)
{
Console.Error.WriteLine($"Error: Failed to check clashes: {Printable(ex.Message)}");
return 3;
}
}

internal static string Printable(string text) =>
string.Concat(text.EnumerateRunes().Select(r =>
Rune.IsControl(r) || Rune.GetUnicodeCategory(r) == UnicodeCategory.Format ? "?" : r.ToString()));
Expand Down
133 changes: 133 additions & 0 deletions tests/IOViewer.Tests/ClashCliTests.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
using IOScene;
using IOViewer.Cli;
using IOViewer.Exporters;
using IOViewer.Importers;
using IOViewer.Model;
using Xunit;

namespace IOViewer.Tests;

[Collection("Console")]
public sealed class ClashCliTests : IDisposable
{
private readonly DirectoryInfo _scratch = Directory.CreateTempSubdirectory("ioviewer-clash-");

[Fact]
public void HardClashes_CheckPlacedModelsAndPreserveExistingResults()
{
var host = Model("Walls");
host.ClashTests.Add(new() { Name = "Previous check" });
string input = Save("host", host);
string addition = Save("services", Model("Mechanical Equipment"));
string html = InScratch("results.html");
string snapshot = InScratch("results.json");

Assert.Equal(0, Program.Main([input, "--add", addition, "--placement", "0.25,0,0,0",
"--clash", "Walls", "Mechanical Equipment", "-o", html, "--json", snapshot]));

var tests = JsonViewerImporter.Load(snapshot).Scene.ClashTests;
Assert.Equal("Previous check", tests[0].Name);
var result = Assert.Single(tests[1].Clashes);
Assert.Equal((1L, 2L), (result.Element1Id, result.Element2Id));
Assert.Equal(-0.75, result.Distance);
Assert.InRange(result.Point.X, 0.25, 1);
Assert.Equal(SceneClashStatus.New, result.Status);

var view = ViewerHtml.Parse(File.ReadAllText(html));
var embedded = view.Meta.GetProperty("clashTests")[1].GetProperty("clashes")[0];
Assert.Equal(1, embedded.GetProperty("element1Id").GetInt64());
Assert.Equal(2, embedded.GetProperty("element2Id").GetInt64());
Assert.Equal(result.Distance, embedded.GetProperty("distance").GetDouble());
Assert.Equal(result.Point.X, embedded.GetProperty("point")[0].GetDouble()
+ view.Meta.GetProperty("rtcOffset")[0].GetDouble(), 8);
}

[Theory]
[InlineData("0.125", true)]
[InlineData("0.124", false)]
public void Clearance_UsesInclusiveSurfaceDistanceAndStoresGapMidpoint(string limit, bool found)
{
var scene = Model("Walls");
scene.Place(scene.Geometries[0], Transform3d.Translate(new(1.125, 0, 0)));
scene.Elements[1].Category = "Floors";
string input = Save("source", scene);
string output = InScratch("results.json");

Assert.Equal(0, Program.Main([input, "--clash-clearance", limit, "--clash", "Walls", "Floors", "-o", output]));

var results = Assert.Single(JsonViewerImporter.Load(output).Scene.ClashTests).Clashes;
if (found)
{
var result = Assert.Single(results);
Assert.Equal((1L, 2L), (result.Element1Id, result.Element2Id));
Assert.Equal(0.125, result.Distance);
Assert.Equal(new Vector3d(1.0625, 0, 0), result.Point);
}
else Assert.Empty(results);
}

[Fact]
public void SameCategory_ReportsAnUnorderedPairOnce()
{
var scene = Model("Walls");
scene.Place(scene.Geometries[0], Transform3d.Translate(new(0.25, 0, 0)));
scene.Elements[1].Category = "Walls";
string input = Save("source", scene);
string output = InScratch("results.json");

Assert.Equal(0, Program.Main([input, "--clash", "Walls", "Walls", "-o", output]));

var result = Assert.Single(Assert.Single(JsonViewerImporter.Load(output).Scene.ClashTests).Clashes);
Assert.Equal((1L, 2L), (result.Element1Id, result.Element2Id));
}

[Theory]
[InlineData("--clash", "Walls")]
[InlineData("--clash-clearance", "0.125")]
[InlineData("--clash", "Walls", "missing category")]
[InlineData("--clash", "Walls", "Walls", "--clash", "Walls", "Walls")]
[InlineData("--clash", "Walls", "Walls", "--clash-clearance", "NaN")]
[InlineData("--clash", "Walls", "Walls", "--clash-clearance", "-1")]
public void InvalidClashArguments_LeaveAnExistingOutputUntouched(params string[] options)
{
string input = Save("source", Model("Walls"));
string output = InScratch("results.json");
File.WriteAllText(output, "existing");

Assert.Equal(1, Program.Main([input, "-o", output, .. options]));
Assert.Equal("existing", File.ReadAllText(output));
}

[Fact]
public void InvalidScene_LeavesAnExistingOutputUntouched()
{
var scene = Model("Walls");
scene.Elements[0].ParentId = 42;
string input = Save("source", scene);
string output = InScratch("results.json");
File.WriteAllText(output, "existing");

Assert.Equal(3, Program.Main([input, "--clash", "Walls", "Walls", "-o", output]));
Assert.Equal("existing", File.ReadAllText(output));
}

private static SceneDocument Model(string category)
{
var scene = TestScenes.Empty(category);
scene.Mesh([Vector3d.Zero, Vector3d.UnitX, Vector3d.UnitY, Vector3d.UnitZ],
[0, 2, 1, 0, 1, 3, 0, 3, 2, 1, 2, 3]);
scene.Elements[0].Category = category;
return scene;
}

private string InScratch(string name) => Path.Combine(_scratch.FullName, name);

private string Save(string name, SceneDocument scene)
{
string path = InScratch(name + ".json");
JsonViewerExporter.Save(new ViewerDocument(scene), path);
return path;
}

public void Dispose() => _scratch.Delete(recursive: true);
}
Loading