@spec chamfer(OCEx.Shape.t(), [OCEx.Shape.t()], number()) :: result(OCEx.Shape.t())

Bevels a nonempty selection of edges with a common distance.

distance must exceed 1.0e-7 model units. This is an equal-distance chamfer; angle/distance and two-distance variants are not exposed. Selections have the same ownership and duplicate checks as fillet/3. The kernel may reject a distance that does not fit the adjoining faces.

@spec clean(OCEx.Shape.t()) :: result(OCEx.Shape.t())

Merges adjacent faces and edges that share underlying geometry.

This includes concatenating compatible B-splines. Returns a new native resource even when no simplification is possible. It can change edge and face counts, so query selections from the returned shape.

Boolean operations in OCEx do not call this automatically.

@spec common(OCEx.Shape.t(), OCEx.Shape.t()) :: result(OCEx.Shape.t())

Returns the geometric intersection of two shapes.

Disjoint inputs produce an empty compound. A successful result can have zero volume; query its topology before using it as a solid. Neither input is changed, and same-domain cleanup is left to clean/1.

@spec compound([OCEx.Shape.t()]) :: result(OCEx.Shape.t())

Copies shapes into a compound without joining their boundaries.

The list may mix topology kinds or be empty. Overlapping solids retain their individual volumes and faces; use fuse/2 to combine material.

iex> {:ok, empty} = OCEx.compound([])
iex> OCEx.solids(empty)
{:ok, []}
iex> OCEx.bounds(empty)
{:error, :empty_shape}

@spec cut(OCEx.Shape.t(), OCEx.Shape.t()) :: result(OCEx.Shape.t())

Subtracts tool from body, preserving both inputs.

A missed tool can leave the geometry unchanged; removing the entire body can return an empty compound. The result is not guaranteed to be a single solid. Call clean/1 to merge same-domain faces afterward.

@spec draft(OCEx.Shape.t(), [OCEx.Shape.t()], point3(), number(), point3(), point3()) ::
  result(OCEx.Shape.t())

Tapers selected faces of one solid around a neutral plane.

A compound wrapping exactly one solid is also accepted. Collections with multiple solids or free faces/edges return :wrong_shape_type.

pull is a nonzero direction vector; angle is in degrees, strictly between -90 and 90. neutral_origin and neutral_normal define the world plane where the selected surfaces retain their intersection. The pull vector must not lie in that plane. Positive angles remove material on the pull side of the neutral plane; negative angles add it. Zero returns an independent copy after validating the inputs.

Faces must be planar, cylindrical, or conical and belong to this exact solid revision. Empty, foreign, and duplicate selections return :empty_selection, :foreign_subshape, or :duplicate_subshape. Unsupported surfaces return :unsupported_draft_surface.

OCCT propagates draft through tangent-connected faces; those faces must also support drafting. The operation cannot handle a taper that requires a topology change, such as collapsing an edge or deleting a face. Build failures return :draft_failed or a native geometry error. Invalid angles/vectors return :invalid_argument; a pull direction parallel to the neutral plane returns :invalid_direction. The input solid and selected faces remain unchanged.

@spec extrude(OCEx.Shape.t(), point3()) :: result(OCEx.Shape.t())

Extrudes a planar face or a nonempty compound of planar faces along a world vector.

The vector may be oblique to the face, but its normal component must exceed 1.0e-7 model units in magnitude. A vector lying in the face's plane returns {:error, :degenerate_extrusion}; a nonplanar face returns {:error, :non_planar_profile}. Face holes pass through the extrusion. Each face produces a solid. Compounds retain separate results; they are not fused. Collections containing edges, solids, or nonplanar faces fail.

@spec extrude(OCEx.Shape.t(), point3(), keyword()) :: result(OCEx.Shape.t())

Extrudes planar faces with symmetric extent and tapered walls.

Options are both: false and taper: 0. With both: true, the full vector applies in each direction, doubling the extent. Each profile still produces one solid; disconnected faces remain separate solids.

Taper is in degrees, strictly between −90 and 90. Positive taper removes material away from the starting plane: outer walls narrow and holes widen. Negative taper adds material. Symmetric taper applies the same angle to both halves with the original profile as their shared neutral section.

Nonzero taper requires travel perpendicular to the profile plane and planar or cylindrical prism walls. Unsupported curves return :unsupported_draft_surface; oblique taper returns :invalid_taper_direction. Collapsing walls or topology changes may return :draft_failed or :invalid_solid. This is not a loft through scaled sections. Zero taper retains the prism behavior of extrude/2. Invalid option lists return :invalid_options; out-of-range angles return :invalid_argument. Inputs remain unchanged.

@spec extrude_until(OCEx.Shape.t(), point3(), point3(), point3()) ::
  result(OCEx.Shape.t())

Extrudes planar faces along a direction until they meet an infinite plane.

origin and normal define the target plane in world coordinates. Direction and normal are nonzero vectors and are normalized. The entire profile must reach the target in the positive travel direction, at a distance greater than 1.0e-7 model units. The target may be tilted, but may not cross or touch the starting profile. Reversing the target normal does not change the result; reverse the travel direction to extrude backwards.

Holes and disconnected faces are preserved. Each face produces a separate solid. Travel may be oblique to the profile; walls remain straight and untapered. This operation targets a plane, not the nearest face of a body.

A parallel target returns :invalid_direction; a target not strictly ahead returns :target_not_ahead. Input topology and profile errors follow extrude/2. Invalid vectors return :invalid_argument. Inputs remain unchanged.

@spec fillet(OCEx.Shape.t(), [OCEx.Shape.t()], number()) :: result(OCEx.Shape.t())

Rounds a nonempty selection of edges with a common radius.

radius must exceed 1.0e-7 model units. Obtain the edges from this exact body using edges/1. Stale or foreign edges return :foreign_subshape; repeated selections return :duplicate_subshape. An empty selection returns :invalid_argument.

The kernel may reject a radius that cannot fit the surrounding geometry. Inputs remain unchanged. Call clean/1 if further topology simplification is needed.

@spec fuse(OCEx.Shape.t(), OCEx.Shape.t()) :: result(OCEx.Shape.t())

Unites two shapes, preserving both inputs.

Disjoint solids remain separate solids in the result. Touching or overlapping solids are combined where the Boolean algorithm permits. Call clean/1 explicitly to merge same-domain faces and edges.

@spec loft([OCEx.Shape.t()], keyword()) :: result(OCEx.Shape.t())

Builds a capped loft through at least two closed wires.

The only option is ruled: true (default), which joins sections with straight generators. ruled: false fits a smooth surface through them; it can overshoot between sections and does not guarantee a particular continuity at caps or seams. Unknown, duplicate, or invalid options return :invalid_options.

List sections in loft order. Each wire supplies one boundary; holes, guide rails, and seam controls are not supported. OCCT determines correspondence between section edges. An open section returns {:error, :open_wire}. Degenerate section arrangements may fail kernel construction or validation.

@spec offset(OCEx.Shape.t(), number(), keyword()) :: result(OCEx.Shape.t())

Builds a parallel surface or expands/contracts a solid by a signed distance.

Accepts faces, shells, solids, or compounds of those shapes. Positive distance follows surface normals, outward for an oriented solid; negative distance goes inward. Its magnitude must exceed 1.0e-7 mm. This is a 3D surface offset, not a planar outline offset.

join: :arc (default) fills convex gaps with rounded transitions; :intersection extends adjacent offset surfaces until they meet. Compound members are offset independently and are not fused. Sew faces first with sew/1 when adjacent faces must offset as one shell.

For solid inputs, the result must have positive volume and preserve directional containment: outward results contain the original; inward results stay inside it. Volume changes and containment use a tolerance of max(1.0e-9 mm³, original volume * 1.0e-9). Violations return :invalid_offset. A complete collapse is an error, not an empty result.

OCCT requires sufficiently smooth surfaces and offsets small enough to avoid inversion or self-intersection. C0 spline surfaces and complex intersections may fail. Global self-intersection repair is not enabled; successful BREP validation does not prove absence of every geometric self-intersection. Inputs remain unchanged. Unknown/duplicate options return :invalid_options; invalid distances return :invalid_argument.

@spec project(OCEx.Shape.t(), OCEx.Shape.t(), keyword()) :: result(OCEx.Shape.t())

Projects edges or wire boundaries onto target surfaces, returning wires.

Supply exactly one option: direction: {x, y, z} for parallel projection, or from: {x, y, z} for conical projection through a world point. Parallel directions are nonzero and normalized. Input coordinates and resulting curves remain in world space.

Sources may be edges, wires, faces, or compounds of those types. A face contributes every boundary wire, including holes; it does not contribute filled material. Targets may be faces, shells, solids, or collections of those types. Free edges in a target collection are rejected.

Returns one wire or a compound of wires. Curves are clipped to target face boundaries. Multiple target intersections are retained; this is not a nearest-hit selection. Parallel projection is bidirectional, so reversing its direction does not select the opposite side of a solid. Select target faces before projection when only one surface is wanted. Conical projection follows half-rays from the point through the source; it can hit before or beyond the source, but not behind the point.

A failed or missed source boundary returns :projection_failed; source collections are not partially accepted after a failed boundary. Successful partial intersections may yield open wires. No faces, shells, or solids are filled from the projected curves. Coincident target/sweep surfaces may return their boundary edges rather than isolated intersection curves. Degenerate geometry can fail. Unknown, duplicate, or missing options return :invalid_options. Bad vectors/points return :invalid_argument; unsupported topology returns :wrong_shape_type. Both inputs remain unchanged.

@spec revolve(OCEx.Shape.t(), point3(), point3(), number()) :: result(OCEx.Shape.t())

Revolves a face around a world axis.

origin is a point on the axis; axis is its nonzero direction vector. degrees must be greater than 1.0e-7 and at most 360. Rotation follows the right-hand rule; reverse the axis for the opposite turn.

The profile and sweep must form valid geometry. This binding validates the returned shape but does not separately assert a single positive-volume solid. Inspect solids/1 and volume/1 when that is required.

@spec section(OCEx.Shape.t(), point3(), point3()) :: result(OCEx.Shape.t())

Intersects solid material with an infinite plane, returning filled planar faces.

origin and normal define a world plane; the nonzero normal is normalized. Accepts the same solid collections as split/4. Holes and disconnected material regions are preserved. Returns one face or a compound of zero/multiple faces. An outside plane or contact only at points/edges gives an empty compound; a coincident boundary face remains.

Face normals follow the supplied plane normal. Coordinates remain in world space. Use area/1, wires/1, or extrude/2 on the result. Inputs remain unchanged. Invalid plane arguments return :invalid_argument; unsupported input topology returns :wrong_shape_type. This operation does not project geometry.

@spec shell(OCEx.Shape.t(), [OCEx.Shape.t()], number(), keyword()) ::
  result(OCEx.Shape.t())

Hollows a solid by removing selected faces and offsetting the remaining walls.

A compound wrapping exactly one solid is also accepted. Free faces/edges or multiple solids return :wrong_shape_type.

thickness is signed: negative builds inward, positive outward. Its magnitude must exceed 1.0e-7 model units. At least one opening is required. Faces must come from this exact body revision; foreign and duplicate faces return :foreign_subshape and :duplicate_subshape. The input is copied, including the correspondence of selected faces, before native construction.

join: :arc (default) rounds gaps between offset surfaces; join: :intersection extends adjacent surfaces to their intersection. Concave details, small radii, and excessive thickness can make the operation fail. Only valid, positive-volume solid results are returned. Inward results must remove material and stay inside the source solid within a volume tolerance of max(1.0e-9, source volume * 1.0e-9); failures return :invalid_thickness. General self-intersection repair, closed cavities, and face thickening are not exposed by this operation.

@spec split(OCEx.Shape.t(), point3(), point3(), keyword()) :: result(OCEx.Shape.t())

Splits solids with an infinite plane through origin along normal.

The plane normal is normalized. keep: accepts :both (default), :positive, or :negative; positive means the side toward the normal. Accepts a solid or a nonempty compound/compsolid containing only solids. Free faces and edges are rejected with :wrong_shape_type.

Returns a solid for one remaining piece or a compound for zero/multiple pieces. Both sides retain separate solids at the cut. A plane outside the body preserves the whole body on its side and leaves the opposite side empty. Boundary-only contact does not produce zero-volume solids. Inputs remain unchanged; output topology belongs to a new revision.

Invalid planes return :invalid_argument; unknown, duplicate, or invalid options return :invalid_options. Kernel failures are tagged errors.

@spec sweep(OCEx.Shape.t(), OCEx.Shape.t(), keyword()) :: result(OCEx.Shape.t())

Sweeps one closed planar wire along an open wire, returning a capped solid.

Place the profile in the plane through the path's starting vertex, perpendicular to its starting tangent. Its in-plane offset is retained; OCEx does not center or rotate the profile automatically. Misplacement returns :misaligned_profile. The spine must be a connected, nonbranching wire. Closed paths and profiles with holes are not supported by this binding.

Options:

• :frame — :corrected (default, corrected Frenet) or :frenet. Controls how the section turns along a curved path.
• :transition — :transformed (default), :right (intersect adjoining swept segments), or :round (rotate around the corner). Sharp corners may fail or self-intersect; use tangent-continuous paths for predictable results.

Both inputs are copied before construction. Invalid geometry returns a tagged kernel error. Successful BREP validation does not prove that an arbitrary sweep is free of geometric self-intersections.

@spec thicken(OCEx.Shape.t(), number(), keyword()) :: result(OCEx.Shape.t())

Builds solid material between an open surface and its signed offset.

Accepts a face, an open shell, or a compound of these. Thickness magnitude must exceed 1.0e-7 mm; positive follows oriented surface normals and negative goes against them. The original surface forms one boundary, and free edges receive connecting walls. Holes in faces remain holes.

join: :intersection (default) extends adjacent offset surfaces; :arc uses rounded transitions where applicable. Sew connected faces with sew/1 first. Disconnected compound members produce separate solids without fusing. Solid inputs return :wrong_shape_type; closed shells return :closed_shell.

Results must contain positive-volume solids and pass native validation. Surface smoothness and self-intersection limits follow offset/3. Excessive thickness may collapse or invert curved features and fail with :thicken_failed, :invalid_solid, or another native geometry error. No global self-intersection repair or variable wall thickness is provided. Input geometry remains unchanged.