Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

PLACEMENT-C0 unify placement anchors and canonicalize on_face

Yuechen Li10eb57e89b8e
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentExamplePackSmokeTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentExamplePackSmokeTests.cs
index b7e42295..9fb408a7 100644
--- a/Aetheris.Kernel.Firmament.Tests/FirmamentExamplePackSmokeTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentExamplePackSmokeTests.cs
@@ -95,6 +95,22 @@ public sealed class FirmamentExamplePackSmokeTests
Assert.Single(result.Compilation.Value.PrimitiveExecutionResult!.ExecutedPrimitives);
}
+ [Theory]
+ [InlineData("testdata/firmament/examples/p1_blind_hole_on_face_semantic.firmament")]
+ [InlineData("testdata/firmament/examples/p1_flange_radial_hole_semantic.firmament")]
+ [InlineData("testdata/firmament/examples/w2_cylinder_root_blind_bore_semantic.firmament")]
+ [InlineData("testdata/firmament/examples/w2_box_sphere_exterior_opening_pocket_semantic.firmament")]
+ [InlineData("testdata/firmament/examples/placed_primitive.firmament")]
+ public void CanonicalExamples_StillBuild(string fixturePath)
+ {
+ var compileResult = FirmamentCorpusHarness.Compile(FirmamentCorpusHarness.ReadFixtureText(fixturePath));
+ Assert.True(compileResult.Compilation.IsSuccess);
+
+ var exportResult = ExportFixture(fixturePath);
+ Assert.True(exportResult.IsSuccess);
+ Assert.Contains("ISO-10303-21", exportResult.Value.StepText, StringComparison.Ordinal);
+ }
+
private static Aetheris.Kernel.Core.Results.KernelResult<FirmamentStepExportResult> ExportFixture(string fixturePath) =>
FirmamentStepExporter.Export(new FirmamentCompileRequest(new FirmamentSourceDocument(FirmamentCorpusHarness.ReadFixtureText(fixturePath))));
}
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentFormatterTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentFormatterTests.cs
index c3ea75c9..527942d9 100644
--- a/Aetheris.Kernel.Firmament.Tests/FirmamentFormatterTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentFormatterTests.cs
@@ -325,6 +325,39 @@ public sealed class FirmamentFormatterTests
Assert.NotEmpty(result.Formatting.Diagnostics);
}
+ [Fact]
+ public void OnFace_And_CenteredOn_Canonicalization()
+ {
+ const string source = """
+ firmament:
+ version: 1
+
+ model:
+ name: demo
+ units: mm
+
+ ops[1]:
+ -
+ op: box
+ id: rib
+ size[3]:
+ 3
+ 3
+ 3
+ place:
+ centered_on: base.top_face
+ offset[3]:
+ 0
+ 0
+ 1
+ """;
+
+ var result = Format(source);
+ Assert.True(result.Formatting.IsSuccess);
+ Assert.Contains("on_face: base.top_face", result.Formatting.Value.Text, StringComparison.Ordinal);
+ Assert.DoesNotContain("centered_on:", result.Formatting.Value.Text, StringComparison.Ordinal);
+ }
+
private static FirmamentFormatResult Format(string source)
{
var formatter = new FirmamentFormatter();
@@ -375,9 +408,15 @@ public sealed class FirmamentFormatterTests
{
FirmamentParsedPlacementOriginAnchor => "origin",
FirmamentParsedPlacementSelectorAnchor selector => selector.Selector,
+ null => null,
_ => throw new InvalidOperationException("Unknown placement anchor.")
},
- entry.Placement.Offset.Select(value => value.ToString("G", CultureInfo.InvariantCulture)).ToArray());
+ entry.Placement.Offset.Select(value => value.ToString("G", CultureInfo.InvariantCulture)).ToArray(),
+ entry.Placement.OnFace,
+ entry.Placement.CenteredOn,
+ entry.Placement.AroundAxis,
+ entry.Placement.RadialOffset?.ToString("G", CultureInfo.InvariantCulture),
+ entry.Placement.AngleDegrees?.ToString("G", CultureInfo.InvariantCulture));
return new FirmamentOpMeaningSnapshot(entry.KnownKind, entry.Family, fields, placement);
}
@@ -438,5 +477,12 @@ public sealed class FirmamentFormatterTests
private sealed record FirmamentFieldMeaningSnapshot(string Name, string Value);
- private sealed record FirmamentPlacementMeaningSnapshot(string On, IReadOnlyList<string> Offset);
+ private sealed record FirmamentPlacementMeaningSnapshot(
+ string? On,
+ IReadOnlyList<string> Offset,
+ string? OnFace,
+ string? CenteredOn,
+ string? AroundAxis,
+ string? RadialOffset,
+ string? AngleDegrees);
}
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentPlacementValidationTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentPlacementValidationTests.cs
index f309f48d..e4ef7eb0 100644
--- a/Aetheris.Kernel.Firmament.Tests/FirmamentPlacementValidationTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentPlacementValidationTests.cs
@@ -57,6 +57,49 @@ public sealed class FirmamentPlacementValidationTests
Assert.Contains("concentric_with", diagnostic.Message, StringComparison.Ordinal);
}
+ [Fact]
+ public void Placement_Alias_Conflict_Between_OnFace_And_CenteredOn_Is_Rejected()
+ {
+ const string source = """
+firmament:
+ version: 1
+
+model:
+ name: placement_alias_conflict
+ units: mm
+
+ops[2]:
+ -
+ op: box
+ id: base
+ size[3]:
+ 20
+ 20
+ 10
+
+ -
+ op: box
+ id: rib
+ size[3]:
+ 2
+ 2
+ 2
+ place:
+ on_face: base.top_face
+ centered_on: base.bottom_face
+ offset[3]:
+ 0
+ 0
+ 0
+""";
+
+ var result = CompileSource(source);
+ Assert.False(result.Compilation.IsSuccess);
+ var diagnostic = Assert.Single(result.Compilation.Diagnostics);
+ Assert.Contains(FirmamentDiagnosticCodes.PlacementInvalidSemanticCombination.Value, diagnostic.Message, StringComparison.Ordinal);
+ Assert.Contains("compatibility alias", diagnostic.Message, StringComparison.Ordinal);
+ }
+
[Fact]
public void Primitive_With_Sphere_Surface_PlaceAnchor_Is_Valid()
{
@@ -256,6 +299,11 @@ public sealed class FirmamentPlacementValidationTests
private static FirmamentCompileResult CompileFixture(string fixturePath)
{
var source = FirmamentCorpusHarness.ReadFixtureText(fixturePath);
+ return CompileSource(source);
+ }
+
+ private static FirmamentCompileResult CompileSource(string source)
+ {
var compiler = new FirmamentCompiler();
return compiler.Compile(new FirmamentCompileRequest(new FirmamentSourceDocument(source)));
}
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentPrimitiveLoweringTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentPrimitiveLoweringTests.cs
index 2deebf74..36720145 100644
--- a/Aetheris.Kernel.Firmament.Tests/FirmamentPrimitiveLoweringTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentPrimitiveLoweringTests.cs
@@ -304,6 +304,59 @@ public sealed class FirmamentPrimitiveLoweringTests
Assert.Equal(new[] { 10d, -5d, 3d }, boolean.Placement.Offset);
}
+ [Fact]
+ public void SemanticPlacement_And_OnOffset_Lower_To_Coherent_Result()
+ {
+ const string source = """
+firmament:
+ version: 1
+
+model:
+ name: placement_c0_lowering_unification
+ units: mm
+
+ops[2]:
+ -
+ op: box
+ id: base
+ size[3]:
+ 20
+ 20
+ 10
+
+ -
+ op: box
+ id: semantic
+ size[3]:
+ 4
+ 4
+ 4
+ place:
+ on_face: base.top_face
+ offset[3]:
+ 1
+ 2
+ 3
+""";
+
+ var semanticResult = Compile(source);
+ Assert.True(semanticResult.Compilation.IsSuccess);
+ var semantic = semanticResult.Compilation.Value.PrimitiveLoweringPlan!.Primitives.Single(p => p.FeatureId == "semantic");
+ var semanticAnchor = Assert.IsType<FirmamentLoweredPlacementSelectorAnchor>(semantic.Placement!.On);
+ Assert.Equal("base.top_face", semanticAnchor.Selector);
+ Assert.Equal(new[] { 1d, 2d, 3d }, semantic.Placement.Offset);
+
+ var explicitResult = Compile(source.Replace("on_face", "on", StringComparison.Ordinal));
+ Assert.True(explicitResult.Compilation.IsSuccess);
+ var explicitPlacement = explicitResult.Compilation.Value.PrimitiveLoweringPlan!.Primitives.Single(p => p.FeatureId == "semantic").Placement!;
+ var explicitAnchor = Assert.IsType<FirmamentLoweredPlacementSelectorAnchor>(explicitPlacement.On);
+ Assert.Equal("base.top_face", explicitAnchor.Selector);
+ Assert.Equal(semantic.Placement.Offset, explicitPlacement.Offset);
+ Assert.Equal(semantic.Placement.AroundAxis, explicitPlacement.AroundAxis);
+ Assert.Equal(semantic.Placement.RadialOffset, explicitPlacement.RadialOffset);
+ Assert.Equal(semantic.Placement.AngleDegrees, explicitPlacement.AngleDegrees);
+ }
+
[Fact]
public void Compile_Validation_Family_Ops_Remain_Explicitly_NonLowered()
{
diff --git a/Aetheris.Kernel.Firmament/Execution/FirmamentPlacementResolver.cs b/Aetheris.Kernel.Firmament/Execution/FirmamentPlacementResolver.cs
index 824e0b32..b33b4fcf 100644
--- a/Aetheris.Kernel.Firmament/Execution/FirmamentPlacementResolver.cs
+++ b/Aetheris.Kernel.Firmament/Execution/FirmamentPlacementResolver.cs
@@ -19,10 +19,9 @@ internal static class FirmamentPlacementResolver
{
if (primitive.Placement is null) return KernelResult<Vector3D>.Success(Vector3D.Zero);
- var semanticAnchorResult = ResolveSemanticAnchorPoint(primitive.Placement, featureBodies);
- if (!semanticAnchorResult.IsSuccess) return KernelResult<Vector3D>.Failure(semanticAnchorResult.Diagnostics);
-
- var baseAnchorPoint = semanticAnchorResult.Value;
+ var anchorResult = ResolveAnchorPoint(primitive.Placement, featureBodies);
+ if (!anchorResult.IsSuccess) return KernelResult<Vector3D>.Failure(anchorResult.Diagnostics);
+ var baseAnchorPoint = anchorResult.Value;
if (!string.IsNullOrWhiteSpace(primitive.Placement.AroundAxis))
{
var axisResult = ResolveAxisFromSelector(primitive.Placement.AroundAxis!, featureBodies);
@@ -42,9 +41,9 @@ internal static class FirmamentPlacementResolver
public static KernelResult<Vector3D> ResolvePlacementTranslation(FirmamentLoweredBoolean booleanOp, IReadOnlyDictionary<string, BrepBody> featureBodies)
{
if (booleanOp.Placement is null) return KernelResult<Vector3D>.Success(Vector3D.Zero);
- var semanticAnchorResult = ResolveSemanticAnchorPoint(booleanOp.Placement, featureBodies);
- if (!semanticAnchorResult.IsSuccess) return KernelResult<Vector3D>.Failure(semanticAnchorResult.Diagnostics);
- var baseAnchorPoint = semanticAnchorResult.Value;
+ var anchorResult = ResolveAnchorPoint(booleanOp.Placement, featureBodies);
+ if (!anchorResult.IsSuccess) return KernelResult<Vector3D>.Failure(anchorResult.Diagnostics);
+ var baseAnchorPoint = anchorResult.Value;
if (!string.IsNullOrWhiteSpace(booleanOp.Placement.AroundAxis))
{
var axisResult = ResolveAxisFromSelector(booleanOp.Placement.AroundAxis!, featureBodies);
@@ -58,18 +57,8 @@ internal static class FirmamentPlacementResolver
return KernelResult<Vector3D>.Success((baseAnchorPoint - Point3D.Origin) + ResolveOffset(o));
}
- private static KernelResult<Point3D> ResolveSemanticAnchorPoint(FirmamentLoweredPlacement placement, IReadOnlyDictionary<string, BrepBody> featureBodies)
+ private static KernelResult<Point3D> ResolveAnchorPoint(FirmamentLoweredPlacement placement, IReadOnlyDictionary<string, BrepBody> featureBodies)
{
- if (!string.IsNullOrWhiteSpace(placement.OnFace))
- {
- return ResolveAnchorPoint(new FirmamentLoweredPlacementSelectorAnchor(placement.OnFace!), featureBodies);
- }
-
- if (!string.IsNullOrWhiteSpace(placement.CenteredOn))
- {
- return ResolveAnchorPoint(new FirmamentLoweredPlacementSelectorAnchor(placement.CenteredOn!), featureBodies);
- }
-
if (placement.On is not null)
{
return ResolveAnchorPoint(placement.On, featureBodies);
@@ -77,9 +66,9 @@ internal static class FirmamentPlacementResolver
if (!string.IsNullOrWhiteSpace(placement.AroundAxis))
{
- var axis = ResolveAxisFromSelector(placement.AroundAxis!, featureBodies);
- if (!axis.IsSuccess) return KernelResult<Point3D>.Failure(axis.Diagnostics);
- return KernelResult<Point3D>.Success(axis.Value.Origin);
+ var axisResult = ResolveAxisFromSelector(placement.AroundAxis!, featureBodies);
+ if (!axisResult.IsSuccess) return KernelResult<Point3D>.Failure(axisResult.Diagnostics);
+ return KernelResult<Point3D>.Success(axisResult.Value.Origin);
}
return KernelResult<Point3D>.Success(Point3D.Origin);
diff --git a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs
index 5079d6f8..0ff822a6 100644
--- a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs
+++ b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs
@@ -529,7 +529,7 @@ internal static class FirmamentPrimitiveExecutor
if (isSphereTool)
{
- return !string.IsNullOrWhiteSpace(boolean.Placement.OnFace)
+ return boolean.Placement.UsesSemanticAnchor
&& BrepBooleanBoxRecognition.TryRecognizeAxisAlignedBox(baseBody, ToleranceContext.Default, out _, out _);
}
@@ -545,13 +545,13 @@ internal static class FirmamentPrimitiveExecutor
return true;
}
- if (!string.IsNullOrWhiteSpace(boolean.Placement.OnFace)
+ if (boolean.Placement.UsesSemanticAnchor
&& BrepBooleanCylinderRecognition.TryRecognizeCylinder(baseBody, ToleranceContext.Default, out _, out _))
{
return true;
}
- if (string.IsNullOrWhiteSpace(boolean.Placement.OnFace))
+ if (!boolean.Placement.UsesSemanticAnchor)
{
return false;
}
diff --git a/Aetheris.Kernel.Firmament/Formatting/FirmamentCanonicalFormatter.cs b/Aetheris.Kernel.Firmament/Formatting/FirmamentCanonicalFormatter.cs
index ca489e6c..56ee9b99 100644
--- a/Aetheris.Kernel.Firmament/Formatting/FirmamentCanonicalFormatter.cs
+++ b/Aetheris.Kernel.Firmament/Formatting/FirmamentCanonicalFormatter.cs
@@ -270,14 +270,45 @@ internal static class FirmamentCanonicalFormatter
private static void AppendPlacement(StringBuilder builder, int indentLevel, FirmamentParsedPlacement placement)
{
builder.Append(Indent(indentLevel)).Append("place:\n");
- var onValue = placement.On switch
+ var explicitAnchor = placement.On switch
{
FirmamentParsedPlacementOriginAnchor => "origin",
FirmamentParsedPlacementSelectorAnchor selector => selector.Selector,
+ null => null,
_ => throw new InvalidOperationException("Unknown placement anchor.")
};
+ var semanticAnchor = !string.IsNullOrWhiteSpace(placement.OnFace)
+ ? placement.OnFace
+ : placement.CenteredOn;
+
+ if (!string.IsNullOrWhiteSpace(semanticAnchor))
+ {
+ AppendScalarField(builder, indentLevel + 1, "on_face", semanticAnchor!);
+ }
+ else if (!string.IsNullOrWhiteSpace(explicitAnchor))
+ {
+ AppendScalarField(builder, indentLevel + 1, "on", explicitAnchor!);
+ }
+ else if (string.IsNullOrWhiteSpace(placement.AroundAxis))
+ {
+ AppendScalarField(builder, indentLevel + 1, "on", "origin");
+ }
+
+ if (!string.IsNullOrWhiteSpace(placement.AroundAxis))
+ {
+ AppendScalarField(builder, indentLevel + 1, "around_axis", placement.AroundAxis!);
+ }
+
+ if (placement.RadialOffset is not null)
+ {
+ AppendScalarField(builder, indentLevel + 1, "radial_offset", FormatNumber(placement.RadialOffset.Value));
+ }
+
+ if (placement.AngleDegrees is not null)
+ {
+ AppendScalarField(builder, indentLevel + 1, "angle_degrees", FormatNumber(placement.AngleDegrees.Value));
+ }
- AppendScalarField(builder, indentLevel + 1, "on", onValue);
builder.Append(Indent(indentLevel + 1))
.Append("offset[")
.Append(placement.Offset.Count.ToString(CultureInfo.InvariantCulture))
diff --git a/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLowerer.cs b/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLowerer.cs
index 4a652133..f2569b48 100644
--- a/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLowerer.cs
+++ b/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLowerer.cs
@@ -185,7 +185,9 @@ internal static class FirmamentPrimitiveLowerer
return null;
}
- FirmamentLoweredPlacementAnchor? loweredAnchor = placement.On switch
+ var canonicalAnchor = ResolveCanonicalPlacementAnchor(placement);
+ var usesSemanticAnchor = !string.IsNullOrWhiteSpace(placement.OnFace) || !string.IsNullOrWhiteSpace(placement.CenteredOn);
+ FirmamentLoweredPlacementAnchor? loweredAnchor = canonicalAnchor switch
{
FirmamentParsedPlacementOriginAnchor => new FirmamentLoweredPlacementOriginAnchor(),
FirmamentParsedPlacementSelectorAnchor selector => new FirmamentLoweredPlacementSelectorAnchor(selector.Selector),
@@ -193,15 +195,29 @@ internal static class FirmamentPrimitiveLowerer
};
return new FirmamentLoweredPlacement(
loweredAnchor,
+ usesSemanticAnchor,
placement.Offset,
- placement.OnFace,
- placement.CenteredOn,
placement.AroundAxis,
placement.RadialOffset,
placement.AngleDegrees,
placement.UnknownFields);
}
+ private static FirmamentParsedPlacementAnchor? ResolveCanonicalPlacementAnchor(FirmamentParsedPlacement placement)
+ {
+ if (!string.IsNullOrWhiteSpace(placement.OnFace))
+ {
+ return new FirmamentParsedPlacementSelectorAnchor(placement.OnFace!);
+ }
+
+ if (!string.IsNullOrWhiteSpace(placement.CenteredOn))
+ {
+ return new FirmamentParsedPlacementSelectorAnchor(placement.CenteredOn!);
+ }
+
+ return placement.On;
+ }
+
private static FirmamentLoweredBoolean LowerBoolean(
int opIndex,
FirmamentParsedOpEntry entry,
diff --git a/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLoweringPlan.cs b/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLoweringPlan.cs
index 3f29de2c..60a85da9 100644
--- a/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLoweringPlan.cs
+++ b/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLoweringPlan.cs
@@ -16,9 +16,8 @@ public sealed record FirmamentLoweredPrimitive(
public sealed record FirmamentLoweredPlacement(
FirmamentLoweredPlacementAnchor? On,
+ bool UsesSemanticAnchor,
IReadOnlyList<double> Offset,
- string? OnFace,
- string? CenteredOn,
string? AroundAxis,
double? RadialOffset,
double? AngleDegrees,
diff --git a/Aetheris.Kernel.Firmament/Validation/FirmamentBooleanRequiredFieldValidator.cs b/Aetheris.Kernel.Firmament/Validation/FirmamentBooleanRequiredFieldValidator.cs
index 4c35816c..c57a593b 100644
--- a/Aetheris.Kernel.Firmament/Validation/FirmamentBooleanRequiredFieldValidator.cs
+++ b/Aetheris.Kernel.Firmament/Validation/FirmamentBooleanRequiredFieldValidator.cs
@@ -750,6 +750,16 @@ internal static class FirmamentBooleanRequiredFieldValidator
return KernelResult<bool>.Failure([semanticSelectorError]);
}
+ if (!string.IsNullOrWhiteSpace(entry.Placement.OnFace)
+ && !string.IsNullOrWhiteSpace(entry.Placement.CenteredOn)
+ && !string.Equals(entry.Placement.OnFace, entry.Placement.CenteredOn, StringComparison.Ordinal))
+ {
+ return KernelResult<bool>.Failure([
+ CreateDiagnostic(
+ FirmamentDiagnosticCodes.PlacementInvalidSemanticCombination,
+ $"Boolean op '{entry.OpName}' at index {opIndex} has ambiguous placement semantics; 'place.centered_on' is a compatibility alias of 'place.on_face' and must match it when both are present.")]);
+ }
+
if (entry.Placement.RadialOffset is not null && string.IsNullOrWhiteSpace(entry.Placement.AroundAxis))
{
return KernelResult<bool>.Failure([
diff --git a/Aetheris.Kernel.Firmament/Validation/FirmamentPrimitiveRequiredFieldValidator.cs b/Aetheris.Kernel.Firmament/Validation/FirmamentPrimitiveRequiredFieldValidator.cs
index 541ff5b4..fd57cdbe 100644
--- a/Aetheris.Kernel.Firmament/Validation/FirmamentPrimitiveRequiredFieldValidator.cs
+++ b/Aetheris.Kernel.Firmament/Validation/FirmamentPrimitiveRequiredFieldValidator.cs
@@ -485,6 +485,16 @@ internal static class FirmamentPrimitiveRequiredFieldValidator
return KernelResult<bool>.Failure([semanticSelectorError]);
}
+ if (!string.IsNullOrWhiteSpace(entry.Placement.OnFace)
+ && !string.IsNullOrWhiteSpace(entry.Placement.CenteredOn)
+ && !string.Equals(entry.Placement.OnFace, entry.Placement.CenteredOn, StringComparison.Ordinal))
+ {
+ return KernelResult<bool>.Failure([
+ CreateDiagnostic(
+ FirmamentDiagnosticCodes.PlacementInvalidSemanticCombination,
+ $"Primitive op '{entry.OpName}' at index {opIndex} has ambiguous placement semantics; 'place.centered_on' is a compatibility alias of 'place.on_face' and must match it when both are present.")]);
+ }
+
if (entry.Placement.RadialOffset is not null && string.IsNullOrWhiteSpace(entry.Placement.AroundAxis))
{
return KernelResult<bool>.Failure([
diff --git a/docs/firmament-language-shape.md b/docs/firmament-language-shape.md
index 19f8ab29..8f9170b4 100644
--- a/docs/firmament-language-shape.md
+++ b/docs/firmament-language-shape.md
@@ -197,12 +197,11 @@ place:
0
```
-Semantic placement subset (P1):
+Semantic-first placement form:
```
place:
on_face: base.top_face
- centered_on: flange.top_face
around_axis: flange.side_face
radial_offset: 20
angle_degrees: 30
@@ -213,7 +212,9 @@ place:
```
Rules:
-- Supported semantic fields are exactly: `on_face`, `centered_on`, `around_axis`, `radial_offset`, `angle_degrees`.
+- Supported semantic fields are exactly: `on_face`, `centered_on` (compatibility alias), `around_axis`, `radial_offset`, `angle_degrees`.
+- Canonical output normalizes semantic anchors to `on_face`.
+- If both `on_face` and `centered_on` are provided, they must match.
- `radial_offset` requires `around_axis`.
- Unknown placement semantic keys are rejected.
- This is a minimal ergonomics subset; it is **not** a general frame/constraint language.
diff --git a/docs/firmament-overview.md b/docs/firmament-overview.md
index 67312921..7746cbc9 100644
--- a/docs/firmament-overview.md
+++ b/docs/firmament-overview.md
@@ -15,7 +15,7 @@ Firmament currently supports these source-level concepts:
- primitive features: `box`, `cylinder`, `sphere`
- boolean features: `add`, `subtract`, `intersect`
- validation ops: `expect_exists`, `expect_selectable`, `expect_manifold`
-- placement blocks with legacy `place.on` + `offset[3]` and minimal P1 semantic placement (`on_face`, `centered_on`, `around_axis`, `radial_offset`)
+- placement blocks with a unified model: semantic-first `on_face` anchors plus explicit `on` + `offset[3]` fallback (`centered_on` remains a compatibility alias), and optional axis placement (`around_axis`, `radial_offset`, `angle_degrees`)
- selector-shaped references rooted at a source feature id
- optional schema blocks for `cnc`, `additive`, and `injection_molded`
- first schema-aware CNC DFM validation for `minimum_tool_radius` on subtract-with-cylinder inputs
@@ -49,14 +49,11 @@ Validation ops check feature existence, selector selectability, and manifold exp
### Placement
-Placement currently supports two small models:
+Placement currently supports one coherent model with two input styles:
-- `place.on: origin`
-- `place.on: feature_id.port`
-- `offset[3]` numeric translation
-- `place.on_face: feature_id.port`
-- `place.centered_on: feature_id.port`
-- `place.around_axis: feature_id.port` (+ optional `place.radial_offset` and `place.angle_degrees`)
+- semantic anchor: `place.on_face: feature_id.port` (`place.centered_on` accepted as a compatibility alias and normalized to `on_face`)
+- explicit spatial fallback: `place.on: origin|feature_id.port` with `offset[3]`
+- optional radial placement: `place.around_axis: feature_id.port` (+ optional `place.radial_offset` and `place.angle_degrees`)
This is intentionally narrow. It lowers deterministically into selector anchor extraction + axis/radial translation and does not introduce a general frame system or constraint solver.
diff --git a/docs/firmament-placement-semantics.md b/docs/firmament-placement-semantics.md
index ad3c8586..e75e65ff 100644
--- a/docs/firmament-placement-semantics.md
+++ b/docs/firmament-placement-semantics.md
@@ -10,22 +10,23 @@ For primitives, note there is still primitive-specific default publish framing i
---
-## 2) Placement keys and mode split
+## 2) Placement keys in one unified model
Supported keys:
- `on`
- `offset[3]`
- `on_face`
-- `centered_on`
- `around_axis`
- `radial_offset`
- `angle_degrees`
-Mode behavior:
+Unified behavior:
-- legacy mode (no semantic keys): `on` + `offset[3]` required,
-- semantic mode (any semantic key present): `on` optional, `offset[3]` defaults to zero if omitted/malformed,
+- semantic anchor placement prefers `on_face`,
+- explicit spatial fallback uses `on` + `offset[3]`,
+- `centered_on` is a compatibility alias of `on_face`,
+- if both `on_face` and `centered_on` are present they must match exactly,
- `radial_offset` requires `around_axis`.
---
@@ -34,11 +35,10 @@ Mode behavior:
Base anchor point is resolved in this strict precedence:
-1. `on_face`
-2. `centered_on`
-3. `on`
-4. if none above and `around_axis` exists: axis origin
-5. otherwise world origin `(0,0,0)`
+1. canonical semantic anchor (`on_face`, or `centered_on` alias normalized to `on_face`)
+2. `on` fallback anchor
+3. if none above and `around_axis` exists: axis origin
+4. otherwise world origin `(0,0,0)`
---
@@ -122,4 +122,4 @@ Reference: `testdata/firmament/examples/w2_box_sphere_exterior_opening_pocket_se
- Using contained sphere placement when you intended an exterior-opening pocket.
- Tangent/grazing placement (zero-thickness boundary conditions) instead of strict overlap.
- Assuming `offset` is face-local; it is world XYZ.
-- Assuming `on_face` and `centered_on` are distinct mating semantics; currently they share anchor extraction behavior.
+- Authoring both `on_face` and `centered_on` with different selectors (now rejected as ambiguous).
diff --git a/docs/firmament-selectors.md b/docs/firmament-selectors.md
index 2fb2c762..fe4bd137 100644
--- a/docs/firmament-selectors.md
+++ b/docs/firmament-selectors.md
@@ -91,13 +91,13 @@ Current boolean outputs (`add`, `subtract`, `intersect`, plus bounded draft/cham
## Placement-relevant meaning of names
-For placement anchors (`place.on`, `place.on_face`, `place.centered_on`) the resolver currently uses representative geometry points and centroids:
+For placement anchors (`place.on`, `place.on_face`, and compatibility alias `place.centered_on`) the resolver uses one shared anchor extraction path with representative geometry points and centroids:
- face/face-set ports → representative face points then centroid,
- edge-set ports → edge endpoint points then centroid,
- vertex-set ports → vertex points then centroid.
-Important implication: names such as `on_face` vs `centered_on` are currently ergonomic aliases over the same anchor extraction behavior, not different mating solvers.
+Important implication: `centered_on` is a compatibility alias of `on_face`, not a different mating solver. Canonical formatting normalizes alias usage to `on_face`.
---
diff --git a/testdata/firmament/examples/README.md b/testdata/firmament/examples/README.md
index 1bdb3dba..7c8c8711 100644
--- a/testdata/firmament/examples/README.md
+++ b/testdata/firmament/examples/README.md
@@ -1,6 +1,7 @@
# Firmament Example Pack
This directory contains small canonical Firmament examples for the current v1 surface.
+Placement examples use canonical `place.on_face` for semantic anchors; `place.centered_on` remains accepted as a compatibility alias but is normalized by formatter output.
These examples represent the currently supported boolean subset.
Other combinations may fail and are intentionally not supported yet.
diff --git a/testdata/firmament/examples/m7_pmi_explicit_dimensions.firmament b/testdata/firmament/examples/m7_pmi_explicit_dimensions.firmament
index eed76903..a8ed0ad3 100644
--- a/testdata/firmament/examples/m7_pmi_explicit_dimensions.firmament
+++ b/testdata/firmament/examples/m7_pmi_explicit_dimensions.firmament
@@ -24,7 +24,6 @@ ops[2]:
height: 24
place:
on_face: base.top_face
- centered_on: base.top_face
pmi[3]:
-