Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add ASM-A4 firmasm roundtrip export package path

Yuechen Lidb3250314dfa
diff --git a/Aetheris.CLI.Tests/CliBaselineTests.cs b/Aetheris.CLI.Tests/CliBaselineTests.cs
index 3659e992..c87bcd84 100644
--- a/Aetheris.CLI.Tests/CliBaselineTests.cs
+++ b/Aetheris.CLI.Tests/CliBaselineTests.cs
@@ -77,6 +77,73 @@ public sealed class CliBaselineTests
Assert.True(root.GetProperty("analysis").GetProperty("summary").GetProperty("faceCount").GetInt32() > 0);
}
+ [Fact]
+ public void Asm_Export_Command_Exports_OcctNutBolt_RoundtripPackage()
+ {
+ var stdout = new StringWriter();
+ var stderr = new StringWriter();
+ var manifestPath = Path.Combine(RepoRoot, "testdata/firmasm/examples/occt-nut-bolt/nut-bolt-assembly.firmasm");
+ var outputDirectory = CreateTempDirectory();
+
+ try
+ {
+ var exitCode = Aetheris.CLI.CliRunner.Run(
+ ["asm", "export", manifestPath, "--out", outputDirectory, "--json"],
+ stdout,
+ stderr);
+
+ Assert.Equal(0, exitCode);
+ Assert.True(string.IsNullOrWhiteSpace(stderr.ToString()));
+
+ using var doc = JsonDocument.Parse(stdout.ToString());
+ var root = doc.RootElement;
+ Assert.True(root.GetProperty("success").GetBoolean());
+ Assert.Equal(".firmasm", root.GetProperty("nativeAuthority").GetString());
+ Assert.Equal("step-instance-package", root.GetProperty("exportShape").GetString());
+ Assert.Equal(2, root.GetProperty("instanceCount").GetInt32());
+ Assert.Equal(2, root.GetProperty("exportedInstanceStepCount").GetInt32());
+
+ var packageManifestPath = root.GetProperty("packageManifestPath").GetString();
+ Assert.False(string.IsNullOrWhiteSpace(packageManifestPath));
+ Assert.True(File.Exists(packageManifestPath));
+ }
+ finally
+ {
+ Directory.Delete(outputDirectory, recursive: true);
+ }
+ }
+
+ [Fact]
+ public void Asm_Export_Command_Exports_As1_RoundtripPackage()
+ {
+ var stdout = new StringWriter();
+ var stderr = new StringWriter();
+ var manifestPath = Path.Combine(RepoRoot, "testdata/firmasm/examples/occt-as1/as1-assembly.firmasm");
+ var outputDirectory = CreateTempDirectory();
+
+ try
+ {
+ var exitCode = Aetheris.CLI.CliRunner.Run(
+ ["asm", "export", manifestPath, "--out", outputDirectory, "--json"],
+ stdout,
+ stderr);
+
+ Assert.Equal(0, exitCode);
+ Assert.True(string.IsNullOrWhiteSpace(stderr.ToString()));
+
+ using var doc = JsonDocument.Parse(stdout.ToString());
+ var root = doc.RootElement;
+ Assert.True(root.GetProperty("success").GetBoolean());
+ Assert.Equal(18, root.GetProperty("instanceCount").GetInt32());
+ Assert.Equal(18, root.GetProperty("composedBodyCount").GetInt32());
+ Assert.Equal(18, root.GetProperty("exportedInstanceStepCount").GetInt32());
+ }
+ finally
+ {
+ Directory.Delete(outputDirectory, recursive: true);
+ }
+ }
+
[Fact]
public void Analyze_Command_Reports_Summary_Facts_And_Discoverability()
{
@@ -827,6 +894,13 @@ public sealed class CliBaselineTests
Assert.Equal(z, vector.GetProperty("z").GetDouble(), 8);
}
+ private static string CreateTempDirectory()
+ {
+ var path = Path.Combine(Path.GetTempPath(), $"aetheris-cli-asm-export-{Guid.NewGuid():N}");
+ Directory.CreateDirectory(path);
+ return path;
+ }
+
private static string FindRepoRoot()
{
var directory = new DirectoryInfo(AppContext.BaseDirectory);
diff --git a/Aetheris.CLI.Tests/CliHelpAndUsageTests.cs b/Aetheris.CLI.Tests/CliHelpAndUsageTests.cs
index 202955dc..bd97ab68 100644
--- a/Aetheris.CLI.Tests/CliHelpAndUsageTests.cs
+++ b/Aetheris.CLI.Tests/CliHelpAndUsageTests.cs
@@ -31,6 +31,7 @@ public sealed class CliHelpAndUsageTests
[InlineData("build")]
[InlineData("canon")]
[InlineData("asm")]
+ [InlineData("asm", "export")]
[InlineData("analyze")]
[InlineData("analyze", "map")]
[InlineData("analyze", "section")]
@@ -110,6 +111,23 @@ public sealed class CliHelpAndUsageTests
Assert.False(sectionDoc.RootElement.GetProperty("success").GetBoolean());
}
+ [Fact]
+ public void Asm_Export_Missing_Out_Has_Clear_Diagnostic()
+ {
+ var stdout = new StringWriter();
+ var stderr = new StringWriter();
+ var manifestPath = Path.Combine(RepoRoot, "testdata/firmasm/examples/occt-nut-bolt/nut-bolt-assembly.firmasm");
+
+ var exitCode = Aetheris.CLI.CliRunner.Run(
+ ["asm", "export", manifestPath, "--json"],
+ stdout,
+ stderr);
+
+ Assert.Equal(1, exitCode);
+ Assert.True(string.IsNullOrWhiteSpace(stdout.ToString()));
+ Assert.Contains("Asm export requires --out <directory>", stderr.ToString(), StringComparison.Ordinal);
+ }
+
private static string FindRepoRoot()
{
var directory = new DirectoryInfo(AppContext.BaseDirectory);
diff --git a/Aetheris.CLI/CliRunner.cs b/Aetheris.CLI/CliRunner.cs
index c9ea8dcc..c66e1058 100644
--- a/Aetheris.CLI/CliRunner.cs
+++ b/Aetheris.CLI/CliRunner.cs
@@ -14,6 +14,7 @@ public static class CliRunner
private const string AnalyzeSectionUsage = "Usage: aetheris analyze section <file.step> (--xy|--xz|--yz) --offset <value> --json";
private const string CanonUsage = "Usage: aetheris canon <file.step> --out <canonical.step> [--json]";
private const string AsmExecUsage = "Usage: aetheris asm exec <file.firmasm> [--json]";
+ private const string AsmExportUsage = "Usage: aetheris asm export <file.firmasm> --out <directory> [--json]";
private static readonly JsonSerializerOptions JsonOptions = new()
{
@@ -520,14 +521,20 @@ public static class CliRunner
return args.Length == 0 ? 1 : 0;
}
- if (!string.Equals(args[0], "exec", StringComparison.Ordinal))
+ if (string.Equals(args[0], "exec", StringComparison.Ordinal))
{
- stderr.WriteLine($"Unknown asm subcommand '{args[0]}'.");
- stderr.WriteLine(AsmExecUsage);
- return 1;
+ return RunAsmExec(args.Skip(1).ToArray(), stdout, stderr);
+ }
+
+ if (string.Equals(args[0], "export", StringComparison.Ordinal))
+ {
+ return RunAsmExport(args.Skip(1).ToArray(), stdout, stderr);
}
- return RunAsmExec(args.Skip(1).ToArray(), stdout, stderr);
+ stderr.WriteLine($"Unknown asm subcommand '{args[0]}'.");
+ stderr.WriteLine(AsmExecUsage);
+ stderr.WriteLine(AsmExportUsage);
+ return 1;
}
private static int RunAsmExec(string[] args, TextWriter stdout, TextWriter stderr)
@@ -622,6 +629,113 @@ public static class CliRunner
return 0;
}
+ private static int RunAsmExport(string[] args, TextWriter stdout, TextWriter stderr)
+ {
+ if (args.Length == 0)
+ {
+ stderr.WriteLine(AsmExportUsage);
+ stderr.WriteLine("Run 'aetheris asm --help' for examples.");
+ return 1;
+ }
+
+ if (IsHelpFlag(args[0]))
+ {
+ WriteAsmHelp(stdout);
+ return 0;
+ }
+
+ if (args[0].StartsWith("-", StringComparison.Ordinal))
+ {
+ stderr.WriteLine("Asm export requires <file.firmasm> as the first argument.");
+ stderr.WriteLine(AsmExportUsage);
+ return 1;
+ }
+
+ var manifestPath = args[0];
+ string? outputDirectory = null;
+ var json = false;
+ for (var i = 1; i < args.Length; i++)
+ {
+ switch (args[i])
+ {
+ case "--out" when i + 1 < args.Length:
+ outputDirectory = args[++i];
+ break;
+ case "--out":
+ stderr.WriteLine("Asm export option --out requires a directory path.");
+ stderr.WriteLine(AsmExportUsage);
+ return 1;
+ case "--json":
+ json = true;
+ break;
+ case "-h":
+ case "--help":
+ WriteAsmHelp(stdout);
+ return 0;
+ default:
+ stderr.WriteLine($"Unknown asm export option '{args[i]}'.");
+ stderr.WriteLine(AsmExportUsage);
+ return 1;
+ }
+ }
+
+ if (string.IsNullOrWhiteSpace(outputDirectory))
+ {
+ stderr.WriteLine("Asm export requires --out <directory>.");
+ stderr.WriteLine(AsmExportUsage);
+ return 1;
+ }
+
+ var exporter = new FirmasmAssemblyRoundtripExporter();
+ var export = exporter.ExportFromFile(manifestPath, outputDirectory);
+ if (!export.IsSuccess)
+ {
+ if (json)
+ {
+ stdout.WriteLine(JsonSerializer.Serialize(new
+ {
+ success = false,
+ manifestPath = Path.GetFullPath(manifestPath),
+ outputDirectory = Path.GetFullPath(outputDirectory),
+ diagnostics = export.Diagnostics.Select(d => new { d.Source, d.Message, severity = d.Severity.ToString() })
+ }, JsonOptions));
+ }
+ else
+ {
+ stderr.WriteLine("ASM export failed:");
+ foreach (var diagnostic in export.Diagnostics)
+ {
+ stderr.WriteLine($"- [{diagnostic.Severity}] {diagnostic.Source}: {diagnostic.Message}");
+ }
+ }
+
+ return 1;
+ }
+
+ if (json)
+ {
+ stdout.WriteLine(JsonSerializer.Serialize(new
+ {
+ success = true,
+ manifestPath = export.Value.SourceManifestPath,
+ outputDirectory = export.Value.OutputDirectory,
+ packageManifestPath = export.Value.PackageManifestPath,
+ nativeAuthority = ".firmasm",
+ exportShape = "step-instance-package",
+ instanceCount = export.Value.InstanceCount,
+ composedBodyCount = export.Value.ComposedBodyCount,
+ exportedInstanceStepCount = export.Value.ExportedInstances.Count
+ }, JsonOptions));
+ return 0;
+ }
+
+ stdout.WriteLine($"ASM export succeeded: {export.Value.SourceManifestPath}");
+ stdout.WriteLine($"Output directory: {export.Value.OutputDirectory}");
+ stdout.WriteLine($"Exported instance STEP files: {export.Value.ExportedInstances.Count}");
+ stdout.WriteLine($"Package manifest: {export.Value.PackageManifestPath}");
+ return 0;
+ }
+
private static int RunAnalyzeMap(string[] args, TextWriter stdout, TextWriter stderr)
{
if (args.Length == 0)
@@ -927,7 +1041,7 @@ public static class CliRunner
stdout.WriteLine(" build Build a .firmament source file into STEP.");
stdout.WriteLine(" analyze Analyze STEP topology, geometry, map, and sections.");
stdout.WriteLine(" canon Import and re-export STEP/AP242 as canonical STEP.");
- stdout.WriteLine(" asm Execute .firmasm assembly IR into composed world-space geometry.");
+ stdout.WriteLine(" asm Execute/export .firmasm assembly IR using rigid world-space composition.");
stdout.WriteLine();
stdout.WriteLine("Global options:");
stdout.WriteLine(" -h, --help Show help.");
@@ -938,6 +1052,7 @@ public static class CliRunner
stdout.WriteLine(" aetheris analyze model.step --json");
stdout.WriteLine(" aetheris canon input.step --out canonical.step --json");
stdout.WriteLine(" aetheris asm exec assembly.firmasm --json");
+ stdout.WriteLine(" aetheris asm export assembly.firmasm --out out/assembly-roundtrip --json");
stdout.WriteLine(" aetheris analyze map model.step --top --rows 40 --cols 60 --json");
stdout.WriteLine(" aetheris analyze section model.step --xy --offset 2.5 --json");
stdout.WriteLine();
@@ -1034,16 +1149,19 @@ public static class CliRunner
private static void WriteAsmHelp(TextWriter stdout)
{
- stdout.WriteLine("Execute flattened .firmasm assemblies as rigidly placed body instances.");
+ stdout.WriteLine("Execute flattened .firmasm assemblies as rigidly placed body instances, or export STEP interop packages.");
stdout.WriteLine();
stdout.WriteLine(AsmExecUsage);
+ stdout.WriteLine($" or: {AsmExportUsage[7..]}");
stdout.WriteLine();
stdout.WriteLine("Options:");
+ stdout.WriteLine(" --out <path> Required for 'asm export'; output directory for package artifacts.");
stdout.WriteLine(" --json Emit machine-readable execution and analyzer JSON.");
stdout.WriteLine(" -h, --help Show this help.");
stdout.WriteLine();
stdout.WriteLine("Example:");
stdout.WriteLine(" aetheris asm exec testdata/firmasm/examples/occt-as1/as1-assembly.firmasm --json");
+ stdout.WriteLine(" aetheris asm export testdata/firmasm/examples/occt-nut-bolt/nut-bolt-assembly.firmasm --out tmp/nutbolt-export --json");
}
private static string FormatBox(Aetheris.Kernel.Core.Math.BoundingBox3D? box) =>
diff --git a/Aetheris.Kernel.Firmament.Tests/Assembly/FirmasmAssemblyRoundtripExporterTests.cs b/Aetheris.Kernel.Firmament.Tests/Assembly/FirmasmAssemblyRoundtripExporterTests.cs
new file mode 100644
index 00000000..9ed3dca2
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/Assembly/FirmasmAssemblyRoundtripExporterTests.cs
@@ -0,0 +1,77 @@
+using System.Text.Json;
+using Aetheris.Kernel.Core.Step242;
+using Aetheris.Kernel.Firmament.Assembly;
+
+namespace Aetheris.Kernel.Firmament.Tests.Assembly;
+
+public sealed class FirmasmAssemblyRoundtripExporterTests
+{
+ [Fact]
+ public void ExportFromFile_NutBolt_WritesStepInteropPackageAndImportableParts()
+ {
+ var exporter = new FirmasmAssemblyRoundtripExporter();
+ var sourcePath = FirmamentCorpusHarness.ResolveFixtureFullPath("testdata/firmasm/examples/occt-nut-bolt/nut-bolt-assembly.firmasm");
+ var outputDirectory = CreateTempDirectory();
+
+ try
+ {
+ var exportResult = exporter.ExportFromFile(sourcePath, outputDirectory);
+
+ Assert.True(exportResult.IsSuccess, string.Join(Environment.NewLine, exportResult.Diagnostics.Select(d => d.Message)));
+ Assert.Equal(2, exportResult.Value.ExportedInstances.Count);
+ Assert.True(File.Exists(exportResult.Value.PackageManifestPath));
+
+ using var document = JsonDocument.Parse(File.ReadAllText(exportResult.Value.PackageManifestPath));
+ var root = document.RootElement;
+ Assert.Equal("asm-a4-step-instance-package/v1", root.GetProperty("schema").GetString());
+ Assert.Equal(".firmasm", root.GetProperty("nativeAuthority").GetString());
+ Assert.Equal("outbound-step-interop", root.GetProperty("exportIntent").GetString());
+ Assert.Equal(2, root.GetProperty("summary").GetProperty("instanceCount").GetInt32());
+
+ foreach (var instance in exportResult.Value.ExportedInstances)
+ {
+ Assert.True(File.Exists(instance.StepPath), $"Expected exported STEP file '{instance.StepPath}'.");
+ var import = Step242Importer.ImportBody(File.ReadAllText(instance.StepPath));
+ Assert.True(import.IsSuccess, $"Failed to import exported STEP '{instance.StepPath}'.");
+ Assert.Single(import.Value.Topology.Bodies);
+ }
+ }
+ finally
+ {
+ Directory.Delete(outputDirectory, recursive: true);
+ }
+ }
+
+ [Fact]
+ public void ExportFromFile_As1_PreservesFlatInstanceCountInPackage()
+ {
+ var exporter = new FirmasmAssemblyRoundtripExporter();
+ var sourcePath = FirmamentCorpusHarness.ResolveFixtureFullPath("testdata/firmasm/examples/occt-as1/as1-assembly.firmasm");
+ var outputDirectory = CreateTempDirectory();
+
+ try
+ {
+ var exportResult = exporter.ExportFromFile(sourcePath, outputDirectory);
+
+ Assert.True(exportResult.IsSuccess, string.Join(Environment.NewLine, exportResult.Diagnostics.Select(d => d.Message)));
+ Assert.Equal(18, exportResult.Value.ExportedInstances.Count);
+ Assert.Equal(18, exportResult.Value.ComposedBodyCount);
+
+ using var document = JsonDocument.Parse(File.ReadAllText(exportResult.Value.PackageManifestPath));
+ var root = document.RootElement;
+ Assert.Equal(18, root.GetProperty("instances").GetArrayLength());
+ Assert.Equal(18, root.GetProperty("summary").GetProperty("composedBodyCount").GetInt32());
+ }
+ finally
+ {
+ Directory.Delete(outputDirectory, recursive: true);
+ }
+ }
+
+ private static string CreateTempDirectory()
+ {
+ var path = Path.Combine(Path.GetTempPath(), $"aetheris-asm-a4-{Guid.NewGuid():N}");
+ Directory.CreateDirectory(path);
+ return path;
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Assembly/FirmasmAssemblyRoundtripExporter.cs b/Aetheris.Kernel.Firmament/Assembly/FirmasmAssemblyRoundtripExporter.cs
new file mode 100644
index 00000000..0cfb6ae3
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Assembly/FirmasmAssemblyRoundtripExporter.cs
@@ -0,0 +1,147 @@
+using System.Text;
+using System.Text.Json;
+using Aetheris.Kernel.Core.Diagnostics;
+using Aetheris.Kernel.Core.Results;
+using Aetheris.Kernel.Core.Step242;
+
+namespace Aetheris.Kernel.Firmament.Assembly;
+
+public sealed record FirmasmAssemblyRoundtripExportedInstance(
+ string InstanceId,
+ string PartName,
+ string StepPath,
+ int BodyCount,
+ int FaceCount,
+ int EdgeCount,
+ int VertexCount);
+
+public sealed record FirmasmAssemblyRoundtripExportResult(
+ string SourceManifestPath,
+ string OutputDirectory,
+ string PackageManifestPath,
+ IReadOnlyList<FirmasmAssemblyRoundtripExportedInstance> ExportedInstances,
+ int InstanceCount,
+ int ComposedBodyCount);
+
+public sealed class FirmasmAssemblyRoundtripExporter
+{
+ private const string PackageSchema = "asm-a4-step-instance-package/v1";
+ private static readonly JsonSerializerOptions JsonOptions = new()
+ {
+ WriteIndented = true,
+ PropertyNamingPolicy = JsonNamingPolicy.CamelCase
+ };
+
+ private readonly FirmasmAssemblyExecutor _executor = new();
+
+ public KernelResult<FirmasmAssemblyRoundtripExportResult> ExportFromFile(string manifestPath, string outputDirectory)
+ {
+ if (string.IsNullOrWhiteSpace(outputDirectory))
+ {
+ return Failure("Roundtrip export requires an output directory path.");
+ }
+
+ var executionResult = _executor.ExecuteFromFile(manifestPath);
+ if (!executionResult.IsSuccess)
+ {
+ return KernelResult<FirmasmAssemblyRoundtripExportResult>.Failure(executionResult.Diagnostics);
+ }
+
+ var executed = executionResult.Value;
+ var outputDirectoryPath = Path.GetFullPath(outputDirectory);
+ Directory.CreateDirectory(outputDirectoryPath);
+
+ var exportedInstances = new List<FirmasmAssemblyRoundtripExportedInstance>(executed.Instances.Count);
+ var orderedInstances = executed.Instances
+ .OrderBy(instance => instance.InstanceId, StringComparer.Ordinal)
+ .ToArray();
+
+ for (var index = 0; index < orderedInstances.Length; index++)
+ {
+ var instance = orderedInstances[index];
+ var fileName = $"{index + 1:D4}-{SanitizeFileName(instance.InstanceId)}.step";
+ var exportPath = Path.Combine(outputDirectoryPath, fileName);
+
+ var export = Step242Exporter.ExportBody(instance.Body, options: new Step242ExportOptions
+ {
+ ProductName = $"{executed.LoadedAssembly.Manifest.Assembly.Name}:{instance.InstanceId}"
+ });
+
+ if (!export.IsSuccess)
+ {
+ var diagnostics = export.Diagnostics.Append(new KernelDiagnostic(
+ KernelDiagnosticCode.ValidationFailed,
+ KernelDiagnosticSeverity.Error,
+ $"Failed to export instance '{instance.InstanceId}' during .firmasm roundtrip export.",
+ Source: "firmasm")).ToArray();
+ return KernelResult<FirmasmAssemblyRoundtripExportResult>.Failure(diagnostics);
+ }
+
+ File.WriteAllText(exportPath, export.Value, new UTF8Encoding(false));
+ exportedInstances.Add(new FirmasmAssemblyRoundtripExportedInstance(
+ instance.InstanceId,
+ instance.PartName,
+ exportPath,
+ instance.Body.Topology.Bodies.Count(),
+ instance.Body.Topology.Faces.Count(),
+ instance.Body.Topology.Edges.Count(),
+ instance.Body.Topology.Vertices.Count()));
+ }
+
+ var packageManifestPath = Path.Combine(outputDirectoryPath, "roundtrip.package.json");
+ var packageManifest = new
+ {
+ schema = PackageSchema,
+ nativeAuthority = ".firmasm",
+ exportIntent = "outbound-step-interop",
+ sourceManifestPath = executed.LoadedAssembly.SourcePath,
+ assemblyName = executed.LoadedAssembly.Manifest.Assembly.Name,
+ units = executed.LoadedAssembly.Manifest.Assembly.Units,
+ summary = new
+ {
+ partCount = executed.LoadedAssembly.LoadedParts.Count,
+ instanceCount = executed.Instances.Count,
+ composedBodyCount = executed.ComposedBody.Topology.Bodies.Count()
+ },
+ instances = exportedInstances.Select(instance => new
+ {
+ instanceId = instance.InstanceId,
+ partName = instance.PartName,
+ stepPath = instance.StepPath,
+ bodyCount = instance.BodyCount,
+ faceCount = instance.FaceCount,
+ edgeCount = instance.EdgeCount,
+ vertexCount = instance.VertexCount
+ }).ToArray()
+ };
+
+ File.WriteAllText(packageManifestPath, JsonSerializer.Serialize(packageManifest, JsonOptions), new UTF8Encoding(false));
+
+ return KernelResult<FirmasmAssemblyRoundtripExportResult>.Success(new FirmasmAssemblyRoundtripExportResult(
+ executed.LoadedAssembly.SourcePath,
+ outputDirectoryPath,
+ packageManifestPath,
+ exportedInstances,
+ executed.Instances.Count,
+ executed.ComposedBody.Topology.Bodies.Count()));
+ }
+
+ private static string SanitizeFileName(string value)
+ {
+ var invalidChars = Path.GetInvalidFileNameChars();
+ var chars = value.Select(ch => invalidChars.Contains(ch) ? '_' : ch).ToArray();
+ var sanitized = new string(chars);
+ return string.IsNullOrWhiteSpace(sanitized) ? "instance" : sanitized;
+ }
+
+ private static KernelResult<FirmasmAssemblyRoundtripExportResult> Failure(string message)
+ {
+ return KernelResult<FirmasmAssemblyRoundtripExportResult>.Failure([
+ new KernelDiagnostic(
+ KernelDiagnosticCode.ValidationFailed,
+ KernelDiagnosticSeverity.Error,
+ message,
+ Source: "firmasm")
+ ]);
+ }
+}