Skip to content

Contraction-Expansion Analysis Module

The Contraction-Expansion module quantifies spatial dynamics of movement patterns by analyzing how trajectories expand and contract in space over time.

Spatial movement analysis examines how body segments or markers change their relative positions during movement. The module provides:

  • 2D/3D area calculations: geometric area enclosed by trajectory points
  • Volume analysis: 3D spatial volume changes
  • Expansion-contraction rates: temporal derivatives of spatial measures

Algorithms Details

2D Area computation

The 2D implementation uses the Shoelace formula 1 for polygon area computation:

\[ A = \tfrac{1}{2} \Bigg| \sum_i \big( x_i y_{i+1} - x_{i+1} y_i \big) \Bigg| \]

3D Volume computation

Calculates 3D volume using tetrahedron volume decomposition:

  1. Divide the 3D shape into tetrahedra
    For a polyhedron defined by vertices \( \{p_i\}_{i=0}^n \), partition it into a set of tetrahedra \(\mathcal{T} = \{ (p_0, p_{i}, p_{j}, p_{k}) \}\).

  2. Calculate each tetrahedron volume using the scalar triple product
    For tetrahedron with vertices \(p_0, p_1, p_2, p_3 \in \mathbb{R}^3\)

\[ V_{\text{tetra}} = \frac{1}{6} \; \det \begin{bmatrix} x_1 - x_0 & x_2 - x_0 & x_3 - x_0 \\ y_1 - y_0 & y_2 - y_0 & y_3 - y_0 \\ z_1 - z_0 & z_2 - z_0 & z_3 - z_0 \end{bmatrix} \]

or equivalently:

\[ V_{\text{tetra}} = \tfrac{1}{6} \, \big( (p_1 - p_0) \cdot \big( (p_2 - p_0) \times (p_3 - p_0) \big) \big) \]
  1. Sum volumes with appropriate signs
    The total polyhedron volume is obtained as:
\[ V = \sum_{k} V_{\text{tetra},k} \]

where the sign of each \(V_{\text{tetra},k}\) depends on the orientation of the vertices.

Performance Optimization

Numba JIT Compilation

The module uses Numba's Just-In-Time compilation for performance.

Note

Numba introduces compilation time on first use, but caches compiled functions for subsequent calls.
This approach grants 10-100x speedups over pure Python, avoiding overhead in critical loops.

@jit(nopython=True, cache=True)
def _area_2d_fast(points):
    # Ultra-fast computation with compiled code
    pass

Memory Efficiency

The implementation is optimized for memory efficiency by using in-place calculations, minimizing temporary arrays, and leveraging efficient array operations.

Limitations & Considerations

  • Assumes meaningful geometric shapes from selected points.
  • Requires consistent point topology across frames.
  • May not capture the full spatial complexity of movement.
  • Performance depends on point selection strategy.
  • Always consider the movement context when interpreting results.
  • Normalize for subject/task differences when appropriate.

References

  1. TODO ↩