C++ API

cadaclysm::open()

Result<Scene> open(const std::string& path, const OpenOptions& options = OpenOptions())

Open a CAD file and read its tree. The format comes from the extension (a .zip or .stpZ opens its first readable member — Scene::source_name() says which — and a .gz is read as the format named before it, part.step.gz as .step). The tree is read now and the geometry is built lazily, node by node, when it is first asked for.

convention is the space to read into — a Convention, optionally with the file-units and world-UV flags — and the library converts everything it hands back into it. schema names an extra EXPRESS schema (.exp, or a directory of them); every schema the SDK ships is already built in, so it is needed only for one the library does not carry. colours asks for per-vertex colours on bodies the file painted in more than one colour.

Never returns an empty handle: on failure it returns an Error in its Result carrying the library's reason.

cadaclysm::open_memory()

Result<Scene> open_memory(const void* data, std::size_t size, const std::string& format, const OpenOptions& options = OpenOptions())

Open a file already in bytes — a download, a database blob, an archive member. With no file name to take the format from, it is named as an extension would name it: step, ifc, igs, 3dm, brep, scad (a leading dot is fine). The bytes are copied; the buffer can be reused as soon as this returns. Otherwise as cadaclysm::open().

cadaclysm::version()

std::string version()

The version of the library actually loaded — the one worth reporting in a bug.

cadaclysm::build_date()

std::string build_date()

When the loaded library was built, YYYY-MM-DD. A licence covers every build dated on or before its expiry.

cadaclysm::license()

Result<void> license(const std::string& text_or_path)

Load a licence: the certificate text, or the path of a file holding it. Without this call the library looks in the CADACLYSM_LICENSE environment variable, then for cadaclysm.lic beside the executable and in the working directory. On a licence that does not verify it returns an Error in its Result with the reason, and the previous licence (if any) stays in use.

cadaclysm::license_info()

std::string license_info()

One line about the licence in use — customer=… expiry=… entitlements=… — or unlicensed (unlicensed -- <reason> when a licence was found but did not verify). Never std::nullopt.

cadaclysm::license_notice_count()

std::uint64_t license_notice_count()

How many unlicensed notices the library has printed to stderr in this process. An application with no console to watch (a GUI, a game) can poll this and show its own banner.

cadaclysm::mesh_formats()

std::vector<MeshFormat> mesh_formats()

Every mesh format Node::save_mesh() writes, with its file extension and a label for a save menu: stl (STL (binary)), stl-ascii (writes .stl too), msh (Gmsh), glb, gltf and obj in this release. Build the menu from this list rather than hard-coding it, and a format added to the library appears without a code change.

cadaclysm::lod_levels()

std::uint32_t lod_levels()

How many coarser levels Node::mesh_lod() offers above the mesh itself (level 0): 3 in this release.

cadaclysm::formats()

std::vector<Format> formats()

Every format this build reads, each with the file extensions it takes — what an open dialog's filter is built from, the way cadaclysm::mesh_formats() feeds a save menu.

datetime_of

A schedule date (seconds since 1970-01-01T00:00, as WorkSchedule::at() and TaskTime give them) as a naive datetime.

Seconds since 1970-01-01T00:00, no zone: std::chrono::sys_seconds{std::chrono::seconds{static_cast<long long>(seconds)}}.

seconds_of

A naive datetime as a schedule date: seconds since 1970-01-01T00:00, the inverse of datetime_of.

Seconds since 1970-01-01T00:00, no zone: std::chrono::sys_seconds{std::chrono::seconds{static_cast<long long>(seconds)}}.

cadaclysm::pick_save()

std::optional<std::string> pick_save(std::optional<std::string_view> suggested_name = std::nullopt)

Ask the user where to save, through the platform's own dialog, with suggested_name prefilled. std::nullopt when they cancel or no dialog is available. Blocks until the user acts; on macOS call it from the main thread.

cadaclysm::pick_file()

std::optional<std::string> pick_file()

Ask the user for a file through the platform's own open dialog, filtered to what this build can read. std::nullopt when they cancel or no dialog is available (on Linux, neither an XDG portal nor zenity). Blocks until the user acts; on macOS call it from the main thread.

cadaclysm::declared_schema()

Result<std::string> declared_schema(const std::string& model)

The schema a STEP or IFC file says it speaks (its FILE_SCHEMA line), read from the first few kilobytes — cheap even on a very large file. Empty when it names none.

cadaclysm::resolve_schema()

Result<SchemaChoice> resolve_schema(const std::string& model, const std::optional<std::string>& schema)

Which .exp of a schema directory matches a model: the chosen file, or — when the file's declared name resembles none of them — the whole list as fallbacks to try in turn. cadaclysm::open() does this itself when given a directory; this is for a caller that wants to report the choice.

library_path

Where the shared library was found: CADACLYSM_LIBRARY (a file or a directory) first, then beside the wrapper, then a lib/ directory in any parent (the SDK's layout).

Linked at build time: the OS loader finds the libraries; see Install.

cadaclysm::NONE

inline constexpr std::uint32_t NONE = CADACLYSM_NONE

The node index the C API uses for "no such node" (CADACLYSM_NONE, 0xFFFFFFFF). The wrappers turn it into std::nullopt where a node may be missing (Node::parent(), Node::instance_of()), so it matters only when reading raw indices.

Scene::close()

void close() noexcept

Give the document back. Idempotent. Every mesh and polyline view still held reads freed memory afterwards (the wrappers that can tell refuse to read them). Node and Godot hand back copies, so nothing of theirs goes stale here.

Scene::closed()

bool closed() const noexcept

Whether Scene::close() has run.

Scene::path()

const std::string& path() const

The file it was read from, or the name given to cadaclysm::open_memory().

Scene::schema_path()

const std::optional<std::string>& schema_path() const

The .exp actually used, or std::nullopt — worth reporting when a directory was passed.

Scene::convention()

std::uint32_t convention() const

The convention it was opened with. Nothing the library hands back says what space it is in, and every array out of this scene is in this one.

Scene::version()

std::string version() const

The version of the library that read it.

Scene::schema()

std::string schema() const

The schema the file named, or empty for a format that names none.

Scene::schema_read()

std::string schema_read() const

The schema that actually read it. A file declaring a release candidate reads under the finished schema of the same version where that is what is built in; a file whose schema is unknown reads under the one that defines its entity types.

Scene::substituted()

bool substituted() const

Whether something other than the file's own schema read it — Scene::schema() and Scene::schema_read() differ.

Scene::metres_per_unit()

double metres_per_unit() const

What one length unit in the file is worth in metres; 1 where the file did not say.

Scene::bounds()

Bounds bounds() const

Everything the model covers, in world coordinates — the one figure not in a node's own frame. This meshes the whole model, being the only way to know how far it reaches; to frame a view quickly, use the bounds of the nodes already built.

Scene::bounds64()

Bounds64 bounds64() const

Scene::bounds() in double precision, in world coordinates: the model's extent unnarrowed, exact far from the origin. This meshes the whole model, as Scene::bounds() does.

Scene::diagnostics()

std::vector<std::string> diagnostics() const

What the file held that the reader could not build, one line each.

Scene::links()

std::vector<Link> links() const

The rigid bodies of the file's mechanism, in the file's order: each names the nodes that move together. Empty for a file that records none.

Scene::joints()

std::vector<Joint> joints() const

The connections between those links, in the file's order; each names, through Joint::pair(), how it moves.

Scene::states()

std::vector<State> states() const

The file's named mechanism poses, in file order, each a State. Empty for a file that records none.

Scene::sequences()

std::vector<Sequence> sequences() const

The file's motion sequences — INTERPOLATED_CONFIGURATION_SEQUENCE, a mechanism moving through its states — in file order, each a Sequence. Empty for a file that records none.

Scene::schedules()

std::vector<WorkSchedule> schedules() const

The file's work schedules (IFC 4D: IfcWorkSchedule and the tasks it controls), in file order, each a WorkSchedule. Empty for a file that records none.

Scene::base()

std::optional<Link> base() const

The link the file declares as the mechanism's base, or std::nullopt when it declares none.

Scene::pose()

Result<Pose> pose(const std::vector<StateValue>& values = {}, std::optional<Link> ground = std::nullopt) const

The mechanism posed by values — rows of a joint and one number per freedom of its pair, in the pair's freedom order, exactly State::values's row type — with ground (a Link, or std::nullopt for the default ground: the declared Scene::base(), else the link on the most joints) held fixed. Values outside a freedom's range are used as given and reported in the answer's Pose::out_of_range. returns an Error in its Result on a bad row or a file with no mechanism, carrying the library's own message.

Scene::pose_state()

Result<Pose> pose_state(const State& state, std::optional<Link> ground = std::nullopt) const

The mechanism posed by a named State's values, ground held fixed as Scene::pose() does. returns an Error in its Result as Scene::pose() does.

Scene::geometry_diagnostics()

std::vector<std::string> geometry_diagnostics() const

What the reader built but the geometry stage could not finish — a face that would not trim, a surface that would not mesh — one line each. Scene::diagnostics() is what the *file* held that could not be read; this is what the geometry did.

Scene::source_name()

std::optional<std::string> source_name() const

The archive member this was read from, or std::nullopt for a plain file.

Scene::nodes()

std::vector<Node> nodes() const

Every node, in index order: assemblies, shapes, layers, storeys — structure as well as geometry. To draw, iterate Scene::placements() instead.

Scene::roots()

std::vector<Node> roots() const

The nodes nothing else contains: where a tree view starts.

Scene::walk()

std::vector<Node> walk() const

Every node reachable from the roots, parents before children.

Scene::query()

Result<std::vector<std::uint32_t>> query(const std::string& filter) const

The indices of the nodes a filter matches, in document order. The filter is one boolean expression in the query language — class == ON_Brep and within(name == Walls). A filter that does not parse returns an Error in its Result with the parser's message and position; one that matches nothing is an empty result, not an error.

Scene::placements()

std::vector<Placement> placements() const

What the document draws, and where. Not the nodes: a block or an instanced part is one node of geometry drawn at several places, and a node walk draws it once at its definition's frame. Iterate this to draw, and the nodes to build a tree. See Placement.

Scene::realize_all()

std::uint32_t realize_all() const

Build every mesh now, across all cores, and return how many were built. Reading is lazy so a tree can be on screen while the shapes are still coming; asking node by node meshes on one core, this uses them all. Watch it from another thread with Scene::realized() and Scene::realize_total(); stop it with Scene::cancel().

Scene::realize_meshes()

std::uint32_t realize_meshes(bool skip_surfaced = true) const

Scene::realize_all(), leaving alone every node that carries surfaces when skip_surfaced is true (the default): a renderer drawing those parts from their surfaces never pays for their triangles, and takes their bounds from Node::bounds(), which falls back to the surfaces.

Scene::realized()

std::uint32_t realized() const

How many nodes Scene::realize_all() has finished. Safe to read from another thread.

Scene::realize_total()

std::uint32_t realize_total() const

How many it will build in all; zero until it starts.

Scene::cancel()

void cancel() const

Ask a running Scene::realize_all() to stop. One-way for the life of the scene: later calls return at once, and meshes are still built one node at a time on request.

Scene::forget_meshes()

void forget_meshes() const

Drop every mesh the scene has built and give the memory back; the next ask rebuilds. For a viewer that has uploaded what it needs. What it frees is the document's own mesh, which Node::mesh64() lends: a view from before it points at freed memory afterwards, so the scene counts its forgets and a Mesh64 read after one is refused as a stale view rather than read. Mesh, Polylines and the Béziers are the library's own caches, which a forget does not touch and which stay good until Scene::close(); Node and Godot hand back copies, unaffected by either.

Scene::save()

Result<void> save(const std::string& path, const std::string& format = "glb") const

Write the whole scene: glb (binary glTF), gltf (text glTF, one file) or obj (every placement baked to its own named object, with a .mtl beside it when anything has a colour). Every placement of every shape, named and placed as the tree is, one material per colour; in the scene's convention (use Y-up metres for the space glTF specifies). A format outside these three, or a failed write, returns an Error in its Result.

Scene::surface_matrix()

Matrix4 surface_matrix() const

The 4×4 that puts Node::surfaces() into the space everything else is already in. Meshes and polylines arrive in the scene's convention; surfaces arrive in the file's own frame, because converting a surface means converting its parameter space too. Identity for a document opened in its native convention and units.

Scene::show()

Result<void> show(const O& options = O{}) const

Draw every visible placement — each block instance where the file puts it — with the viewer in use. Keywords: view= (front, back, left, right, top, bottom, iso), az=, el=, zoom=, up= (default from the convention the scene was opened with), edges= (the B-rep edges over the shapes; on the terminal library, edges=False also hides free curves — the two share one layer there), width=, height=, hint=. No tolerance=: a document is drawn at the tolerance it was read with. With the GPU library (import cadaclysm.view.wgpu) the drawing replaces what one shared window shows and stays live — at the REPL, in IPython and in Jupyter by themselves, in a script until it exits; cadaclysm.view.View draws several items or several windows.

Takes a cadaclysm::ShowOptions (edges true by default, azimuth/elevation/up std::optional). A tolerance is refused: a document is drawn at the tolerance it was read with. Blocks until the window is closed on the wgpu library (cadaclysm::view::use_wgpu()); the terminal prints a still. Several items or a window that stays: cadaclysm::View. A member template: #include <cadaclysm/view.hpp> to call it, and link cadaclysm::view_loader (cadaclysm::view is the linked C library, for hosts that call cadaclysm_view.h directly).

Scene::view()

auto view(const O& options = O{}) const

Orbit the model with the viewer in use; returns the camera where it was left — a dict of eye, target, up, orthographic, azimuth and elevation — and pick, what was last clicked (item, node, face) or None. A fresh window, run until closed, with the GPU library.

Takes the options show does; returns a Result<Camera>.

Scene::svg()

Result<void> svg(const std::string& path, const SvgOptions& options = SvgOptions()) const

Every visible placement's wireframe as SVG, from a camera the keywords describe rather than a viewer window: view= (front, back, left, right, top, bottom, iso — Scene::show()'s own table), az=/el= over it, up= (default from the convention this scene was opened with), fov= (0, the default, is orthographic), size= (width, height), margin= (fraction of the content's extent left each side), tolerance= (how far a written curve may stray, in page units), stroke= and background= ("#rgb", "#rrggbb" or a CSS colour name in every language, beside that language's own numeric form; background= std::nullopt for transparent), width= (the stroke's, in page units), edges=, curves=, isocurves=, polylines= (which line sets are drawn; edges by default), and silhouettes= (also draw where each solid's surfaces turn away from the eye — the outline a sphere has no edge for, on by default: a sphere's and a torus's only curves are the seams where their one face meets itself, which are not edges of the body and are never drawn, so without it those two draw a blank page. A line set in its own right, so silhouettes= with edges= off draws the outline alone).

The SVG *is* the drawing, not a picture of one: with path, this writes it to the file and returns std::nullopt; without, it returns the SVG text instead of writing anything. returns an Error in its Result on a refused option (naming the field) or a failed write.

Node.scene

The scene it belongs to.

Not exposed: keep the Scene you opened.

Node::index()

std::uint32_t index() const noexcept

Its index in the scene, stable while the scene is open: a key for a map of what has been uploaded.

Node::name()

std::string name() const

The name the file gave it, or empty.

Node::id()

std::string id() const

What the file calls it: a STEP #N, an IFC GlobalId, a Rhino object id.

Node::kind()

std::string kind() const

Its type in the file: an IFC class, an openNURBS class, a STEP shape kind.

Node::label()

std::string label() const

Something to put in a tree row: the name, else the kind, else #index.

Node::depth()

std::uint32_t depth() const

How far down the tree it sits; a root is zero.

Node::generator()

std::string generator() const

What its geometry was before it was triangles — brep, mesh, csg — or empty for a node that draws nothing.

Node::visible()

bool visible() const

Whether the file says to show it when opened. The node's own switch, not inherited; true where the format has no such switch.

Node::visible_now()

bool visible_now() const

Node::visible() with every ancestor consulted: a layer switched off hides what hangs under it.

Node::locked()

bool locked() const

Whether the file says it cannot be selected or edited (Rhino's lock, own or by layer). A locked node is still drawn.

Node::parent()

std::optional<Node> parent() const

The node containing this one, or std::nullopt for a root.

Node::children()

std::vector<Node> children() const

The nodes directly under this one.

Node::instance_of()

std::optional<Node> instance_of() const

The node whose geometry this one places, or std::nullopt. A part placed seventy times is one mesh and seventy transforms; this is how a caller knows to upload it once.

Node::select_as()

Node select_as() const

What a click on this node's geometry should select — usually itself. Formats that hang geometry under the object it belongs to (an IFC representation under its product) point back at the object.

Node::attributes()

std::vector<Attribute> attributes() const

Everything the file said about the node, as Attribute values.

Node::can_mesh()

bool can_mesh() const

Whether the node has geometry of its own to draw. Builds nothing; most nodes are structure and answer false.

Node::colour()

std::optional<std::array<float, 4>> colour() const

The colour the file gave it as RGBA in 0–1, or std::nullopt — most STEP files carry none, and the caller's default is the right answer.

Node::transform()

Matrix4 transform() const

Where the node's geometry sits: a 4×4 in double precision, composed through every frame above it. Meshes stay single precision in their own frame under a double transform, so a model at survey coordinates keeps its millimetres.

Node::raw_transform()

std::array<double, 16> raw_transform() const

The same matrix as 16 numbers in the C API's column-major order, ready for a GPU uniform.

Node::bounds()

Bounds bounds() const

The extent of the node's geometry in that geometry's own frame. Builds the geometry if needed; carry it through Node::transform() for world coordinates.

Node::bounds64()

Bounds64 bounds64() const

Node::bounds() in double precision: the node's extent in that geometry's own frame, unnarrowed — exact far from the origin, where Node::bounds()'s float32 corners are not. Builds the geometry if needed.

Node::mesh()

Mesh mesh() const

Its triangles in their own frame, built now if they have not been. A node that instances another hands back the instanced node's arrays — the same memory for every placement. The arrays are views into the scene — copies in Node and Godot; see Lifetimes.

Node::mesh64()

Mesh64 mesh64() const

Node::mesh() in double precision: the document's own mesh, lent rather than narrowed — the same indices, Node::mesh()'s positions being exactly these rounded. For a mesh used as geometry (an exporter, a measurement, a solver) far from the origin, where float32 cannot hold the file's coordinates. Where the wrapper hands out views over the scene's memory, forgetting the scene's meshes invalidates them — these lend the document's own mesh, where the float mesh is a copy the library keeps and a forget leaves alone; asked again it is built again. Each one is stamped with the scene's forget count, so reading its arrays after a forget raises a stale view rather than reading freed memory — an array already taken out of it before the forget is not caught.

A checked build counts the scene's forgets and reports a stale view rather than reading freed memory; an unchecked one reads it, as the C ABI says.

Node::fem_mesh()

Result<FemMesh> fem_mesh(double tolerance = 0.01, double max_size = 0.0, const std::optional<std::array<double, 16>>& placement = std::nullopt) const

Its body meshed for a solver, as a FemMesh: nodes welded by bits — two mesh points are one node only where their coordinates are the same doubles, so no tolerance ever merges two distinct points and a crack stays a crack — triangles wound outward, and every node tagged with the lowest-dimension B-rep entity it lies on. Meshed in the part's own frame, following the hop from an instance to the shape it draws that Node::mesh() follows, so a node instanced six times meshes once.

tolerance is the chordal tolerance in model units, and it alone governs how closely the mesh follows the geometry. max_size is a size ceiling, 0 for none (curvature alone): it splits boundary segments to at most that length and lays interior stations max_size / √2 apart as a target, and it adds nodes without refining the boundary geometry — a caller that wants the rim nearer its curve lowers the tolerance, where max_size only makes the elements smaller. FemMesh::longest_edge() is what the mesh actually came to, and the figure to check.

placement is sixteen numbers, in Placement::raw_transform()'s own column-major order — which Node::bounds_placed() takes too, in the wrappers that have it — applied in double precision throughout. The kernel's Solid::fem_mesh() takes twelve instead — an origin and three axes — so a caller moving between the two reformats the placement.

The space is the body's own for a B-rep and the scene's for a mesh, which FemMesh::from_mesh() is the flag for: under a convention other than the native one those are two different spaces, and mixing these nodes with Node::transform() without reading it gives a rotated part.

A cracked body is not a failure: it comes back with FemMesh::watertight() false and its cracks in FemMesh::open_edges() and FemMesh::folded_edges(), and nothing is welded shut to make it look sound. It returns an Error in its Result for a tolerance or size the mesher refuses, a placement that is not sixteen finite and invertible numbers, a node with neither a B-rep nor a mesh (an assembly, a storey, a layer, a curve), and a body that meshes to no triangles at all.

The unlicensed notice is printed here, once, and on neither of the two .msh calls — where the kernel library is the other way round. Read FemMesh::msh_text() before porting either convention onto the other side.

Node::mesh_lod()

Mesh mesh_lod(std::uint32_t level) const

Its triangles at a coarser level of detail: 0 is Node::mesh() itself, 1 up to cadaclysm::lod_levels() each about a quarter of the triangles of the one before, and past that empty. Every level shares the level-0 vertices — the same positions, only the indices differ — so upload the vertices once and switch level by drawing a different index range. Simplifying costs about what meshing did, once per node.

Node::lod_error()

float lod_error(std::uint32_t level) const

How far Node::mesh_lod() at this level moved the surface, in the scene's units — what to pick a level by against the pixel size on screen. Zero at level 0.

Node::surfaces()

Surfaces surfaces() const

Its faces as exact surfaces plus the trim loops that cut them, each in the surface's own (u, v). Nothing is meshed to produce it, and reading it costs Node::mesh() nothing. Empty where the reader has no parametric description (a tessellated body, a mesh format). In the file's frame — see Scene::surface_matrix().

Node::edges()

Polylines edges() const

Its feature edges as polylines, for an outline overlay. Builds the geometry if needed.

Node::brep()

std::optional<Brep> brep() const

Its exact B-rep, as a Brep, for the kernel's Solid::from_node() to operate on — or std::nullopt where it has none (a mesh, a curve, a CSG body, a JT or OpenSCAD part). Shared with the scene, not copied.

Node::curves()

Polylines curves() const

Its free curves as polylines; a 2D drawing is all of these.

Node::isocurves()

Polylines isocurves() const

Lines ruled across its surfaces, so a curved face reads as curved in a wireframe. A flat face yields its outline, so these can overlap Node::edges().

Node::edge_beziers()

Beziers edge_beziers() const

Its feature edges as cubic Bézier curves, a Beziers — exact where the file's curves were, where Node::edges() are their chords. Builds the geometry if needed.

Node::edge_beziers64()

Beziers64 edge_beziers64() const

Node::edge_beziers() in double precision, kept beside the float Béziers: a forget leaves it valid, unlike Node::mesh64() — in a wrapper that lends views. Node and Godot copy both, so a forget leaves both valid.

Node::curve_beziers()

Beziers curve_beziers() const

Its free curves as cubic Béziers; see Node::edge_beziers().

Node::curve_beziers64()

Beziers64 curve_beziers64() const

Node::curve_beziers() in double precision; see Node::edge_beziers64().

Node::isocurve_beziers()

Beziers isocurve_beziers() const

Its isocurves as cubic Béziers; see Node::edge_beziers().

Node::isocurve_beziers64()

Beziers64 isocurve_beziers64() const

Node::isocurve_beziers() in double precision; see Node::edge_beziers64().

Node::collision()

std::optional<Collision> collision(std::uint32_t hull_budget = 0) const

The collision body for what this node draws, as a Collision: a box, sphere, capsule or cylinder where one fits, else a convex hull. hull_budget is the most triangles a hull may have; 0 (the default) asks for the Unity limit of 255 and is not clamped to it. std::nullopt for a node that draws nothing. Builds the mesh if it is not built; cached per node and budget.

Node::collision_hull()

CollisionHull collision_hull(std::uint32_t hull_budget = 0) const

The convex hull Node::collision() counted, as triangles — a CollisionHull, a view into the scene (a copy in Node and Godot). Empty for a node that draws nothing. Asking the same node for a different hull_budget refits it and frees the hull the earlier call returned: hold one budget.

Node::is_meshed()

bool is_meshed() const

Whether its mesh has been built and is held — by Scene::realize_all(), by an ask for it, or by anything else that needed it. A renderer drawing the part from its surfaces checks it never paid for the triangles.

Node::triangle_estimate()

std::int64_t triangle_estimate() const

About how many triangles Node::mesh() would give, without building it — for sizing a budget before meshing. Exact for a stored mesh, within a few tens of percent for a B-rep; -1 where the reader cannot say without doing the work, and for a node that draws nothing. Treat -1 as unknown, never as zero.

Node::bounds_placed()

Bounds bounds_placed(const std::array<double, 16>& placement) const
Bounds bounds_placed() const

The box of what this node draws under a placement (16 numbers, column-major, as Placement::raw_transform(); std::nullopt for the identity), for a part drawn from its surfaces: every sample is carried through the convention and the placement before it is boxed, so it is tighter than placing the corners of Node::bounds(). All zeros for a part with no surfaces.

Node::bounds_placed64()

Bounds64 bounds_placed64(const std::array<double, 16>& placement) const
Bounds64 bounds_placed64() const

Node::bounds_placed() in double precision, from the unnarrowed surface samples; see Node::bounds64().

Node::surface_edges()

Polylines surface_edges() const

Its face boundaries taken from its trimmed surfaces — the outline that costs no tessellation, where Node::edges() meshes the part. In the surfaces' own frame (Scene::surface_matrix()); empty without surfaces. A shared edge appears once from each face.

Node::surface_edge_beziers()

Beziers surface_edge_beziers() const

Its edges as the exact curves, a Beziers, where the part has them without meshing — a Rhino extrusion's rims are its profile — and empty everywhere else. A caller drawing from surfaces tries it before Node::surface_edges(), whose trims are thinned to the mesh tolerance and so cut chords across a curve the surface rounds. The same segments as Node::edge_beziers(), in the scene's space: not the surfaces' frame, so no Scene::surface_matrix().

Node::edge_colours()

std::vector<std::optional<std::array<float, 4>>> edge_colours() const

One RGBA per polyline of Node::edges(), and none for an edge the file does not style; empty when nothing is styled. STEP files carry them as CURVE_STYLE styling.

Node::surface_edge_colours()

std::vector<std::optional<std::array<float, 4>>> surface_edge_colours() const

Node::edge_colours() for Node::surface_edges().

Node::surface_isocurves()

Polylines surface_isocurves() const

Its isocurves taken from its trimmed surfaces and clipped to the trims, without meshing: lines at a surface's bend lines and an even spread where it has none; a flat face gets none. In the surfaces' frame; empty without surfaces.

Node::surface_pick()

std::optional<Vec3> surface_pick(const Vec3& from, const Vec3& to) const

Where a segment first meets this part's surfaces, or std::nullopt. Exact — it answers from the surface and tests the trims at the hit's own (u, v) — and in the surfaces' own frame: carry a ray from the scene's space through the inverse of Scene::surface_matrix() first.

Node::surface_proxy_mesh()

Mesh surface_proxy_mesh(std::uint32_t cells) const

A coarse mesh over its surfaces for the things that need triangles and not a picture — ray tracing, distance fields: each face gridded cells by cells over its trim window, two triangles a cell whose centre lies inside the trims, never welded. Built once per part at the first cells asked for. In the scene's space, like Node::mesh(). Empty without surfaces or for zero cells.

Node::save_mesh()

Result<void> save_mesh(const std::string& path, const std::string& format = "stl") const

Write this node's own mesh — where it is defined, without its placement — in one of cadaclysm::mesh_formats(). A node that draws nothing, or an unknown format, returns an Error in its Result; ask Node::can_mesh() first to grey out a menu entry. To write the whole model, see Scene::save().

Node::walk()

std::vector<Node> walk() const

This node and every node under it, parents before children.

Node::show()

Result<void> show(const O& options = O{}) const

Draw what this node and everything under it places with the viewer in use — shown by handle on its scene, hiding the siblings along the path from the scene's root to this node (each ancestor's own geometry stays visible) and framing this node. Keywords as Scene::show(). With the GPU library (import cadaclysm.view.wgpu) the drawing replaces what one shared window shows and stays live — at the REPL, in IPython and in Jupyter by themselves, in a script until it exits; cadaclysm.view.View draws several items or several windows.

Takes a cadaclysm::ShowOptions (edges true by default, azimuth/elevation/up std::optional). A tolerance is refused: a document is drawn at the tolerance it was read with. Blocks until the window is closed on the wgpu library (cadaclysm::view::use_wgpu()); the terminal prints a still. Several items or a window that stays: cadaclysm::View. A member template: #include <cadaclysm/view.hpp> to call it, and link cadaclysm::view_loader (cadaclysm::view is the linked C library, for hosts that call cadaclysm_view.h directly). The shown Node borrows from its Scene: keep the Scene open.

Node::view()

auto view(const O& options = O{}) const

Orbit this node and everything under it; returns the camera where it was left — a dict of eye, target, up, orthographic, azimuth and elevation — and pick, what was last clicked (item, node, face) or None. A fresh window, run until closed, with the GPU library.

Takes the options show does; returns a Result<Camera>.

Node::svg()

Result<void> svg(const std::string& path, const SvgOptions& options = SvgOptions()) const

This node's own wireframe as SVG, in its own frame — Scene::svg()'s keywords, read from just this node rather than every placement. With path, writes the file and returns std::nullopt; without, returns the SVG text. returns an Error in its Result on a refused option (naming the field) or a failed write.

Brep::pointer()

const CadaclysmBrep* pointer() const noexcept

The brep's C pointer, which the kernel's wrapper hands across. returns an Error in its Result once released.

Brep::layout_id()

static std::string layout_id()

How this library lays a brep out in memory: its compiler, target and source. The kernel shares a brep only with a reader whose id equals its own.

Brep::manifold()

Result<Manifold> manifold() const

Whether its faces make a manifold — every edge bordered by one face or two, the faces round every vertex one fan — and whether it is closed, as a Manifold. Read off the topology the file wrote, not a mesh. returns an Error in its Result once released.

Brep::sewed()

Result<std::pair<Brep, SewReport>> sewed(std::optional<double> tolerance = std::nullopt, std::optional<double> vertex = std::nullopt) const

This brep with its free edges sewn, and what was sewn, as a new Brep and a SewReport; this one is left as it was. Two free edges become one shared edge where both their ends coincide within vertex — by default the rounding Brep::manifold() merges vertices at — and their curves lie within tolerance of each other, by default vertex too, so only edges that are one curve written twice are joined. A larger tolerance also joins two curves between the same two vertices that part by up to it; vertex is what decides which edges are candidates at all, and raising it is what could close a slot. Nothing moves. returns an Error in its Result once released.

Brep::release()

void release() noexcept

Give the reference back now. Leaving a with block, or the garbage collector, does it otherwise.

Placement.scene

The scene it belongs to.

Not exposed: keep the Scene you opened.

Placement::index()

std::uint32_t index() const noexcept

Its index in Scene::placements().

Placement::geometry()

Node geometry() const

The node whose mesh, edges and curves this draws.

Placement::select()

Node select() const

What a click on this drawing selects: the placement's own node rather than the shared shape, which would light up every copy.

Placement::transform()

Matrix4 transform() const

Where to draw it: a 4×4, already composed through every frame from the root.

Placement::raw_transform()

std::array<double, 16> raw_transform() const

The same matrix as 16 numbers, column-major.

Link.scene

The scene this link belongs to.

Not exposed: keep the Scene you opened.

Link::index()

std::uint32_t index() const noexcept

Its position in the scene's links.

Link::name()

std::string name() const

Its name, as the file gives it.

Link::nodes()

std::vector<Node> nodes() const

The topmost node of each subtree it moves, in node order: moving these moves everything under them.

Joint.scene

The scene this joint belongs to.

Not exposed: keep the Scene you opened.

Joint::index()

std::uint32_t index() const noexcept

Its position in the scene's joints.

Joint::name()

std::string name() const

Its name, as the file gives it.

Joint::start()

Link start() const

The link it starts at.

Joint::end()

Link end() const

The link it ends at.

Joint::pair()

std::optional<Pair> pair() const

How this joint moves: the kinematic pair naming it, a Pair, or std::nullopt when the file gives it none.

Pair::kind()

PairKind kind() const noexcept

One of thirteen kinds: revolute, prismatic, cylindrical, spherical, spherical_with_pin, planar, universal, homokinetic, screw, fully_constrained, unconstrained, low_order, other.

Pair::type_name()

std::optional<std::string> type_name() const

For other: the pair's entity type name (GEAR_PAIR). std::nullopt otherwise.

Pair::pitch()

std::optional<double> pitch() const

For screw: its pitch, a length per revolution in the scene's units. std::nullopt otherwise.

Pair::frame_start()

Matrix4 frame_start() const

The pair's contact frame fixed in its joint's start link, in world coordinates at the file's rest pose: a 4x4, already composed like Node::transform().

Pair::frame_end()

Matrix4 frame_end() const

The pair's contact frame fixed in its joint's end link.

Pair::raw_frame_start()

std::array<double, 16> raw_frame_start() const

frame_start as 16 numbers, column-major — like Node::raw_transform().

Pair::raw_frame_end()

std::array<double, 16> raw_frame_end() const

frame_end as 16 numbers, column-major.

Pair::freedoms()

std::vector<Freedom> freedoms() const

Its degrees of freedom, in the reader's per-kind order, each a Freedom. A State's values compose in this order.

Freedom::motion

Motion motion

rotation or translation.

Freedom::axis

FreedomAxis axis

x, y or z: the contact frames' axis the motion is about or along.

Freedom::lower

std::optional<double> lower

The lower limit — radians for a rotation, a length for a translation — or std::nullopt for unbounded.

Freedom::upper

std::optional<double> upper

The upper limit, or std::nullopt for unbounded.

State::index

std::uint32_t index

Its position in the scene's states.

State::name

std::string name

Its name, as the file gives it.

State::values

std::vector<StateValue> values

One row per joint this state sets, in file order: the joint, then one value per freedom of its pair, in the pair's freedom order.

Sequence::index

std::uint32_t index

Its position in the scene's sequences.

Sequence::name

std::string name

Its name: its representation's, name #2 and on for further sequences in one representation.

Sequence::closed

bool closed

Whether the motion returns to its first segment (its last segment is not discontinuous).

Sequence::seconds_per_unit

std::optional<double> seconds_per_unit

Seconds per unit of the parameter where the file states a time unit, or std::nullopt where it states none (the parameter is then read as seconds).

The seconds rule, to play a sequence on a clock: with a duration, stretch start to end (plus the closing span of a closed sequence, (end - start) divided by one less than the number of segments) over it; with none, seconds are (t - start) times Sequence::seconds_per_unit, or times 1 where it is std::nullopt.

Sequence::segments

std::vector<Segment> segments

The segments, in file order (at least two), each a Segment.

Sequence::start()

double start() const

The first segment's parameter.

Sequence::end()

double end() const

The last segment's parameter (the closing span of a closed sequence not included).

Sequence::pose()

Result<Pose> pose(double t, std::optional<Link> ground = std::nullopt) const

The mechanism posed by this sequence at parameter t, in the file's own parameter: a segment is a keyframe of its state, a discontinuous segment holds until the next and every other kind moves linearly, an open sequence holds its ends and a closed one wraps (its closing span, last back to first, is the mean of its spans, and each joint loops on its own keys, so one that only some segments name still comes back round smoothly). ground is held fixed as Scene::pose() does. returns an Error in its Result for a t that is not finite.

Segment::state

State state

The State this segment reaches.

Segment::t

double t

Its parameter.

Segment::interpolation

std::string interpolation

How the motion leaves it: "undefined", "discontinuous", "synchronous" or "linear".

WorkSchedule::index

std::uint32_t index

Its position in the scene's schedules.

WorkSchedule::name

std::string name

Its name, else its identification, else schedule #k (k from 1, in file order).

WorkSchedule::identification

std::string identification

Its identification, empty where the file gives none.

WorkSchedule::kind

std::string kind

"planned", "actual", "baseline", "notdefined" or "other".

WorkSchedule::kind_name

std::string kind_name

The text of a user-defined kind (kind is "other"); empty otherwise.

WorkSchedule::start

std::optional<double> start

The schedule's start date, or std::nullopt where the file gives none.

WorkSchedule::finish

std::optional<double> finish

The schedule's finish date, or std::nullopt where the file gives none.

WorkSchedule::tasks()

std::vector<Task> tasks() const

Its tasks, in file order, each a Task.

WorkSchedule::links()

std::vector<TaskLink> links() const

Its task links (IfcRelSequence), in file order, each a TaskLink.

WorkSchedule::at()

Result<std::vector<ElementState>> at(double date, std::string_view dates = "scheduled") const

What each element this schedule names is doing on date, as ElementState rows in node order; an element no task names is not listed. dates says which of a task's dates to play: "scheduled" (the default) or "actual", where each actual date overrides its scheduled one. A task builds its nodes over its window, or removes them (demolition, dismantling, removal, disposal); summary tasks span their children. returns an Error in its Result for a date that is not finite, and a dates other than those two words is refused.

Task.schedule

The WorkSchedule it belongs to.

Not exposed: keep the WorkSchedule you read it from.

Task::index

std::uint32_t index

Its position in its schedule's tasks.

Task::name

std::string name

Its name.

Task::identification

std::string identification

Its identification, empty where the file gives none.

Task::kind

std::string kind

"attendance", "construction", "demolition", "dismantle", "disposal", "installation", "logistic", "maintenance", "move", "operation", "removal", "renovation", "notdefined" or "other".

Task::kind_name

std::string kind_name

The text of a user-defined kind (kind is "other"); empty otherwise.

Task::status

std::string status

Its status as the file writes it, empty where none.

Task::milestone

bool milestone

Whether it is a milestone: an instant, not a span.

Task::parent()

std::optional<Task> parent() const

The summary task nesting it, or std::nullopt for a top-level task.

Task::time

TaskTime time

Its dates, a TaskTime.

Task::nodes()

std::vector<Node> nodes() const

The nodes it builds or removes, each a Node.

TaskTime::schedule_start

std::optional<double> schedule_start

The scheduled start.

TaskTime::schedule_finish

std::optional<double> schedule_finish

The scheduled finish.

TaskTime::early_start

std::optional<double> early_start

The early start.

TaskTime::early_finish

std::optional<double> early_finish

The early finish.

TaskTime::late_start

std::optional<double> late_start

The late start.

TaskTime::late_finish

std::optional<double> late_finish

The late finish.

TaskTime::actual_start

std::optional<double> actual_start

The actual start.

TaskTime::actual_finish

std::optional<double> actual_finish

The actual finish.

TaskTime::duration

std::optional<double> duration

The scheduled duration, in seconds.

TaskLink::from

Task from

The predecessor, a Task.

TaskLink::to

Task to

The successor, a Task.

TaskLink::kind

std::string kind

"finish_start", "start_start", "finish_finish", "start_finish", "notdefined" or "other".

TaskLink::kind_name

std::string kind_name

The text of a user-defined kind (kind is "other"); empty otherwise.

TaskLink::lag

std::optional<double> lag

The time lag, in seconds, or std::nullopt where the file gives none.

ElementState::node

Node node

The Node.

ElementState::phase

std::string phase

"unbuilt", "building", "built", "demolishing" or "demolished".

ElementState::progress

double progress

How far through the window that governs the phase, 0 to 1: 0 unbuilt, 1 built or demolished.

ElementState::variance

std::optional<double> variance

Seconds late (positive) or early (negative) against the schedule, or std::nullopt where there is none to give.

Pose::ground

Link ground

The link held fixed.

Pose::unsolved

std::vector<Joint> unsolved

Joints that close a loop and were not honoured, in file order, each a Joint.

Pose::out_of_range

std::vector<std::tuple<Joint, std::uint32_t, double>> out_of_range

One entry per given value that fell outside its freedom's range: the Joint, the freedom's index in its pair, and the value used.

Pose::transform()

Matrix4 transform(const Node& node) const

A node's posed transform, in the same form Node::transform() returns.

Pose::raw_transform()

std::array<double, 16> raw_transform(const Node& node) const

The same matrix in the ABI's own column-major order, as 16 numbers.

Pose::show()

Result<void> show(const O& options = O{}) const

Draw this pose's scene with the viewer in use, as Scene::show() does, but with each placement moved by its select node's pose — each node a joint turned draws at its posed transform rather than its rest one. Same keywords as Scene::show().

Takes a cadaclysm::ShowOptions (edges true by default, azimuth/elevation/up std::optional). A tolerance is refused: a document is drawn at the tolerance it was read with. Blocks until the window is closed on the wgpu library (cadaclysm::view::use_wgpu()); the terminal prints a still. Several items or a window that stays: cadaclysm::View. A member template: #include <cadaclysm/view.hpp> to call it, and link cadaclysm::view_loader (cadaclysm::view is the linked C library, for hosts that call cadaclysm_view.h directly). The shown Pose borrows from its Scene: keep the Scene open.

Pose::view()

auto view(const O& options = O{}) const

Pose::show()'s orbiting twin; returns what Scene::view() returns — the camera where it was left, and the last pick.

Takes the options show does; returns a Result<Camera>.

Mesh::positions()

Span<const float> positions() const

Three floats a vertex.

Mesh::normals()

Span<const float> normals() const

Three floats a vertex, or std::nullopt for a mesh that carries none.

Mesh::uvs()

Span<const float> uvs() const

Two floats a vertex, or std::nullopt: only readers asked for world-scale UVs fill them. One unit of u or v is one world unit, so faces overlap in UV space — a tiling material, not a lightmap.

Mesh::colors()

Span<const float> colors() const

Four floats (RGBA) a vertex, or std::nullopt — the common case. Only a body painted in several colours, opened with colours on, carries them.

Mesh::indices()

Span<const std::uint32_t> indices() const

Three vertex indices a triangle, unsigned 32-bit.

Mesh::vertex_count()

std::uint32_t vertex_count() const

How many vertices.

Mesh::index_count()

std::uint32_t index_count() const

How many indices: three a triangle.

Mesh::triangle_count()

std::uint32_t triangle_count() const

How many triangles.

Mesh::copy()

MeshData copy() const

The same arrays in memory of your own, safe to keep after Scene::close(). Deliberately visible: on a large model this is where the gigabytes go.

Polylines::positions()

Span<const float> positions() const

Three floats a point, the runs end to end.

Polylines::counts()

Span<const std::uint32_t> counts() const

How many points each run has, in order.

Polylines::polyline_count()

std::uint32_t polyline_count() const

How many runs.

Polylines::vertex_count()

std::uint32_t vertex_count() const

How many points in all.

Polylines::segment_indices()

std::vector<std::uint32_t> segment_indices() const

Index pairs into the positions, two per line segment — what GL_LINES and every pair-taking API want. Indices rather than points, so a caller can transform the points once and expand afterwards.

Polylines::segments()

std::vector<float> segments() const

The segment endpoints themselves, two points per segment.

Beziers::points()

Span<const float> points() const

Four control points a curve, three floats each.

Beziers::weights()

Span<const float> weights() const

A weight per control point: all ones for a polynomial curve, and the weights that make a circular arc exact for a rational one.

Beziers::count()

std::uint32_t count() const

How many curves.

Beziers::copy()

BeziersData copy() const

The same arrays in memory of your own, safe to keep after Scene::close().

Mesh64::positions()

Span<const double> positions() const

Three doubles a vertex.

Mesh64::normals()

Span<const double> normals() const

Three doubles a vertex, or std::nullopt for a mesh that carries none.

Mesh64::uvs()

Span<const double> uvs() const

Two doubles a vertex, or std::nullopt; see Mesh::uvs().

Mesh64::colors()

Span<const float> colors() const

Four floats (RGBA) a vertex, or std::nullopt — always float32, as Mesh::colors() are.

Mesh64::indices()

Span<const std::uint32_t> indices() const

Three vertex indices a triangle, unsigned 32-bit — the same triangles as Mesh::indices().

Mesh64::vertex_count()

std::uint32_t vertex_count() const

How many vertices.

Mesh64::index_count()

std::uint32_t index_count() const

How many indices: three a triangle.

Mesh64::triangle_count()

std::uint32_t triangle_count() const

How many triangles.

Mesh64::copy()

MeshData64 copy() const

The same arrays in memory of your own, safe to keep after a forget or Scene::close().

Beziers64::points()

Span<const double> points() const

Four control points a curve, three doubles each.

Beziers64::weights()

Span<const double> weights() const

A weight per control point, as doubles.

Beziers64::count()

std::uint32_t count() const

How many curves.

Beziers64::copy()

BeziersData64 copy() const

The same arrays in memory of your own, safe to keep after Scene::close().

Bounds64::min

std::array<double, 3> min

The low corner.

Bounds64::max

std::array<double, 3> max

The high corner.

Bounds64::is_empty()

bool is_empty() const noexcept

Whether this is the all-zero box that stands for nothing.

Bounds64::size()

std::array<double, 3> size() const noexcept

The extent along each axis.

Bounds64::centre()

std::array<double, 3> centre() const noexcept

The midpoint.

Collision::shape_name()

std::string_view shape_name() const noexcept

none, box, sphere, capsule, cylinder or hull.

Collision::error

double error

How far the fitted shape strays from the mesh, in the scene's units; zero for an exact fit.

Collision::frame

std::array<double, 16> frame

The oriented box's frame, 16 numbers column-major.

Collision::half_extent

std::array<double, 3> half_extent

Half the oriented box's size along its own three axes.

Collision

struct Collision
std::uint32_t shape
std::uint32_t confidence
std::uint32_t axis
double radius
double height
std::uint32_t hull_vertex_count
std::uint32_t hull_index_count

shape, confidence, axis, radius, height, hull_vertex_count and hull_index_count, alongside frame, half_extent, error and shape_name.

CollisionHull

class CollisionHull
Span<const float> positions() const
Span<const std::uint32_t> indices() const
std::uint32_t vertex_count() const
std::uint32_t index_count() const

The hull's positions, indices, vertex_count and index_count.

Meshlets::build()

static Result<Meshlets> build(Span<const float> positions, Span<const float> normals, Span<const std::uint32_t> indices, std::uint32_t max_triangles, std::uint32_t max_vertices, std::int32_t levels = 0)

Split positions (three floats a vertex), normals (the same, or none) and indices (three a triangle) into meshlets of at most max_triangles and max_vertices each. The limits are the consumer's own, with no default: Nanite takes 128 and 256, a mesh-shader pipeline 124 and 64, and the vertex cap is the one that bites. levels above 0 groups and simplifies each level into the next until one meshlet is left; Meshlets::level() and a meshlet's children say which is which. A budget of zero, or arrays whose lengths do not agree, returns an Error in its Result before the library is called.

Meshlets::count()

std::uint32_t count() const

How many meshlets, every level counted.

Meshlets::triangle_count()

std::uint32_t triangle_count(std::uint32_t i) const

How many triangles meshlet i has.

Meshlets::vertex_count()

std::uint32_t vertex_count(std::uint32_t i) const

How many vertices meshlet i has.

Meshlets::level()

std::uint32_t level(std::uint32_t i) const

0 for a leaf over the mesh itself, higher for a simplified level above it.

Meshlets::group()

std::uint32_t group(std::uint32_t i) const

Which group of a levelled build meshlet i belongs to.

Meshlets::error()

float error(std::uint32_t i) const

How far meshlet i's level moved the surface; zero at level 0.

Meshlets::child_count()

std::uint32_t child_count(std::uint32_t i) const

How many finer meshlets sit below meshlet i.

Meshlet

struct Meshlet
std::uint32_t index
std::uint32_t level
std::uint32_t group
float error
std::uint32_t vertex_count() const noexcept
std::uint32_t triangle_count() const noexcept
std::vector<float> positions
std::vector<float> normals
std::vector<std::uint32_t> indices
std::vector<std::uint32_t> children
Meshlet meshlet(std::uint32_t i) const

One meshlet's arrays and numbers, copied out: index, level, group, error, vertex_count, triangle_count, positions, normals (zeros where the mesh had none), indices (into the meshlet's own vertices) and children. The arrays are yours.

Meshlets::free()

void free() noexcept

Give the meshlets back. Idempotent; the collector or scope does it otherwise.

Meshlets::freed()

bool freed() const noexcept

Whether Meshlets::free() has run.

FemMesh::nodes()

Span<const double> nodes() const

Every node's position, three doubles each, placed by Node::fem_mesh()'s placement and in the space FemMesh::from_mesh() names. Every node is used by at least one triangle.

The five arrays are Spans into the handle's own memory, and every accessor here checks the handle in both modes — not only under CADACLYSM_CHECKED, as the scene's and the solid's views do, because what it guards is a pointer handed to C, the way Meshlets' own check does, rather than a borrowed view's owner. So a call on a freed mesh — an array, a count, or either .msh call — goes to CADACLYSM_BAD_ACCESS rather than returning an Error, even in a release build. A Span already in hand is a pointer and a length from then on, and reading one after free() — or after the FemMesh itself went out of scope — reads freed memory in either mode: measured on a body away from the origin, it still gave that body's own coordinates until the block was reused. So hold the FemMesh while you read a span, and copy (std::vector<double>(mesh.nodes().begin(), mesh.nodes().end())) anything that must outlive it. FemEdge's nodes and runs borrow the same way.

FemMesh::triangles()

Span<const std::uint32_t> triangles() const

Three node indices a triangle, wound outward — a mirroring placement is wound back.

FemMesh::triangle_face()

Span<const std::uint32_t> triangle_face() const

Which B-rep face each triangle lies on, one per triangle, into the body's FemMesh::face_count() faces.

FemMesh::node_kind()

Span<const std::uint32_t> node_kind() const

What each node lies on — 0 a B-rep vertex, 1 an edge, 2 a face — one per node: the lowest-dimension entity it lies on, which is the .msh format's own classification rule. FemMesh::node_entity() says which entity of that kind.

FemMesh::node_entity()

Span<const std::uint32_t> node_entity() const

Which vertex, edge or face each node lies on, read by the matching FemMesh::node_kind(): an index into FemMesh::vertices(), into FemMesh::edges(), or into the body's faces.

FemMesh::face_count()

std::uint32_t face_count() const

The body's faces; FemMesh::triangle_face() and a FemMesh::node_kind() of 2 index them.

FemMesh::edges()

Result<std::vector<FemEdge>> edges() const

One FemEdge per B-rep edge, in the order a FemMesh::node_kind() of 1 indexes them. Empty for a FemMesh::from_mesh() body, which has no B-rep edges at all.

FemEdge

struct FemEdge
std::uint32_t id
Span<const std::uint32_t> nodes
Span<const std::uint32_t> runs
std::pair<std::uint32_t, std::uint32_t> faces
std::pair<std::uint32_t, std::uint32_t> ends
bool closed
bool seam
std::vector<Span<const std::uint32_t>> chains() const

One B-rep edge's chain of nodes, and where that chain breaks. nodes are this mesh's node indices in order along the edge, its end vertices included. runs says where the chain breaks: each entry is a start offset into nodes, and the nodes from one offset up to the next — the last offset running to the end — are a polyline of their own, with nothing joining across a boundary. The two ends either side of a boundary are two points of the edge with no mesh edge between them, a crack along the edge or a stretch of it sampled on one face only. (0,) is the ordinary answer, and a caller reading nodes as one polyline without looking here jumps the gap silently.

faces is (face_a, face_b) and ends is (end_a, end_b), the second of each a sentinel where there is none — an open body's rim, or both ends at one vertex. 0 is a real face and a real vertex, not a sentinel. Which end comes first is the first trim's direction and means nothing else: the pair bounds the edge, it does not orient it. closed where the nodes make one loop, never with more than one run; seam where one face bounds the edge twice, and both faces are then that same face.

id is the body's own edge id, not this mesh's edge index: FemMesh::edges() is a densely renumbered subset of the body's edges, ascending by id, with every edge collapsed to a point left out, so edge 0 of a STEP body's mesh routinely has an id in the hundreds. Everything else that names an edge means the index — a FemMesh::node_kind() of 1 read through FemMesh::node_entity(), the third number of a FemMesh::open_edges() or FemMesh::folded_edges() row, and the edge_<i> physical group of FemMesh::msh_text() — and this is the one way back from any of them to the topology the file wrote.

FemMesh::vertices()

Result<std::vector<FemVertex>> vertices() const

One FemVertex per B-rep vertex, in the order a FemMesh::node_kind() of 0 indexes them. Empty for a FemMesh::from_mesh() body.

FemVertex

struct FemVertex
std::uint32_t node
Vec3 point
bool has_position

One B-rep vertex: node is the mesh node there, a sentinel where the mesh has none, which is ordinary rather than a fault — the analysis rebuilds a vertex wherever two trims meet, so a sphere has 48 of them where the mesh has two points, and a caller walking these skips the sentinel instead of reading it as a gap.

point is where the topology says the vertex is, in the same space and under the same placement as FemMesh::nodes() — the file's own vertex rather than a mesh node, so the two can differ by the reader's rounding. Meaningless unless has_position: it is all zeros then, a point no geometry has and one a solver would read as a node at the origin.

FemMesh::open_edges()

Result<std::vector<std::array<std::uint32_t, 3>>> open_edges() const

Every crack, as (a, b, brep_edge): a directed mesh edge (a, b) with no (b, a), and the B-rep edge both nodes lie on where they share one.

Empty unless the body's topology is closed — for a B-rep body, whose mesh is otherwise not asked about at all. The census asks whether a body that ought to enclose a solid does, and an open one — a sheet, a bag of surfaces, a shell the file itself wrote open — makes no such claim to check: its rim is not a crack. So such a body reports FemMesh::watertight() false with this and FemMesh::folded_edges() both empty, and that trio of answers together is what says "not asked", not "nothing found".

A FemMesh::from_mesh() body is the exception, and the opposite case. A bare mesh carries no topology to say whether it ought to close, so its census always runs over the welded triangles: an open one lists its cracks here with FemMesh::watertight() false, a closed one reports FemMesh::watertight() true with no topology consulted at all, and an empty census there really does mean "nothing found".

FemMesh::folded_edges()

Result<std::vector<std::array<std::uint32_t, 3>>> folded_edges() const

Every fold, as FemMesh::open_edges() reports a crack: a directed mesh edge used by more than one triangle, once.

A body can be folded without being open — a solid no thicker than a line leaves no hole for an open edge to find — and the closure census's own known-bad bodies are folds rather than open cracks. A caller that checks FemMesh::open_edges() alone calls such a body sound. Empty under the same rule as FemMesh::open_edges().

FemMesh::crossings()

Result<std::vector<std::array<std::uint32_t, 2>>> crossings() const

Every pair of triangles that pass through each other, as (a, b) with a < b, sorted: an edge of one through the other's interior. Their B-rep faces are FemMesh::triangle_face() at a and b.

Computed for every body, open or closed. FemMesh::watertight(), FemMesh::open_edges() and FemMesh::folded_edges() are topological and cannot see a surface passing through itself; a mesh is ready for a volume mesher when it is FemMesh::watertight() and this is empty — Gmsh refuses one that crosses. A copy.

FemMesh::watertight()

bool watertight() const

The welded mesh closes — every directed mesh edge paired with its reverse and none used twice — and, for a B-rep body, so does the topology behind it. false for every B-rep body whose topology is not closed, whose mesh is then not asked about; read FemMesh::open_edges() for what an empty census beside a false here does and does not mean.

A FemMesh::from_mesh() body has no topology to ask of, so this says only that its triangles close: a closed render mesh reports true with nothing exact behind it at all.

Ready for a volume mesher means this and an empty FemMesh::crossings(): this census is topological and cannot see a surface passing through itself.

FemMesh::from_mesh()

bool from_mesh() const

This came from the scene's own mesh rather than from a B-rep: one face, every node on face 0, no edges and no vertices.

It is also which space the mesh is in. A B-rep body's FEM mesh is in the file's own units and axes, whatever Convention the scene was opened with, because it is taken off the B-rep — and a B-rep is in the file's own space for the reason Brep gives. A node with no B-rep falls back to the scene's mesh, which is converted, so that one comes back in the scene's convention, wound counter-clockwise about the outward normal even where the convention winds the other way.

And it is which contract the census is reporting under: read FemMesh::open_edges().

FemMesh::min_angle()

double min_angle() const

The smallest interior angle of any triangle, in degrees. There is always one: a body that meshed to no triangles is a refusal, not a mesh.

FemMesh::worst_triangle()

std::uint32_t worst_triangle() const

The triangle with that angle, as an index into FemMesh::triangles().

FemMesh::longest_edge()

double longest_edge() const

The longest triangle edge, placed. The figure to check against Node::fem_mesh()'s max_size, and the only one that says what the mesh actually is. max_size bounds the boundary segments and merely targets the interior: measured at 1.03 x max_size on a face whose parameters run unevenly, where a full-size boundary piece met a much shorter one left by halving. One small enough beside the body to reach the mesher's own piece and station ceilings is not honoured at all.

FemMesh::msh_text()

Result<std::string> msh_text() const

The mesh as Gmsh 4.1 ASCII .msh text: an entity per B-rep vertex, edge and face, a volume where the body closes, and a physical group naming each.

Gmsh reads the file as written — measured with Gmsh 4.15: node and triangle counts equal to this mesh's, and a physical group per entity. To fill a closed body with tetrahedra, give Gmsh a volume of its own over the file's surfaces. In its Python API: gmsh.open(path), then faces = [t for _, t in gmsh.model.getBoundary([(3, 1)], oriented=False)], gmsh.model.geo.addVolume([gmsh.model.geo.addSurfaceLoop(faces)]), gmsh.model.geo.synchronize() and gmsh.model.mesh.generate(3). A plain generate(3) leaves a volume read from any .msh file empty — Gmsh's own saved meshes too — and gmsh.model.mesh.createGeometry() re-meshes the surfaces rather than keeping these triangles.

Prefer Gmsh's HXT algorithm: gmsh.option.setNumber("Mesh.Algorithm3D", 10) before generate(3). On these surfaces the default left tetrahedra of exactly zero volume (four in a 100 mm bar), which no solver can use, and HXT's worst element came out far better on curved bodies (a minimum SICN of 0.1 to 0.3 where the default's was 0.001). Then name the tetrahedra before saving: HXT fills the new volume rather than the file's own, and gmsh.write keeps only elements in a physical group, so without this step every tetrahedron is dropped from the file without a word — filled = [t for _, t in gmsh.model.getEntities(3) if len(gmsh.model.mesh.getElementsByType(4, t)[0])], gmsh.model.removePhysicalGroups(gmsh.model.getPhysicalGroups(3)) and gmsh.model.addPhysicalGroup(3, filled, name="body"). The saved file also lists a few interior nodes no element uses — points Gmsh's refinement tried and gave up on — so a solver reading it should keep only the tetrahedra's own nodes: each unused one is an unconstrained unknown.

On this side of the ABI the library's text is borrowed — a slot on this handle, replaced by the next call on it and gone when the mesh is freed. The wrapper copies it out on the way, so what a caller holds is a string of its own. The kernel library's own msh_text is the other way round: an owned string, released by the wrapper (cadaclysm_blacksmith_string_free at the ABI), two asks giving two independent texts. A reader porting one side's reasoning onto the other leaks or double-frees.

No unlicensed notice is printed here. Node::fem_mesh() gave it once when the mesh was built, and this ABI deliberately does not repeat it on either .msh call — where the kernel library notices on both of its writers and not on its builder. Each matches its own siblings, so moving the call to look like the other side breaks a convention.

It returns an Error in its Result for a mesh the writer refuses, naming the field it cannot honour, and for a freed handle.

A freed handle traps here rather than returning an Error. This call, save_msh and every array accessor check the handle first, and on a freed one that check reaches CADACLYSM_BAD_ACCESS (FemMesh::msh_text: the FEM mesh is freed) and does not return — in both modes, not only under CADACLYSM_CHECKED, because what it guards is a pointer about to be handed to C rather than a borrowed view's owner. Measured. So the Result above carries the writer's refusal and nothing else; a freed handle is a bug in the caller, as it is for Meshlets.

FemMesh::save_msh()

Result<void> save_msh(const std::string& path) const

FemMesh::msh_text() written to a path by the library itself: the same bytes from the same writer, straight to the file rather than through the borrowed slot, so a text asked of this handle on another thread cannot be freed under the write. It returns an Error in its Result for a mesh the writer refuses or a file it cannot write, naming the path. No notice here either; see FemMesh::msh_text().

FemMesh::free()

void free() noexcept

Give the mesh back, and with it every view taken from it. Idempotent; the collector or the scope does it otherwise.

FemMesh::freed()

bool freed() const noexcept

Whether FemMesh::free() has run.

Surfaces::faces()

const std::vector<Face>& faces() const

The faces, one per trimmed face of the body.

Face

struct Face
std::uint32_t kind
std::array<float, 3> origin
std::array<float, 4> domain
std::array<float, 4> scalars
std::vector<Span<const float>> loops
Span<const float> nurbs

One trimmed face. kind is the surface: 0 plane, 1 cylinder, 2 cone, 3 sphere, 4 torus, 5 revolution, 6 extrusion, 7 NURBS, 8 sum. origin, ax, ay, az are its frame, scalars its kind-dependent sizes (radius, angle…) and domain its (u min, v min, u max, v max). loops holds the trim loops as (u, v) points, each closing implicitly; profile, profile2 and nurbs carry what a swept or NURBS surface needs. reversed flips the normal; transposed swaps u and v. The C header's CadaclysmFace is the full description.

Bounds::min

std::array<float, 3> min

The low corner.

Bounds::max

std::array<float, 3> max

The high corner.

Bounds::is_empty()

bool is_empty() const noexcept

Whether this is the all-zero box that stands for nothing.

Bounds::size()

std::array<float, 3> size() const noexcept

The extent along each axis.

Bounds::centre()

std::array<float, 3> centre() const noexcept

The midpoint.

Attribute::name

std::string name

What the file called it.

Attribute::kind

ValueKind kind

Which kind of value it holds — a ValueKind. Lets a caller tell a reference from prose, or total the numbers.

Attribute::value

std::variant<std::monostate, std::string, std::int64_t, double, bool> value

The value, in the language's own type where it has one for the kind.

A std::variant: std::monostate for none, std::string for text (lists and references too), std::int64_t, double or bool; read it with std::get_if.

Attribute::text()

std::string text() const

The value rendered for display, identically in every wrapper: true/false, reals in their shortest exact form, lists as [a, b, c].

Convention

enum class Convention : std::uint32_t
native
unreal
unity
y_up
blender

The presets: NATIVE keeps the file's own axes and units; UNREAL is Z up, left-handed, centimetres; UNITY Y up, left-handed, metres; Y_UP Y up, right-handed, metres (glTF, three.js, most real-time engines); BLENDER Z up, right-handed, metres.

cadaclysm::FILE_UNITS

inline constexpr std::uint32_t FILE_UNITS = 0x100

Combine with a preset to keep its axes but the file's own units.

cadaclysm::UV_WORLD

inline constexpr std::uint32_t UV_WORLD = 0x200

Combine with a preset to ask for world-scale texture coordinates in Mesh::uvs(). Off by default: eight bytes a vertex nobody asked for.

cadaclysm::parse_convention()

Result<std::uint32_t> parse_convention(std::string_view text)

A convention from a name a user typed: unreal, or unreal+file-units. An unknown name returns an Error in its Result listing the accepted ones, rather than silently reading as native.

ValueKind

enum class ValueKind : std::uint32_t
none
text
integer
real
boolean
list
reference

TEXT, INTEGER, REAL, BOOLEAN; LIST (the elements rendered as [a, b, c]); REFERENCE (another entity, by the id the file gave it, so it can be followed rather than shown as prose); NONE for an attribute that had no value.

Manifold::faces

std::uint32_t faces

How many faces.

Manifold::edges

std::uint32_t edges

How many distinct edges: one shared by two faces counts once.

Manifold::vertices

std::uint32_t vertices

How many distinct vertices.

Manifold::boundary_edges

std::uint32_t boundary_edges

Edges only one face borders: a sheet's rim, a hole in a shell.

Manifold::non_manifold_edges

std::uint32_t non_manifold_edges

Edges three or more faces border: a fin, or two solids meeting along a line.

Manifold::non_manifold_vertices

std::uint32_t non_manifold_vertices

Vertices whose faces make more than one fan: two solids touching at a corner.

Manifold::is_manifold

bool is_manifold

No non-manifold edge or vertex: a manifold, possibly with a boundary.

Manifold::is_closed

bool is_closed

A manifold with no boundary edge either: it encloses a solid.

SewReport::pairs

std::uint32_t pairs

How many pairs of free edges it joined into one shared edge.

SewReport::free_before

std::uint32_t free_before

Free edges (those only one face borders) before sewing.

SewReport::free_after

std::uint32_t free_after

Free edges after sewing.

SewReport::refused

std::uint32_t refused

How many groups of free edges between the same two vertices it left free: too far apart for the tolerance, or more than two.

SewReport::worst_gap

double worst_gap

The widest gap between two curves it sewed.

SewReport::tolerance

double tolerance

How close two curves had to lie, as used: by default vertex.

SewReport::vertex

double vertex

How close two edges' ends had to coincide, as used: by default the rounding Brep::manifold() merges vertices at.

cadaclysm::blacksmith::write_step()

Result<void> write_step(const std::string& path, const Solids& solids, const std::optional<std::string>& schema = std::nullopt, Unit unit = Unit::millimetre)

Write several solids as one STEP file, each its own body. unit is mm, m or in. schema is left out for AP203 (built in — no file needed; AP242 when any solid, face or edge is coloured, since AP203 has no colour entities), the name of another built-in schema such as AP242's AP242_MANAGED_MODEL_BASED_3D_ENGINEERING_MIM_LF (AP214's AUTOMOTIVE_DESIGN cannot carry the writer's mechanical_context), or a custom EXPRESS schema: a path to its .exp or its text. Colours from coloured and edges_coloured are written as STEP styling wherever the schema has it, a solid's read back as the node's colour; a named schema without it writes the solids bare.

cadaclysm::blacksmith::write_step_text()

Result<std::string> write_step_text(const Solids& solids, const std::optional<std::string>& schema = std::nullopt, Unit unit = Unit::millimetre)

The same STEP file as text, for a caller that stores or sends it rather than writing a file.

write_step_assembly

Write an assembly as one STEP file: parts names each solid, in its own coordinates, and each is written once as its own product; placements lists (name, frame) pairs, each an occurrence of that part at that frame (right-handed and orthonormal), all under one root product. A reader tessellates a part once however many times it is placed, and shows each placement under its part's name. schema and unit as cadaclysm::blacksmith::write_step().

Not in this wrapper: build an Assembly and write it with step or step_text.

write_step_assembly_text

The same assembly as STEP text.

Not in this wrapper: build an Assembly and write it with step or step_text.

cadaclysm::blacksmith::write_brep()

Result<void> write_brep(const std::string& path, const Solids& solids)

Write several solids as one OCCT .brep file, each its own solid under one compound (a single solid is the file's root): the exact surfaces and curves, with a curve in each face's own parameters for every edge, so Open CASCADE's BRepTools::Read gives a shape its BRepCheck_Analyzer finds valid. No unit is declared — a .brep carries none — so the numbers written are the numbers held. The library writes the file itself.

cadaclysm::blacksmith::write_brep_text()

Result<std::string> write_brep_text(const Solids& solids)

The same .brep file as text.

cadaclysm::blacksmith::write_sat()

Result<void> write_sat(const std::string& path, const Solids& solids, Unit unit)

Write several solids as one ACIS SAT file, each its own body: planes, cylinders, cones, spheres and tori as their own records, splines and swept surfaces as exact NURBS, in the layout Rhino's own exporter writes. unit is mm, m or in and goes into the header as millimetres per unit. The library writes the file itself, so a refusal names it.

cadaclysm::blacksmith::write_sat_text()

Result<std::string> write_sat_text(const Solids& solids, Unit unit)

The same SAT file as text.

cadaclysm::blacksmith::write_svg()

Result<void> write_svg(const std::string& path, const Solids& solids, const SvgOptions& options)
Result<void> write_svg(const std::string& path, const Solids& solids, const Profiles& profiles, const SvgOptions& options)

Several solids and profiles' wireframe as one SVG, any mix and any order: a <g id="solid-<i>"> per solid then a <g id="profile-<i>"> per profile, each stroked in its own colour where it carries one — a solid's edge colour first, then its body colour (a face colour says nothing about a wireframe) — and the keywords' stroke= otherwise. The keywords are Scene::svg()'s own: view= (front, back, left, right, top, bottom, iso), az=/el= over it, up= (default z: neither a solid nor a profile carries a convention of its own to default it from), fov= (0, the default, is orthographic), size=, margin=, tolerance=, stroke= and background= ("#rgb", "#rrggbb" or a CSS colour name in every language, beside that language's own numeric form; background= std::nullopt for transparent), width= (the stroke's, in page units), edges=, curves=, isocurves=, polylines= (which line sets are drawn; edges by default), and silhouettes= (also draw where each solid's surfaces turn away from the eye — the outline a sphere has no edge for, on by default: a sphere's and a torus's only curves are the seams where their one face meets itself, which are not edges of the body and are never drawn, so without it those two draw a blank page. A line set in its own right, so silhouettes= with edges= off draws the outline alone).

A list of solids alone draws exactly as it always did. The SVG is the drawing itself: with path, writes it to the file and returns std::nullopt; without, returns the SVG text. Both lists empty returns an Error in its Result; so does anything in them that is neither a solid nor a profile, a refused option, or a failed write.

cadaclysm::blacksmith::default_schema()

Result<std::string> default_schema()

Where an ap203.exp file is found (CADACLYSM_SCHEMAS, else schemas/ in a parent). No longer needed to write STEP: the kernel's AP203 is built in.

cadaclysm::blacksmith::version()

std::string version()

The version of the kernel library actually loaded.

cadaclysm::blacksmith::build_date()

std::string build_date()

When the loaded kernel was built, YYYY-MM-DD.

cadaclysm::blacksmith::pair_freedom_count()

std::uint32_t pair_freedom_count(std::string_view kind)

How many freedoms a pair kind has, so a caller can size Assembly::pair()'s ranges. 0 for an unknown name, and for fully_constrained, which has none.

cadaclysm::blacksmith::license()

Result<void> license(const std::string& text_or_path)

Load a licence into the kernel — the text, or a file's path. The reader has its own call; the same file works for both.

cadaclysm::blacksmith::license_info()

std::string license_info()

One line about the kernel's licence, or unlicensed. Never std::nullopt.

cadaclysm::blacksmith::license_notice_count()

std::uint64_t license_notice_count()

How many unlicensed notices the kernel has printed to stderr in this process.

cadaclysm::blacksmith::set_option()

Result<void> set_option(const std::string& name, double value)

Set a kernel option, by its name, for the whole process from the next call on — every thread, every solid. The options are numbers under stable names, one call for all of them, so an option added later needs no new function:

boolean.mesh_budget (default 500000): the most triangles a boolean (join, cut, common, split) builds its trees from, its two solids' meshes together. Past it the boolean refuses with a tolerance error rather than running for minutes or hours. A whole number, at least 1, or infinity for no limit.

boolean.finest_tolerance (default 1e-8): the finest tolerance a boolean takes, as a share of how far its two solids reach; under it the boolean refuses before meshing anything. From 0 (no floor) to below 1.

profile_boolean.point_budget (default 8000000): the most points a profile boolean follows its two profiles' arcs and splines with. Past it the boolean refuses with a tolerance error; 8 million is about 128 MB. A whole number, at least 1, or infinity for no limit.

measure.default_accuracy (default 1e-7): the relative accuracy Solid::mass() refines to when it is asked for 0, the default. Above 0 and below 1.

A name that is not an option, or a value the option does not take, returns an Error in its Result and changes nothing, saying which and what it takes.

cadaclysm::blacksmith::option()

Result<double> option(const std::string& name)

A kernel option's value, by its name: what cadaclysm::blacksmith::set_option() last set, else its default (see cadaclysm::blacksmith::set_option() for the names). A name that is not an option returns an Error in its Result, listing the ones there are.

cadaclysm::blacksmith::brep_layout_id()

std::string brep_layout_id()

How the loaded kernel lays a brep out in memory: its compiler, target and source. Solid::from_node() works only where this equals the reader's Brep::layout_id() — the two libraries from the same release.

library_path

Where the kernel library was found: CADACLYSM_BLACKSMITH_LIBRARY first, then as the reader's.

Linked at build time: the OS loader finds the libraries; see Install.

cadaclysm::blacksmith::boxes_apart()

Result<bool> boxes_apart(const Box& a, const Frame& frame_a, const Box& b, const Frame& frame_b)

True only if box a at frame_a and box b at frame_b cannot touch — a separating axis among the boxes' face normals and edge-direction crosses; touching is not apart. Sharper than moving each box (Box::moved()) and asking Box::overlaps(), which boxes the *result* on the world axes again and so can call two oriented boxes overlapping when they are not (two unit boxes, the second turned 45 degrees about z and moved 2.3 along x: their world boxes overlap, but the boxes themselves do not touch). frame_a or frame_b not twelve finite numbers or not rigid returns an Error in its Result.

Profile::rect()

static Result<Profile> rect(double w, double h)

A w × h rectangle centred on the origin.

Profile::circle()

static Result<Profile> circle(double r)

A circle of radius r about the origin.

Profile::slot()

static Result<Profile> slot(const Vec2& centre, double length, double r)

A slot (stadium) length long overall, with end radius r, centred on centre and running along x. length must exceed 2 * r.

Profile::polygon()

static Result<Profile> polygon(const std::vector<Vec2>& points)

A closed polygon through the points, in order, its side back to the first point a segment of its own. At least three points.

Profile::regular_polygon()

static Result<Profile> regular_polygon(const Vec2& centre, double radius, std::uint32_t sides, double angle = 0.0)

A regular polygon of sides sides (at least 3) on the circle of radius about centre, its first corner at angle radians from the sketch's x axis (0 by default), the rest counter-clockwise.

Profile::star()

static Result<Profile> star(const Vec2& centre, double outer, double inner, std::uint32_t points, double angle = 0.0)

A star of points tips (at least 3) on the circle of outer about centre, its inner corners on the circle of inner (positive, under outer), alternating: the first tip at angle radians from the sketch's x axis (0 by default), the rest counter-clockwise, each inner corner half a step on from the tip before it. 2 * points straight sides; an inner not under outer returns an Error in its Result.

Profile::text()

static Result<std::vector<Profile>> text(const std::string& text, double size = 10.0, const std::string& font = "", const std::string& halign = "left", const std::string& valign = "baseline", double spacing = 1.0, const std::string& direction = "ltr", const std::optional<std::vector<std::uint8_t>>& font_bytes = std::nullopt)

text set in a font, one profile per closed shape — a letter with its counters as holes (o one, 8 two; i is two profiles) — on the sketch plane, the baseline along x from the origin, each outline counter-clockwise and its holes clockwise, a curved side the font's own cubic Bezier kept exactly: an extruded O has curved walls, and writes to STEP as splines. size (10 by default) is roughly the height of a capital. font is a family, optionally with a style ("Liberation Sans:style=Bold"), a font file's path, or empty for the bundled Liberation Sans Regular — which also serves when the family is not found, so text never comes back empty; font_bytes a font file's bytes, used instead of font when given (a page or a phone fetches its own font). halign is left (default), center or right; valign baseline (default), bottom, center or top; spacing (1 by default) multiplies the gap between glyphs; direction ltr (default) or rtl. Glyphs are laid out one after another by their advance widths — no shaping, so Latin sets as expected and scripts that need ligatures or reordering do not. Empty text is an empty list. A size or spacing not positive and finite, an alignment or direction not one of those words, or font bytes that are not a font returns an Error in its Result.

Profile::spline()

static Result<Profile> spline(const std::vector<Vec2>& points, std::uint32_t degree = 3, const std::optional<std::vector<double>>& weights = std::nullopt, bool closed = false)

A spline of degree (3 by default) through the control polygon points, weights one per point or std::nullopt. Open, it starts on the first point and ends on the last: an open chain, for Solid::extrude_open() or Profile::chain(). Closed, it is periodic — smooth through its own start, no corner there — and a closed profile. The degree is lowered to fit the points; a degree of zero, too few points (two open, three closed) or a weight not positive returns an Error in its Result.

Profile::path()

static Path path(const Vec2& start)

Start drawing an outline segment by segment at start; see Path.

Profile::parabola()

static Path parabola(const Vec2& vertex, const Vec2& axis, double focal, double from, double to)

Start drawing on the arc of the parabola with vertex, axis direction axis and focal length focal, over the across-axis coordinates from..to: the path begins at the arc's first point and holds the arc as one conic segment — a reflector from rim to rim; parabola((0, 0), (0, 1), 20, -50, 50) is a dish 100 wide opening up. A zero axis, a focal length not positive and finite, or from not under to returns an Error in its Result.

Profile::chain()

static Result<Profile> chain(const Profiles& pieces, double tolerance = 1e-6)

Open profiles — paths ended open — joined end to end into one: the forge's merge. They may come in any order and either way round: each next piece is the first of the rest with an end within tolerance (1e-6 by default) of either end of the chain so far, reversed where that makes it meet. Every segment is kept exactly — a line a line, an arc an arc, a spline the same spline. Closed where the chain's two ends meet, otherwise an open chain. A piece that is empty, has holes, is closed on its own or meets none of the others returns an Error in its Result naming it by its index.

Profile::from_loops()

static Result<Profile> from_loops(const Profiles& loops)

Closed loops, in any order, as one profile: the loop enclosing the most area is the boundary and every other a hole in it, in the order given — a sketch's rectangle and the circles drawn inside it. Each loop is a closed profile with no holes of its own, wound either way; one that closes within rounding is closed exactly. A loop that is open, empty or encloses no area, loops that cross or touch, a hole outside the boundary, or one inside another hole (an island) returns an Error in its Result, naming the loops by their index.

Profile::close_loop()

Result<Profile> close_loop() const

This profile closed — the forge's sketch "close": where its last segment stops short of its start (a path ended open), a straight segment back to it; where it already comes back within 1e-9 of its extent, its last segment made to land on the start exactly. A closed profile comes back as it is, and holes are closed the same way.

Profile::pieces()

Result<std::vector<Profile>> pieces(const Profiles& cutters, double tolerance = 1e-6) const

This curve cut where the cutters cross, touch or run along it — the sketch trim's pieces: in order along the curve from its start, each an open profile of portions of this one's own segments (a line's stretch a line, an arc's an arc, a spline's the same spline over part of its domain, nothing refitted). One piece, this curve, where nothing cuts it; a closed curve's piece round its start is one piece. Cuts closer than tolerance to each other fold onto one. A curve with no segments returns an Error in its Result.

Profile::trim()

Result<std::vector<Profile>> trim(const Profiles& cutters, std::uint32_t piece, double tolerance = 1e-6) const

This curve with piece piece of Profile::pieces() taken away — the sketch trim, the forge's: what is left, as open profiles. One for a closed curve (its other pieces run together from where the removed one ended), the stretches before and after for an open one, none where the piece was the whole curve. A piece the curve does not have returns an Error in its Result.

Profile::with_hole()

Result<Profile> with_hole(const Profile& hole) const

This outline with hole cut out of it.

Profile::hits()

Result<std::vector<Hit>> hits(const Profile& other, double tolerance = HIT_TOLERANCE) const

Where this outline's curves cross, touch or run along other's, both read in one plane, as Hit values ordered along this outline. Points closer than tolerance merge; two curves within tolerance of each other for longer than it are one run when they part only where one of them ends or the stretch is flat — one curve following the other, offset within tolerance or tilted by under about half of it, even where it leaves mid-both; a tangency or a shallow crossing is one point. A loop that stops short of its start is an open chain, its closing side not tested.

Profile::common()

Result<std::vector<Profile>> common(const Profile& other, double tolerance = HIT_TOLERANCE) const

The region this outline and other share, both read in one plane, as a list of zero or more profiles — each boundary counter-clockwise, each hole clockwise, arcs and splines kept exact. An arc kept from an input can still come out split at that input's own seam point (two circles' lens is four arcs, one pair per circle) — exact, not an approximation. Two loops of a result may touch at a point (two holes whose corners meet, one from each input): a right point set that the verbs needing simple loops — Solid::extrude(), a boolean taking it as an input — refuse. Both must be closed and simple; no shared area is an empty list. A tolerance not positive and finite, an outline open or crossing itself, a tolerance too fine for these outlines (following their arcs and splines to a tenth of it would take more than 8 million points, about 128 MB), and, as a defect rather than an outcome, a result that fails to close, returns an Error in its Result.

Profile::translate()

Result<Profile> translate(double dx, double dy) const

This outline moved by (dx, dy).

Profile::coloured()

Result<Profile> coloured(const Vec3& rgb_value) const
Result<Profile> coloured(std::string_view colour) const

A new outline coloured (r, g, b), each 0..1, "#rgb", "#rrggbb" or a CSS colour name ("tomato", "RebeccaPurple"): how it is drawn. The verbs that make a profile from one carry it (translate, round, with_hole keeps the outer's, chain and from_loops the first's); a solid made from it takes nothing — colour a solid with Solid::coloured().

Takes a Vec3, or, as a std::string_view overload, colour text through blacksmith::rgb().

Profile::colour()

Result<std::optional<Vec3>> colour() const

The outline's colour as (r, g, b), or none.

Profile::round()

Result<Profile> round(double radius, const std::optional<std::vector<std::uint32_t>>& corners = std::nullopt, bool as_open = false) const

This outline with its corners rounded by radius: where two straight segments meet, both are cut back and an exact arc tangent to both goes between them; a corner next to an arc or a spline is left as it is. With no corners every such corner is rounded, the holes' too; a list picks corners of the outline — corner k is where segment k ends. open reads the profile as an open chain whose two ends stay square. A radius that does not fit returns an Error in its Result naming the corner.

Profile::to_arcs()

Result<Profile> to_arcs(double tolerance = 0.01) const

This profile with every free-form side (a Bezier, a conic, a NURBS) replaced by lines and arcs within tolerance of it — what a G-code writer can say. Lines and arcs pass through as they are, every loop closes on itself exactly, holes are converted the same way. tolerance (0.01 by default) not positive and finite, or a spline that does not evaluate, returns an Error in its Result.

Profile::offset()

Result<std::vector<Profile>> offset(double distance, double tolerance = 0.01) const

This profile grown by distance (shrunk where it is negative), as zero or more profiles, all lines and arcs: outward corners rounded by |distance|, holes moving against the boundary (a hole shrinks as the profile grows). Free-form sides are fitted to tolerance first (Profile::to_arcs()). A shrink that eats the whole profile is an empty list. A distance not finite, a tolerance (0.01 by default) not positive and finite, a loop with no sides, or loops that cross or touch, returns an Error in its Result.

Profile::polylines()

Result<ProfilePolylines> polylines(double tolerance = DEFAULT_TOLERANCE) const

The outline, then each hole, as polylines at z = 0 within tolerance of its arcs and splines — what a viewer draws it with. A closed loop repeats its first point at the end; an open chain (a profile ended open) stays open. Views, like Solid::mesh() — copies in Node, Godot and Python.

Returns a view into the profile's cache: asking again at another tolerance makes it stale (a bad access in checked mode).

Profile.show

Draw the outline and holes with the viewer in use, from the top by default. Keywords as Solid::show(); edges= is ignored, the lines being the whole picture. With the GPU library (import cadaclysm.view.wgpu) the drawing replaces what one shared window shows and stays live — at the REPL, in IPython and in Jupyter by themselves, in a script until it exits; cadaclysm.view.View draws several items or several windows.

Comes with the viewers follow-up.

Profile.view

Orbit the outline with the viewer in use; returns the camera where it was left — a dict of eye, target, up, orthographic, azimuth and elevation — and pick, what was last clicked (item, node, face) or None. A fresh window, run until closed, with the GPU library.

Comes with the viewers follow-up.

Profile::svg()

Result<void> svg(const std::string& path, const SvgOptions& options = SvgOptions{SvgView::top}) const

This profile's own loops as SVG: a line a line, an arc an arc, a spline the NURBS' own Béziers — exact curves, nothing flattened to the polyline Profile::polylines() samples. The keywords are cadaclysm::blacksmith::write_svg()'s own, except view= defaults to top here rather than iso: a profile lies in z = 0, so its own plane is already the page and it reads flat and true. In the languages whose options are a struct (view already iso, not nullable), that default holds only when no options value is passed at all — pass one for anything else and its own view applies. With path, writes the file and returns std::nullopt; without, returns the SVG text. returns an Error in its Result on a refused option or a failed write.

Path::line_to()

Path& line_to(double x, double y) &

A straight segment to (x, y).

Path::arc_to()

Path& arc_to(double x, double y, const Vec2& centre, bool ccw = true) &

A circular arc to (x, y) about centre, counter-clockwise unless ccw is false.

Path::bezier_to()

Path& bezier_to(const Vec2& c1, const Vec2& c2, const Vec2& to) &

A cubic Bézier through control points c1, c2 to to.

Path::conic_to()

Path& conic_to(const Vec2& to, const Vec2& control, double weight) &

A conic arc to (x, y) through the control point control with middle weight: under 1 an elliptical arc, 1 a parabola, over 1 a hyperbola — the rational quadratic Bézier, kept exact. A weight not positive and finite, an end on the current point, or a control point on the chord returns an Error in its Result.

Path::parabola_to()

Path& parabola_to(const Vec2& to, const Vec2& control) &

A parabolic arc to (x, y) whose end tangents meet at control: Path::conic_to() with weight 1.

Path::hyperbola_to()

Path& hyperbola_to(const Vec2& to, const Vec2& control, double weight) &

A hyperbolic arc to (x, y) through control with middle weight over 1; a weight of 1 or under returns an Error in its Result.

Path::parabola_by_vertex()

Path& parabola_by_vertex(const Vec2& to, const Vec2& vertex) &

The parabolic arc to (x, y) whose vertex is vertex: the axis and focal length are solved from the two ends. A vertex on the chord, or one no parabola through both ends has (the vertex must be the arc's extreme point), returns an Error in its Result.

Path::parabola_by_focus()

Path& parabola_by_focus(const Vec2& to, const Vec2& focus) &

The parabolic arc to (x, y) whose focus is focus: of the two parabolas through the ends with that focus, the one whose vertex lies between the ends' projections, then the one whose arc cups the focus (the focus between the arc and its chord), then the more symmetric; with the focus beyond the chord that is the arch over the ends, not the shallow dish — draw that one with Profile::parabola(). A focus on the chord returns an Error in its Result.

Path::nurbs_to()

Path& nurbs_to(const std::vector<Vec2>& control, const std::vector<double>& knots, std::uint32_t degree, const std::optional<std::vector<double>>& weights = std::nullopt) &

A NURBS segment: control is every control point after the current one, the endpoint last; knots the full knot vector; weights one per control point including the current one, or std::nullopt for a non-rational curve.

Path::end()

Result<Profile> end()

Close the outline back to its start and return the Profile.

Path::end_open()

Result<Profile> end_open()

The path as it stands, not closed: an open chain for Solid::extrude_open(), Solid::sweep_open() or Solid::loft_open().

SweepPath::at()

static SweepPath at(const Vec3& point)

Start a path at a 3D point.

SweepPath::along()

static SweepPath along(const Profile& curve, const Frame& frame, double tolerance = DEFAULT_TOLERANCE, bool leave_open = true)

The path a 2D chain (usually from Path::end_open()) draws on frame: a line a straight piece, an arc a circular one, a Bézier or spline fitted with biarcs — arcs tangent to each other and to the curve — within tolerance, so the path is tangent throughout and the sweep exact along it. open false closes the path back to its start.

SweepPath::line_to()

SweepPath& line_to(const Vec3& point) &

A straight piece to a 3D point.

SweepPath::arc()

SweepPath& arc(const Vec3& centre, const Vec3& axis, double angle) &

Turn angle radians (in (0, 2π]) about the axis through centre along axis.

SweepPath::close()

void close() noexcept

Free the path.

Slant::at

double at

The height at the sketch origin.

Slant::grad

Vec2 grad

The slope in x and y.

Slant::flat()

static Slant flat(double height)

A flat plane at height at.

Slant::of_plane()

static Result<Slant> of_plane(const Frame& frame, const Vec3& point, const Vec3& normal)

The plane through point square to normal, as heights over frame. A plane that contains the extrusion direction has no height and returns an Error in its Result.

Frame::xy()

static Result<Frame> xy(const Vec3& o = {0, 0, 0})

The world XY plane through origin: z up, as Workplane::xy().

Frame::xz()

static Result<Frame> xz(const Vec3& o = {0, 0, 0})

The world XZ plane through origin: x along X, y along Z, so z is -Y, as Workplane::xz().

Frame::yz()

static Result<Frame> yz(const Vec3& o = {0, 0, 0})

The world YZ plane through origin: x along Y, y along Z, so z is +X, as Workplane::yz().

Frame::at()

static Result<Frame> at(const Vec3& o, const Vec3& normal, const std::optional<Vec3>& x_hint = std::nullopt)

The plane through origin square to normal, which becomes the frame's z (it need not be unit). Its x axis is x laid onto that plane; with none, world X laid onto it, or world Y when the normal is within about 25° of X — the axes Solid::face_frame() gives a face facing normal. So a normal along +Z, -Y or +X gives exactly Frame::xy(), Frame::xz() or Frame::yz(). A zero normal, or an x along the normal, returns an Error in its Result.

Frame::of()

static Result<Frame> of(const std::array<double, 12>& raw)

Twelve numbers — what Solid::face_frame() and Workplane::frame() hand back — as a checked frame, to read its axes or move it.

Frame::midplane()

static Result<Frame> midplane(const Frame& a, const Frame& b)

The plane midway between the planes of frames a and b: for parallel planes the one halfway between, on a's axes; for planes that meet, the plane bisecting them through the line they meet on, its x along that line.

Frame::through()

static Result<Frame> through(const Vec3& p, const Vec3& q, const Vec3& r)

The plane through the points p, q and r: its origin p, its x towards q, its z the normal the three turn about counter-clockwise. Three points on one line returns an Error in its Result.

Frame::origin()

Vec3 origin() const noexcept
Vec3 x() const noexcept
Vec3 y() const noexcept
Vec3 z() const noexcept

The origin and the three axes, each three numbers.

Frame::translate()

Result<Frame> translate(double dx, double dy, double dz) const

This frame moved by (dx, dy, dz) in world coordinates.

Frame::offset()

Result<Frame> offset(double distance) const

This frame moved distance along its own z: Frame::xy() and offset() return Result<Frame>, so Frame::xy().and_then([](Frame f) { return f.offset(5); }) is the XY plane at z = 5.

Workplane::xy()

static Workplane xy()

Start on the XY plane at the origin (Z up). Workplane::xz() and Workplane::yz() start on the other two.

Workplane::xz()

static Workplane xz()

Start on the XZ plane.

Workplane::yz()

static Workplane yz()

Start on the YZ plane.

Workplane::on()

static Workplane on(const Frame& f)

Start on any frame (see Frames).

Workplane::from_solid()

static Workplane from_solid(const Solid& source)

Start from an existing solid, on the XY plane — the usual way to pick one of its faces and build on it.

Workplane::frame()

Frame frame() const

The current frame, 12 numbers.

Workplane::cuboid()

Workplane& cuboid(double x, double y, double z) &

A box x × y × z centred on the current frame's origin and aligned to its axes — on a picked face, half of it below the face; replaces the solid.

Workplane::cylinder()

Workplane& cylinder(double r, double height) &

A cylinder of radius r and height h standing on the current frame; replaces the solid.

Workplane::face()

Workplane& face(const Profile& profile) &

The planar sheet the profile bounds on this frame — see Solid::face(); replaces the solid.

Workplane::extrude()

Workplane& extrude(const Profile& profile, double height) &

The profile extruded height along the frame's z; replaces the solid.

Workplane::revolve()

Workplane& revolve(const Profile& profile, double angle) &

The profile revolved angle radians about the frame's y axis; replaces the solid.

Workplane::translate()

Workplane& translate(double dx, double dy, double dz) &

Slide the current solid. Keeps the face selection — a rigid move keeps every face's index.

Workplane::faces()

Workplane& faces(const Selector& selector) &

Pick a face of the current solid with a Selector.

Workplane::workplane()

Workplane& workplane() &

Move the frame onto the face last picked (outward normal as z), so the next step builds on it.

Workplane::solid()

Result<Solid> solid()

The solid built so far. On an empty chain it returns an Error in its Result.

Selector::max()

static Selector (max)(Axis axis)

The face furthest along axis.

Selector::min()

static Selector (min)(Axis axis)

The face furthest against axis.

Selector::normal()

static Selector normal(const Vec3& direction)

The face whose outward normal is nearest direction (need not be unit).

Selector::index()

static Selector index(std::uint32_t i)

The face with this index.

Axis

enum class Axis : std::uint32_t
x
y
z

X, Y, Z: the axes Selector::max() and Selector::min() take.

Solid::cuboid()

static Result<Solid> cuboid(double x, double y, double z)

A box x × y × z, centred on the origin.

Solid::cylinder()

static Result<Solid> cylinder(double r, double h)

A cylinder of radius r, from z = 0 to h.

Solid::cone()

static Result<Solid> cone(double r, double h)

A cone of base radius r and height h, apex up.

Solid::sphere()

static Result<Solid> sphere(double r)

A sphere of radius r about the origin.

Solid::torus()

static Result<Solid> torus(double major, double minor)

A torus about the z axis: major to the tube's centre, minor the tube's radius. A tube wider than its ring (minor > major, a spindle) builds the solid it sweeps, the outer sheet with a pole at each end on the axis; minor == major is refused.

Solid::wedge()

static Result<Solid> wedge(double x, double y, double z, double top_x)

A box whose top face is top_x long instead of x: a ramp.

Solid::pyramid()

static Result<Solid> pyramid(std::uint32_t sides, double r, double h)

A pyramid of sides sides (at least 3): its base the regular polygon of radius r on z = 0 (r to a corner, the first on +x), its tip at height h.

Solid::extrude()

static Result<Solid> extrude(const Profile& profile, const Frame& frame, double height)

The profile on frame, extruded height along the frame's z.

Solid::extrude_open()

static Result<Solid> extrude_open(const Profile& profile, const Frame& frame, double height)

The walls only, no caps: an open sheet. Takes an open Path::end_open() chain as well as a closed profile.

Solid::extrude_tapered()

static Result<Solid> extrude_tapered(const Profile& profile, const Frame& frame, double height, double taper)

Extrude with a draft: the walls lean out by taper radians as they rise (in, when negative). Every wall stays exact — a plane off a line, a cone off an arc.

Solid::extrude_open_tapered()

static Result<Solid> extrude_open_tapered(const Profile& profile, const Frame& frame, double height, double taper)

The tapered walls without caps.

Solid::extrude_between()

static Result<Solid> extrude_between(const Profile& profile, const Frame& frame, const Slant& bottom, const Slant& top)

Extrude between two planes rather than two heights: bottom and top are each a Slant (a bare number is a flat one). With both flat this is Solid::extrude(); with a slope it is the mitred end of a frame member. A top that comes down to or through the bottom returns an Error in its Result.

Solid::extrude_open_between()

static Result<Solid> extrude_open_between(const Profile& profile, const Frame& frame, const Slant& bottom, const Slant& top)

Solid::extrude_between() without the caps.

Solid::revolve()

static Result<Solid> revolve(const Profile& profile, const AxisLine& axis, double angle)

The profile swung angle radians about axis (a point and a direction — see Frames). The profile's x is read as the radius and its y as the height along the axis, so it must lie to one side of it.

Solid::revolve_open()

static Result<Solid> revolve_open(const Profile& profile, const AxisLine& axis, double angle)

The revolved surface of an open profile: a sheet.

Solid::revolve_in_plane()

static Result<Solid> revolve_in_plane(const Profile& profile, const Frame& frame, const Vec2& a, const Vec2& b, double angle)

The profile on frame swung angle radians about the axis through the sketch points a and b (each (x, y) on the frame) — the profile and its axis drawn together, as a sketch draws them, where Solid::revolve() reads the profile as (radius, height). The profile may lie on either side of the axis and touch it (a half-disc with its diameter on the axis turns into a ball), but not cross it. The sweep starts where the profile is drawn and turns right-handed about b - a, so a partial turn leaves one end of the solid over the profile itself.

Solid::revolve_open_in_plane()

static Result<Solid> revolve_open_in_plane(const Profile& profile, const Frame& frame, const Vec2& a, const Vec2& b, double angle)

Solid::revolve_in_plane() for a curve: its segments swung into a sheet, no caps.

Solid::coil()

static Result<Solid> coil(const Profile& profile, const AxisLine& axis, double pitch, double turns)

The profile coiled about axis (a point and a direction): read as Solid::revolve() reads it — x the distance from the axis, y along it — and turned turns times while climbing pitch along the axis each turn: a spring, a thread. The walls follow the helix to a few millionths of the radius (a helix is not a NURBS curve, so they are a close fit, exact at both ends); the two ends are the profile itself, flat. A profile reaching the axis, one with holes, or — from a full turn up — a pitch no taller than the profile returns an Error in its Result.

Solid::loft()

static Result<Solid> loft(const Profile& a, const Frame& frame_a, const Profile& b, const Frame& frame_b)

The solid between profile a on one frame and b on another: ruled walls between matching sides (both profiles need the same number of sides, and no holes), capped by the two.

Solid::loft_open()

static Result<Solid> loft_open(const Profile& a, const Frame& frame_a, const Profile& b, const Frame& frame_b)

The ruled walls without the caps.

Solid::loft_through()

static Result<Solid> loft_through(const Sections& sections)

The solid smooth through every section — a profile on its frame, in order: each wall interpolates its side across all the profiles (cubic through four or more, quadratic through three, Solid::loft() through two), capped by the first and the last. Every section of the result is its profile exactly, arcs and all. The profiles must have the same number of sides and no holes; otherwise returns an Error in its Result.

Sections is a std::vector of Sections, each a {profile, frame} pair, both borrowed for the call.

Solid::loft_through_open()

static Result<Solid> loft_through_open(const Sections& sections)

The walls through the curves without the caps: an open sheet.

Solid::sweep()

static Result<Solid> sweep(const Profile& profile, const Frame& frame, const SweepPath& path)

The profile on frame, carried along a SweepPath. A straight piece is an extrusion and an arc a revolution about the arc's axis, so nothing is approximated — a circle along an arc is an exact torus wall.

Solid::sweep_open()

static Result<Solid> sweep_open(const Profile& profile, const Frame& frame, const SweepPath& path)

The swept walls without caps: an open sheet.

Solid::pipe()

static Result<Solid> pipe(const SweepPath& path, double radius, double thickness = 0.0)

A circle of radius carried along a SweepPath, square to where it starts: a solid rod, or with a positive thickness a tube whose walls are that thick. The path is only borrowed, as by Solid::sweep(), and refused the same way.

Solid::extrude_faces()

Result<Solid> extrude_faces(double height) const

Every face of a sheet pushed height along its own normal, walled and closed: the sheet as a solid of that thickness.

Solid::face()

static Result<Solid> face(const Profile& profile, const Frame& frame)

The flat sheet a profile bounds on frame: one planar face, each hole a hole through it, its normal the frame's z however the profile winds, every edge the exact line, arc or spline its segment is. An open sheet — raise it with Solid::extrude_faces(), cut it with Solid::trim().

Solid::place()

Result<Solid> place(const Frame& frame) const

A solid built about the origin moved onto frame: its origin to the frame's origin, its axes to the frame's (see Frames).

Solid::translate()

Result<Solid> translate(double dx, double dy, double dz) const

Moved by (dx, dy, dz).

Solid::scaled()

Result<Solid> scaled(double factor) const

Scaled by factor about the origin: every length times factor, exactly. factor must be positive and finite.

Solid::rotate()

Result<Solid> rotate(const AxisLine& axis, double radians) const

Turned radians about axis (a point and a direction).

Solid::mirror()

Result<Solid> mirror(const Frame& plane) const

Reflected across plane: a frame whose z is the mirror plane's normal.

Solid::join()

Result<Solid> join(const Solid& other, double tolerance = DEFAULT_TOLERANCE, const Progress& progress = {}, bool merge = false) const

The union with other, as an exact B-rep. merge (off by default, so face and edge numbers stay as they were) merges the flush faces the join leaves, as Solid::merge_flush() does — Go takes it as a trailing true, Java as an overload; Solid::cut() and Solid::common() take it too. tolerance (0.05 by default) is the mesh tolerance the boolean decides at: both solids are meshed at it, so a tighter one is as correct and slower. It is also the resolution: two faces on one surface to within it — a peg the size of its hole, or a hair thinner — are one surface, and the join is a fit; a gap wider than it is a gap. progress, where the wrapper takes one, is called with a phase name and a done/total count.

merge and progress are the last two arguments; progress is a std::function<void(std::string_view, std::size_t, std::size_t)>.

Solid::cut()

Result<Solid> cut(const Solid& other, double tolerance = DEFAULT_TOLERANCE, const Progress& progress = {}, bool merge = false) const

This solid with other removed.

Solid::common()

Result<Solid> common(const Solid& other, double tolerance = DEFAULT_TOLERANCE, const Progress& progress = {}, bool merge = false) const

What this solid and other share.

Solid::intersect()

Result<Intersection> intersect(const Solid& other, double tolerance = DEFAULT_TOLERANCE, const Progress& progress = {}) const

Where this solid's faces cross or coincide with other's, at tolerance, as an Intersection: every crossing as a Chain, every coincident face pair that shares a region as an Overlap. Not a boolean: neither solid changes, nothing is built. tolerance (0.05 by default) is read as Solid::join()'s — both solids' mesh resolution and how close a point may sit to both faces' exact surfaces to be reported. No crossing at all is an empty Intersection, never an error. progress, where the wrapper takes one, is called with a phase and a done/total count: meet on the exact route; mesh, cull, cross, snap, curve where it falls back to the mesh route.

There is one chain per face pair per branch: a chain does not cross a face boundary or a closed curve's own seam, so a crossing that runs past either comes back as more than one chain, joined by matching ends. Two faces on one surface sharing no region — an edge or a rim resting against another face, two flush faces meeting along a line — are silent: neither a chain nor an overlap. Known limit: a crossing narrower than tolerance — two surfaces passing within it of each other without their meshes actually crossing — can be missed; where this bites the surfaces are near-tangent, and the chain that is found (if any) carries tangent.

Solid::section()

Result<std::vector<Profile>> section(double z, double tolerance = 0.05) const

This solid cut by the plane Z = z: its closed outlines there, in XY, nested into profiles with holes (boundaries counter-clockwise, holes clockwise), a line or a circle crossing kept exact and any other curve as lines within tolerance. A plane that misses the solid is an empty list. A z not finite, a tolerance (0.05 by default) not positive and finite, a face lying in the plane (section a little above or below it), or a crossing that does not close, returns an Error in its Result.

Solid::hits()

Result<SolidHits> hits(const Profile& profile, const Frame& frame, double tolerance = DEFAULT_TOLERANCE, const Progress& progress = {}) const

Where profile, placed on frame, pierces this solid's faces, and the pieces its loops cut into, as a SolidHits. Neither is changed. A point hit lies within tolerance of the segment's exact curve and of the face's exact surface, inside the face's trim; its profile spot (Hit::a_start: loop, segment, t) and face spot (Hit::b_start: face, u, v) evaluate to the point within tolerance; touch where the curve's tangent lies within 1e-3 (sine) of the surface's tangent plane there (a graze), false at a crossing. A run is a stretch of one segment lying within tolerance of one face and inside it, longer than tolerance. Hits within tolerance of each other merge (a hit at a segment join reported once, as (k, t = 1); a closed loop's closing join reads (0, 0)). Every point is in world space (the frame applied).

Pieces (Piece) only for a closed body — an open body has none — in loop order, covering every loop exactly; a piece's spots read a segment join as the next segment's start (k + 1, 0), and an open chain runs from (0, 0) to (n - 1, 1); a loop no hit cuts is one closed piece. inside by the piece middle's winding number over the body's mesh; a piece lying on the surface is inside. Known limit: a segment passing within tolerance of a face without its polyline crossing the mesh can be missed (near-tangent grazes).

progress, where the wrapper takes one, is called with phases mesh, cull, hits and pieces and a done/total count. A tolerance not positive and finite, a solid with no faces or that meshes to nothing, a profile with no segments, or a free-form segment that is not an evaluable NURBS curve returns an Error in its Result.

Solid::split_sheet()

Result<Solid> split_sheet(const Solid& tool, double tolerance = DEFAULT_TOLERANCE, const Progress& progress = {}) const

This solid or sheet cut along tool's boundary with nothing removed: each face comes back as its pieces outside tool and then its pieces inside, in the original face order — the start of a surface trim. tool must be a closed solid. Keep the pieces you want with Solid::drop_faces(), or split and drop in one call with Solid::trim().

Solid::face_sheet()

Result<Solid> face_sheet(std::uint32_t f) const

One face alone, as an open sheet: its surface, its loops and the exact curves on its edges, the rest of the solid left behind — raised by Solid::extrude_faces() it is the prism over that face. Keeps the face's colour.

Solid::drop_faces()

Result<Solid> drop_faces(const std::vector<std::uint32_t>& which) const

This solid without the faces listed: the rest keep their surfaces, curves and colours in their order, so an index into the result is this one's with the dropped ones closed up. Dropping every face returns an Error in its Result.

Solid::trim()

Result<Solid> trim(const Solid& tool, Keep keep = Keep::outside, double tolerance = DEFAULT_TOLERANCE, const Progress& progress = {}) const

This sheet (or solid) cut along the closed tool's boundary and the pieces on one side thrown away: keep Keep::outside (the default) keeps what lies outside the tool — a hole punched through — and Keep::inside what lies within it. Nothing on the kept side returns an Error in its Result. tolerance and progress as for Solid::join().

keep is Keep::outside or Keep::inside.

Solid::push_pull()

Result<Solid> push_pull(std::uint32_t f, double distance, double tolerance = DEFAULT_TOLERANCE, const Progress& progress = {}) const
Result<Solid> push_pull(const std::vector<std::uint32_t>& which, double distance, double tolerance = DEFAULT_TOLERANCE, const Progress& progress = {}) const
Result<Solid> push_pull(std::initializer_list<std::uint32_t> which, double distance, double tolerance = DEFAULT_TOLERANCE, const Progress& progress = {}) const

Face face pushed out by distance along its outward normal — pulled in, negative — as a face extrude does it: the prism over it joined on (cut out) at tolerance, and the flush faces merged, so a box's top raised is one taller box of six faces rather than a box and a prism with every side wall split at the seam. A face on a cylinder, a cone, a sphere or a torus moves out along its normal instead, as a press-pull does: the surface a step out — a boss fatter, a bore or a countersink narrower, a dome fuller — with the flat faces beside it carried along in their own planes. Any other curved face is refused, as is a curved face with anything but a plane it can follow beside it, reaching a cone's apex, pushed to its axis or centre, off a plane beside it or run into another edge. A flat face keeps its own colour where it now lies.

Several faces push together, as a press-pull on a selection: each by its own rule, one after another in the order given, each found again after the pushes before it renumbered the faces — a box's top and a side pushed 5 is the box 5 taller and 5 wider, a boss's top and wall the boss taller and fatter. A face on the same curved surface as one before it, and joined to it, moved with that one and is not pushed twice. No faces, or a face an earlier push took away, returns an Error in its Result.

Overloaded: a face index, or a std::vector<std::uint32_t> of them.

Solid::refillet()

Result<Solid> refillet(std::uint32_t f, double radius, double tolerance = FILLET_TOLERANCE) const

The round face belongs to — a fillet's bands, balls and rim bands joined to that face — made again at radius, as a press-pull on a fillet face: taken back to the sharp edges it replaced, and those rounded again, so the round is the one Solid::fillet() makes at that radius. Rounds of straight edges between planes (their ends square corners, mitres, balls, or a cylinder, cone or sphere the edge runs into — a D-cut shaft's top edge, a rib's into a boss) and of circular rims between a plane and a cylinder or cone (a boss's foot, a bore's mouth, a counterbore's step); a face that is not one, or a radius that does not fit, returns an Error in its Result.

Solid::unfillet()

Result<Solid> unfillet(std::uint32_t f) const

The round face belongs to taken off, the faces beside it made sharp again, meeting on the edges the round replaced — the delete of a fillet face. The same rounds as Solid::refillet().

Solid::rechamfer()

Result<Solid> rechamfer(std::uint32_t f, double distance, double tolerance = FILLET_TOLERANCE) const

The chamfer face belongs to — its bevels (flat between two planes, cones round rims) and the corner triangles joined to that face — cut again at distance, as a press-pull on a chamfer face: taken back to the sharp edges it cut, and those bevelled again, so the chamfer is the one Solid::chamfer() cuts at that distance. A flat bevel's ends may run into a cylinder, cone or sphere, as a round's may. A face that is not a chamfer's bevel, or a distance that does not fit, returns an Error in its Result.

Solid::unchamfer()

Result<Solid> unchamfer(std::uint32_t f) const

The chamfer face belongs to taken off, the faces beside it made sharp again — the delete of a chamfer face. The same chamfers as Solid::rechamfer().

Solid::merge_flush()

Result<Solid> merge_flush() const

This solid with its flush faces merged: flat faces on one plane, facing one way and meeting along their edges — the seams Solid::join() leaves where two parts are flush — made one face, and the vertices left mid-way along a straight edge taken out.

Solid::split()

Result<std::vector<Solid>> split(const Solid& tool, double tolerance = DEFAULT_TOLERANCE, const Progress& progress = {}) const

This solid split by tool into bodies — returned as a list: a closed tool gives the parts outside it, then the parts inside; a flat sheet (a Solid::face()) splits by the whole plane it lies on. Each connected part is a body of its own, so a U cut across both arms is three. The new faces are pieces of the tool's, the colours carried over. A tool that does not cross the solid, or a curved sheet, returns an Error in its Result. tolerance and progress as for Solid::join().

Solid::split_by_plane()

Result<std::vector<Solid>> split_by_plane(const Frame& plane, double tolerance = DEFAULT_TOLERANCE, const Progress& progress = {}) const