diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0e1fc68..1a35407 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -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
diff --git a/Directory.Packages.props b/Directory.Packages.props
index 72938e3..8ae4a68 100644
--- a/Directory.Packages.props
+++ b/Directory.Packages.props
@@ -6,6 +6,7 @@
+
diff --git a/README.md b/README.md
index 463f403..007c5f6 100644
--- a/README.md
+++ b/README.md
@@ -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
diff --git a/THIRD-PARTY-NOTICES.md b/THIRD-PARTY-NOTICES.md
index 6a32ec5..de3238d 100644
--- a/THIRD-PARTY-NOTICES.md
+++ b/THIRD-PARTY-NOTICES.md
@@ -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 |
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 7aa0971..4343ae8 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -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 ` 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,
diff --git a/docs/public-api.md b/docs/public-api.md
index fdbd5ef..8287805 100644
--- a/docs/public-api.md
+++ b/docs/public-api.md
@@ -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`.
diff --git a/src/IOViewer.Cli/IOViewer.Cli.csproj b/src/IOViewer.Cli/IOViewer.Cli.csproj
index 60e4ea4..3f3dc1b 100644
--- a/src/IOViewer.Cli/IOViewer.Cli.csproj
+++ b/src/IOViewer.Cli/IOViewer.Cli.csproj
@@ -16,6 +16,7 @@
+
diff --git a/src/IOViewer.Cli/Program.cs b/src/IOViewer.Cli/Program.cs
index 2abad6e..4e0fade 100644
--- a/src/IOViewer.Cli/Program.cs
+++ b/src/IOViewer.Cli/Program.cs
@@ -4,6 +4,7 @@
using System.Reflection;
using System.Text;
using IfcIO.Scene;
+using IOCoord;
using IOScene;
using IOViewer.Exporters;
using IOViewer.Importers;
@@ -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 Page title shown in the browser tab.
--bcf Import topics from a local BCF 2.1 archive in the scene's coordinates.
+ --clash
+ Check two exact category names for hard clashes after placing all models.
+ --clash-clearance
+ 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.
@@ -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;
@@ -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 .");
+ 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))
@@ -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 .");
+ return 1;
+ }
+
if (string.IsNullOrEmpty(inputPath))
{
Console.Error.WriteLine("Error: Input file must be specified.");
@@ -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;
@@ -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()));
diff --git a/tests/IOViewer.Tests/ClashCliTests.cs b/tests/IOViewer.Tests/ClashCliTests.cs
new file mode 100644
index 0000000..cefed06
--- /dev/null
+++ b/tests/IOViewer.Tests/ClashCliTests.cs
@@ -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);
+}