Docs
Introduction
What this is
brep-conformance is a test suite and a benchmark for exact B-rep kernels: the geometry engines under CAD tools, which build solids from exact curves and surfaces and compute on them.
It defines a set of functions a kernel offers, such as making a box, cutting one solid from another, rounding an edge or measuring a volume. It defines each function's result as a set of points, and it checks a kernel's answers against that definition. It scores every kernel the same way and publishes the results.
It is for people who build kernels, and for people who choose one.
How it works
- The suite draws cases. A case is a few calls: make two solids, combine them, measure the result. Each case belongs to a test, such as "booleans of crossing cylinders".
- An adapter passes each call to the kernel. An adapter is a small program that answers the suite's calls with the kernel's own functions. It adds no geometry of its own.
- The suite checks the answers. No expected value comes from a kernel. Volumes, areas and moments come from closed forms. Where there is none, the suite tests which points lie inside the exact solid itself and compares.
- Each case gets a result. A case passes at the tightest tolerance at which all its checks hold: 1e-7, 1e-6, 1e-5 or 1e-3 mm. Otherwise it fails, or the kernel refused it, does not support it, timed out or crashed.
A kernel's headline number is the share of all cases it passes at 1e-7 mm.
What it covers
| Area | Functions |
|---|---|
| Constructors | Boxes, cylinders, extrusions, revolutions, lofts and sweeps |
| Booleans | Union, intersection and difference, of two solids or many |
| Blends | Fillets and chamfers, of one size or several, and full rounds |
| Changing a solid | Offsets, shells, drafts, and moving, deleting and thickening faces |
| Exchange | Reading and writing STEP, and sewing loose faces |
| Queries | Volume, area, moments, distance, sections, meshes, rays and more |
It covers kernels that compute exact geometry. Mesh kernels are a different class of tool, and this suite does not test them.
Add your kernel
An adapter is one program that reads a call on a line of input and writes the reply on a line of output. Calling a kernel is the whole of what it must do.
- Run the example.
box_kernel.rsis a complete adapter for a kernel that makes boxes and nothing else, in about a hundred lines of Rust. From the repository's root:
cargo build --release --example box_kernel -p brep-protocol
cargo run --release -p brep-conformance -- --adapter target/release/examples/box_kernelThe summary says how many cases call only functions the adapter offers, and how many of those it passes: every one, for these boxes. The suite runs only those cases, and scores the rest unsupported.
- Put your kernel's calls in. Each method of the
Kerneltrait inbrep-protocolis one function of the API, and its body is your kernel's own call for it. An adapter in another language answers the same lines of JSON without the crate.
- Declare the rest unsupported.
unsupportedlists the functions your kernel has no one call for;helloreports the others, and the suite runs no case that needs a missing one. Never build a function out of others: the adapter rule says why. Refusals says what to answer for an input you cannot build.
- Run the suite, and read the report.
--html report.htmlwrites a page with every case, its checks and the shapes it drew.--familyruns one area of the suite while you work on it.
- Ask to be scored. An official run uses an adapter at a commit the suite's maintainers have reviewed against the adapter rule, listed in the registry. Open an issue with your adapter's repository; once it is reviewed, a pull request adds it.
Where to look
| To find | Read |
|---|---|
| What a function must return | API, by function |
| How a value is written | Types |
| How an answer is judged, and at what tolerance | The contract |
| What a results file holds | Result files |
| How a function enters the suite | Process |
API
This document defines the functions a B-rep kernel offers the suite, and says how a client calls them. Each function has a signature, a statement of what it requires, and a definition of the solid or value it returns, written as a set of points in our own words. A kernel is judged against these definitions alone, never against another kernel or an outside standard. contract.md says how results are checked.
Each group of functions opens with a table of its commands. The definitions follow the table.
Calling a kernel
A kernel takes part by shipping an adapter, a program that answers these calls with the kernel's own functions. The suite runs the adapter as one or more worker processes, so the client never links the kernel. This is version 1.0.0 of the protocol.
Lifecycle
- The client starts the worker from a command line, with stdin and stdout as pipes. The worker keeps its stderr for its own logs, and the client does not read it.
- The client's first request is
hello. The client compares the reply'sprotocolwith the version the client speaks. It stops when the two versions do not agree in the way Versions defines. - The client sends one request, waits for its reply, then sends the next. Each worker has one request in flight at a time, and replies come in request order.
- When stdin closes, the worker exits with status 0.
A client may run several workers at once, typically one per thread. Each worker holds its own solids, and a handle means something only to the worker that issued it.
Requests and replies
Every message is one JSON object on one line, encoded as UTF-8 and ended by a newline.
A request calls one function. It has the form {"cmd": name, …}, with each of the function's parameters as a field of the same name. A value is written in the format that the Format column of Types gives for its type: a Point3 is [x, y, z], a Frame is {"origin": …, "x": …, "y": …, "z": …}, and a Solid is its handle.
A reply is exactly one of:
| Reply | Meaning |
|---|---|
{"ok": value} | The call completed; value is what the function returns |
{"err": reason, "kind": k} | A refusal: the kernel declines with a reason; the worker carries on |
{"crash": message} | A crash: the kernel failed unexpectedly, and the worker recovered |
- Refusals. Refusals says when a function must refuse and how a refusal is scored.
- Crashes. A worker that writes no reply, or exits, has crashed. The client starts a fresh worker for its next request, and every handle of the old worker is gone.
- Time limit. Every call has a time limit, which is 120 s unless the run sets another with
--timeout. A worker that has not replied within the limit has timed out. The client kills that worker and starts a fresh one. - Handles. A
Solidtravels as a handle. A handle is a positive integer that the worker issues when a function returns a solid. The solid itself stays in the worker. - Repeated handles. A handle may appear more than once in one request.
union,intersectionanddifferencemay take the same handle asaandb, and the adapter then passes that solid to the kernel as both operands. The adapter never copies the solid to get round a kernel that refuses the same solid as both operands. Such a kernel refuses, and the case scores refused. - Numbers. A writer gives each double in a form that reads back exactly. NaN and infinities are not JSON numbers and never appear in a request.
- No answer. In a reply,
nullwhere a value belongs means there is no value.normalgivesnullat a crease, andcentroidgivesnullfor an empty solid. A function the kernel lacks is refused asunsupportedand is never answered withnull.
The session
Two commands are not functions of a kernel:
| Command | Fields | Returns |
|---|---|---|
hello | {name, version, tolerance, configuration, protocol, supports} | |
reset | null |
hellogives the kernel'snameandversion.toleranceis the linear tolerance declared for the kernel, in mm.configurationis a sentence on anything the adapter set differently from the kernel's defaults, and it is empty when the adapter set nothing differently.protocolis the protocol version the adapter speaks.supportslists the names of the functions the kernel offers, out of the functions of that protocol version. A case that needs a function thatsupportsleaves out is not run. A function added in a later version is not in the list of any older adapter, so an adapter is never taken to offer a function that was added after the adapter was written. contract.md says what tolerance an adapter sets and declares.resetreleases every solid. No handle issued before aresetis valid after it.
The session below makes a box and a cylinder, intersects them and measures the result. > marks a request and < marks its reply.
> {"cmd": "hello"}
< {"ok": {"name": "example-kernel", "version": "1.2.0", "tolerance": 1e-7,
"configuration": "", "protocol": "1.0.0",
"supports": ["box", "cylinder", "intersection", "volume", "check"]}}
> {"cmd": "box", "frame": {"origin": [0, 0, 0], "x": [1, 0, 0], "y": [0, 1, 0], "z": [0, 0, 1]},
"size": [10, 10, 10]}
< {"ok": 1}
> {"cmd": "cylinder", "frame": {"origin": [5, 5, -1], "x": [1, 0, 0], "y": [0, 1, 0],
"z": [0, 0, 1]}, "radius": 2, "height": 12}
< {"ok": 2}
> {"cmd": "intersection", "a": 1, "b": 2}
< {"ok": 3}
> {"cmd": "volume", "s": 3}
< {"ok": 125.66370614359172}
> {"cmd": "check", "s": 3}
< {"ok": []}Requests are wrapped here to fit the page. On the wire each request is one line.
Versions
A version is three numbers, major.minor.patch. Adding a function or field without changing what the existing ones mean raises the minor number. A correction to this text that changes no message raises the patch number. Any other change raises the major number.
A client and an adapter work together when their major versions agree. A client stops when an adapter's major version differs from the client's own.
An adapter ignores fields it does not know. A command it does not know is refused as unsupported.
Implementations
The crate brep-protocol is the Rust binding. It holds four things: the values as types; a Kernel trait with a method per function; serve, which answers the protocol with any implementation of the trait; and Remote, an implementation of the trait that forwards to workers. An adapter need not use the crate, because the protocol is lines of JSON, which a program in any language can answer.
Types
| Type | Format | Meaning |
|---|---|---|
Number | double | Unitless |
Length | double | mm |
Angle | double | rad |
Area | double | mm² |
Volume | double | mm³ |
Count | integer | A number of things |
Index | integer | A position in a list, from 0 |
Point2 | double[2] | [x, y], mm |
Point3 | double[3] | [x, y, z], mm |
Vector3 | double[3] | A direction [x, y, z]. Nonzero; any length unless stated |
Frame | {origin: Point3, x: Vector3, y: Vector3, z: Vector3} | Right-handed orthonormal axes at origin, z = x × y |
Placement | double[3][4] | The rigid motion p ↦ R·p + t, rows [R \| t], t in mm |
Loop | list<Segment> | Segments end to end, closed; or one spline |
Profile | list<Loop> | The outer loop, counter-clockwise, then holes, clockwise |
Path | list<PathPiece> | Runs and bends end to end, each leaving as the last arrived |
Spline3 | {degree: integer, knots: list<Number>, ctrl: list<Point3>} | A clamped B-spline curve in space |
Solid | integer | A handle, 1 or more, to a solid set the kernel holds |
A Segment is one of:
| Segment | Format | Meaning |
|---|---|---|
line | {line: Point2[2]} | The straight line from the first point to the second |
arc | {arc: {center: Point2, radius: Length, start: Angle, sweep: Angle}} | A circular arc from angle start through sweep |
conic | {conic: {a: Point2, apex: Point2, b: Point2, w: Number}} | A conic arc from a to b, defined below |
gn | {gn: {a: Point2, apex: Point2, b: Point2, order: integer, w: Number}} | A blend section from a to b, defined below |
spline | {spline: {degree: integer, knots: list<Number>, ctrl: list<Point2>}} | A periodic B-spline, the whole of its loop |
A PathPiece is one of:
| Piece | Format | Meaning |
|---|---|---|
line | {line: Length} | A straight run of that length |
arc | {arc: {radius: Length, angle: Angle}} | A bend of angle at radius |
A spline segment's ctrl lists the n points of one period, followed by the first degree of those points again. Its knots hold n + 2·degree + 1 values, which run degree values past each end of the period. One period is the parameter range knots[degree] ..= knots[n + degree].
A double is a finite IEEE 754 binary64 value, and an integer is a whole number from 0 to 2⁵³. 5 and 5.0 are the same value. A string is UTF-8 text. T[n] is exactly n values, T[n][m] is n rows of m values, and list<T> is any number of values. A value of the wrong format, such as a Point3 of two numbers, is a malformed request and not an input a kernel refuses.
A matrix is a list of its rows, and each row is a list of numbers. The matrix multiplies a point written as a column: p ↦ M·p + t. A Number[3][4] holds [M | t]. Each row holds three numbers of M and then that row's part of t:
[[m11, m12, m13, tx], x' = m11·x + m12·y + m13·z + tx
[m21, m22, m23, ty], y' = m21·x + m22·y + m23·z + ty
[m31, m32, m33, tz]] z' = m31·x + m32·y + m33·z + tzA solid set is a bounded set of points that is equal to the closure of its interior. It may be empty, or it may be several separate pieces. Pieces may touch at points or along curves, but they never share an area of boundary, because sharing an area would make them one.
A frame's local coordinates (u, v, w) name the point o + u·x + v·y + w·z. Every constructor below defines its solid in local coordinates, and the constructor's frame places the solid.
A conic arc runs from a to b. At a and at b it is tangent to the line from that point to the arc's corner, apex. The arc is the rational quadratic (t̄²a + 2w·t·t̄·apex + t²b) / (t̄² + 2w·t·t̄ + t²), where t̄ = 1 − t, over t from 0 to 1. Its shoulder is the point at t = ½. The shoulder lies rho = w/(1 + w) of the way from the chord's middle to the corner. The conic is an ellipse for w < 1, a parabola when w is 1 and a hyperbola when w is above 1. A circular arc turning θ is the conic arc with w = cos(θ/2).
A blend section of order n and thumbweight w runs from a to b between its two legs, which are the lines from apex to a and from apex to b. The section is the curve apex + α(t)(a − apex) + β(t)(b − apex), with α = f·(1 − p₁), β = (1 − f)·p₂, f = t̄ⁿ⁺¹/(t̄ⁿ⁺¹ + tⁿ⁺¹), p₁ = t/(1 − w + wt) and p₂ = t(1 − w)/(1 − wt). The section meets each leg with contact of order n. At n = 2 the section starts as straight as the leg, so the section is curvature-continuous with the leg. Its equal-area thumbweight is the w at which the section removes from the triangle on its legs the same area that the circle tangent to both legs at a and b removes. "Thumbweight" is the name this shape parameter has in parametric Gⁿ blending (E. Hartmann, "Parametric Gⁿ blending of curves and surfaces", The Visual Computer 17, 2001, pp. 1–13).
A profile's region Ω is the set of points about which the winding numbers of the profile's loops sum to a nonzero value, together with the boundary of that set. No loop may cross another loop or itself. A is the area of Ω, M is the first moment ∫∫ u dA of Ω, and L is the length of the boundary of Ω.
Every function may refuse. To refuse is to decline with a reason instead of returning a result, for input that the function does not support or cannot build correctly. A function never returns a result it knows to be wrong.
Constructors
| Function | Fields | Returns |
|---|---|---|
box | frame, size | Solid |
cylinder | frame, radius, height | Solid |
sphere | frame, radius | Solid |
torus | frame, major, minor | Solid |
cone | frame, bottom, top, height | Solid |
extrude | frame, profile, height | Solid |
revolve | frame, profile, angle | Solid |
screw | frame, profile, rise, angle | Solid |
loft | frame, profile, scale, height, top | Solid |
loft_through | frame, profiles, heights | Solid |
sweep | frame, profile, path | Solid |
sweep_path | frame, profile, path, twist | Solid |
slab | frame, size, knots_u, knots_v, heights | Solid |
box
box(frame: Frame, size: Length[3]) -> Solid
Makes a rectangular block with one corner at the frame's origin and its edges along the frame's axes, not centred on the origin.
Each of size = (a, b, c) must be positive. The result is the set of points where 0 ≤ u ≤ a, 0 ≤ v ≤ b and 0 ≤ w ≤ c.
{
"cmd": "box",
"frame": {
"origin": [0, 0, 0],
"x": [1, 0, 0],
"y": [0, 1, 0],
"z": [0, 0, 1]
},
"size": [10, 20, 30]
}{"ok": 1}cylinder
cylinder(frame: Frame, radius: Length, height: Length) -> Solid
Makes a round bar standing on the frame's xy plane. Its axis runs up z from the origin.
radius and height must both be positive. The result is the set of points where u² + v² ≤ radius² and 0 ≤ w ≤ height.
{
"cmd": "cylinder",
"frame": {
"origin": [0, 0, 0],
"x": [1, 0, 0],
"y": [0, 1, 0],
"z": [0, 0, 1]
},
"radius": 5,
"height": 20
}{"ok": 1}sphere
sphere(frame: Frame, radius: Length) -> Solid
Makes a ball centred on the frame's origin.
radius must be positive. The result is the set of points where u² + v² + w² ≤ radius².
{
"cmd": "sphere",
"frame": {
"origin": [0, 0, 0],
"x": [1, 0, 0],
"y": [0, 1, 0],
"z": [0, 0, 1]
},
"radius": 5
}{"ok": 1}torus
torus(frame: Frame, major: Length, minor: Length) -> Solid
Makes a ring lying round the frame's z axis: a tube of radius minor whose centre runs round a circle of radius major in the xy plane.
major > minor > 0 must hold. The result is the set of points where (√(u² + v²) − major)² + w² ≤ minor².
{
"cmd": "torus",
"frame": {
"origin": [0, 0, 0],
"x": [1, 0, 0],
"y": [0, 1, 0],
"z": [0, 0, 1]
},
"major": 10,
"minor": 2
}{"ok": 1}cone
cone(frame: Frame, bottom: Length, top: Length, height: Length) -> Solid
Makes a cone or truncated cone that stands on the frame's xy plane round the frame's z axis. Its radius goes from bottom at the origin to top at height.
height must be positive. bottom and top must each be at least zero, and must not both be zero. A zero radius is an apex. The result is the set of points where √(u² + v²) ≤ bottom + (top − bottom)·w/height and 0 ≤ w ≤ height.
{
"cmd": "cone",
"frame": {
"origin": [0, 0, 0],
"x": [1, 0, 0],
"y": [0, 1, 0],
"z": [0, 0, 1]
},
"bottom": 5,
"top": 2,
"height": 10
}{"ok": 1}extrude
extrude(frame: Frame, profile: Profile, height: Length) -> Solid
Pushes a flat profile straight out of its plane, like a part cut from plate. The profile lies in the frame's xy plane and is swept height along z.
height must be positive. The result is the set of points where (u, v) ∈ Ω and 0 ≤ w ≤ height: the profile drawn in the frame's xy plane, moved along z. The result's volume is A·height and its area is 2A + L·height.
{
"cmd": "extrude",
"frame": {
"origin": [0, 0, 0],
"x": [1, 0, 0],
"y": [0, 1, 0],
"z": [0, 0, 1]
},
"profile": [
[
{"line": [[0, 0], [10, 0]]},
{"line": [[10, 0], [10, 10]]},
{"line": [[10, 10], [0, 10]]},
{"line": [[0, 10], [0, 0]]}
]
],
"height": 5
}{"ok": 1}revolve
revolve(frame: Frame, profile: Profile, angle: Angle) -> Solid
Spins a profile about an axis, as on a lathe. The profile lies beside the frame's z axis and is turned about that axis by angle. A whole turn makes a closed body of revolution.
The profile is drawn in the plane of the frame's x and z, with its first coordinate measured out from the z axis and its second coordinate measured along the z axis. Ω must lie in the half-plane where the first coordinate is at least zero, and 0 < angle ≤ 2π must hold. The result is the set of points (ρ cos φ, ρ sin φ, w) for (ρ, w) ∈ Ω and 0 ≤ φ ≤ angle: the profile turned right-handed about z. The result's volume is M·angle (Pappus). Its area is angle·∮ u ds, plus 2A for the end faces when angle < 2π.
{
"cmd": "revolve",
"frame": {
"origin": [0, 0, 0],
"x": [1, 0, 0],
"y": [0, 1, 0],
"z": [0, 0, 1]
},
"profile": [
[
{"line": [[5, 0], [8, 0]]},
{"line": [[8, 0], [8, 4]]},
{"line": [[8, 4], [5, 4]]},
{"line": [[5, 4], [5, 0]]}
]
],
"angle": 6.283185307
}{"ok": 1}screw
screw(frame: Frame, profile: Profile, rise: Length, angle: Angle) -> Solid
Spins a profile about an axis while moving the profile along the axis, as a thread is formed. Each whole turn rises 2π·rise.
The profile is drawn as for revolve. Ω must lie where the first coordinate is at least zero, and angle must be positive. The turns must stay apart: 2π·|rise| must be at least the profile's extent along z. The result is the set of points (ρ cos φ, ρ sin φ, w + rise·φ) for (ρ, w) ∈ Ω and 0 ≤ φ ≤ angle: the profile turned about z while rising rise per radian, as a thread. The result's volume is M·angle, because the rise moves each section within its own plane. Its area is angle·∮ √(u² + rise²·(du/ds)²) ds + 2A.
{
"cmd": "screw",
"frame": {
"origin": [0, 0, 0],
"x": [1, 0, 0],
"y": [0, 1, 0],
"z": [0, 0, 1]
},
"profile": [
[
{"line": [[5, 0], [6, 0]]},
{"line": [[6, 0], [6, 1]]},
{"line": [[6, 1], [5, 1]]},
{"line": [[5, 1], [5, 0]]}
]
],
"rise": 0.5,
"angle": 12.566370614
}{"ok": 1}loft
loft(frame: Frame, profile: Profile, scale: Number, height: Length, top: Profile) -> Solid
Joins a profile by straight lines to a scaled copy of the profile above it, like a tapered post. A scale of 1 gives an extrusion, and a smaller scale narrows the solid toward the top.
top is profile scaled by scale about the origin. The client sends top, so that an adapter whose kernel lofts between two sections passes both profiles on and scales nothing itself.
The profile must have one loop, and scale and height must be positive. The result is the set of points (σu, σv, w) for (u, v) ∈ Ω and 0 ≤ w ≤ height, with σ = 1 + (scale − 1)·w/height. The result is ruled from the profile in the xy plane to the profile's copy scaled about the origin, height up z. The result's volume is A·height·(1 + s + s²)/3 with s = scale, and its area is A·(1 + s²) + (1 + s)/2 · ∮ ‖(height·q′, (s − 1)·q × q′)‖ round the profile q.
{
"cmd": "loft",
"frame": {
"origin": [0, 0, 0],
"x": [1, 0, 0],
"y": [0, 1, 0],
"z": [0, 0, 1]
},
"profile": [
[
{"line": [[-5, -5], [5, -5]]},
{"line": [[5, -5], [5, 5]]},
{"line": [[5, 5], [-5, 5]]},
{"line": [[-5, 5], [-5, -5]]}
]
],
"scale": 0.5,
"height": 10,
"top": [
[
{"line": [[-2.5, -2.5], [2.5, -2.5]]},
{"line": [[2.5, -2.5], [2.5, 2.5]]},
{"line": [[2.5, 2.5], [-2.5, 2.5]]},
{"line": [[-2.5, 2.5], [-2.5, -2.5]]}
]
]
}{"ok": 1}loft_through
loft_through(frame: Frame, profiles: list<Profile>, heights: list<Length>) -> Solid
Makes the smooth solid through two or more sections. Section k is profile k drawn in the frame's xy plane and moved heights[k] up the frame's z, and the heights rise. The solid's section at each of those heights is that profile, the solid's ends are the first and last profiles, and its side passes smoothly from one section to the next. How the side runs between sections is open: tools interpolate differently, and no tool's interpolation is the answer.
There must be two or more profiles and one height for each profile, and every height must be above the one before. Each profile is one loop; sections with holes are not yet specified.
A section means the profile's region, not the way the profile's loop is written. The result does not depend on which segment a loop starts with, nor on how a curve is cut into segments, so the side has no twist that the regions do not ask for. When every section is the same profile, the result is that profile's extrusion from the first height to the last, wherever each loop starts.
Smoothly means that the side has a tangent plane at every point between the first section and the last, including the points at the heights of the inner sections. The side has no crease along a section and no crease across one.
which kernels offer it{
"cmd": "loft_through",
"frame": {
"origin": [0, 0, 0],
"x": [1, 0, 0],
"y": [0, 1, 0],
"z": [0, 0, 1]
},
"profiles": [
[
[
{"line": [[-5, -5], [5, -5]]},
{"line": [[5, -5], [5, 5]]},
{"line": [[5, 5], [-5, 5]]},
{"line": [[-5, 5], [-5, -5]]}
]
],
[
[
{"line": [[-3, -3], [3, -3]]},
{"line": [[3, -3], [3, 3]]},
{"line": [[3, 3], [-3, 3]]},
{"line": [[-3, 3], [-3, -3]]}
]
]
],
"heights": [0, 10]
}{"ok": 1}sweep
sweep(frame: Frame, profile: Profile, path: Path) -> Solid
Carries a profile along a path of straight runs and bends, like a pipe or a bent bar.
The path starts at the frame's origin heading along z, with the profile in the xy plane square to it. A line runs straight on by length. An arc bends toward the current x by angle, about an axis that lies along the current y at a distance radius from the path, and the arc turns the frame with it. The result is the union of the pieces: each line gives the extrusion of the profile along the line, and each arc gives the revolution of the profile about the arc's axis. Every profile point must be closer to the path than any bend's radius, and all lengths, radii and angles must be positive. The result's volume, area and moments are those of its pieces added together, less the end caps that meet inside the result.
{
"cmd": "sweep",
"frame": {
"origin": [0, 0, 0],
"x": [1, 0, 0],
"y": [0, 1, 0],
"z": [0, 0, 1]
},
"profile": [
[
{"line": [[-1, -1], [1, -1]]},
{"line": [[1, -1], [1, 1]]},
{"line": [[1, 1], [-1, 1]]},
{"line": [[-1, 1], [-1, -1]]}
]
],
"path": [
{"line": 10},
{"arc": {"radius": 5, "angle": 1.570796327}},
{"line": 10}
]
}{"ok": 1}sweep_path
sweep_path(frame: Frame, profile: Profile, path: Spline3, twist: Angle) -> Solid
Carries a profile along a smooth space curve, like a bent pipe or a twisted rib.
path is a clamped B-spline in the frame's coordinates, given by its degree, knots and control points. The path starts at the origin heading along z, with the profile in the xy plane square to it. twist may be any angle, either way round. The profile's plane stays square to the path. The profile's axes follow the path's rotation-minimizing frame, which never turns about the tangent. The axes also turn by twist more by the end of the path, evenly in arc length. Every profile point must be closer to the path than the path's least radius of curvature, and the sweep must never meet itself.
Let T be the tangent, and let K₁, K₂ be the curvature along the profile's turned axes. A profile point (X, Y) then sweeps a volume element (1 − K₁X − K₂Y) dA ds. The volume and moments are therefore integrals along the path of the profile's moments up to the third. The side's element is √(a²|b′|² + φ′²(b·b′)²) along the boundary b, where a = 1 − K₁X − K₂Y and φ′ is the twist per length. A profile centred on the path gives volume A·ℓ (Pappus), where ℓ is the path's length. If that profile is also untwisted, the side is L·ℓ.
{
"cmd": "sweep_path",
"frame": {
"origin": [0, 0, 0],
"x": [1, 0, 0],
"y": [0, 1, 0],
"z": [0, 0, 1]
},
"profile": [
[
{"line": [[-1, -1], [1, -1]]},
{"line": [[1, -1], [1, 1]]},
{"line": [[1, 1], [-1, 1]]},
{"line": [[-1, 1], [-1, -1]]}
]
],
"path": {
"degree": 3,
"knots": [0, 0, 0, 0, 1, 1, 1, 1],
"ctrl": [
[0, 0, 0], [0, 0, 5], [3, 0, 10], [8, 0, 12]
]
},
"twist": 0
}{"ok": 1}slab
slab(frame: Frame, size: Length[2], knots_u, knots_v: list<Number>, heights: list<list<Length>>) -> Solid
Makes a block with a freeform top. The block is flat underneath and on its four sides, and its top is a smooth surface.
The result is the set of points over the rectangle 0 ≤ u ≤ size[0], 0 ≤ v ≤ size[1] from w = 0 up to the height field w = f(u/size[0], v/size[1]). f is the bicubic B-spline over [0, 1]² with clamped knots knots_u, knots_v (each running four times 0 first and four times 1 last) and coefficients heights[i][j]. Every height must be positive, which keeps f positive. As a surface, the top is the B-spline whose control points sit at the knots' Greville abscissae times the size, so the top's x and y run linearly with its parameters. The result's volume and moments are integrals of polynomials in f, and its area is the integral of √(1 + (f_u/size[0])² + (f_v/size[1])²).
{
"cmd": "slab",
"frame": {
"origin": [0, 0, 0],
"x": [1, 0, 0],
"y": [0, 1, 0],
"z": [0, 0, 1]
},
"size": [10, 10],
"knots_u": [0, 0, 0, 1, 1, 1],
"knots_v": [0, 0, 0, 1, 1, 1],
"heights": [[5, 5, 5], [5, 7, 5], [5, 5, 5]]
}{"ok": 1}Booleans
Every boolean returns the regularized set operation, which is the closure of the interior of the set result. The result may be empty. It may also be several pieces, touching as Types allows. Pieces that share an area of boundary are returned as one. The operands are left as they were.
| Function | Fields | Returns |
|---|---|---|
union | a, b | Solid |
intersection | a, b | Solid |
difference | a, b | Solid |
union_all | solids | Solid |
difference_all | target, tools | Solid |
union
union(a: Solid, b: Solid) -> Solid
Joins two solids. Returns the regularized a ∪ b, where a ∪ b is what either solid holds.
{"cmd": "union", "a": 1, "b": 2}{"ok": 3}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin. Solid 2 is a cylinder of radius 5 and height 20 on the z axis.
intersection
intersection(a: Solid, b: Solid) -> Solid
Keeps what two solids share. Returns the regularized a ∩ b, where a ∩ b is what both solids hold.
{"cmd": "intersection", "a": 1, "b": 2}{"ok": 3}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin. Solid 2 is a cylinder of radius 5 and height 20 on the z axis.
difference
difference(a: Solid, b: Solid) -> Solid
Cuts one solid from another. Returns the regularized a ∖ b, where a ∖ b is what a holds and b does not.
{"cmd": "difference", "a": 1, "b": 2}{"ok": 3}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin. Solid 2 is a cylinder of radius 5 and height 20 on the z axis.
union_all
union_all(solids: list<Solid>) -> Solid
Joins two or more solids in one call. solids must list at least two solids. Returns their regularized union, which is the same as the result of union applied to the solids one at a time, in any order. A pattern is a union_all over copies of a solid moved by transform.
{"cmd": "union_all", "solids": [1, 2, 3]}{"ok": 4}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin. Solid 2 is a cylinder of radius 5 and height 20 on the z axis. Solid 3 is a ball 30 mm away.
difference_all
difference_all(target: Solid, tools: list<Solid>) -> Solid
Cuts one or more tools from target in one call. tools must list at least one tool. Returns the regularized difference, which is the same as the result of difference applied to target one tool at a time, in any order.
{
"cmd": "difference_all",
"target": 1,
"tools": [2, 3]
}{"ok": 4}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin. Solid 2 is a cylinder of radius 5 and height 20 on the z axis. Solid 3 is a ball 30 mm away.
Blends
An edge is named by a point on it. Each point names the edge of s that passes within 10·ε of the point, where ε is the suite's tolerance of 1e-7 mm. A call with a point that names no edge refuses. Naming an edge by a point does not depend on how any kernel numbers or labels its topology, and a test can compute such a point from the solid's definition.
A blend runs along the whole tangent chain of its edge. The chain is the named edge and every edge reached from it through vertices where the next edge leaves in the direction in which the last edge arrived. The top loop of a prism on a rounded rectangle is one chain, so a point on any edge of that loop blends the whole loop. Following the chain is the work of the function, and so of the kernel. An adapter passes on the edge the point names and no other edge.
| Function | Fields | Returns |
|---|---|---|
fillet | s, edges, radius | Solid |
fillet_radii | s, edges, radii | Solid |
fillet_variable | s, edge, from, r_from, r_to | Solid |
fillet_conic | s, edges, setback, rho | Solid |
fillet_g2 | s, edges, offset, center | Solid |
fillet_setback | s, edges, radius, setback | Solid |
fillet_setback_g2 | s, edges, radius, setback | Solid |
fillet_faces | s, face_a, face_b, radius | Solid |
full_round | s, side_a, middle, side_b | Solid |
chamfer | s, edges, distance | Solid |
chamfer_two | s, edge, face, d1, d2 | Solid |
chamfer_distances | s, edges, distances | Solid |
fillet
fillet(s: Solid, edges: list<Point3>, radius: Length) -> Solid
Rounds edges. Each named edge is replaced by the surface that a ball of radius sweeps as the ball rolls along the edge, touching both faces that meet there.
edges must name one edge or more, radius must be positive, and the ball must fit. The ball fits when its contact with each face stays on that face, except where the fillet swallows a face as described below. At a convex edge, the result is s less the material between the ball's sweep and the edge. At a concave edge, the result is s with the space between the ball's sweep and the edge filled. Where the two faces are planes, or surfaces of revolution meeting round a circle, the section across the edge is the circle of radius tangent to both faces' traces. s is left as it was.
A fillet swallows a face too narrow for its ball. Take a narrow face N between two faces A and B, with both of N's edges named: the edge N shares with A and the edge N shares with B. A small enough ball rolls along each edge in turn, touching A and N along the first edge and N and B along the second, and leaves a strip of N between two fillets. A ball too big for that cannot touch N at all. Resting against A and B at once, the ball bridges over N. The ball then rolls touching A and B alone, and makes one fillet from A to B. For this, A and B are each continued past the edge shared with N, as if N were not there. N lies wholly in the material the ball's sweep removes, so none of N is left. The result is the same as the result of fillet on the solid in which A and B run on to meet in a single edge, with that edge named. For example, a corner chamfered by a hair, with both edges of the chamfer filleted, gives the same result as the sharp corner filleted.
Where named convex edges meet at a corner, the corner is what the balls touching the edges' faces leave. Filleting every edge of a convex solid, or every convex edge of a prism whose concave edges all run along its axis, gives the union of the balls of radius inside s. A box with all twelve edges filleted by r is the box made r smaller on every side and then swelled by r. Other corners are not yet specified. Whatever closes such a corner, a fillet leaves no crease. Where the boundary of the result is not the boundary of s, the boundary of the result has a tangent plane, and shares that tangent plane with each face it meets. A fillet changes nothing farther than twice the radius from the named edges. Where a motion leaves s and the named edges as they were round a blend, the motion also leaves the result as it was there, within a thousandth of the radius.
{
"cmd": "fillet",
"s": 1,
"edges": [[0, 0, 15]],
"radius": 2
}{"ok": 2}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin. The point names its vertical edge at the origin.
fillet_radii
fillet_radii(s: Solid, edges: list<Point3>, radii: list<Length>) -> Solid
Rounds edges as fillet does, in one operation, with each point's chain at its own radius, so that fillets of unequal radii meet at shared corners. radii must give one radius for each point, and each radius must be as fillet requires. Away from those corners, each edge is as fillet makes it at that edge's radius. The corner itself is open within limits. The result lies, point for point, between the solid filleted at the largest of the corner's radii and the solid filleted at the smallest: the result holds every point of the first solid and no point outside the second. The surface of the result is closed and has no crease: the corner joins every fillet and face it meets with their tangent planes. The pieces, tunnels and voids of the result are those of s.
{
"cmd": "fillet_radii",
"s": 1,
"edges": [[0, 0, 15], [10, 0, 15]],
"radii": [1, 2]
}{"ok": 2}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
fillet_variable
fillet_variable(s: Solid, edge: Point3, from: Point3, r_from: Length, r_to: Length) -> Solid
Rounds one edge as fillet does, but by a ball whose radius changes evenly with length along the edge, from r_from at the end nearest from to r_to at the other end. Both radii must be positive, the ball must fit all along the edge, and from must be nearer one end of the edge than the other. The ball touches each face along the line where the foot of the ball's centre falls, and the blend meets each face there tangentially. The surface of the blend between those two lines is open within limits. The blend has no crease. A ball reaches no farther along the edge than its radius. So at each point along the edge, the result lies between the edge filleted at the least radius and the edge filleted at the greatest radius that the ball has within a distance of the larger of r_from and r_to from that point.
{
"cmd": "fillet_variable",
"s": 1,
"edge": [0, 0, 15],
"from": [0, 0, 0],
"r_from": 1,
"r_to": 2
}{"ok": 2}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
fillet_conic
fillet_conic(s: Solid, edges: list<Point3>, setback: Length, rho: Number) -> Solid
Rounds edges by a conic instead of a circle. Each named edge is replaced by a blend that meets both faces setback back from the edge and is tangent to them there. Between planes, the section of the blend across the edge is the conic arc from one contact to the other, with its corner on the edge and shoulder rho. rho = 0.5 gives a parabola. At a square edge, rho = √2 − 1 gives a quarter circle.
setback must be positive, both contacts must be on their faces, and rho must satisfy 0 < rho < 1.
{
"cmd": "fillet_conic",
"s": 1,
"edges": [[0, 0, 15]],
"setback": 2,
"rho": 0.5
}{"ok": 2}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
fillet_g2
fillet_g2(s: Solid, edges: list<Point3>, offset: Length, center: Length) -> Solid
Rounds edges by a curvature-continuous blend sized by two lengths. The first is its tangent offset, the radius of the ball whose contacts the blend shares: the blend meets each face where a ball of offset rolling along the edge touches that face. The second is its center radius, the blend's radius of curvature at its middle. Between planes, the section of the blend across the edge is the blend section of order 2 between the two contacts, with its apex on the edge, at the thumbweight that gives the middle of the section the center radius. The blend shares each face's tangent plane and the face's curvature too, so the blend starts as straight as the face. A circular fillet bends at once by 1/offset, and so fails to share the face's curvature. The section at the equal-area thumbweight takes off what the ball's round takes off. At a square edge, the center radius of that section is about 1.389 times the offset.
Both lengths must be positive, a ball of offset must fit as fillet requires, and center must be a radius that the section takes at some thumbweight between 0 and 1.
{
"cmd": "fillet_g2",
"s": 1,
"edges": [[0, 0, 15]],
"offset": 2,
"center": 1.5
}{"ok": 2}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
fillet_setback
fillet_setback(s: Solid, edges: list<Point3>, radius: Length, setback: Length) -> Solid
Rounds edges as fillet of radius does, except at every corner where three named edges meet. There, each fillet stops setback short of the corner, and one smooth patch closes the corner. The patch meets the three fillets and the three faces tangentially. setback must be greater than radius. Farther than setback from such a corner, each edge is as fillet makes it.
The patch is open within limits. The result lies, point for point, between two solids: s filleted with the corner's cube of side setback taken away, and s filleted with the corner left sharp. Neither of those two solids is itself a result, because the patch leaves no crease. On each face, the flat stops short of the point where the contact lines of the face's two fillets would cross. The rolling-ball corner reaches that point. A square corner whose three edges are filleted and set back alike is closed alike on all three edges: the result is unchanged by any swap of the three edges, within a thousandth of the radius.
{
"cmd": "fillet_setback",
"s": 1,
"edges": [[5, 0, 0], [0, 10, 0], [0, 0, 15]],
"radius": 1,
"setback": 2
}{"ok": 2}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin. The three edges meet at the origin.
fillet_setback_g2
fillet_setback_g2(s: Solid, edges: list<Point3>, radius: Length, setback: Length) -> Solid
Rounds edges as fillet_setback does, and requires what fillet_setback requires, but with the fillets and the patch curvature-continuous throughout. Each fillet is the fillet_g2 blend of tangent offset radius at the equal-area thumbweight, so the fillet meets its faces with their curvature and takes off what the round of radius does. Each fillet holds that section until setback from the corner. The patch meets the three fillets and the three faces with their curvature as well as their tangent planes. Where fillet i ends, on its section square to its edge setback from the corner, the boundary bends by the section's center radius round the edge and not along it, on both sides of the seam. Across the whole corner, which is its faces, fillets and patch, the boundary's curvature changes without a jump. Circular fillets cannot be closed this way. They meet their faces with a jump in curvature, and no patch matches both the fillet and the face where a fillet's end section meets a face.
{
"cmd": "fillet_setback_g2",
"s": 1,
"edges": [[5, 0, 0], [0, 10, 0], [0, 0, 15]],
"radius": 1,
"setback": 2
}{"ok": 2}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
fillet_faces
fillet_faces(s: Solid, face_a: Point3, face_b: Point3, radius: Length) -> Solid
Rounds between two faces that need not share an edge. A ball of radius rolls touching the face that each point names. What lies outside the ball's path between the two contacts is removed, including any faces between the contacts. A chamfer narrower than the round is consumed: two planes that meet at a chamfered edge give the sharp edge filleted by radius. radius must be positive, the two points must name different faces, and the ball must fit between the two faces.
{
"cmd": "fillet_faces",
"s": 1,
"face_a": [5, 10, 0],
"face_b": [0, 10, 15],
"radius": 2
}{"ok": 2}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
full_round
full_round(s: Solid, side_a: Point3, middle: Point3, side_b: Point3) -> Solid
Replaces the face that middle names by a round. The round is tangent to that face and to the faces that side_a and side_b name, and those two side faces stay where they are. A rib between parallel sides w apart gets a half cylinder of radius w/2. A rib between sides that close toward the middle face gets the arc of the circle touching all three faces.
The three points must name three different faces, and the face that middle names must share an edge with each of the other two.
{
"cmd": "full_round",
"s": 1,
"side_a": [0, 10, 15],
"middle": [5, 0, 15],
"side_b": [10, 10, 15]
}{"ok": 2}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
chamfer
chamfer(s: Solid, edges: list<Point3>, distance: Length) -> Solid
Bevels edges. Each named edge is cut by the surface through the two lines that lie distance back from the edge, one along each face.
edges must name one edge or more, distance must be positive, and each cut must stay on its faces. Where the faces are planes, the cut is the plane through those two lines. About a circular edge of a solid of revolution, the cut is the cone through the two circles. Corners where chamfered edges meet are not yet specified. s is left as it was.
{
"cmd": "chamfer",
"s": 1,
"edges": [[0, 0, 15]],
"distance": 2
}{"ok": 2}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
chamfer_two
chamfer_two(s: Solid, edge: Point3, face: Point3, d1: Length, d2: Length) -> Solid
Bevels one edge unevenly. The cut runs through two lines: the line d1 back from the edge along the face that face names, and the line d2 back from the edge along the other face that meets there. Between planes, the section the cut takes off is the triangle on those two lines. A chamfer given by a distance and an angle from the named face is a chamfer_two with d2 = d1·tan(angle).
Both distances must be positive, each cut must be on its face, and face must name one of the two faces that meet at the edge.
{
"cmd": "chamfer_two",
"s": 1,
"edge": [0, 0, 15],
"face": [0, 10, 15],
"d1": 1,
"d2": 2
}{"ok": 2}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
chamfer_distances
chamfer_distances(s: Solid, edges: list<Point3>, distances: list<Length>) -> Solid
Bevels edges as chamfer does, in one operation, with each point's chain at its own distance, so that chamfers of unequal distances meet at shared corners. distances must give one distance for each point, and each distance must be as chamfer requires. Away from those corners, each edge is as chamfer cuts it at that edge's distance. The corner is open within limits. The result lies, point for point, within the solid chamfered at the smallest of the corner's distances. The volume of the result is no less than the volume of the solid chamfered at the largest of the corner's distances. The result holds every point of that second solid farther than the largest distance from the corner along any edge. Nearer the corner, the three chamfers' planes meet at a point, and a result may run out to that point or be cut flat across short of it.
{
"cmd": "chamfer_distances",
"s": 1,
"edges": [[0, 0, 15], [10, 0, 15]],
"distances": [1, 2]
}{"ok": 2}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
Changing a solid
A face is named in the same way as an edge: each point names the face of s that the point lies on, within 10·ε.
| Function | Fields | Returns |
|---|---|---|
offset | s, distance | Solid |
offset_faces | s, faces, distance | Solid |
delete_faces | s, faces | Solid |
move_faces | s, faces, matrix | Solid |
thicken | s, faces, thickness | Solid |
shell | s, open, thickness | Solid |
draft | s, faces, origin, pull, angle | Solid |
offset
offset(s: Solid, distance: Length) -> Solid
Grows the solid by a constant distance all round, rounding its convex edges and corners.
distance must be positive. The result is the set of points within distance of s. For a convex solid, the volume of the result is given by Steiner's formula V + S·d + M·d² + (4π/3)·d³, where M is the integral of mean curvature over the boundary of s.
{"cmd": "offset", "s": 1, "distance": 1}{"ok": 2}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
offset_faces
offset_faces(s: Solid, faces: list<Point3>, distance: Length) -> Solid
Pushes or pulls faces, as a direct edit. Each named face moves distance along its outward normal onto its offset surface: a plane is moved, and a cylinder's radius is changed. The faces round the named face are extended or trimmed to meet it. A negative distance pulls the face in.
Where a moved face comes to lie on another face's plane, the two faces merge into one face, and a face between them that shrinks to nothing is removed. A step pushed level becomes one top, and a slot's wall pushed across to the other wall closes the slot. faces must name one face or more, distance must not be zero, and no face may pass beyond the face it meets.
{
"cmd": "offset_faces",
"s": 1,
"faces": [[5, 10, 30]],
"distance": 2
}{"ok": 2}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin. The point names its top face.
delete_faces
delete_faces(s: Solid, faces: list<Point3>) -> Solid
Takes the faces that the points lie on out of the solid, and closes the gap by extending or trimming the faces round them, as defeaturing does. Taking out a hole's face leaves the plate whole. Taking out a notch's or groove's faces leaves the block or shaft that the notch or groove was cut from. Taking out a chamfer restores the corner. The faces round the gap must be able to close the gap.
which kernels offer it{
"cmd": "delete_faces",
"s": 2,
"faces": [[1, 1, 15]]
}{"ok": 3}Solid 2 is the box with one edge chamfered. The point names the chamfer's face.
move_faces
move_faces(s: Solid, faces: list<Point3>, matrix: Placement) -> Solid
Moves the faces that the points lie on rigidly by p ↦ R·p + t. The rows of matrix are [R | t], where R is a rotation. The faces round the moved faces are extended or trimmed to meet them, as a direct edit. Moving a hole's face across a plate moves the hole. Moving a notch's faces along a side moves the notch. Turning a side about its bottom edge leans the side. A plane moved along itself is the same plane.
faces must name one face or more, R must be a rotation, and the faces round the moved faces must reach them.
{
"cmd": "move_faces",
"s": 1,
"faces": [[5, 10, 30]],
"matrix": [
[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 3]
]
}{"ok": 2}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
thicken
thicken(s: Solid, faces: list<Point3>, thickness: Length) -> Solid
Makes the solid that each face the points lie on sweeps as the face moves from where it is to a distance of thickness along its outward normal. The face moves inward where thickness is negative. The walls of the swept solid are swept along the normals from the face's edges. The input solid is not part of the result. A box's face gives a slab. A cylinder's side gives a tube. A ball's face gives a spherical shell, and a ring's face gives a hollow ring.
faces must name one face or more, and thickness must not be zero. When the face moves inward, the thickness must be less than the face's least radius of curvature on that side, so that the swept face does not fold.
{
"cmd": "thicken",
"s": 1,
"faces": [[5, 10, 30]],
"thickness": 2
}{"ok": 2}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
shell
shell(s: Solid, open: list<Point3>, thickness: Length) -> Solid
Hollows the solid to walls of one thickness, open through the named faces.
The result is the set of points of s within thickness of the boundary of s, with the named faces left out of that boundary. With no faces named, the walls close round a void. thickness must be positive, and the walls must not meet.
{
"cmd": "shell",
"s": 1,
"open": [[5, 10, 30]],
"thickness": 1
}{"ok": 2}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
draft
draft(s: Solid, faces: list<Point3>, origin: Point3, pull: Vector3, angle: Angle) -> Solid
Tilts faces so that a part draws out of a mould. The neutral plane is the plane through origin perpendicular to pull. Each named face turns by angle about the line where the face meets the neutral plane, which narrows the part along pull.
faces must name one face or more, each face must be a plane that meets the neutral plane, and angle must be between 0 and π/2, with neither included. The result is s with those faces moved onto their tilted planes, and with the faces round them extended or trimmed to meet them. Where tilted faces meet each other or another face before the part ends, the part closes there, along a ridge or at an apex, and what lay beyond is removed. The result is still the part cut by the tilted planes.
{
"cmd": "draft",
"s": 1,
"faces": [[0, 10, 15]],
"origin": [0, 0, 0],
"pull": [0, 0, 1],
"angle": 0.05
}{"ok": 2}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
Refusals
A function refuses when it declines an input instead of returning a result. Any function may refuse an input it cannot build correctly. Every function must refuse the inputs in the table at the end of this section. The suite sends no other input outside what a definition requires. A kernel may give such an input a meaning of its own: for example, a height below zero may extrude the other way.
How a refusal is made:
- The adapter passes each call to the kernel as it is. It does not check the input itself.
- When the kernel declines, by an error, an exception or no result at all, the adapter replies
{"err": reason, "kind": kind}with the kernel's own reason, and goes on to the next request. In a Rust adapter, theKernelmethod returnsErr(Refusal). Requests and replies gives the reply. kindsays why the kernel declined, as the kernel's own error reports it:
kind | Meaning |
|---|---|
"unsupported" | The kernel has no way to do what is asked: not this function, or not with these arguments |
"invalid" | The request is at fault: it describes no solid, or names an edge or a face not there |
"failed" | The kernel took the request as a fair one and could not carry it out |
A reply with no kind, or with a kind that a client does not know, is read as "failed". A kernel whose errors do not distinguish these kinds answers "failed" every time.
- A refusal is not a crash. A panic, or a process that dies, is a crash. An empty solid is not a refusal either: two solids that do not overlap intersect in the empty solid, which is a result.
How a refusal is scored, under clause B18 of contract.md:
| The input | The kernel | The case's outcome |
|---|---|---|
| Must be refused | Refuses as invalid or failed | Pass |
| Must be refused | Returns a solid | Fail, however plausible the solid |
| Is allowed | Refuses as invalid or failed | Refused |
| Either | Refuses as unsupported | Unsupported: no judgement |
| Either | Crashes or hangs | Crash or timeout |
unsupported means that the kernel has not built the function, or has not built it for arguments of this sort. The case is scored in the same way as a case for a function that the kernel's hello leaves out of supports: the case is left out of what the kernel is judged on. So a kernel is not marked down for saying plainly what it cannot do, and is not given a pass for an input it never judged. An input that has no answer, such as a fillet too big for its faces, is invalid, not unsupported.
The inputs every kernel must refuse:
| Input | Functions | Tested |
|---|---|---|
| A profile whose loops cross themselves or each other | Every constructor that takes a profile | Yes |
| A profile whose hole lies outside it | Every constructor that takes a profile | Yes |
| A profile that crosses the axis | revolve, screw | Yes |
| Turns that meet | screw | Yes |
| A tube wider than its ring | torus | Yes |
| Heights that do not rise | loft_through | Yes |
| A radius or distance too large for the faces it must fit on | Every fillet and chamfer | Yes |
| One radius or distance of several, or a variable fillet's ball, that is too large | fillet_radii, chamfer_distances, fillet_variable | Yes |
| A shell as thick as the part | shell | Yes |
| A face pushed through the part, or past the face it meets | offset_faces | Yes |
| A side, radius or height of zero, or a side or radius below it | box, cylinder, sphere, extrude | Yes |
| A radius or distance of zero or less | fillet, chamfer | Yes |
| A cone with no radius at either end | cone | Yes |
| A point that names no edge or face | fillet, chamfer, offset_faces | Yes |
A point names nothing when no edge, or no face, of the solid passes within 10·ε of the point. Where a kernel takes its edges and faces by its own handles, the kernel's adapter finds the handle that a point names, and the adapter, not the kernel, refuses a point that names no handle.
Exchange
A STEP file travels as a string holding the file's contents: all of its text, from ISO-10303-21; to END-ISO-10303-21;, in the clear-text encoding of ISO 10303-21. The string is never a path or a file name, because the kernel and the suite need not share a disk. The adapter hands the kernel that text as UTF-8 bytes. The files the suite writes use only the standard's basic alphabet, which is plain ASCII.
| Function | Fields | Returns |
|---|---|---|
write_step | s | string |
sew | text, tolerance | Solid |
read_step | text | Solid |
write_step
write_step(s: Solid) -> string
Writes the solid as a STEP file. Returns the file's contents, as a string.
The kernel chooses the schema, which is AP203, AP214 or AP242, and the file's header names the schema. Another reader must be able to read the file, not only the kernel that wrote it. When the suite is run with a second kernel as --peer, the suite has the second kernel read the file, and reports whether the second kernel reads the same solid.
{"cmd": "write_step", "s": 1}{
"ok": "ISO-10303-21;\nHEADER;\nFILE_DESCRIPTION(('springrep solid'),'2;1');… (10,474 characters)"
}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
sew
sew(text: string, tolerance: Length) -> Solid
Sews the faces of a STEP file into one closed solid. text is the contents of a STEP file that holds loose faces and no solid.
In a solid, two faces that meet share one edge, and that sharing is what makes the solid's boundary closed. A file of loose faces has lost that sharing. Each face is written as a surface of its own, with its own copy of every edge and corner, so nothing in the file says which faces are neighbours. Files like this come from tools that export surfaces, or that drop a solid's connections on the way out. The faces in such files may not quite meet, and some faces may be written inside out.
Sewing joins the faces wherever their edges lie within tolerance of each other, and turns any face written inside out to face outward. tolerance must be positive, and the faces must close into a solid once joined. A prism whose faces are written loose and shifted apart by less than the tolerance sews back into the prism, to within the shifts.
{
"cmd": "sew",
"text": "ISO-10303-21;\nHEADER;\nFILE_DESCRIPTION((''),'2;1');\nFILE_NAME('case','',(''),(''),'','','');\nFILE_SCHEMA(('AUTOMOTIVE_DESIGN { 1 0 10303 214… (15,069 characters)",
"tolerance": 0.002
}{"ok": 1}The file holds the six faces of a 10 × 20 × 30 mm box, each written as its own surface with its own edges and corners. Three are shifted off the box by less than 0.0001 mm, and one is written inside out. Sewn, they close into the box: volume of the result gives 6000.04 mm³, the box's 6000 to within the shifts.
read_step
read_step(text: string) -> Solid
Reads the solids that a STEP file holds, together as one solid set. text is the contents of a STEP file, in AP203, AP214 or AP242. A file written by write_step reads back as the same solid, which means the same set of points within the tolerance.
{
"cmd": "read_step",
"text": "ISO-10303-21;\nHEADER;\nFILE_DESCRIPTION(('springrep solid'),'2;1');\nFILE_NAME('conformance','',(''),(''),'','springrep','');\nFILE_SCHEMA(('AU… (10,474 characters)"
}{"ok": 1}The text is the file write_step returned for the box.
Queries
| Function | Fields | Returns |
|---|---|---|
volume | s | Volume |
area | s | Area |
classify | s, points | list<"in" or "on" or "out"> |
closest | s, points | list<Point3> |
normal | s, points | list<Vector3 or null> |
curvature | s, points | list<Number[2] or null> |
check | s | list<string> |
centroid | s | Point3 or null |
inertia | s | Number[3][3] |
distance | a, b | Length |
interference | a, b | {volume: Volume, gap: Length} |
betti | s | Count[3] |
section_area | s, origin, normal | Area |
section | s, origin, normal, tolerance | list<list<Point3>> |
project | s, direction, tolerance | {visible: list<list<Point2>>, hidden: list<list<Point2>>} |
bounding_box | s | Point3[2] |
split | s, origin, normal | Solid[2] |
mesh | s, tolerance | {positions: list<Point3>, triangles: list<Index[3]>} |
display | s, tolerance | {faces: list<Face>, edges: list<list<Point3>>} |
raycast | s, origin, direction; or s, rays | list<Length>; or list<list<Length>> |
volume
volume(s: Solid) -> Volume
Measures how much space the solid fills.
Returns the measure of s in mm³. It is zero for an empty solid. A kernel that cannot measure the solid answers err, never a number that is not one.
{"cmd": "volume", "s": 1}{"ok": 6000.0}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
area
area(s: Solid) -> Area
Measures the total area of the solid's surface.
Returns the measure of the boundary of s in mm². It is zero for an empty solid. A kernel that cannot measure the boundary answers err.
{"cmd": "area", "s": 1}{"ok": 2200.0}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
classify
classify(s: Solid, points: list<Point3>) -> list<"in" or "on" or "out">
Asks where each of many points lies against the solid.
Returns one answer for each point, in order. The answer is "in" where s holds the point clear of the boundary of s, "on" where the point lies on the boundary, and "out" otherwise. The boundary is every point within ε of a face, an edge or a vertex. A point further than 10·ε from the boundary is "in" or "out". A point off the boundary but within 10·ε of it may be given as either or as "on". A kernel that cannot place one of the points refuses the whole call. It does not answer for the other points alone.
{
"cmd": "classify",
"s": 1,
"points": [[5, 10, 15], [5, 10, 30], [20, 0, 0]]
}{"ok": ["in", "on", "out"]}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin. The second point lies on its top face.
closest
closest(s: Solid, points: list<Point3>) -> list<Point3>
Finds the point of the solid nearest each point.
Returns, for each point in order, a point of s such that no other point of s is nearer to the given point. Here s is the solid with its inside counted in, as for distance, so a point that s holds is its own nearest point. For a point outside s, the nearest point lies on the boundary of s: on a face, an edge or a vertex. Where several points of s are equally near, as the points round a ring are from a point on a torus's axis, any one of them is a correct answer.
{
"cmd": "closest",
"s": 1,
"points": [[5, 10, 15], [20, 10, 15]]
}{"ok": [[5.0, 10.0, 15.0], [10.0, 10.0, 15.0]]}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin. The first point is inside it.
normal
normal(s: Solid, points: list<Point3>) -> list<Vector3 or null>
Gives the outward unit normal at each point of the solid's boundary. Where faces meet smoothly, as a fillet meets the faces it rounds, the boundary still has a tangent plane, and the normal there is the normal of both faces. At a crease, where faces meet at an angle, the boundary has no tangent plane, and the answer is null. The answer is also null for a point that is off the boundary by more than 10·ε.
{
"cmd": "normal",
"s": 1,
"points": [[5, 10, 30], [0, 0, 15]]
}{"ok": [[0.0, 0.0, 1.0], null]}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin. The second point lies on an edge, a crease.
curvature
curvature(s: Solid, points: list<Point3>) -> list<Number[2] or null>
Gives the principal curvatures [k1, k2] of the boundary, with k1 ≥ k2, in 1/mm. For each given point, the curvatures are taken at the point of the boundary nearest to it, so the given point need not lie on the boundary. A curvature is positive where the boundary bends away from its outward normal, as on a ball, and negative where the boundary bends toward its outward normal, as round a hole. Where the nearest point lies on a crease, the answer is null.
A plane has [0, 0]. A cylinder of radius r has [1/r, 0], a ball has [1/R, 1/R], and a hole has [0, −1/r]. A cone has [cos α/ρ, 0] at radius ρ, where its side leans α from its axis. A ring of radii R and r has 1/r and cos φ/(R + r cos φ) at angle φ round its tube.
{"cmd": "curvature", "s": 1, "points": [[5, 0, 10]]}{"ok": [[0.2, 0.0]]}Solid 1 is a cylinder of radius 5 on the z axis.
check
check(s: Solid) -> list<string>
Asks the kernel whether the solid is well formed.
Returns the problems that the kernel's own validity checker finds in s. The list is empty when the checker finds s to be a valid solid set as Types defines it.
A checker that declines the solid refuses, as any function does. The checker has not found the solid valid, so a client reads a refusal as a problem found. A kernel with no checker leaves check out of its supports, and that kernel's results are then not judged on validity.
{"cmd": "check", "s": 1}{"ok": []}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
centroid
centroid(s: Solid) -> Point3 or null
Finds the solid's balance point, as if it were of uniform density.
Returns ∭ r dV / volume(s) over s, or null when s is empty.
{"cmd": "centroid", "s": 1}{"ok": [5.0, 10.0, 15.0]}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
inertia
inertia(s: Solid) -> Number[3][3]
Measures how the solid's material is spread about its centroid, as if it were of uniform density 1.
Returns ∭ (|d|²·I − d dᵀ) dV over s, in mm⁵, where d is the offset of each point from the centroid. The diagonal holds the moments about axes through the centroid, and the other entries hold the negated products. The matrix is symmetric, so its rows and its columns are the same. Every entry is zero when s is empty.
{"cmd": "inertia", "s": 1}{
"ok": [
[650000.0, -0.0, 0.0], [-0.0, 500000.0, 0.0],
[0.0, 0.0, 250000.0]
]
}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
distance
distance(a: Solid, b: Solid) -> Length
Measures how far apart two solids are: the clearance between them.
Returns the least |p − q| over points p of a and q of b, insides included. It is zero when a and b touch or overlap, or when one holds the other. a and b must both be non-empty.
{"cmd": "distance", "a": 1, "b": 2}{"ok": 15.0}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin. Solid 2 is a ball of radius 5 at x = 30.
interference
interference(a: Solid, b: Solid) -> {volume: Volume, gap: Length}
Says how two solids meet, as they stand. It returns the volume they share and the gap between them, which is the least distance from a point of one to a point of the other. Two solids that overlap have a volume above 0 and a gap of 0. Two that only touch have 0 for both. Two that are apart have a volume of 0 and the gap between them. A solid held whole inside the other shares its own volume.
The function answers one pair. A client checking an assembly makes or moves each part to where it stands and asks for the pairs it cannot rule out itself.
which kernels offer it{"cmd": "interference", "a": 1, "b": 2}{"ok": {"gap": 0.0, "volume": 392.699081699}}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin. Solid 2 is a cylinder of radius 5 and height 20 on the z axis.
betti
betti(s: Solid) -> Count[3]
Counts the solid's separate pieces, the tunnels that run through it and the voids it encloses.
Returns the solid set's Betti numbers b0, b1, b2. A box is [1, 0, 0], a ring is [1, 1, 0], a plate with n holes is [1, n, 0], and a box with a ball removed from inside it is [1, 0, 1]. Pieces that only touch count as one piece here, because the point set is connected.
{"cmd": "betti", "s": 1}{"ok": [1, 0, 0]}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
section_area
section_area(s: Solid, origin: Point3, normal: Vector3) -> Area
Measures the area, in mm², of the cut that the plane through origin square to normal makes through the solid. The area is zero where the plane misses the solid.
{
"cmd": "section_area",
"s": 1,
"origin": [0, 0, 15],
"normal": [0, 0, 1]
}{"ok": 200.0}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
section
section(s: Solid, origin: Point3, normal: Vector3, tolerance: Length) -> list<list<Point3>>
Gives the curves that the plane through origin square to normal cuts from the solid's boundary. The curves come in pieces, in any order. Each piece is a stretch of one curve, given as two or more points along the curve from one end of the stretch to the other. Every point lies on the plane and on the boundary, and every chord between consecutive points lies within tolerance of the curve. tolerance must be positive.
The pieces join end to end into closed curves. Each end of a piece lies within 10·ε of an end of another piece, and a piece that is a whole closed curve ends on its first point. A kernel returns the pieces as it has them: one for each edge of the section, or one for each curve. The client joins the pieces.
{
"cmd": "section",
"s": 1,
"origin": [0, 0, 15],
"normal": [0, 0, 1],
"tolerance": 0.01
}{
"ok": [
[
[10.0, -0.0, 15.0], [9.375, -0.0, 15.0],
[8.75, -0.0, 15.0], [8.125, -0.0, 15.0],
[7.5, -0.0, 15.0], [6.875, -0.0, 15.0],
… 59 more
]
]
}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
project
project(s: Solid, direction: Vector3, tolerance: Length) -> {visible: list<list<Point2>>, hidden: list<list<Point2>>}
Makes a hidden-line drawing of the solid seen looking along direction. The drawing shows the solid's edges, and its outlines where the line of sight grazes a curved face. Each edge and each outline is cut into the stretches the viewer sees and the stretches the solid hides. A point is hidden when the ray from that point toward the viewer passes through the solid. An edge between faces that meet smoothly is not drawn, and neither is a face's seam.
Each stretch is returned as a polyline in the view plane. Every vertex of the polyline lies on the stretch, and every chord lies within tolerance of the stretch. tolerance must be positive. The plane has two axes. The axis across is u = d × z, made unit, or d × x when d runs along z. The axis up is v = −d × u. A point p draws at (p·u, p·v).
{
"cmd": "project",
"s": 1,
"direction": [0, 0, -1],
"tolerance": 0.01
}{
"ok": {
"hidden": [],
"visible": [
[
[0.0, 0.0], [0.0, 0.625], [0.0, 1.25],
[0.0, 1.875], [0.0, 2.5], [0.0, 3.125],
… 11 more
],
[
[0.0, 0.0], [0.0, 0.625], [0.0, 1.25],
[0.0, 1.875], [0.0, 2.5], [0.0, 3.125],
… 11 more
],
[
[0.0, 10.0], [-1.25, 10.0], [-2.5, 10.0],
[-3.75, 10.0], [-5.0, 10.0], [-6.25, 10.0],
… 11 more
],
[
[0.0, 10.0], [-1.25, 10.0], [-2.5, 10.0],
[-3.75, 10.0], [-5.0, 10.0], [-6.25, 10.0],
… 11 more
],
[
[-20.0, 10.0], [-20.0, 9.375],
[-20.0, 8.75], [-20.0, 8.125], [-20.0, 7.5],
[-20.0, 6.875], … 11 more
],
[
[-20.0, 10.0], [-20.0, 9.375],
[-20.0, 8.75], [-20.0, 8.125], [-20.0, 7.5],
[-20.0, 6.875], … 11 more
],
… 6 more
]
}
}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
bounding_box
bounding_box(s: Solid) -> Point3[2]
Finds the least box with sides square to the axes that holds the solid, and returns the box as its low and high corners. The box is not padded by the tolerance, and it is not a box round the control points.
which kernels offer it{"cmd": "bounding_box", "s": 1}{"ok": [[0.0, 0.0, 0.0], [10.0, 20.0, 30.0]]}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
split
split(s: Solid, origin: Point3, normal: Vector3) -> Solid[2]
Cuts the solid by the plane through origin square to normal. It returns the regularized part on the normal's side first, then the part on the other side. Either part may be empty, and either may be several pieces.
{
"cmd": "split",
"s": 1,
"origin": [0, 0, 15],
"normal": [0, 0, 1]
}{"ok": [2, 3]}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
mesh
mesh(s: Solid, tolerance: Length) -> {positions: list<Point3>, triangles: list<Index[3]>}
Covers the solid's boundary with triangles. No triangle lies farther than tolerance from the boundary. tolerance must be positive.
The mesh is closed. When positions within 10·ε of each other are read as one vertex, every edge between two triangles is used once each way round. The triangles, which are counter-clockwise seen from outside, therefore all face outward. Because positions within 10·ε of each other are read as one vertex, a kernel that meshes each face on its own may repeat the vertices along an edge, once for each face. The volume that the mesh bounds differs from the solid's volume by at most tolerance times the solid's area.
{"cmd": "mesh", "s": 1, "tolerance": 0.5}{
"ok": {
"positions": [
[0.0, 0.0, 0.0], [10.0, 0.0, 0.0],
[10.0, 20.0, 0.0], [0.0, 20.0, 0.0],
[0.0, 0.0, 30.0], [10.0, 0.0, 30.0],
[10.0, 20.0, 30.0], [0.0, 20.0, 30.0]
],
"triangles": [
[2, 1, 0], [3, 2, 0], [6, 4, 5], [4, 6, 7],
[5, 0, 1], [0, 5, 4], … 6 more
]
}
}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
display
display(s: Solid, tolerance: Length) -> {faces: list<{positions: list<Point3>, normals: list<Vector3>, triangles: list<Index[3]>}>, edges: list<list<Point3>>}
Draws the solid as a viewer shows it: each face meshed on its own, and its edges as polylines.
Each face has its own vertices, so shading is smooth within a face and sharp where two faces meet. Every vertex lies on the face's surface, and normals gives the surface's outward unit normal at each vertex. Where the surface has no one normal, as at a cone's apex, each triangle meeting there has its own vertex there, whose normal is one the surface has along that triangle, such as the normal of the cone's ruling halfway across it. The triangles are counter-clockwise seen from outside, and no triangle lies farther than tolerance from the face. Together the faces close the solid, as mesh does.
edges holds each edge between two faces, whether they meet at an angle or smoothly, as where a fillet meets the face it rounds into. Each edge is given as a polyline whose every vertex lies on the edge and whose every chord lies within tolerance of the edge. A seam, where a face meets itself, is not drawn, and neither is an edge between two faces on one surface: neither marks a change in the shape.
The suite's runner draws the files it exports with display (formats.md).
{"cmd": "display", "s": 1, "tolerance": 0.1}{
"ok": {
"faces": [
{
"positions": [
[10.0, 20.0, 0.0], [10.0, 0.0, 0.0],
[0.0, 0.0, 0.0], [0.0, 20.0, 0.0]
],
"normals": [
[-0.0, -0.0, -1.0], [-0.0, -0.0, -1.0],
[-0.0, -0.0, -1.0], [-0.0, -0.0, -1.0]
],
"triangles": [[0, 1, 2], [3, 0, 2]]
},
… 5 more
],
"edges": [
[[0.0, 0.0, 0.0], [10.0, 0.0, 0.0]],
… 11 more
]
}
}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin. One face and one edge of each are shown.
raycast
raycast(s: Solid, origin: Point3, direction: Vector3) -> list<Length>
raycast(s: Solid, rays: list<[Point3, Vector3]>) -> list<list<Length>>
Finds where a ray meets the solid's faces. It returns the distance from origin to each meeting, in mm, in any order. direction need not be a unit vector. A ray through an edge or a vertex meets every face there, and a kernel may list that point once for each face. A client reads meetings within 10·ε of each other as one crossing. A request may carry many rays at once by giving rays, a list of [origin, direction] pairs, in place of origin and direction. The reply is then one list of distances for each ray, in the rays' order. An adapter that reads only one ray per request refuses the many-ray form, and the client falls back to one request per ray.
{
"cmd": "raycast",
"s": 1,
"origin": [-5, 10, 15],
"direction": [1, 0, 0]
}{"ok": [5.0, 15.0]}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
transform
transform(s: Solid, matrix: Number[3][4]) -> Solid
Moves the solid by p ↦ M·p + t, where the rows of matrix are [M | t].
M must be a similarity: an orthogonal matrix (a rotation or a mirror) times a nonzero scale c. The result's volume is |c|³ times the solid's volume, and its area is c² times the solid's area. A mirror keeps the result a valid solid, with its faces still facing outward. A part is joined to its own mirror image by a transform and a union. Where the part has a face on the mirror plane, the part and its image meet face to face.
{
"cmd": "transform",
"s": 1,
"matrix": [
[1, 0, 0, 5], [0, 1, 0, 0], [0, 0, 1, 0]
]
}{"ok": 2}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
affine
affine(s: Solid, matrix: Number[3][4]) -> Solid
Maps the solid by p ↦ M·p + t, where the rows of matrix are [M | t]. M may be any matrix with a nonzero determinant: a stretch along any axes, a shear, a mirror, or a similarity.
The result's volume is |det M| times the solid's, and its centroid is M·c + t. A point lies inside the result exactly when its preimage lies inside the solid. A surface element grows by the factor |det M|·|M⁻ᵀ n|. For singular values σ₁ ≥ σ₂ ≥ σ₃, that factor lies between σ₂σ₃ and σ₁σ₂, so the result's area lies between σ₂σ₃ times and σ₁σ₂ times the solid's area. A cylinder, sphere or torus that is stretched unevenly is no longer a cylinder, sphere or torus, and a kernel may carry such a face as a spline.
{
"cmd": "affine",
"s": 1,
"matrix": [
[2, 0, 0, 0], [0, 1, 0, 0], [0, 0, 0.5, 0]
]
}{"ok": 2}Solid 1 is a 10 × 20 × 30 mm box with one corner at the origin.
The contract
This is version 1.0.0 of the contract: what a conforming kernel promises for its booleans, constructions and queries. Each clause has an id, which the runner's checks cite.
Tolerance
Each check has a bound, written in terms of a linear tolerance ε in mm. ε is how far a kernel's geometry may lie from the exact geometry. The suite's own tolerance is ε = 1e-7 mm, and a case passes when its checks hold at that tolerance. Each check is also read at looser tolerances, as Tiers describes. A kernel built to a looser tolerance then shows where it stands instead of only failing.
Every kernel is judged the same way, whatever tolerance it declares. An adapter sets every tolerance setting its kernel offers to the suite's tolerance, 1e-7 mm, so that every kernel is asked for the same thing. A setting that cannot be made that tight is set to the tightest value the kernel supports.
In hello the adapter declares one tolerance: the loosest tolerance that still governs the kernel's results. For example, a kernel that intersects at 1e-7 mm but builds its solids at 1e-5 declares 1e-5. In configuration the adapter lists every setting it changed from the kernel's default. Both are reported beside the kernel's results as information only, and no check reads them.
Geometry that lies within ε of the exact geometry changes a volume by at most ε times the surface area. A measured volume therefore meets its exact value within
10 · ε · (area of both operands) + 1e-9 · (volume of both operands)
A measured area meets its exact value within a relative error of 1e-6. The factor of 10 allows for the kernel's own measuring error, so an adapter measures with the kernel's most accurate integration. A kernel's default integration can be looser than these bounds. For example, a fixed rule can be off by 4e-4 of the volume on the spline faces of crossing cylinders, where an adaptive rule on the same faces meets the bounds.
Tiers
A tier is one of four tolerances: 1e-7, 1e-6, 1e-5 or 1e-3 mm. Results are counted at four levels:
| Level | What it is | Its result |
|---|---|---|
| Check | One comparison of the kernel's answer with what it must be | The tightest tolerance at which it holds |
| Case | A few calls on one set of shapes, and the checks on them | The loosest of its checks' tiers |
| Test | A named group of cases, such as booleans of two boxes | The count of its cases at each tier |
| Run | Every case of the suite, on one kernel | The count of cases at each tier, and the share at 1e-7 mm |
A test's cases are generated by one or more families. A family is a generator of cases of one kind, and formats.md names them. A failed check fails only the case it belongs to. A case is one piece of geometry, so it is wrong if any check on it fails. A test and a run only count their cases.
A check that compares an error with a bound is judged at four tolerances: 1e-7, 1e-6, 1e-5 and 1e-3 mm. Its bound grows with the tolerance in the same way as the volume bound above. Its tier is the tightest of the four tolerances at which it holds. Some checks do not depend on a tolerance, such as a result's validity, its Betti numbers, a point placed on the wrong side, or a refusal that was due. Such a check holds at every tier or at none.
A case takes the loosest of its checks' tiers. One check that holds only at 1e-3 mm makes the case 1e-3, however many of its other checks hold at 1e-7. A case fails if any of its checks holds at no tier. A case that ends without an answer has no tier: it is unsupported, refused, timed out or crashed.
A test has no result of its own. For example, if a test has 60 cases, of which 59 hold at 1e-7 and one fails, it is reported as exactly that. One failed case does not fail the test.
A run counts its cases at each tier. Unlike a case, it never takes the loosest tier among them. It has one total over every case, of all three kinds. The kinds are exact, where the definition fixes one answer; sound, where the definition leaves the answer open within limits; and rejection, where the input must be refused. The headline is the share of all cases in that total whose tier is 1e-7. For example, if a run has 20 cases, with 19 at 1e-7 and one at 1e-3, the headline is 95%, and the one case appears in the count at 1e-3. A case at any other tier, a failed case and a case without an answer all count against the headline.
A failed check is classed by what failed. If the check compared a measured value with a bound, it is a failure of measurement: the volume, area, moment or distance the kernel reported is off. If the check compared no measured value, it is a failure of geometry: the shape itself is wrong in its points, its validity or its topology. A case with any failure of geometry is reported as a failure of geometry.
Outcomes
Each operation returns a valid result within the bounds, or refuses with a reason. A case's outcome is the worst outcome among its operations and checks:
| Outcome | Meaning |
|---|---|
| pass | Every operation completed and every check held at 1e-7 mm |
| unsupported | The kernel does not offer a function the case needs, or declined as unsupported |
| refused | An operation declined as invalid or failed; the checks that needed it are skipped |
| timeout | An operation was still running at the time limit |
| fail | A check did not hold at 1e-7 mm: an invalid result, or a value outside its bound |
| crash | An operation panicked, or its worker died |
A case that fails at 1e-7 mm may still hold at a looser tier, and a results file records both facts. The case's outcome is the verdict at 1e-7 mm. Its result names the tier the case holds at (1e-6, 1e-5 or 1e-3), and is fail only when a check holds at none of them. formats.md describes both fields.
The outcomes rank in the order of the table above, worst last: a refusal declines openly, a timeout never answers, a failed check misleads, and a crash takes the operation down.
Clauses
| Clause | Promise |
|---|---|
| B0 | Each operand is the shape described: see below |
| B1 | Every result is valid by the kernel's own checker, built operands among them |
| B2 | Where a family knows them exactly, the intersection's volume and area meet them |
| B3 | vol(A ∪ B) + vol(A ∩ B) = vol(A) + vol(B) |
| B4 | vol(A ∖ B) + vol(A ∩ B) = vol(A), and the same for B |
| B5 | vol(A ∩ B) = vol(B ∩ A) |
| B6 | Moving both operands by one rigid motion leaves vol(A ∩ B) unchanged |
| B7 | The operations leave their operands as they were |
| B8 | vol(A ∩ B) meets the suite's own sampled estimate of it, within its bound |
| B9 | The kernel's classifier places the suite's sample points as the exact operands do |
| B10 | Each primitive operand's centroid and inertia meet their closed forms |
| B11 | Moments add up as volumes do in B3 and B4 |
| B12 | A ∩ B's moments meet the sampled estimate, and move with a rigid motion |
| B13 | distance meets its exact value, agrees both ways round, and survives a motion |
| B14 | A fillet or chamfer gives the blended solid: its volume, area and moments |
| B15 | The kernel places sample points as the blended solid holds them |
| B16 | Blending the moved solid at the moved points gives the result moved |
| B17 | A result written as STEP and read back is valid, with its volume, area, moments |
| B18 | An input the functions do not allow is refused |
| B19 | Betti numbers meet the ones the case knows |
| B20 | The same intersection asked for twice is the same to the last bit |
| B21 | A plane section's area meets the suite's sampled estimate |
| B22 | A STEP file the suite writes reads as the solid it describes |
| B23 | A mesh is closed, faces outward, and bounds the volume within its tolerance |
| B24 | A solid with itself: union and intersection give it back, difference nothing |
| B25 | A similarity, mirrors included, moves the solid and scales its volume and area |
| B26 | A ray's crossings meet the suite's own march along the ray |
| B27 | Interference finds exactly an assembly's clashing pairs, their volumes and gaps |
| B28 | A boolean of many solids meets its closed form and the booleans one at a time |
| B29 | A part joined to its mirror image meets its closed form |
| B30 | Normals at boundary points meet the exact normals, and are null at a crease |
| B31 | A fillet meets its faces smoothly; a chamfer or an unblended corner is a crease |
| B32 | A stretch or shear maps the solid: volume, moments and points exactly, area bound |
| B33 | A solid's bounding box is the least box round it |
| B34 | A split's pieces are valid, hold its volume, and each its side's points |
| B35 | A plane section's curves lie on the plane and boundary, and have their length |
| B36 | Loose faces sew back into the solid they bound |
| B37 | Principal curvatures meet their closed forms at the nearest boundary point |
| B38 | A hidden-line drawing lies on the seen and hidden edges and covers them |
| B39 | By its seams a curvature-continuous blend bends as what it meets does |
| B40 | The solid's nearest point to a point is a point of it, as near as the closed form |
| B41 | A point of the boundary is on it; a point clear of it is in or out as it is held |
| B42 | A display closes the solid with its normals exact, and draws exactly its creases |
Sound cases (process.md) check limits instead of one answer, and have their own clauses. They count in the same total as every other case:
| Clause | Promise |
|---|---|
| Q1 | The kernel completes the act |
| Q2 | Its own checker finds the result valid |
| Q3 | The result has the pieces, tunnels and voids it must |
| Q4 | Outside the zone the definition leaves open, the result's volume is exact |
| Q5 | The result's volume lies between the results at the act's largest and smallest sizes |
| Q6 | The blend meets its faces tangentially where it must touch them |
| Q7 | A loft passes through its sections: their outlines on its boundary, their areas cut |
| Q8 | By its seams a curvature-continuous blend bends as what it meets does |
| Q9 | The result holds none of the points the definition takes away |
| Q10 | Point for point, the result holds what every acceptable one holds and no more |
| Q11 | Across the blend the boundary has no crease |
| Q12 | Across a curvature-continuous blend the curvature carries on without a jump |
| Q13 | The result is unchanged by the motions that leave the case unchanged |
Q10 to Q13 examine the result's shape itself, whereas Q5 bounds only its volume:
- Q10, point for point. The suite samples 8192 points of the shifted Halton sequence in the case's open zone, or in the base's box where the case has no open zone. It sets aside the points that the limits leave open and asks the kernel to classify the rest. The result must hold each point that every acceptable result holds, and must hold no point that no acceptable result holds. One point placed differently is allowed, as in B9.
- Q11, no crease. The suite casts a round grid of parallel rays, 24 across, at the blend. It asks for the normal at the point where each ray first meets the result. Where the normals of two neighbouring rays differ by more than 0.1 rad, it casts the ray between them, and repeats this on each half. The surface is smooth there if the normals of the halves come to agree. The surface has a crease if two points closer together than a thousandth of the blend's smallest radius still have normals that differ by more than 0.1 rad. Only a surface that bends at least a hundred times as tightly as the blend could differ that much over that distance.
- Q12, no jump in curvature. The suite runs the same scan on the principal curvatures. A jump is a change of more than a quarter of one over the radius, within a distance of a hundredth of the radius.
- Q13, symmetry. The suite moves every ray of the grid by each motion the case names and casts it again. It must stop where it did, within a thousandth of the radius. A case names the motions that leave its solid and its named edges unchanged within the grid. These are the swaps of a square corner's three edges, where the three are blended alike, and the mirror in the plane between two faces, two arms or two sides that are alike there.
Three more rules apply to these checks:
- A point where the kernel gives no normal, such as a point on an edge, does not count as a crease by itself. It is halved round like any other.
- A kernel that gives no normal at more than a fiftieth of the grid's points fails Q11.
- Q11 to Q13 are skipped for a kernel that offers no
raycastor nonormal. A kernel with nocurvaturefails Q12, as it fails Q8.
The tests that carry these clauses:
| Test | Q10's limits | Q11 | Q12 | Q13 |
|---|---|---|---|---|
chamfers/three-distances-at-a-corner | Within the box chamfered at the smallest distance. Holds the box chamfered at the largest, except in the corner's cube of that side | No | No | No |
fillets/three-radii-at-a-corner | Between the box filleted at the largest radius and at the smallest, each closed by its ball | Yes | No | No |
fillets/concave-meets-convex-corner | Holds the prism less a 2r box along each convex edge. Within the prism plus a 2r box in the concave edge | Yes | No | The mirror between its two arms |
fillets/set-back-corner | Between the fillets with the corner's cube removed and with it left sharp | Yes | No | The five swaps of the corner's edges |
fillets/g2-set-back-corner | The same, with the curvature-continuous section | Yes | Yes | The same |
fillets/top-loop-bigger-than-corner-rounds | Holds the union of balls. Within the prism less the ordinary fillet along each straight run | Yes, at each loop corner | No | Each corner's mirror, where its sides run straight past the scan |
fillets/variable-radius | At each height, between the edge filleted at the least and the greatest radius the ball has within its largest radius of that height | Yes | No | The mirror between the edge's two faces |
constructions/smooth-loft-through-sections | None | Yes, four scans of its side | No | No |
A primitive operand meets B0 when its volume and area meet their closed forms. B0 is therefore also the contract for the constructions that make primitives from a profile:
- An extrusion's volume is the profile's area times the height.
- A revolution's volume, and a screw's, is the profile's first moment about the axis times the angle (Pappus). A screw's rise moves the profile within its own plane, so it sweeps no volume.
- A ruled loft between a profile and its copy scaled by s has the volume h·A·(1 + s + s²)/3.
The areas of screwed and lofted sides are integrals, which the suite evaluates by Gauss quadrature to well inside the bound.
A built operand is a boolean of other operands. It meets B0 when its volume meets the suite's sampled estimate within B8's bound. If the kernel fails to build one, the case is refused.
B8 and B9 do not need any kernel to know the answer. The suite itself tests whether a point is in each exact primitive. It samples the box that both operands' boxes share, at 4096 points of a Halton sequence shifted by irrational amounts. B8 allows five standard errors of a random sample of that size, two points' share of the box, and the volume bound. B9 allows one point placed differently. B8 catches a wrong volume, whether the geometry is wrong or the measurement of it is. B9 catches wrong geometry alone.
Every clause that asks the kernel where sample points lie treats the kernel's classifier the same way. If a kernel offers no classify, or refuses the call as unsupported, the suite does not ask, and the check is left out. If a kernel offers classify but gives no answer for a solid, it fails the check. Giving no answer means refusing as failed or invalid, running out of time, or crashing. The reason is that a result whose points the kernel cannot place has not been shown to be the right solid.
The suite's membership test follows each definition in api.md. A profile's region is tested by winding number: exactly for lines and arcs, and from a fine polygon for a spline. For the swept solids:
- A point is in a revolution when its angle lies in
[0, angle]and its(ρ, w)lies in the region. - A point is in a screw when
(ρ, w − rise·φ)lies in the region at some turnφ ≤ anglecongruent to the point's angle. - A point is in a loft when
(u/σ, v/σ)lies in the region, at its height.
Membership in a boolean follows from membership in its operands.
Moments and distance
B10 to B12 judge centroid and inertia through the raw moments they give: ∭ r dV and ∭ r rᵀ dV about the world origin. Raw moments add over pieces as volume does. Every primitive's raw moments are known exactly. Each kind of primitive is an extrusion, revolution, screw or loft of a profile, and its moments reduce to the profile's area moments by Green's theorem and one integral along the sweep. Geometry within ε changes a first moment by at most the volume bound times R, and a second moment by at most the volume bound times R². Here R is the greatest distance from the origin to any point of either operand. Those two limits are the bounds. B12's sampled estimate allows five standard errors per component, as B8 does.
B13 allows 10·ε + 1e-9·R. A family states the exact distance where it knows it: zero for operands that overlap or touch, and the gap for the separated family. Wherever the sample finds a point in both operands, the distance must be zero. Distance to an empty solid is undefined, so the suite does not ask for it.
Results that touch
A boolean's result is the regularized set operation: the closure of the interior of the set result. Its separate pieces may touch at points or along curves, and such a result is valid (B1). For example, when a cylinder is cut by an equal cylinder crossing it at a right angle, its two halves touch at two points. Pieces that share an area of face are one solid, because that area is interior to the regularized result, and they must be returned merged. A piece may also touch itself, as a block with a bore flush to one face does along that line. A piece that passes into another piece, or into itself, is invalid. The kernel may represent a contact as it likes: as one edge or vertex that several faces share, or as copies of it. The Betti numbers are those of the point set, so pieces that only touch count as one piece. A kernel that refuses a touching result scores refused, not pass.
STEP's solids are manifold, so a touching result is written as the manifold boundary of its interior. Each piece is a solid of its own, and each side of a contact has its own vertices and edges. Exchange files are commonly written this way. The solids in a file are together one part's shape, so an adapter reads them back as their union, which is the result again (B17).
Blends and exchange
A fillet or chamfer case blends edges of a prism, or the rims of a cylinder or cone. The case names the solid the blend must give. That solid is either the prism on the profile with those corners rounded or cut, or the revolution of the meridian with those corners rounded or cut. B14 to B16 judge the result against that solid's closed forms and membership, as B0, B9 and B6 do for primitives. B17 sends two kinds of result through the kernel's own STEP writer and reader: a ∪ b of every pair case, and every blend's result.
How the later clauses are tested
This section says how each of the following clauses is tested. A clause not listed here is checked as its row in the table above says:
- B18, refusals. The kernel is given an input that api.md rules out, and it passes only when it refuses the input. The fault is in the shape itself (such as a profile that crosses itself), in one number (such as a radius of zero), or in a point that names no edge or face.
- B19, Betti numbers. The suite asks for the Betti numbers where the case knows them. It knows them from a primitive's kind, a drilled plate's holes, a solid inside a box, two solids apart, the union of two solids that touch (one piece), and a bore flush to a face (a tunnel).
- B20, repeatability.
a ∩ bis asked for twice in one worker, and the volumes and areas are compared bit for bit. - B21, section area.
a ∩ bis cut by the plane through the middle of its sample box that is perpendicular to a direction drawn from the case. The area must meet a sampled estimate over that plane, within five standard errors and two points' share. - B23, meshes.
a ∩ bis meshed within 0.01 mm. Its volume may differ by at most twice that tolerance times its area. That is twice whatmeshpromises, which allows for the kernel's own measuring error. - B24, a solid with itself (
self-booleans). A primitive is combined with itself: the same handle is passed as both operands. This clause has a family of its own, so that a kernel that refuses such a pair does not lose every other boolean. - B25, similarities (
transforms). Half the cases are rigid motions, a quarter are scaled and a quarter are mirrored. This clause has a family of its own, so that a kernel without one does not lose every other case. - B26, rays. A ray is cast through
a ∪ bfrom outside its box. The suite sorts the meetings the kernel lists and treats meetings within10·εof each other as one crossing. It compares the crossings with its own march along the ray, which it refines by bisection to 1e-12 of the ray's length. Families whose features may be thinner than a step of the march, or may touch, are left out. - B27, assemblies (
assemblies). The suite makes each part on its frame moved to where the part stands. It asksinterferenceabout one pair at a time, and leaves out the pairs whose bounding balls are farther apart than the clearance. A pair clashes when the kernel's answer has a volume above 0 or a gap below the clearance. - B32, stretches and shears (
stretches). The cases areaffinemaps. A third are stretched along axes by unequal factors, a third are also sheared, and a third are also mirrored. The volume, moments and placed points have closed forms. The area has none, so it must lie between the singular-value bounds. - B33, bounding boxes (
bounding-boxes). The cases ask for the box round turned boxes, cylinders, frustums, balls and rings, alone or joined. A primitive's least box has a closed form, and a union's least box is the box round both. - B34, splits (
splits). Any primitive is cut through the middle of its box at a slant. The pieces' volumes must add up to the solid's, and every sample point must lie in the piece for its side. - B35, sections (
sections). A ball, a cylinder's side, a box, or a ring is cut level or through its axis. Each section is circles, an ellipse or a convex polygon. The suite joins the pieces the kernel returns end to end, treating ends within10·εof each other as one point. An end that meets no other end fails the case. Every point must lie within ten times the tolerance of both the plane and the boundary. Chords may fall short of the curves' length by at mosts/(3ρ)of it, wheresis the chord tolerance andρis the least radius of curvature. - B36, sewing (
sewing). A prism's faces are written as loose open shells. Each is shifted along its normal by up to 1e-4 mm, and a quarter of them are turned inside out. They are then sewn within 2e-3 mm. The volume may change by at most the shift times the area.
- B40, nearest points (
nearest-points,nearest-in-holes). The cases callcloseston a turned box, cylinder, frustum, ball or ring. The query points lie all about the solid, inside and outside it, and on its axis beyond each end, where a ball has its poles and a cone has its apex. Each answer must lie on the solid and be as far from its query point as the closed form says. Where several points are equally near, any of them passes. For a block drilled through, queried from points in the hole, the nearest point is the one point of the hole's wall straight out from the axis, and the answer must be that point. - B41, points on the boundary (
boundary-points). The cases callclassifyon a turned primitive, at points of its faces, edges and rims, and at points a hundredth of a millimetre to either side of a face. The points of the first kind are"on". The points to either side are"in"and"out". - B42, displays (
displays). The cases calldisplayon a box, a cylinder, a ball, a cone or a drilled box, within 0.01 mm. The faces, once joined, must close, with every edge used once each way round, and must bound the volume within twice the tolerance times the area. Every vertex must lie within 1e-5 of the solid's size of one of its surfaces, with that surface's outward normal there to within 1e-3, and every triangle must face the way its normals do. A vertex at the cone's apex must, in each triangle that uses it, have to within 1e-3 one of the normals the cone has across that triangle halfway out from the apex; a triangle of no area is passed over. The edges are judged in space by the rules B38 applies to a drawing: every vertex lies on a crease, every chord lies within the tolerance of a crease, every crease is covered, and the edges have no more length than the creases have. A ball has no crease, a cone's one crease is its rim, and a cylinder's seam does not count as one. None of these solids has two faces meeting smoothly, so their creases are every edgedisplaydraws.
The face edits delete_faces, move_faces and thicken are treated as features, so B14 to B16 judge each result as the primitive it must be. sweep_path is treated as a constructor, so B0 to B13 judge it. Its closed forms are integrals along the path.
STEP
B22 gives the kernel a STEP file that the suite itself writes: a prism of planar faces in AP214. It judges what the kernel reads against the prism. The solid read must be valid, have the prism's volume and area, and place the sample points as the prism does. The file's meaning comes from the format, not from another kernel. B17, by contrast, sends a kernel's own output back through its own reader. A kernel can pass B17 while writing files that no other reader understands.
When the suite is run with --peer, a second kernel reads what the first writes. The suite reports whether the second kernel reads the solid that the suite's sample describes. This is reported as interop, apart from the score. A mismatch may be the fault of either kernel, so it counts against neither.
What an adapter may do
An adapter answers each function with the kernel's one call for it, or the function is unsupported. An adapter never composes one function from others, and it never makes a decision. A threshold, a vote between answers, a retry with other settings and a repair of the result are all decisions. For example, a split made from booleans with a half-space would score the booleans twice and credit the kernel with a split it does not have.
unsupported means one thing: the kernel has not built this. Either the kernel lacks the function, or it lacks the function for arguments of this sort. An example of the second is a mirror in a kernel that only moves solids rigidly. An input that has no answer is invalid. A call that should have worked and did not is failed.
A kernel may well be able to reach the same answer another way. It could get a section's area from a boolean with a half-space, a ray's crossings by firing again from each crossing, or a distance by classifying a point after the solve. Kernels differ in how they are built, as browsers do, and that is not a fault. But a suite can only compare kernels on functions they offer in the same form. An adapter that builds a missing function out of other functions becomes a second, untested kernel standing in for the first, and its results say nothing about either. Such a function is therefore unsupported. Each adapter says why in one line, and the kernel is judged on what it offers directly.
An adapter may do four things that are not a call of the kernel. No others are allowed:
- Translating form. The adapter may give a profile's segments as the kernel's curves, a frame as its placement, and a path as its spine. It may sample a curve the kernel returns into points, sort a split's solids by side, and move a solid that the kernel builds at the origin onto its frame.
- Addressing a point. When a point names an edge or a face, the adapter turns it into the kernel's own address for that edge or face: the nearest entity and its parameters there. It does this through the kernel's distance query at the contract's
10·ε, and uses no number of its own. Where a kernel answers on one face and the point lies on several, as a point on an edge does, the adapter does not choose between them: the call isunsupported. - The empty solid. A kernel that has no empty solid says in its own way that a result is empty. The adapter reads that statement, and no other refusal, as the empty solid. The adapter itself answers queries on an empty solid: a volume of 0, no meetings of a ray, and every point outside.
- What a handle means. A handle is a solid that stays as it was. Where a kernel's call consumes its operand, the adapter keeps a record of how the solid was made and makes it again.
Where a case asks for one thing by way of another, the suite does the other thing itself. It uses one recipe that is public and the same for every kernel. The recipes are the stand-ins below, the pairing of an assembly's parts, the merging of a ray's meetings at an edge, the joining of a section's pieces, and the welding of a mesh's vertices. A test of a function itself never takes a recipe: a kernel without the function is unsupported there, and only there.
In a kernel's hello, configuration states every setting the adapter gives the kernel that is not the kernel's default, such as a tolerance, a mode of integration or a mesh's angular deflection. An adapter that sets nothing states nothing.
A kernel's hello leaves out the functions the kernel does not offer, and the suite does not ask for them. A case that needs such a function is unsupported. In the other cases, the checks that the function would feed are left out.
Stand-ins for the five primitives
A case about a boolean or a fillet starts from a box or a sphere, and its result should not depend on whether the kernel has a constructor for that primitive. So where a kernel lists box, cylinder, sphere, torus or cone as unsupported, the suite sends the same solid as an extrusion or a revolution in its place:
| Primitive | Sent instead |
|---|---|
box | extrude of the rectangle from the origin to size[0], size[1], by size[2] |
cylinder | extrude of the circle of its radius about the origin, by its height |
sphere | revolve, a whole turn, of the half disc right of the axis |
torus | revolve, a whole turn, of the tube's circle, its centre major out from the axis |
cone | revolve, a whole turn, of the meridian: the axis, the two radii and the side |
The suite makes the stand-in, and it is the same one for every kernel. The adapter still only answers the call it is sent. If a kernel also lacks the stand-in's function, it cannot make the solid, and the case is unsupported.
The constructors' own tests are the exception. These are constructions/box, cylinder, sphere, torus and cone, and a test that a constructor refuses a bad solid. They ask for the constructor and nothing else, so a kernel without the constructor is unsupported there. The results name each stand-in a run used, in stand_ins.
Stand-ins for a mirror image and a placed part
Two more kinds of case ask for one thing by way of another. The suite makes that other thing itself where the kernel cannot:
- A part joined to its mirror image (
mirror-joins,chain-across-a-mirror-join). The suite asks for the image withtransform. Where the kernel refuses the mirror asunsupported, the suite makes the image as a primitive of the same kind. The primitive's frame is mirrored, with x turned back to keep it right-handed, and its box or profile is mirrored across that x to match. The union, or the fillet across the join, is then judged as it is for any kernel.transformsremains the test of a mirror itself. - The parts of an assembly (
assemblies). Each part is made on its frame moved to where the part stands, and is never moved after it is made. The interference test therefore does not depend ontransform.
Time
Each call has a time limit, which is 120 s unless the run sets another. A call that passes the limit times out, and its worker is replaced. A case's time is the sum of its calls' wall times, as the client measures them. A run is one pass. A test's time is the median of its cases' times, leaving out the cases that gave no answer. A test with fewer than five timed cases is marked as low confidence. Two kernels' times are comparable only on the cases both pass at the same tier, and only when both ran on the same machine. The run also times a calibration workload on its kernel and machine: two crossing cylinders, their intersection and its volume. That time is recorded for comparing machines, never kernels.
Known limits
- Measuring. B0 to B6 trust each kernel's own volume and area, and a kernel's integration can be off where its geometry is right. A fixed rule can measure 4e-4 of the volume off on crossing cylinders, and an adaptive rule can be 5% off on a periodic spline prism while reporting an error estimate of 1e-17. B8 and B9 now separate such errors from wrong geometry, but only to their sampling bound.
- Time budgets. A call has a time limit, but no budget that scales with its work. A boolean of two boxes and a boolean of two splines may each take the same 120 s. Work counters reported by the kernel would let budgets scale with the case.
- Tolerance scale. ε is absolute. The
scaledfamily's parts range from microns to tens of metres, so they test whether a kernel holds one tolerance at every size or scales its own. Whether the contract should declare ε relative to a part's size is an open question.
Result files
This document describes the files a run writes and reads, and how cases are named.
Tests and case ids
Every case belongs to a test. A test is named by a path: a directory for the feature it exercises and a name for the situation, such as booleans/touching/sphere-in-a-cone or fillets/rejects-radius-past-half-width. The top-level directories are booleans, constructions, fillets, chamfers, modify, queries, step and parts. parts holds whole parts built step by step, such as gears. Only booleans has a second level, which says how its two solids meet. A test whose name starts with rejects- passes only when the kernel refuses its input, and it sits with the feature it refuses.
Cases are drawn by families. A family is a generator, and it may feed several tests. A case id is its family's name followed by a hash of what the family drew, for example box-box-1a2b3c4d5e6f7a8b. An id is opaque: it names one case of one suite release, and nothing outside the suite can work out an id from a case's parameters. The same seed draws the same cases on every platform. A family that changes what it draws for a seed bumps its version, which gives its cases new ids. A change that keeps the draws keeps the ids, and moving a case to another test changes neither.
Results
A results file is one JSON object per run. This is format 1, which the object gives as format. Adding a field later does not change the number, so a reader ignores fields it does not know. Removing a field, or changing a field's meaning, raises the number.
The run's fields:
| Field | Value |
|---|---|
format | The version of this format, an integer |
suite | The suite's release, numbered as versioning.md says |
contract | The version of contract.md its checks implement |
tolerance | The suite's linear tolerance in mm, which every check is judged to |
kernel | name, version, declared tolerance and configuration, as hello gave them |
adapter | On an official run (--kernel): the adapter's repo and the commit it ran |
unsupported | The functions of the suite's protocol version that the kernel's hello leaves out |
stand_ins | For each primitive the kernel has no constructor for, the function sent in its place |
environment | The machine's os, arch and cores, and the run's threads |
unix | When the run ended, in seconds since 1970 |
calibration_ms | The time of the calibration workload on this kernel and machine |
cases | One object per case, in generation order |
A kernel's version is a release number, or a digest of the source it was built from. stand_ins looks like {"sphere": "revolve"}, and contract.md gives the solids sent.
A case's fields:
| Field | Value |
|---|---|
id | The case's id |
test | The path of the test it belongs to |
family | The family that drew it |
kind | exact, sound or rejection: how it is judged, as process.md describes |
outcome | pass, fail, unsupported, refused, timeout or crash |
result | The tier it passes at, 1e-7, 1e-6, 1e-5 or 1e-3; else its outcome |
why | Where the result is not 1e-7: the failed clause and its detail, or the error |
failure | Where a check failed: geometry, or measurement when every failed check weighed one |
over | On a failed case: its worst measure's error as a multiple of its bound |
a, b | The operands, as Operands writes them |
feature | On a blend or an edit: the act, the points naming edges or faces, the size |
checks | The checks made, below |
ops | The steps run, below |
error | Where the case's own solids could not be made: the kernel's reason |
interop | With --peer: whether the second kernel read this one's STEP file as the same solid |
time_ms | The sum of its steps' times |
asset | The name of its shape files |
sound | true on a case judged as sound |
asset_step | true when the case has STEP files (Assets) |
exports | With --glb or --step: the keys written as glb and step, what could not be drawn or written as errors, and as skipped a ghost the kernel could not cut or a refused case's input it would not make |
In a feature, b is the shape the act must give, and a draft also has its pull. A case that must be refused passes only when it is refused.
A step is one entry of ops. Its fields:
| Field | Value |
|---|---|
op | The step's label, for a reader: a function's name, or words such as a ∪ b |
outcome | done, refused, unsupported, timeout or crash |
ms | Its time |
error | Where it did not finish: for a refusal its kind, then the kernel's reason |
A step may time several calls, such as a boolean and the measures taken of its result. op is therefore a label and not always one function's name, and no reader should parse it. A step that finished may also give what it found: the result's volume, area, centroid and checker issues, a distance, or the number of clashes in an assembly. For classify a ∩ b it gives, as mismatched, the number of sample points the kernel placed differently from the exact operands, and the first few of them, each with its point and whether it is inside.
A check has a clause, whether it held as ok, the tier it holds at, and what it weighed and counted:
measures: each entry has ameasure(volume,area,distance,first momentorsecond moment) in itsunit, theerror, and theboundthe error had to stay within. Where the check compares two values, the entry also has the kernel's value asgotand the expected value aswant.counts: each entry has acountof something (checker issues,sample points placed wrongly,pieces,closed curves) and how many there were asgot. It also has either themostthere may be, or the number there must be aswant.detail: a few words saying what the check was of, followed by a sentence made from those numbers. A check that is only a yes or no, such as whether an input was refused, has the sentence only.
Reports
A run's --html FILE option, and the command brep-conformance-report RESULTS.json... --out FILE, each write a report page for reading on the machine that ran it. The page is one HTML file that holds its results, its styles and its scripts, and it asks the network for nothing. It is a view of the results file, not a format to read back.
brep-conformance-report RESULTS.json --flat report.json writes one run in the form the results site reads. It holds format (the same number as the results file's), kernel, adapter, assets (the URL of the folder its files are published in, where it wrote any), suite, run (unix, and verified when the suite's own benchmark machine ran it), environment, unsupported, stand_ins, a summary (the number of cases, the headline pass_1e7 and the count of each result) and cases. cases has one row per case, with id, test, operation, kind, result, why, failure, time_ms, asset, its test's group_median_ms, group_low_confidence, and, where files were drawn, exports: the glb key and the list of step keys, below the kernel's folder of Assets.
Operands
Each operand is a constructor call written as data: the request api.md sends for it, with the constructor's name as kind in place of cmd, for example {"kind": "extrude", "frame": …, "profile": …, "height": …}. Its fields are the function's parameters in api.md.
An operand may instead be built from other operands. A built operand has kind boolean, an op of union, intersection or difference, and operands a and b, each of which is a primitive or another boolean. The runner builds it with the kernel under test, innermost first, so a case feeds results into the next operation as modelling does. Its id hashes the operation round its operands' parameters.
Assets
A run with --glb DIR or --step DIR writes each case's shape files there, as the kernel under test draws them. Failed cases' files are included (export.rs):
| Key | Holds |
|---|---|
<test>/<id>.<asset>.glb | The case's views |
<test>/<id>.<asset>.step | The one solid of its first view, as the kernel made it |
<test>/<id>.<asset>.<role>.step | Each of the two solids of its first view, named by role |
STEP files are written for the subjects of a case's first view, not counting ghosts: a boolean's intersection, a feature's result, a queried solid, a mirror join's joined part, or the solid a sewing or a STEP read made. Each is the kernel's own result, for exact and sound cases alike, so on a failed case it may be wrong. A case that must be refused has none, and nor has a view of more than two solids, such as an assembly of a hundred parts, which its GLB shows. A kernel whose adapter does not offer display draws nothing, so its cases have no GLB, and one without write_step has no STEP files. asset is a 64-bit FNV-1a of the case id and ASSET_GENERATOR in run.rs. ASSET_GENERATOR changes when what draws the files changes. A test in springrep's adapter pins it to a fingerprint of what springrep's display draws, and fails when that drifts.
A view's subject is the kernel's own result where the case's runner kept one. The runner keeps a boolean's four results and operands, a feature's or chain's result, a moved solid, a split's pieces, a boolean of many, a mirror join, a sewn solid, the solid a STEP file was read as, a smooth loft, and a blend that no one shape is right for. A case of those last kinds opens on a view of the kernel's result alone, marked own: where the kernel made nothing, that view stays empty, for no shape of the suite's is the answer. Any other solid the view names is built by the kernel from the case's shapes and moved by the kernel's transform, or by its affine where transform refuses. A ghost is the part of an operand that lies outside the view's subject. It is the kernel's difference of the two, less each face and each edge whose middle the kernel classifies as on the subject's boundary. Subjects are drawn first and ghosts last. An operand's ghost behind a union of that operand is empty, so it is not cut. Each solid is drawn with display within DRAWN (5e-4) of its diagonal, and each STEP file is written with write_step.
The GLB holds one scene per view, named as the view. A scene's extras carry the view's note, the line saying what it shows, and, where the view draws solids in the second tone, alt, what that tone marks, such as written inside out. Each scene has one node per solid. A node is named by its role (main, alt, ghost, ghost2) and also carries the role as extras.role. Its mesh has the display's faces as triangles and the display's edges as lines. Positions are in the suite's millimetres with z up, under a root node that scales them to glTF's metres and turns z to glTF's y, which every glTF viewer takes as up. The file's extras carry the case's id, test and hash, the kernel that drew it, the case's outcome and result, and the views' points, box and plane. The file requires KHR_mesh_quantization, which three.js, Blender and <model-viewer> read. Positions are SHORT over the solid's box, and the node's translation and uniform scale take them back to millimetres. Normals are normalized SHORT, fine enough for reflection stripes to show where faces meet. Both primitives are indexed, with UNSIGNED_SHORT where the vertices fit.
Each registered kernel's files are published under <base>/<suite>/<kernel>/<version>/<key>, the folder its report has on the results site. The base is compiled in from BREP_CONFORMANCE_ASSET_BASE, https://cdn.springcraft.ai/brep-conformance by default; assets.rs gives a file's URL. They are the files of the official benchmark pass itself: each kernel's pass runs with both exports, so its report and its shapes come from one run. The suite draws a case after judging it, outside every timed call. The Benchmark workflow's publish job then uploads each pass's files the bucket lacks, with each file's type and an immutable cache lifetime. A file is never rewritten: a change to what it shows, or to what draws it, gives it a new name.
Process
This document says how the suite's specifications change: when a function enters api.md, and where the ideas for new functions come from. It governs the specs and is not part of them.
Adding a function
- A test needs it. The functions are the smallest set that the tests call. A family that needs a new function brings the function's definition with it.
- Its result is decidable. Its definition is exact enough for the suite to decide, for any point, whether the result holds it. A function whose definition is not that exact is not yet specified.
- Two kernels implement it. The function is interoperable once two independent kernels meet the contract on its tests. Until then it is specified but not interoperable.
The registry
kernels.json lists the kernels the suite scores officially. Each entry names the kernel as its adapter's hello does, the kernel release that adapter must report, the kernel's licence and source, and its adapter: the repository, the commit the suite's maintainers reviewed as pass-through against the adapter rule, the adapter's licence, the commands that build it, and the command that starts it, with {dir} for its checkout. reviewers names the kernel's own maintainers who review its adapter, where they do.
An official run is brep-conformance --kernel NAME. The runner reads the registry it was built with, checks the adapter out at the pinned commit, refuses a checkout with changed files, builds it, refuses an adapter that reports another kernel or release, and records the repository and commit in the results. The site lists only the kernels in the registry.
A merge to an adapter's repository changes no official run until a pull request here moves its pin. The suite's maintainers review that pull request against the adapter's changes since the last pinned commit, with the kernel's reviewers where it has them. A new kernel release moves version with the adapter commit that builds it.
Two kinds of test
- Exact. The definition fixes the result as a set of points. The test checks the kernel's answer against that set, through a closed form for its volume and area, or through the suite's own sample. Most tests are exact.
- Sound. The definition leaves the result open within limits, in places where CAD tools legitimately differ. The corner where fillets of unequal radii meet is one such place. The test checks that the kernel completes, that its result is valid and covers what was asked, and that the result keeps the properties every acceptable answer has. It does not check for one particular answer. Sound cases count in the same total as exact ones.
Behaviour no definition limits, such as how a tool names faces or which of two valid corner patches it prefers, is not tested.
What is out of scope
- Annotations. STEP's product manufacturing information (dimensions, tolerances, datums) is data about a part, not a set of points, so no function here defines it and no test reads it.
Where new functions come from
The choice of what to specify next comes from what CAD users expect: the features common to modelling tools and the functions common to kernel APIs. Those are evidence of what is standard, but they are never the definition. Every definition in the specs is the suite's own, written as a set of points.