# geometry capsule

Describes the entry `capsule` at version `0.2.0`, registered by `mime.scene._solids.Capsule`.

Kept registered beside it: `capsule` at version `0.1.0`, by `mime.scene._previous.CapsuleGrid`, which a document naming that version loads; its differences are in the hand-written part's versions.

## At a glance

- geometry `capsule`, version `0.2.0`, namespace `mime`
- Derivative: `piecewise_jump`
- Validity: none declared

## What it models, and when not to use it

### `capsule`

A solid capsule: a cylinder of a radius and a height (between the centres of its caps, as USD's `Capsule` counts it)
along an axis, capped by two hemispheres, centred on its centroid. An elongated body pulled by a field gradient, or a
rod. As a body's part it gives the body its volume and inertia, its extent (its radius, about its own axis) and its
surface samples by patch, `lateral` and `caps`; at run time a node evaluates it by the shape `capsule`.

**When not to use it.** For a body whose extent across its axis is not its radius all along: a tapered or a threaded
body. A capsule tilted in a tube reaches further than its radius from the tube's axis, which the extent does not hold.

**Its derivative** is the shape's: the distance from its segment less the radius, so on the segment the distance is a
cone and the normal has no limit; across the planes through the segment's ends only the curvature changes.

**Its sampling.** At a spacing, for a solver whose unknowns sit at the samples (the MRS rung), it samples its surface
quasi-uniformly: as many samples as its quadrature has at that spacing, chosen from its quadrature at a finer spacing
by farthest points and Lloyd's relaxation (`mime.scene.quasi_uniform`), each a quadrature sample with its cell's area as
its weight, so that no two crowd. Its hull query, its reach in a direction, is the sphere's about the end of its segment
that lies that way.

**Regions, surfaces, directions and frames.** What a kind names and how a law or a stage reads it: [the scene note](../../scene.md).

**Versions.** 0.2.0 samples its surface quasi-uniformly; 0.1.0, the first, sampled it by its
quadrature, whose polar grids crowd the caps' poles (MIME-ANO-123). 0.1.0 stays registered so that a folder saved with
it loads and reproduces; a script that writes `Capsule(...)` gets 0.2.0. The quadrature, the shape and every closed form
are unchanged.

## Settings

| Setting | Type | Default | Dimension | Role | Default's kind |
|---|---|---|---|---|---|
| `axis` | `Annotated[DirectionLike, Direction]` | `{"required": true}` | marked Direction | physical | none |
| `height` | `Annotated[Quantity, Length]` | `{"required": true}` | length (m) | physical | none |
| `radius` | `Annotated[Quantity, Length]` | `{"required": true}` | length (m) | physical | none |

Each role and default's kind is the entry's `setting_roles` (`mime.registry.SettingRole`); a setting that declares none is required.

## Capabilities

Generated from which of the optional methods of `mime.registry.Geometry` the kind implements; a consumer that needs one it lacks is refused when it plans, naming both.

| Capability | What it gives | Used by | This kind |
|---|---|---|---|
| `samples` | surface samples by named patch, at a resolution the consumer chooses | the MRS; immersed-boundary markers | yes |
| `area` | the area of each patch | the samples' weights | yes |
| `mass_properties` | volume and inertia at a density | the part resolver | yes |
| `radial_reach` | the hull's radial reach about its axis | a body's extent; contact on the hull | yes |
| `family_parameters` | the parameters of the family it is | a surrogate trained on one family | yes |
| `tangent` | a tangent it declares at a surface point | a law anisotropic along it | no |
| `native` | its native form, one of USD's own primitives | the stage writer | yes |
| `drawing` | a drawing, tessellated at the writer's resolution | the stage writer, for a kind with no native form | no |
| `region_primitive` | its regions as OpenMaterica's primitives: exactly, or (a region with no end along an axis) clipped at the kind's own length, or refused | OpenMaterica's manifest and stage | yes |
| `reach` | reach | not stated | yes |
| `sampling` | sampling | not stated | yes |
| `support` | support | not stated | yes |

`native`: written as USD's `Capsule`, its attributes the kind's settings (`height` holds `height`, `radius` holds `radius`, `axis` is `Z`).

`placement`: `axis` is its prim's z axis; on a stage, the prim's transform, never an attribute.

Run-time capabilities (signed distance, outward normal, nearest point) are its regions' and surfaces' shapes, listed below.

## Nodes it builds

Builds no node of its own.

## Gradient status

The derivative through this entry is `piecewise_jump`: not the exact derivative of what it computes everywhere.

## Validity

none declared

## References

[@WeissteinCylinder], [@WeissteinEllipsoid]

## Other declarations

| Class variable | Type | Value |
|---|---|---|
| `directions` | `ClassVar[tuple[str, ...]]` | `[]` |
| `moving` | `ClassVar[bool]` | `false` |
| `patches` | `ClassVar[Mapping[str, str]]` | `{"caps": "solid", "lateral": "solid"}` |
| `reach_envelope` | `ClassVar[float]` | `0.0` |
| `region_shapes` | `ClassVar[Mapping[str, str]]` | `{"solid": "capsule"}` |
| `regions` | `ClassVar[tuple[str, ...]]` | `["solid"]` |
| `support_basis` | `ClassVar[str]` | `closed form` |
| `support_error` | `ClassVar[float]` | `0.0` |
| `surfaces` | `ClassVar[Mapping[str, str]]` | `{}` |