Annotation Volume Measurements

Volume measurement is an additional annotation mode shown beside the ordinary measurement types and selected explicitly. It does not replace or change the normal distance, area, m², VOB, report, or DXF measurement workflows, and clients must never select it as the default mode.

Availability

Authenticated volume routes require all of the following:

• the backend VolumeMeasurements switch is enabled;
• the caller uses an interactive signed-in user session;
• the selected source is a ready model artifact for the same location; and
• the caller has the ordinary location and source permissions.

Personal access tokens, API keys, and service identities are not interactive authoring sessions. No administrator or organization-owner role is required as a separate rollout gate. Call the capability route before loading authoring tools:

GET /v1/spatial/locations/{locationId}/volume-measurement-capabilities?sourceArtifactId={sourceArtifactId}&annotationId={annotationId}

Before an annotation exists, omit annotationId to check whether the selected model can begin authoring. After creating or loading a volume annotation, pass its ID so readiness is checked against that exact definition revision, source, and transform. The indexedVolumeCalculation member contains stable reason codes, resolved annotation/index identity, the indexed algorithm and sidecar versions, the automatic reference mode, and mesh-independent footprint/time limits. Camera/image metadata is not required for indexed volume. Treat the mode-specific capability as the authoring decision; do not infer eligibility from a role.

Authoring and calculation

Indexed calculation submits the closed footprint only. BackgroundJobs selects bounded footprint-relevant geometry from the immutable model index; the browser does not copy rendered triangles, encode PXVS, or upload calculation input. Units, up axis, handedness, source version and checksum, and the model-to-calculation transform must be known; the server does not guess missing provenance or fall back to loading the whole model.

Viewer raycasts may use a recentered or rotated scene even though the geometry index uses authored model coordinates. Keep the annotation boundary in viewer coordinates and include coordinateFrame.boundaryToModel as the finite, invertible 4x4 column-major affine transform from that boundary frame to the indexed model frame. The server applies it before modelToCalculation. Omit the field only when both frames are identical; omission remains identity for older definitions. The versioned transform digest covers both matrices.

In the viewer, trace the plan-view footprint around the elevation and close it at the first point or with Enter. New and edited definitions use boundaryTriangulatedSurface: the server deterministically triangulates the simple boundary and every local reference triangle passes through its three exact selected 3D points. The viewer renders that underside directly without a second dashed planar outline. Historical calculations may retain a best-fit or horizontal plane and remain readable with their original semantics.

The displayed volume is the positive material above the matching local reference surface. This measures one visible height surface; it is not a watertight solid-volume calculation and does not accumulate hidden or internal building geometry.

When indexedVolumeCalculation.available is true, create the polygon annotation with its volume definition and queue:

POST /v1/spatial/annotations/{annotationId}/volume-calculations/indexed
Idempotency-Key: <stable request key>
Content-Type: application/json

{"expectedDefinitionRevision": 1}

The indexed request accepts no geometry, chunk, storage, range, or result fields. The server resolves and immutably pins the current model artifacts and geometry-index run. Missing, pending, stale, or incompatible index state returns a stable prerequisite conflict and queues nothing.

Calculation responses include inputMode. Legacy legacyPxvs records keep their immutable input artifact, checksum, and schema pins. New indexedModelGeometry records omit those legacy input fields and return an immutable model/index pin summary instead. Legacy PXVS creation and upload routes are retired; historical results, reports, evidence, and public-share snapshots remain readable. An indexed request never falls back to PXVS.

Definition updates use PUT /v1/spatial/annotations/{annotationId}/volume-definition and optimistic expectedRevision concurrency. A conflict returns the current definition so the user can explicitly reconcile and retry. Dragging a vertex is only a local draft; it must not create calculations.

Lifecycle values are Queued, Running, Succeeded, Invalid, Failed, and Cancelled. Invalid means the geometry was understood but rejected, for example because of a gap, overlap, disconnected surface, ambiguous layer, invalid footprint, or digest mismatch. Failed represents processing or storage failure. Terminal notifications can prompt a refresh, but clients must retain bounded backoff polling as a fallback.

The current indexed surface policy repairs only an isolated, fully enclosed single-sample hole whose covered neighbours define an unambiguous local plane. It does not bridge adjacent holes, footprint/model boundaries, or ambiguous layers. If coverage still fails, the response can contain up to 20 coverageGapPoints in the annotation boundary/viewer coordinate frame. These are display hints, not authoritative geometry: show them only for the invalid calculation, clear them on retry or panel teardown, and use them to explain when moving the footprint edge slightly inward may avoid an uncovered model edge.

Results and assurance

Successful results provide projected and covered area in square metres. The user-facing volume is the API result's positive cutCubicMetres component: material below the reference surface is not subtracted. fillCubicMetres and netCubicMetres remain calculation/evidence diagnostics and are not displayed as separate measurements in the viewer, labels, public shares, or ordinary reports. Store and compare full-precision values; rounding is presentation-only.

New indexed results record assurance ServerCalculatedFromIndexedModelGeometry; historical PXVS results retain ServerCalculatedFromClientSnapshot. Neither label claims independent survey verification or REB, OKSTRA, or other formal standards conformance. Ordinary viewer panels, labels, shares, and reports do not expose the raw enum or an evidence-download control. API evidence downloads are short-lived, authorization-checked links for the checksum-pinned server manifest.

Limits and public sharing

The capability advertises the footprint point-count and processing timeout. BackgroundJobs separately enforces bounded indexed chunk, byte, triangle, memory, temporary-disk, and time policies. These controls do not depend on the model resolution loaded by the browser and never trigger a whole-model fallback.

A public location share can contain an immutable captured volume footprint and the then-current successful scalar/reference summary. Public viewers render that captured snapshot even when authoring flags are off. They must not poll live calculation routes or expose edit, recalculate, input, history, or evidence actions. Later edits and recalculations do not alter an existing share snapshot.