Physics Calculations

Inertia tensor calculations for various geometries.

Inertia Calculations

Inertia tensor calculation for primitive geometries.

Provides standard formulas and advanced numerical integration (Mirtich algorithm) for computing physically accurate mass properties of robot links.

Core Components:

calculate_inertia: Unified wrapper for all geometry types.
calculate_mesh_inertia_from_triangles: High-fidelity Mirtich integration.
_calculate_box/cylinder/sphere_inertia: Primitive analytic formulas.

linkforge.core.physics.inertia.calculate_box_inertia(box, mass)[source]

Calculate inertia tensor for a box (rectangular cuboid).

Parameters:

box (Box) – Box geometry with size (x, y, z)
mass (float) – Total mass in kg

Return type:

InertiaTensor

Returns:

Inertia tensor about center of mass

linkforge.core.physics.inertia.calculate_cylinder_inertia(cylinder, mass)[source]

Calculate inertia tensor for a cylinder (axis along Z).

Parameters:

cylinder (Cylinder) – Cylinder geometry with radius and length
mass (float) – Total mass in kg

Return type:

InertiaTensor

Returns:

Inertia tensor about center of mass

linkforge.core.physics.inertia.calculate_sphere_inertia(sphere, mass)[source]

Calculate inertia tensor for a sphere.

Parameters:

sphere (Sphere) – Sphere geometry with radius
mass (float) – Total mass in kg

Return type:

InertiaTensor

Returns:

Inertia tensor about center of mass

linkforge.core.physics.inertia.calculate_mesh_inertia_from_triangles(vertices, triangles, mass)[source]

Calculate inertia tensor for a triangle mesh using the Mirtich algorithm.

Based on: Brian Mirtich, “Fast and Accurate Computation of Polyhedral Mass Properties,” Journal of Graphics Tools, volume 1, number 2, pages 31-50, 1996.

This implementation uses the Divergence Theorem to convert volume integrals into surface integrals across triangles. The calculation follows 4 phases:

Validation: Ensures mesh topology and numerical integrity.
Conditioning: Translates mesh to a local mean origin to preserve floating-point precision.
Integration: Accumulates signed volume and moments across all tetrahedra.
Normalization: Applies Parallel Axis Theorem and density scaling to produce the final tensor about the Center of Mass (CoM).

Parameters:

vertices (list[tuple[float, float, float]]) – List of (x, y, z) vertex coordinates in meters
triangles (list[tuple[int, int, int]]) – List of (v0, v1, v2) triangle indices
mass (float) – Total mass in kg

Return type:

InertiaTensor

Returns:

Inertia tensor about center of mass in kg·m²

Raises:

RobotPhysicsError – If mesh is non-manifold, zero-volume, or physically unstable

linkforge.core.physics.inertia.calculate_mesh_inertia_approximation(mesh, mass)[source]

Calculate approximate (bounding box) inertia for a mesh.

This is a lightweight fallback that treats the mesh as an axis-aligned bounding box based on its scale. It does not require triangle data.

Parameters:

mesh (Mesh) – Mesh geometry with scale
mass (float) – Total mass in kg

Return type:

InertiaTensor

Returns:

Approximate inertia tensor using bounding box approximation

linkforge.core.physics.inertia.calculate_inertia(geometry, mass)[source]

Unified wrapper for any geometry type.

Parameters:

geometry (Box | Cylinder | Sphere | Mesh)
mass (float)

Return type:

InertiaTensor

Usage Examples

Box Inertia

from linkforge.core.physics import calculate_box_inertia
from linkforge.core import Box, Vector3

box = Box(size=Vector3(1.0, 0.5, 0.3))
inertia = calculate_box_inertia(box, mass=10.0)

print(f"Ixx: {inertia.ixx}")
print(f"Iyy: {inertia.iyy}")
print(f"Izz: {inertia.izz}")

Cylinder Inertia

from linkforge.core.physics import calculate_cylinder_inertia
from linkforge.core import Cylinder

cylinder = Cylinder(radius=0.1, length=0.5)
inertia = calculate_cylinder_inertia(cylinder, mass=5.0)

Sphere Inertia

from linkforge.core.physics import calculate_sphere_inertia
from linkforge.core import Sphere

sphere = Sphere(radius=0.2)
inertia = calculate_sphere_inertia(sphere, mass=3.0)

Mesh Inertia Approximation

from linkforge.core.physics import calculate_mesh_inertia_approximation
from linkforge.core import Mesh, Vector3

# Uses bounding box approximation (no triangle data required)
mesh = Mesh(resource="robot_part.stl", scale=Vector3(1.0, 1.0, 1.0))
inertia = calculate_mesh_inertia_approximation(mesh, mass=2.5)

Precise Mesh Inertia (Tetrahedral Integration)

from linkforge.core.physics import calculate_mesh_inertia_from_triangles

# Requires raw vertex and triangle data
# vertices: list of (x,y,z) tuples, triangles: list of (i,j,k) index tuples
inertia = calculate_mesh_inertia_from_triangles(vertices, triangles, mass=2.5)

Formulas

Box

For a box with dimensions (x, y, z) and mass m:

Ixx = (m/12) * (y² + z²)
Iyy = (m/12) * (x² + z²)
Izz = (m/12) * (x² + y²)

Cylinder

For a cylinder with radius r, length l, and mass m (axis along Z):

Ixx = Iyy = (m/12) * (3r² + l²)
Izz = (m/2) * r²

Sphere

For a sphere with radius r and mass m:

Ixx = Iyy = Izz = (2/5) * m * r²