Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add six-view analyze map LLM summaries

Yuechen Lia1edb6043d04
diff --git a/Aetheris.CLI.Tests/CliBaselineTests.cs b/Aetheris.CLI.Tests/CliBaselineTests.cs
index 19672dba..f09e5d4e 100644
--- a/Aetheris.CLI.Tests/CliBaselineTests.cs
+++ b/Aetheris.CLI.Tests/CliBaselineTests.cs
@@ -538,6 +538,58 @@ public sealed class CliBaselineTests
Assert.Equal(2, root.GetProperty("samples")[12].GetProperty("intersectionModes").GetProperty("analytic").GetInt32());
}
+ [Fact]
+ public void Analyze_Map_SixView_Llm_Box_Returns_Compact_Summaries()
+ {
+ var stepPath = ExportPrimitiveToTempStep(BrepPrimitives.CreateBox(10d, 6d, 4d).Value, "cli-six-view-box");
+ using var doc = RunAnalyzeSixViewMap(stepPath, "8x8");
+ var root = doc.RootElement;
+
+ Assert.Equal("six-view-summary", root.GetProperty("mode").GetString());
+ Assert.Equal("analyze-map-v1", root.GetProperty("mapVersion").GetString());
+ Assert.Equal(6, root.GetProperty("views").GetArrayLength());
+ foreach (var view in root.GetProperty("views").EnumerateArray())
+ {
+ var summary = view.GetProperty("summary");
+ Assert.Equal(64, summary.GetProperty("sampleCount").GetInt32());
+ Assert.Equal(64, summary.GetProperty("hitCount").GetInt32());
+ Assert.Equal(1d, summary.GetProperty("hitCoverage").GetDouble(), 8);
+ Assert.True(summary.GetProperty("surfaceFamiliesHit").TryGetProperty("plane", out _));
+ Assert.True(summary.GetProperty("backendCounts").GetProperty("analytic").GetInt32() > 0);
+ Assert.Equal(0d, summary.GetProperty("fallbackRatio").GetDouble(), 8);
+ Assert.True(view.TryGetProperty("compactGrid", out var compactGrid));
+ Assert.Equal(8, compactGrid.GetProperty("width").GetInt32());
+ Assert.Equal(8, compactGrid.GetProperty("height").GetInt32());
+ Assert.Equal(8, compactGrid.GetProperty("rows").GetArrayLength());
+ }
+ }
+
+ [Fact]
+ public void Analyze_Map_SixView_Llm_Torus_Discloses_Analytic_Ring_And_No_Fallback()
+ {
+ var stepPath = ExportPrimitiveToTempStep(BrepPrimitives.CreateTorus(3d, 1d).Value, "cli-six-view-torus");
+ using var doc = RunAnalyzeSixViewMap(stepPath, "9x9");
+ var root = doc.RootElement;
+ var top = root.GetProperty("views").EnumerateArray().Single(v => v.GetProperty("name").GetString() == "top");
+
+ Assert.True(top.GetProperty("summary").GetProperty("surfaceFamiliesHit").TryGetProperty("torus", out _));
+ Assert.True(top.GetProperty("summary").GetProperty("backendCounts").GetProperty("analytic").GetInt32() > 0);
+ Assert.Equal(0, top.GetProperty("summary").GetProperty("backendCounts").GetProperty("tessellated-fallback").GetInt32());
+ Assert.DoesNotContain("~", string.Concat(top.GetProperty("compactGrid").GetProperty("rows").EnumerateArray().Select(r => r.GetString())));
+ }
+
+ [Fact]
+ public void Analyze_Map_SixView_Llm_LinearExtrusion_Discloses_Fallback()
+ {
+ var stepPath = Path.Combine(RepoRoot, "testdata", "step242", "generated", "ruled-a2", "ellipse-linear-extrusion-production.step");
+ using var doc = RunAnalyzeSixViewMap(stepPath, "4x4");
+ var root = doc.RootElement;
+
+ Assert.Contains("linear-extrusion", root.GetRawText(), StringComparison.Ordinal);
+ Assert.Contains("tessellated-fallback", root.GetRawText(), StringComparison.Ordinal);
+ Assert.Contains(root.GetProperty("diagnostics").EnumerateArray(), d => d.GetString()?.Contains("used tessellated fallback", StringComparison.Ordinal) == true);
+ }
+
[Fact]
public void Analyze_Map_RayProbe_CylinderSide_Uses_Analytic_Exact_Hits()
@@ -1468,6 +1520,16 @@ public sealed class CliBaselineTests
return JsonDocument.Parse(stdout.ToString());
}
+ private static JsonDocument RunAnalyzeSixViewMap(string stepPath, string resolution)
+ {
+ var stdout = new StringWriter();
+ var stderr = new StringWriter();
+ var exitCode = Aetheris.CLI.CliRunner.Run(["analyze", "map", stepPath, "--views", "six", "--resolution", resolution, "--llm", "--json"], stdout, stderr);
+ Assert.Equal(0, exitCode);
+ Assert.True(string.IsNullOrWhiteSpace(stderr.ToString()), stderr.ToString());
+ return JsonDocument.Parse(stdout.ToString());
+ }
+
private static JsonDocument RunAnalyzeSection(string stepPath, string planeFlag, double offset)
{
var stdout = new StringWriter();
diff --git a/Aetheris.CLI/CliRunner.cs b/Aetheris.CLI/CliRunner.cs
index 62142077..159a9647 100644
--- a/Aetheris.CLI/CliRunner.cs
+++ b/Aetheris.CLI/CliRunner.cs
@@ -109,7 +109,7 @@ public static class CliRunner
private const string TopLevelUsage = "Usage: aetheris <build|analyze|trace|canon|asm|experimental> <path> [options]";
private const string BuildUsage = "Usage: aetheris build <file.firmament> [--out <path>] [--json]";
private const string AnalyzeUsage = "Usage: aetheris analyze <file.step> [--face <id>] [--edge <id>] [--vertex <id>] [--json]";
- private const string AnalyzeMapUsage = "Usage: aetheris analyze map <file.step> --plane <xy|xz|yz> --direction <+x|-x|+y|-y|+z|-z> --resolution <NxM> [--point <u,v>] --json";
+ private const string AnalyzeMapUsage = "Usage: aetheris analyze map <file.step> (--plane <xy|xz|yz> --direction <+x|-x|+y|-y|+z|-z> | --views six --llm) --resolution <NxM> [--point <u,v>] --json";
private const string AnalyzeSectionUsage = "Usage: aetheris analyze section <file.step> (--xy|--xz|--yz) --offset <value> --json";
private const string AnalyzeVolumeUsage = "Usage: aetheris analyze volume <file.step> [--approximate --resolution <N>] [--json]";
private const string AnalyzeCompareUsage = "Usage: aetheris analyze compare <reference.step> <candidate.step> [--approximate-volume --resolution <N>] [--json]";
@@ -1762,8 +1762,10 @@ public static class CliRunner
int? cols = null;
string? plane = null;
string? direction = null;
+ string? views = null;
(double U, double V)? point = null;
var json = false;
+ var llm = false;
for (var i = 1; i < args.Length; i++)
{
@@ -1814,6 +1816,17 @@ public static class CliRunner
case "--direction" when i + 1 < args.Length:
direction = args[++i];
break;
+ case "--views" when i + 1 < args.Length:
+ views = args[++i];
+ break;
+ case "--views":
+ stderr.WriteLine("Analyze map option --views requires six.");
+ stderr.WriteLine(AnalyzeMapUsage);
+ return 1;
+ case "--llm":
+ case "--summary":
+ llm = true;
+ break;
case "--direction":
stderr.WriteLine("Analyze map option --direction requires +x, -x, +y, -y, +z, or -z.");
stderr.WriteLine(AnalyzeMapUsage);
@@ -1852,6 +1865,14 @@ public static class CliRunner
}
}
+ var sixViewMode = string.Equals(views, "six", StringComparison.OrdinalIgnoreCase);
+ if (views is not null && !sixViewMode)
+ {
+ stderr.WriteLine("Analyze map option --views currently supports only 'six'.");
+ stderr.WriteLine(AnalyzeMapUsage);
+ return 1;
+ }
+
var legacyViewMode = plane is null && view.HasValue;
if (legacyViewMode)
{
@@ -1868,12 +1889,18 @@ public static class CliRunner
};
}
- if (plane is null || direction is null || (viewOptionCount > 0 && viewOptionCount != 1))
+ if (!sixViewMode && (plane is null || direction is null || (viewOptionCount > 0 && viewOptionCount != 1)))
{
stderr.WriteLine("Analyze map requires --plane and --direction (or one legacy view option --top|--bottom|--front|--back|--left|--right).");
return 1;
}
+ if (sixViewMode && (point.HasValue || plane is not null || direction is not null || viewOptionCount > 0 || !llm))
+ {
+ stderr.WriteLine("Analyze map --views six requires --llm or --summary and cannot be combined with --point, --plane, --direction, or legacy view flags.");
+ return 1;
+ }
+
if (!rows.HasValue || !cols.HasValue)
{
stderr.WriteLine("Analyze map requires both --rows <N> and --cols <N>.");
@@ -1889,9 +1916,11 @@ public static class CliRunner
object map;
try
{
- map = legacyViewMode
+ map = sixViewMode
+ ? StepAnalyzer.AnalyzeSixViewMapSummary(stepPath, cols.Value, rows.Value)
+ : legacyViewMode
? StepAnalyzer.AnalyzeMap(stepPath, view.GetValueOrDefault(), rows.Value, cols.Value)
- : StepAnalyzer.AnalyzeRayMap(stepPath, plane, direction, cols.Value, rows.Value, point);
+ : StepAnalyzer.AnalyzeRayMap(stepPath, plane!, direction!, cols.Value, rows.Value, point);
}
catch (Exception ex)
{
@@ -2255,13 +2284,19 @@ public static class CliRunner
stdout.WriteLine(AnalyzeMapUsage);
stdout.WriteLine();
stdout.WriteLine("Required:");
- stdout.WriteLine(" exactly one view: --top | --bottom | --front | --back | --left | --right");
+ stdout.WriteLine(" either --plane <xy|xz|yz> with --direction <axis>, exactly one legacy view, or --views six --llm.");
+ stdout.WriteLine(" legacy views: --top | --bottom | --front | --back | --left | --right");
stdout.WriteLine(" --rows <N> Positive integer row count.");
stdout.WriteLine(" --cols <N> Positive integer column count.");
+ stdout.WriteLine(" --resolution NxM Alternative to --cols N --rows M.");
stdout.WriteLine(" --json Required output mode.");
stdout.WriteLine();
+ stdout.WriteLine("Six-view convention:");
+ stdout.WriteLine(" top xy/-z, bottom xy/+z, right yz/-x, left yz/+x, back xz/+y, front xz/-y.");
+ stdout.WriteLine();
stdout.WriteLine("Example:");
stdout.WriteLine(" aetheris analyze map part.step --top --rows 48 --cols 64 --json");
+ stdout.WriteLine(" aetheris analyze map part.step --views six --resolution 32x32 --llm --json");
}
private static void WriteAnalyzeSectionHelp(TextWriter stdout)
diff --git a/Aetheris.CLI/StepAnalysisModels.cs b/Aetheris.CLI/StepAnalysisModels.cs
index 6ae028bc..8d4b65b8 100644
--- a/Aetheris.CLI/StepAnalysisModels.cs
+++ b/Aetheris.CLI/StepAnalysisModels.cs
@@ -124,6 +124,11 @@ public sealed record RayMapHit(double T, Point3D Position, int? FaceIndex, strin
public sealed record RayMapSample(int I, int J, double U, double V, bool Hit, RayMapHit? FirstHit, RayMapHit? LastHit, int HitCount, IReadOnlyList<RayMapHit> Hits, IReadOnlyDictionary<string, int> IntersectionModes);
public sealed record RayMapSummary(double HitCoverage, double[]? HeightRange, IReadOnlyDictionary<string, int> SurfaceFamiliesHit, int AnalyticHitCount, int CirHitCount, int TessellatedFallbackHitCount, int UnsupportedSampleCount);
public sealed record RayMapResult(string Mode, string Plane, string Direction, int[]? Resolution, double[]? Point, RayMapBounds Bounds, IReadOnlyList<RayMapSample> Samples, int HitCount, IReadOnlyList<RayMapHit>? Hits, RayMapSummary Summary, string IntersectionMode, string BackendPolicy, IReadOnlyList<string> Diagnostics);
+public sealed record SixViewMapResult(string Mode, string MapVersion, int[] Resolution, IReadOnlyList<SixViewMapView> Views, IReadOnlyList<string> Diagnostics);
+public sealed record SixViewMapView(string Name, string Plane, string Direction, SixViewMapSummary Summary, CompactGrid? CompactGrid, IReadOnlyList<string> MeasuredSummary);
+public sealed record SixViewMapSummary(int SampleCount, int HitCount, double HitCoverage, double[]? HeightRange, IReadOnlyList<DominantBand> DominantBands, IReadOnlyDictionary<string, int> SurfaceFamiliesHit, IReadOnlyDictionary<string, int> BackendCounts, double FallbackRatio);
+public sealed record DominantBand(double? Value, int SampleCount, double Coverage, string? Meaning, bool MostlyFallback);
+public sealed record CompactGrid(string Encoding, int Width, int Height, IReadOnlyDictionary<string, string> Legend, IReadOnlyList<string> Rows);
public enum SectionPlaneFamily
{
diff --git a/Aetheris.CLI/StepAnalyzer.cs b/Aetheris.CLI/StepAnalyzer.cs
index 9bc26b71..d8f1f32e 100644
--- a/Aetheris.CLI/StepAnalyzer.cs
+++ b/Aetheris.CLI/StepAnalyzer.cs
@@ -934,6 +934,41 @@ public sealed record VolumeAnalysisResult(
return AnalyzeImportedBodyRayMap(body, fullPath, plane, direction, cols, rows, point);
}
+ public static SixViewMapResult AnalyzeSixViewMapSummary(string stepPath, int cols, int rows)
+ {
+ var (fullPath, body) = ImportStepBody(stepPath);
+ return AnalyzeImportedBodySixViewMapSummary(body, fullPath, cols, rows);
+ }
+
+ public static SixViewMapResult AnalyzeImportedBodySixViewMapSummary(BrepBody body, string stepPath, int cols, int rows)
+ {
+ if (rows <= 0 || cols <= 0) throw new InvalidOperationException("Map resolution must be positive.");
+ (string Name, string Plane, string Direction)[] definitions =
+ [
+ ("top", "xy", "-z"),
+ ("bottom", "xy", "+z"),
+ ("right", "yz", "-x"),
+ ("left", "yz", "+x"),
+ ("back", "xz", "+y"),
+ ("front", "xz", "-y")
+ ];
+
+ var views = new List<SixViewMapView>();
+ var diagnostics = new SortedSet<string>(StringComparer.Ordinal);
+ foreach (var definition in definitions)
+ {
+ var map = AnalyzeImportedBodyRayMap(body, stepPath, definition.Plane, definition.Direction, cols, rows);
+ foreach (var diagnostic in map.Diagnostics)
+ {
+ diagnostics.Add($"{definition.Name}: {diagnostic}");
+ }
+
+ views.Add(BuildSixViewSummary(definition.Name, map, cols, rows));
+ }
+
+ return new SixViewMapResult("six-view-summary", "analyze-map-v1", [cols, rows], views, diagnostics.ToArray());
+ }
+
public static RayMapResult AnalyzeImportedBodyRayMap(BrepBody body, string stepPath, string plane, string direction, int cols, int rows, (double U, double V)? point = null)
{
if (rows <= 0 || cols <= 0) throw new InvalidOperationException("Map resolution must be positive.");
@@ -1028,6 +1063,148 @@ public sealed record VolumeAnalysisResult(
return new RayMapResult(mode, plane.ToLowerInvariant(), direction.ToLowerInvariant(), point.HasValue ? null : [cols, rows], pointArray, bounds, samples, samples.Sum(s => s.HitCount), point.HasValue ? samples.Single().Hits : null, summary, resultMode, "analytic-cir-tessellated-fallback", diagnostics);
}
+ private static SixViewMapView BuildSixViewSummary(string name, RayMapResult map, int cols, int rows)
+ {
+ var sampleCount = map.Samples.Count;
+ var hitCount = map.Samples.Count(s => s.Hit);
+ var bands = BuildDominantBands(map.Samples, sampleCount, map.Direction);
+ var backendCounts = new SortedDictionary<string, int>(StringComparer.Ordinal)
+ {
+ ["analytic"] = map.Summary.AnalyticHitCount,
+ ["cir-evaluated"] = map.Summary.CirHitCount,
+ ["tessellated-fallback"] = map.Summary.TessellatedFallbackHitCount,
+ ["unsupported"] = map.Summary.UnsupportedSampleCount
+ };
+ var backendHitTotal = map.Summary.AnalyticHitCount + map.Summary.CirHitCount + map.Summary.TessellatedFallbackHitCount;
+ var summary = new SixViewMapSummary(
+ sampleCount,
+ hitCount,
+ sampleCount == 0 ? 0d : hitCount / (double)sampleCount,
+ map.Summary.HeightRange,
+ bands,
+ map.Summary.SurfaceFamiliesHit,
+ backendCounts,
+ backendHitTotal == 0 ? 0d : map.Summary.TessellatedFallbackHitCount / (double)backendHitTotal);
+
+ var compactGrid = cols <= 64 && rows <= 64 ? BuildCompactGrid(map.Samples, cols, rows, bands, map.Direction) : null;
+ var measured = BuildMeasuredSummary(name, map, summary);
+ return new SixViewMapView(name, map.Plane, map.Direction, summary, compactGrid, measured);
+ }
+
+ private static IReadOnlyList<DominantBand> BuildDominantBands(IReadOnlyList<RayMapSample> samples, int sampleCount, string direction)
+ {
+ var groups = new Dictionary<double, (int Count, int Fallback)>();
+ var noHit = 0;
+ foreach (var sample in samples)
+ {
+ if (!sample.Hit || sample.FirstHit is null)
+ {
+ noHit++;
+ continue;
+ }
+
+ var value = Math.Round(GetRayAxisScalar(sample.FirstHit.Position, direction), 4, MidpointRounding.AwayFromZero);
+ groups.TryGetValue(value, out var current);
+ var fallback = sample.FirstHit.IntersectionMode == "tessellated-fallback" ? 1 : 0;
+ groups[value] = (current.Count + 1, current.Fallback + fallback);
+ }
+
+ var bands = groups
+ .OrderByDescending(kvp => kvp.Value.Count)
+ .ThenBy(kvp => kvp.Key)
+ .Take(5)
+ .Select(kvp => new DominantBand(kvp.Key, kvp.Value.Count, sampleCount == 0 ? 0d : kvp.Value.Count / (double)sampleCount, null, kvp.Value.Fallback > kvp.Value.Count / 2d))
+ .ToList();
+ if (noHit > 0)
+ {
+ bands.Add(new DominantBand(null, noHit, sampleCount == 0 ? 0d : noHit / (double)sampleCount, "no-hit", false));
+ }
+
+ return bands.OrderByDescending(b => b.SampleCount).ThenBy(b => b.Value ?? double.PositiveInfinity).ToArray();
+ }
+
+ private static double GetRayAxisScalar(Point3D position, string direction)
+ {
+ return direction.EndsWith("x", StringComparison.OrdinalIgnoreCase)
+ ? position.X
+ : direction.EndsWith("y", StringComparison.OrdinalIgnoreCase)
+ ? position.Y
+ : position.Z;
+ }
+
+ private static CompactGrid BuildCompactGrid(IReadOnlyList<RayMapSample> samples, int cols, int rows, IReadOnlyList<DominantBand> bands, string direction)
+ {
+ var symbols = "0123456789";
+ var valueToSymbol = bands.Where(b => b.Value.HasValue)
+ .Select((b, index) => (Value: b.Value!.Value, Symbol: symbols[Math.Min(index, symbols.Length - 1)]))
+ .ToDictionary(x => x.Value, x => x.Symbol);
+ var byCell = samples.ToDictionary(s => (s.I, s.J));
+ var gridRows = new List<string>();
+ for (var j = rows - 1; j >= 0; j--)
+ {
+ var chars = new char[cols];
+ for (var i = 0; i < cols; i++)
+ {
+ if (!byCell.TryGetValue((i, j), out var sample) || !sample.Hit || sample.FirstHit is null)
+ {
+ chars[i] = '.';
+ continue;
+ }
+
+ if (sample.FirstHit.IntersectionMode == "tessellated-fallback")
+ {
+ chars[i] = '~';
+ continue;
+ }
+
+ if (sample.FirstHit.IntersectionMode == "unsupported")
+ {
+ chars[i] = '?';
+ continue;
+ }
+
+ var value = Math.Round(GetRayAxisScalar(sample.FirstHit.Position, direction), 4, MidpointRounding.AwayFromZero);
+ chars[i] = valueToSymbol.TryGetValue(value, out var symbol) ? symbol : '9';
+ }
+
+ gridRows.Add(new string(chars));
+ }
+
+ return new CompactGrid("height-band-ascii", cols, rows, new SortedDictionary<string, string>(StringComparer.Ordinal)
+ {
+ ["."] = "no-hit",
+ ["0"] = "most common rounded first-hit axis value",
+ ["1"] = "next most common rounded first-hit axis value",
+ ["2-9"] = "additional rounded first-hit axis value bands",
+ ["~"] = "tessellated-fallback or approximate first hit",
+ ["?"] = "unsupported or unknown first hit"
+ }, gridRows);
+ }
+
+ private static IReadOnlyList<string> BuildMeasuredSummary(string name, RayMapResult map, SixViewMapSummary summary)
+ {
+ var lines = new List<string>
+ {
+ $"{name} view: {summary.HitCoverage:P1} of samples hit the model."
+ };
+ var dominant = summary.DominantBands.FirstOrDefault(b => b.Value.HasValue);
+ if (dominant is not null)
+ {
+ lines.Add($"Dominant rounded first-hit axis value is {dominant.Value:0.####} across {dominant.Coverage:P1} of samples.");
+ }
+
+ var noHit = summary.DominantBands.FirstOrDefault(b => b.Meaning == "no-hit");
+ if (noHit is not null)
+ {
+ lines.Add($"{noHit.Coverage:P1} of samples are no-hit, indicating measured empty rays in this view.");
+ }
+
+ lines.Add(summary.FallbackRatio > 0d
+ ? $"{name} view includes tessellated fallback hits; fallback ratio is {summary.FallbackRatio:P1} of hit intersections."
+ : $"{name} view hit intersections are reported without tessellated fallback.");
+ return lines;
+ }
+
private static AnalyzeSummary BuildSummary(BrepBody body, ICollection<string> notes)
{
var topology = body.Topology;
diff --git a/docs/implementation/analyze-map-a3-cone-torus-analytic-hits.md b/docs/implementation/analyze-map-a3-cone-torus-analytic-hits.md
index d81b851f..b053f31b 100644
--- a/docs/implementation/analyze-map-a3-cone-torus-analytic-hits.md
+++ b/docs/implementation/analyze-map-a3-cone-torus-analytic-hits.md
@@ -81,3 +81,5 @@ testdata/step242/generated/ruled-a2/ellipse-linear-extrusion-production.step
- No volume integration behavior is changed.
- No linear-extrusion, surface-of-revolution, or B-spline analytic hits are added.
- No DisplayIR/frontend changes or new modeling features are included.
+
+Forward link: ANALYZE-MAP-A4 adds compact six-view LLM summaries; see `docs/implementation/analyze-map-a4-six-view-llm-summary.md`.
diff --git a/docs/implementation/analyze-map-a4-six-view-llm-summary.md b/docs/implementation/analyze-map-a4-six-view-llm-summary.md
new file mode 100644
index 00000000..819448e6
--- /dev/null
+++ b/docs/implementation/analyze-map-a4-six-view-llm-summary.md
@@ -0,0 +1,120 @@
+# ANALYZE-MAP-A4 Six-view LLM Summary
+
+ANALYZE-MAP-A4 adds a compact six-view summary mode to `aetheris analyze map` for LLM-oriented spatial inspection. The mode keeps detailed single-view ray sample JSON intact, but adds a smaller measured representation that can be scanned without machine vision.
+
+## Purpose
+
+Dense ray samples are useful for tools. Six-view summaries are useful when an LLM needs quick evidence for silhouette, empty rays, height/depth plateaus, curved versus planar hit families, and exact-versus-approximate backend provenance.
+
+The output reports measured ray-map patterns only. It does not reconstruct or name CAD features.
+
+## CLI
+
+```bash
+aetheris analyze map part.step --views six --resolution 32x32 --llm --json
+```
+
+`--summary` is accepted as an alias for `--llm` in this route:
+
+```bash
+aetheris analyze map part.step --views six --resolution 32x32 --summary --json
+```
+
+Existing detailed modes remain supported:
+
+```bash
+aetheris analyze map part.step --plane xy --direction -z --resolution 8x8 --json
+aetheris analyze map part.step --plane xy --point 0,0 --json
+aetheris analyze map part.step --top --rows 8 --cols 8 --json
+```
+
+## Six-view conventions
+
+The six-view route uses the same analytic-first ray backend as explicit `--plane/--direction` map probes:
+
+| View | Plane | Direction |
+| --- | --- | --- |
+| `top` | `xy` | `-z` |
+| `bottom` | `xy` | `+z` |
+| `right` | `yz` | `-x` |
+| `left` | `yz` | `+x` |
+| `back` | `xz` | `+y` |
+| `front` | `xz` | `-y` |
+
+These names match the legacy view flag conventions used by `--top`, `--bottom`, `--front`, `--back`, `--left`, and `--right`.
+
+## Output shape
+
+The top-level JSON uses:
+
+- `mode: "six-view-summary"`;
+- `mapVersion: "analyze-map-v1"`;
+- `resolution: [cols, rows]`;
+- `views`: one entry for each of the six named views;
+- `diagnostics`: de-duplicated view-prefixed diagnostics from the underlying map probes.
+
+Each view includes:
+
+- `name`, `plane`, and `direction`;
+- `summary`;
+- `compactGrid` when resolution is at most `64x64`;
+- `measuredSummary`, a short non-feature textual summary.
+
+## Summary fields
+
+Each view summary reports:
+
+- `sampleCount` and `hitCount`;
+- `hitCoverage`;
+- `heightRange`, using the underlying first-hit scalar range from the map backend;
+- `dominantBands`, produced by rounding first-hit axis values to four decimals and counting the most common values;
+- `surfaceFamiliesHit`, such as `plane`, `cylinder`, `sphere`, `cone`, `torus`, or fallback families like `linear-extrusion`;
+- `backendCounts` for `analytic`, `cir-evaluated`, `tessellated-fallback`, and `unsupported`;
+- `fallbackRatio`, computed from tessellated fallback hit intersections divided by hit intersections.
+
+A no-hit dominant band is represented with `value: null` and `meaning: "no-hit"`.
+
+## Compact grid
+
+For resolutions up to `64x64`, each view includes a deterministic ASCII grid:
+
+| Symbol | Meaning |
+| --- | --- |
+| `.` | no hit |
+| `0` | most common rounded first-hit axis value |
+| `1` | next most common rounded first-hit axis value |
+| `2-9` | additional rounded first-hit axis value bands |
+| `~` | tessellated-fallback or approximate first hit |
+| `?` | unsupported or unknown first hit |
+
+The grid is intended to show measured silhouette, gaps, and plateaus compactly. It is not an image rendering and does not use machine vision.
+
+## Backend provenance
+
+A4 preserves the A1/A2/A3 provenance model. Analytic plane, cylinder, sphere, cone, and torus hits remain exact where supported. Unsupported analytic families are surfaced through diagnostics and tessellated fallback counts rather than hidden behind the summary.
+
+## Examples
+
+### Box
+
+A box sampled with `--views six --resolution 8x8 --llm --json` should report six views, full hit coverage for all views, dominant planar bands, analytic backend counts, and compact grids filled by a single dominant band symbol.
+
+### Box with cylindrical through-hole
+
+A box with a through-hole should report measured no-hit rays and/or `cylinder` surface-family hits where the ray sampling crosses the opening. The summary should stay measured: it may indicate empty rays or cylinder hits, but should not assert a named feature unless a future feature recognizer provides that evidence.
+
+### Torus
+
+A simple torus should report `torus` in ring samples, analytic backend hits, no tessellated fallback for supported torus intersections, and compact-grid no-hit symbols where rays pass through empty center/open space according to the selected view.
+
+### RULED-A2 fallback
+
+For `testdata/step242/generated/ruled-a2/ellipse-linear-extrusion-production.step`, six-view summary succeeds and reports fallback evidence such as `linear-extrusion` diagnostics, `tessellated-fallback` backend counts, `~` compact-grid symbols where fallback supplies first hits, and non-zero fallback ratios for affected views.
+
+## Limitations
+
+- Dominant bands use simple four-decimal rounding, not advanced clustering.
+- Compact grids are omitted above `64x64` to keep output compact.
+- The route summarizes first-hit measurements; it does not replace detailed single-view sample JSON.
+- The route does not perform feature reconstruction, connected-component naming, rendering, or machine vision.
+- `analyze volume` policy is unchanged.