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