OneCAD-Draft/crates/ocs_doc_api/src/gen/api_reference.md

ocs_doc_api — API reference (auto-generated)

Envelope version: 1

Do NOT edit: regenerated by build.rs from spec/entities.toml.

Solid (acadrust Solid3D, collection solids)

B-rep solid. Host resolves bodies via the solid_models cache (lift-on-miss from ACIS SAT).

Constructors (doc.solids())

• create_cuboid(origin: [f64; 3], size: [f64; 3]) -> Solid
• create_sphere(centre: [f64; 3], radius: f64) -> Solid
• create_cylinder(base: [f64; 3], radius: f64, height: f64) -> Solid
• create_cone(base: [f64; 3], radius: f64, height: f64) -> Solid
• create_torus(centre: [f64; 3], major_radius: f64, minor_radius: f64) -> Solid
• create_wedge(origin: [f64; 3], size: [f64; 3]) -> Solid
• extrude(profile: EntityRef, direction: [f64; 3]) -> Solid
• revolve(profile: EntityRef, pivot: [f64; 3], axis: [f64; 3], angle: f64) -> Solid

Methods

• intersect(other: Solid) -> Solid — op SolidBoolean
• union(other: Solid) -> Solid — op SolidBoolean
• subtract(other: Solid) -> Solid — op SolidBoolean
• volume(``) -> f64 — query GetVolume
• centroid(``) -> [f64; 3] — query GetCentroid
• intersects(other: Solid) -> bool — query GetIntersects

Line (acadrust Line, collection curves)

Constructors (doc.curves())

• create_line(start: [f64; 3], end: [f64; 3]) -> Line

Circle (acadrust Circle, collection curves)

Constructors (doc.curves())

• create_circle(centre: [f64; 3], radius: f64) -> Circle

Polyline (acadrust LwPolyline, collection curves)

Constructors (doc.curves())

• create_polyline(points: &[[f64; 3]], closed: bool) -> Polyline

Methods

• add_vertex(at: usize, point: [f64; 3]) -> () — op AddVertex

Point (acadrust Point, collection curves)

Constructors (doc.curves())

• create_point(position: [f64; 3]) -> Point
• create_points(positions: &[[f64; 3]]) -> Vec<Point> (bulk op)

ArcCurve (acadrust Arc, collection curves)

Constructors (doc.curves())

• create_arc(centre: [f64; 3], radius: f64, start_angle: f64, end_angle: f64) -> ArcCurve

Ellipse (acadrust Ellipse, collection curves)

Constructors (doc.curves())

• create_ellipse(centre: [f64; 3], major_axis: [f64; 3], ratio: f64, start: f64, end: f64) -> Ellipse

Spline (acadrust Spline, collection curves)

Constructors (doc.curves())

• create_spline(degree: i32, control_points: &[[f64; 3]], knots: &[f64], weights: &[f64]) -> Spline

Ray (acadrust Ray, collection curves)

Constructors (doc.curves())

• create_ray(origin: [f64; 3], direction: [f64; 3]) -> Ray

XLine (acadrust XLine, collection curves)

Constructors (doc.curves())

• create_xline(origin: [f64; 3], direction: [f64; 3]) -> XLine

Entity (acadrust Insert, collection entities)

Block reference. Place an existing BlockRecord by name; transform moves its insert point.

Constructors (doc.entities())

• create_insert(block_name: &str, insert_point: [f64; 3], scale: f64, rotation: f64) -> Entity

Entity (acadrust Viewport, collection entities)

Paper-space viewport: a width×height window at center looking at view_target with view_height zoom. bounds = center ± w/2,h/2; transform moves center.

Constructors (doc.entities())

• create_viewport(center: [f64; 3], width: f64, height: f64, view_target: [f64; 3], view_height: f64) -> Entity

Generic methods (every handle)

Every typed handle (Solid, Line, Circle, Polyline, Point, Entity) is a Copy, Send, Sync token { ObjectId, session } and supports:

• id() -> ObjectId — the stable entity identity.
• bounds() -> Aabb — coarse bounding box (solids lift-on-miss; 2D entities computed; later families may be Unsupported).
• transform(placement) — in-place rigid similarity (same ObjectId). v1: solids only.
• delete() — remove the entity (one undo step).

Entity additionally has view() (id + kind + bounds) and as_solid() (typed downcast when kind == "Solid3D").

Collections & cross-cutting

• DocApi — root: document(tab), active_tab(), alive().
• Document — solids() / curves() / entities() factories + lookup, revision(), assert_revision(rev) (read-guard), query_batch(|q| …) (read-only batch, one round-trip, no revision bump).
• EntityCollection — get(id) -> Entity, delete(id), transform_many(&ids, placement), delete_many(&ids).
• OpGroup — best-effort client-side failure cleanup (track / commit / compensate). Not a transaction: no atomicity, no rollback.

Bulk ops — single op, all-or-nothing, item-capped

CreateMany / TransformMany / DeleteMany are single write ops: one undo step, one publish, and all-or-nothing via upfront validation (no rollback). Item-capped at BULK_ITEM_CAP = 100_000 to bound host execution. Use them for bulk data (N ≳ a few hundred); per-op autocommit is the right tool for modeling-scale work.

Semantics

• Per-op autocommit, no write transactions. Every write op is ONE atomic host call = one undo step. Multi-op write transactions were removed (security/ integrity review).
• Per-op atomicity. Validate + compute geometry before any mutation; a failed op applies nothing and records no undo step. erase_sources booleans run only on success.
• Structured errors. ApiError::{Validation, Geometry, UnknownId, Unsupported, Transport}; bulk validation names the failing index; a stale handle returns UnknownId (never a panic).

Kernel mapping

op	kernel call	returns
CreateSolid.Cuboid	cadkernel::brep::make::cuboid	Option
CreateSolid.Sphere	cadkernel::brep::make::sphere	Option
SolidBoolean	cadkernel::brep::combine	Result<Body, Snag>
Transform	cadkernel::brep::transform	Option
GetBounds	cadkernel::brep::body_bounds	Option
GetVolume	cadkernel::brep::mesh_body + divergence	computed