# 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<Body> |
| CreateSolid.Sphere | `cadkernel::brep::make::sphere` | Option<Body> |
| SolidBoolean | `cadkernel::brep::combine` | Result<Body, Snag> |
| Transform | `cadkernel::brep::transform` | Option<Body> |
| GetBounds | `cadkernel::brep::body_bounds` | Option<Aabb> |
| GetVolume | `cadkernel::brep::mesh_body + divergence` | computed |