> ## Documentation Index
> Fetch the complete documentation index at: https://invariant-cad.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Measurements and mass properties

> Read geometric measurements, density-aware physical properties, inertia, and radii of gyration.

## Geometric measurements

Every evaluated solid, part, and assembly exposes `measure()`:

```ts theme={"system"}
const properties = output.measure();

console.log(properties.volume);          // mm^3
console.log(properties.surfaceArea);     // mm^2
console.log(properties.centerOfMass);    // [x, y, z] in mm, or null
console.log(properties.inertiaTensor);   // central volumetric inertia, mm^5
console.log(properties.boundingBox);
if (properties.genus === null) {
  console.log("genus is unsupported by this backend/result");
} else {
  console.log(properties.genus);         // exact nonnegative integer
}
console.log(properties.tolerance);
```

`genus` never uses a guessed value. A number is the exact sum of the genera of
the connected components in the backend representation; `null` means that the
backend or aggregate result cannot establish that quantity exactly. Manifold
decomposes the mesh and sums each validated component genus. Stock and owned
OCCT currently return `null` because their exposed native boundary lacks the
edge-degeneracy primitive needed for a correct bounded B-Rep computation.
Assemblies also return `null`: an occurrence mesh is an aggregate view, not a
Boolean-unioned closed boundary.

The inertia tensor uses the standard mechanics sign convention
`∫((r · r)I - rrᵀ) dV` about `centerOfMass`, expressed in world axes. It is a
volumetric tensor until scaled by density.

## Principal inertia

```ts theme={"system"}
const principal = principalInertia(properties.inertiaTensor);

console.log(principal.moments);
console.log(principal.axes);
console.log(principal.axisStatus, principal.degeneracy);
```

The result handles repeated or nearly repeated eigenvalues explicitly. In a
sphere or symmetric cylinder, individual principal axes are not uniquely
physical; consumers should inspect degeneracy/status rather than presenting an
arbitrary axis as meaningful.

## Axis queries

```ts theme={"system"}
const inertia = momentOfInertiaAboutAxis(properties, {
  point: [0, 0, 0],
  direction: [0, 0, 1],
});

const radius = radiusOfGyrationAboutAxis(properties, {
  point: [0, 0, 0],
  direction: [0, 0, 1],
});
```

Axis directions are normalized and validated. Parallel-axis translation is
applied when the requested axis does not pass through the centroid.

## Physical mass properties

Parts and assemblies require authored mass density:

```ts theme={"system"}
const aluminum = cad.material("aluminum", {
  name: "Aluminum",
  massDensity: kgPerCubicMeter(2700),
});

const part = cad.part("body-part", body, {
  materialRef: aluminum,
});
```

Then:

```ts theme={"system"}
const physical = evaluatedPart.physicalMassProperties();
if (!physical.ok) {
  console.error(physical.diagnostics);
} else {
  console.log(physical.value.mass);            // kg
  console.log(physical.value.centerOfMass);    // mm
  console.log(physical.value.inertiaTensor);   // kg mm^2
}
```

Density is stored in base unit kg/mm³. Helper constructors convert common
engineering units without changing document semantics.

## Assembly aggregation

Assembly physical properties transform each occurrence's centroid and tensor,
apply determinant volume scaling for affine placements, and combine them using
the parallel-axis theorem. Mirrored occurrences remain positive mass; a
nonuniform scale changes volume and inertia as geometry requires.

Missing density is a diagnostic, not zero mass. A BOM may still report known
mass and `massComplete: false` while aggregate physical properties fail.

## Combining external properties

`combinePhysicalMassProperties` combines already computed records after the
caller has expressed them in the same world frame; it does not accept or apply
placements itself. `physicalMassProperties` converts volumetric properties
plus density into a physical record. These helpers are useful for integrations
that combine InvariantCAD output with externally measured components.

## Precision source

OCCT measures exact native shapes and verifies certain sweep volumes against
analytic profile/path oracles, but does not currently report genus. Manifold
provides native volume and surface-area measurements with mesh-based tensor
integration and exact genus for its mesh representation. Check `tolerance`,
nullable capabilities, and backend representation when comparing results
across kernels; equality of authored intent does not promise byte-identical
floating-point output.