@maruaudio/dsp/acoustics/directivity gives sources and microphones in a simulated room a cardioid-family pattern, ported from pyroomacoustics' analytic directivities. The response to a direction is gain · (p + (1 − p) · d·r / |r|) for a unit orientation d, with p 1 for omni, 0.75 subcardioid, 0.5 cardioid, 0.25 hypercardioid and 0 figure-eight. It also gives orientation vectors, cartesian and spherical conversion, the angle function, Fibonacci sphere sampling and each pattern's exact energy, (4π/3) G² (4p² − 2p + 1).
Parameters
| Call | Accepts |
|---|---|
directivityParameter(pattern) | DIRECTIVITY_OMNI (0), FIGURE_EIGHT (1), HYPERCARDIOID (2), CARDIOID (3), SUBCARDIOID (4); anything else gives NaN |
directionVectorUnit(out, offset, azimuth, colatitude, degrees) | Radians unless degrees; colatitude required (π/2 is the XY plane), not range-checked |
cardioidFamilyResponse(…, p, gain, magnitude) | p is not validated; magnitude writes the absolute value |
Lifecycle
None: plain functions over caller-owned Float64Arrays (directions stride 3 from index 0), writing outputs in place, with no allocation or closures.
When to use it
Placing a cardioid pair, a figure-eight or a directional source in a simulated room, so each reflection is weighted by its direction.
Limits
- Room simulation must pass
magnitude = false: the signed response, which flips the polarity of a figure-eight's rear-lobe images, is what upstream's ISM and ray tracer use. - A zero direction gives NaN for a directional pattern, as upstream's 0/0; omni returns the gain without reading directions.
countmust stay within 65,536 directions. Measured and SOFA directivities, spherical-harmonic interpolation andRotation3Dare not ported.