fastsim.api.geometry

class GeometryPurpose(StrEnum)

class GeometryRepresentation(StrEnum)

class GeometryMotionClass(StrEnum)

class GeometryStorageKind(StrEnum)

class GeometryLocatorScheme(StrEnum)

class GeometryAxis(StrEnum)

class SignedGeometryAxis(StrEnum)

class GeometryDType(StrEnum)

class GeometryContentProfile(StrEnum)

Closed, versioned byte layouts supported by ``scene.geometry@2``. Every profile is headerless, C-contiguous, and little-endian. Consequently ``byte_size`` is both the encoded payload size and the decoded array size in version 1; compressed/container formats require a future profile or service version instead of being guessed from an arbitrary format string.

class GeometrySdfSignConvention(StrEnum)

class GeometryVoxelValueSemantics(StrEnum)

class GeometryAxisConvention(object)

Fully specified portable basis convention for one resolved resource.

class MeshResourceSchema(object)

Raw mesh arrays: vertices first, then triangle indices. Both arrays are headerless C-order arrays. Vertices have shape ``(N, 3)`` in metres and use a floating dtype. Triangle indices have shape ``(M, 3)`` and use an unsigned integer dtype. The profile fixes little-endian byte order; ``index_byte_offset`` is therefore the exact vertex byte count.

class SdfResourceSchema(object)

Dense SDF array with shape ``(X, Y, Z)`` and Z as the fastest axis.

class VoxelResourceSchema(object)

Dense uint8 occupancy grid shaped ``(X, Y, Z)``, Z fastest.

class HeightfieldResourceSchema(object)

Dense height samples shaped ``(Y, X)`` with X as the fastest axis.

class AxisAlignedBoundingBox(object)

A finite AABB expressed in one explicitly named frame.

class CollisionFilterMetadata(object)

Portable collision-layer membership and allow-list metadata.

class InlineBox(object)

class InlineSphere(object)

class InlineCapsule(object)

class InlineCylinder(object)

class InlineHalfspace(object)

Exact infinite half-space with local boundary ``z=0`` and solid ``z<=0``.

class GeometryLocalPose(object)

A frame-free geometry-local rigid transform. In ``InlineCompoundPart`` this value is exactly ``geometry_T_part``. It is intentionally not a :class:`Pose`: a geometry-local coordinate system is not a public FrameCatalog node and therefore must not masquerade as one.

class InlineCompoundPart(object)

One primitive child in a bounded inline compound collider. ``local_pose`` is exactly ``geometry_T_part``. It has no ``frame_id`` because the geometry-local coordinate system is not a FrameCatalog node.

class InlineCompound(object)

aabb_intersects_halfspace(aabb: AxisAlignedBoundingBox, parent_frame_T_halfspace: Pose) -> bool

Return exact analytic intersection with an oriented infinite half-space. The AABB and pose must use the same frame. Local ``+Z`` is the outward normal, so a point is occupied exactly when ``normal · (point-origin) <= 0``.

class GeometryCatalogEntry(object)

One path-free collision, visual, or planning geometry fact. ``local_pose`` is ``parent_frame_T_geometry``; its ``frame_id`` is the owning entity/link frame selected by the provider. Compound child poses are frame-free ``geometry_T_part`` values.

class GeometryQuery(object)

Bounded deterministic intersection filter shared by geometry reads.

class GeometryCapabilities(object)

Exact service capabilities; callers must fail closed outside this set.

class GeometryCatalogSnapshot(object)

Path-free deterministic structural geometry for one generation.

class ScopedResourceLocator(object)

Opaque provider-scoped locator; never a filesystem path or native handle.

class GeometryResourceLeaseDescriptor(object)

Portable metadata for one digest-verified read-only resource lease. The v1 resource profiles deliberately support only closed raw little-endian encodings. ``byte_size`` is the encoded byte length and must exactly equal ``schema.decoded_byte_size``. A future compressed encoding must introduce another explicit profile with its own encoded/decoded relationship.

class GeometryResourceReadRequest(object)

One ordered, bounded byte-span request within a resolved batch.

class GeometryResourceReadResult(object)

One immutable payload result in the exact order requested by a caller.

class ResolvedGeometryResource(Protocol)

Live provider-owned lease around an immutable resource descriptor. ``read`` returns an exact immutable ``bytes`` chunk and must enforce :meth:`GeometryResourceLeaseDescriptor.read_span`. It never exposes a filesystem path, shared-memory object, mmap, file object, native handle, or mutable buffer. A provider invalidates every retained lease on service revocation or generation reset. ``descriptor`` and ``read`` after revocation or close must raise ``RESOURCE_LEASE_REVOKED``. ``closed`` and idempotent ``close`` remain available for lifecycle cleanup.

class ResolvedGeometryResourceBatch(Protocol)

Generation-scoped lease over ordered immutable geometry resources. ``descriptors`` is shared by lightweight aliases of the same compiled batch. ``read`` addresses one member by geometry ID without exposing a native handle or requiring one Python lease object per resource. ``read_many`` validates the complete request before one provider batch operation. Results preserve request order; exact duplicate spans retain duplicate logical results while providers may read their native bytes once. Logical result bytes, including duplicates, must fit ``max_total_bytes``; callers split larger worlds into bounded batches. High-rate callers should compile and retain one immutable request tuple per static catalog revision; providers may reuse its validated spans and immutable results by identity. Rebuilding an equivalent tuple is a new public-boundary request and may require O(N) validation again.

class GeometryTransform(object)

One geometry pose expressed in its enclosing snapshot's world frame.

class GeometryAttachmentRecord(object)

Compact attachment relation for planner collision-world mirrors.

class GeometryTransformSnapshot(object)

One committed transform/attachment view without geometry buffers.

class GeometryDeltaKind(StrEnum)

class GeometryDelta(object)

Exactly one structural update, transform update, or terminal resync.

class SceneGeometryErrorCode(StrEnum)

class SceneGeometryError(RuntimeError)

Typed bounded failure from ``fastsim.scene.geometry@2``.

validate_geometry_resource_binding(catalog: GeometryCatalogSnapshot, descriptor: GeometryResourceLeaseDescriptor, capabilities: GeometryCapabilities) -> GeometryCatalogEntry

Validate the exact catalog-to-resolved-resource join before publication. Providers call this after digest verification and before returning a live lease. No field is inferred and no representation fallback is permitted.

validate_geometry_projection(scene_catalog: object, scene_state: object, frame_catalog: object, geometry_catalog: GeometryCatalogSnapshot, transform_snapshot: GeometryTransformSnapshot, *, frame_transforms: tuple[TransformStamped, ...] | None=None) -> None

Validate one numerically coherent scene/frame/geometry projection. ``frame_transforms`` is the complete set of committed world-to-frame lookup results when arbitrary joint or named frames participate. For the compact base/link-only projection, the same values can be derived exactly from the scene state, which preserves the five-argument validation entry point.

validate_geometry_delta_against(catalog: GeometryCatalogSnapshot, attachments: tuple[GeometryAttachmentRecord, ...], delta: GeometryDelta) -> tuple[tuple[GeometryCatalogEntry, ...], tuple[GeometryAttachmentRecord, ...]]

Apply a delta to compact prior facts and validate resulting closure. This helper does not mutate inputs. It is the provider-side publication gate for relationships that cannot be checked from an isolated delta.

class GeometryDeltaSubscription(Protocol)

class SceneGeometryService(Protocol)

Capability-scoped collision catalog, resources, transforms, and deltas.

class SceneGeometryBatchService(SceneGeometryService, Protocol)

Optional additive batch-resource extension for scene geometry.