Utilities and readers#

Geometry and conversion#

Coordinate, conversion, visualization, and local I/O helpers.

class pyradar.utils.ICPResult(transform, aligned, rmse, iterations, converged)[source]#

Result of deterministic point-to-point ICP registration.

Parameters:

transform (NDArray[float64])
aligned (NDArray[float64])
rmse (float)
iterations (int)
converged (bool)

transform: NDArray[float64]#

aligned: NDArray[float64]#

rmse: float#

iterations: int#

converged: bool#

pyradar.utils.axis_aligned_bounds(points)[source]#

Return minimum and maximum FLU corners.

Parameters:: points (ArrayLike)
Return type:: tuple[NDArray[float64], NDArray[float64]]

pyradar.utils.beat_frequency_to_range(beatFrequency, *, slope)[source]#

Convert FMCW beat frequency in Hz to range in meters.

Parameters:

beatFrequency (ArrayLike)
slope (float)

Return type:

NDArray[float64]

pyradar.utils.cartesian_to_spherical(points)[source]#

Convert FLU points to columns range, azimuth, elevation.

Parameters:: points (ArrayLike)
Return type:: NDArray[float64]

pyradar.utils.compose_transforms(*transforms)[source]#

Compose transforms in application order from left to right.

Parameters:: transforms (ArrayLike)
Return type:: NDArray[float64]

pyradar.utils.db_to_power(db)[source]#

Convert dB to linear power.

Parameters:: db (ArrayLike)
Return type:: NDArray[float64]

pyradar.utils.doppler_frequency_to_velocity(dopplerFrequency, *, wavelength)[source]#

Convert monostatic Doppler frequency in Hz to radial velocity in m/s.

Parameters:

dopplerFrequency (ArrayLike)
wavelength (float)

Return type:

NDArray[float64]

pyradar.utils.icp_register(source, target, *, initialTransform=None, maxIterations=50, tolerance=1e-06, maxCorrespondenceDistance=inf)[source]#

Parameters:

source (ArrayLike)
target (ArrayLike)
initialTransform (ArrayLike | None)
maxIterations (int)
tolerance (float)
maxCorrespondenceDistance (float)

Return type:

ICPResult

pyradar.utils.inverse_transform(transform)[source]#

Invert a rigid 4x4 transform without a general matrix inversion.

Parameters:: transform (ArrayLike)
Return type:: NDArray[float64]

pyradar.utils.magnitude_to_db(magnitude, *, floor=1e-12)[source]#

Convert nonnegative linear magnitude to dB.

Parameters:

magnitude (ArrayLike)
floor (float)

Return type:

NDArray[float64]

pyradar.utils.make_transform(rotation, translation)[source]#

Build a 4x4 rigid transform from a rotation and translation.

Parameters:

rotation (ArrayLike)
translation (ArrayLike)

Return type:

NDArray[float64]

pyradar.utils.max_unambiguous_range(*, sampleRate, slope, complexSampling=True)[source]#

Return the beat-frequency-limited unambiguous range in meters.

Parameters:

sampleRate (float)
slope (float)
complexSampling (bool)

Return type:

float

pyradar.utils.max_unambiguous_velocity(*, wavelength, slowTimeInterval)[source]#

Return one-sided monostatic unambiguous radial velocity.

Parameters:

wavelength (float)
slowTimeInterval (float)

Return type:

float

pyradar.utils.power_to_db(power, *, floor=1e-12)[source]#

Convert nonnegative linear power to dB.

Parameters:

power (ArrayLike)
floor (float)

Return type:

NDArray[float64]

pyradar.utils.random_sample(points, *, count, seed=None)[source]#

Sample points without replacement using a reproducible generator.

Parameters:

points (ArrayLike)
count (int)
seed (int | None)

Return type:

NDArray[float64]

pyradar.utils.range_axis(*, fftSize, sampleRate, slope)[source]#

Return unshifted FMCW range-bin centers in meters.

Parameters:

fftSize (int)
sampleRate (float)
slope (float)

Return type:

NDArray[float64]

pyradar.utils.range_resolution(*, bandwidth)[source]#

Return ideal FMCW range resolution in meters.

Parameters:: bandwidth (float)
Return type:: float

pyradar.utils.spherical_to_cartesian(range, azimuth, elevation=0.0)[source]#

Convert range/azimuth/elevation in radians to FLU x/y/z.

Parameters:

range (ArrayLike)
azimuth (ArrayLike)
elevation (ArrayLike | float)

Return type:

NDArray[float64]

pyradar.utils.transform_points(points, transform)[source]#

Apply a 4x4 homogeneous transform to Cartesian points.

Parameters:

points (ArrayLike)
transform (ArrayLike)

Return type:

NDArray[float64]

pyradar.utils.ula_angle_axis(*, fftSize, wavelength, spacing)[source]#

Map a centered spatial FFT coordinate to ULA broadside angles.

Parameters:

fftSize (int)
wavelength (float)
spacing (float)

Return type:

NDArray[float64]

pyradar.utils.ula_unambiguous_fov(*, wavelength, spacing)[source]#

Return a ULA’s alias-free broadside field of view in radians.

Parameters:

wavelength (float)
spacing (float)

Return type:

tuple[float, float]

pyradar.utils.velocity_axis(*, fftSize, wavelength, slowTimeInterval)[source]#

Return the centered Doppler velocity coordinate in meters per second.

Parameters:

fftSize (int)
wavelength (float)
slowTimeInterval (float)

Return type:

NDArray[float64]

pyradar.utils.velocity_resolution(*, wavelength, numSlowTimeSamples, slowTimeInterval)[source]#

Return monostatic radial-velocity resolution in meters per second.

Parameters:

wavelength (float)
numSlowTimeSamples (int)
slowTimeInterval (float)

Return type:

float

pyradar.utils.voxel_downsample(points, *, voxelSize)[source]#

Replace points in each cubic voxel by their centroid.

Parameters:

points (ArrayLike)
voxelSize (float)

Return type:

NDArray[float64]

Dataset readers#

Dataset adapters and lightweight local file helpers.

class pyradar.utils.io.ColoRadarPlusReader(datasetRoot, sequence, *, applyCalibration=True)[source]#

Bases: ColoRadarReader

Sequence reader for ColoRadar+ (same cascade ADC encoding).

Parameters:

datasetRoot (PathLike)
sequence (str)
applyCalibration (bool)

class pyradar.utils.io.ColoRadarReader(datasetRoot, sequence, *, applyCalibration=True, plus=False)[source]#

Bases: object

Sequence reader for an original ColoRadar cascade recording.

Parameters:

datasetRoot (PathLike)
sequence (str)
applyCalibration (bool)
plus (bool)

property radar: TI2243CascadeRadar#

read(frameIndex)[source]#

Parameters:: frameIndex (int)
Return type:: ADCFrame

class pyradar.utils.io.FrameReader(*args, **kwargs)[source]#

Bases: Protocol

Protocol implemented by all dataset ADC readers.

property radar: Radar#: Physical radar and capture profile represented by this reader.

read(frameIndex)[source]#

Decode one frame without running signal processing.

Parameters:: frameIndex (int)
Return type:: ADCFrame

class pyradar.utils.io.RAMPCNNReader(root)[source]#

Bases: object

Numeric-order reader for a RAMPCNN radar_raw_frame directory.

Parameters:: root (PathLike)

property radar: AWR1843Radar#

read(frameIndex)[source]#

Parameters:: frameIndex (int)
Return type:: ADCFrame

class pyradar.utils.io.RaDelftReader(rawDirectory, *, configPath=None, calibrationPath=None)[source]#

Bases: object

Random-access reader for segmented 4-device RaDelft raw captures.

Parameters:

rawDirectory (PathLike)
configPath (PathLike | None)
calibrationPath (PathLike | None)

rxOrder = array([12, 13, 14, 15, 0, 1, 2, 3, 8, 9, 10, 11, 4, 5, 6, 7])#

property radar: TI2243CascadeRadar#

read(frameIndex)[source]#

Parameters:: frameIndex (int)
Return type:: ADCFrame

pyradar.utils.io.decode_dca1000(raw, *, numChirps, numRx, numSamples, numAdcBits=16)[source]#

Decode DCA1000 words into (chirp, rx, sample) complex IQ data.

Parameters:

raw (ArrayLike | bytes)
numChirps (int)
numRx (int)
numSamples (int)
numAdcBits (int)

Return type:

NDArray[complex128]

pyradar.utils.io.decode_tsw1400(raw, *, numFrames, numChirpsPerFrame, numRx, numSamples, complexSampling=True, numAdcBits=16)[source]#

Decode TSW1400 offset-binary rows into frame/chirp/RX/sample data.

Parameters:

raw (ArrayLike | bytes)
numFrames (int)
numChirpsPerFrame (int)
numRx (int)
numSamples (int)
complexSampling (bool)
numAdcBits (int)

Return type:

NDArray

pyradar.utils.io.load_coloradar_calibration(calibrationDir, *, radar=None)[source]#

Parse cascade ADC, phase, frequency, and coupling calibration.

Parameters:

calibrationDir (str | Path)
radar (TI2243CascadeRadar | None)

Return type:

Calibration

pyradar.utils.io.load_mat_array(path, key=None)[source]#

Load one public array from a MATLAB file.

Parameters:

path (str | Path)
key (str | None)

Return type:

NDArray[Any]

pyradar.utils.io.load_npy(path)[source]#

Load an ndarray without enabling pickle deserialization.

Parameters:: path (str | Path)
Return type:: NDArray[Any]

pyradar.utils.io.load_radelft_calibration(path, *, radar, txIds=(11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0), rxOrder=(12, 13, 14, 15, 0, 1, 2, 3, 8, 9, 10, 11, 4, 5, 6, 7), calibrationSlope=35003000000000.0, calibrationRate=12000000.0, interpolation=5, phaseOnly=True)[source]#

Convert TI RangeMat/PeakValMat calibration to ADC terms.

Parameters:

path (str | Path)
radar (TI2243CascadeRadar)
txIds (tuple[int, ...])
rxOrder (tuple[int, ...])
calibrationSlope (float)
calibrationRate (float)
interpolation (int)
phaseOnly (bool)

Return type:

Calibration

pyradar.utils.io.radar_from_coloradar(calibrationDir, *, plus=False, applyCalibration=True)[source]#

Create a TI2243 capture profile from ColoRadar text/JSON metadata.

Parameters:

calibrationDir (str | Path)
plus (bool)
applyCalibration (bool)

Return type:

TI2243CascadeRadar

pyradar.utils.io.radar_from_radelft_json(path)[source]#

Create a RaDelft profile from mmWave Studio JSON metadata.

Parameters:: path (str | Path)
Return type:: TI2243CascadeRadar

pyradar.utils.io.read_coloradar_frame(path, *, radar, timestamp=None, frameId=None)[source]#

Decode one ColoRadar cascade ADC bin into canonical dimensions.

Parameters:

path (str | Path)
radar (TI2243CascadeRadar)
timestamp (float | None)
frameId (int | str | None)

Return type:

ADCFrame

pyradar.utils.io.read_complex_iq_bin(path, *, dtype=<class 'numpy.int16'>)[source]#

Read interleaved scalar I/Q values as a complex vector.

Parameters:

path (str | Path)
dtype (Any)

Return type:

NDArray[complex64]

pyradar.utils.io.read_dca1000(path, radar, *, numFrames=None, timestamps=None)[source]#

Read one or more DCA1000 frames using a Radar capture model.

Parameters:

path (str | Path)
radar (Radar)
numFrames (int | None)
timestamps (ArrayLike | None)

Return type:

tuple[ADCFrame, …]

pyradar.utils.io.read_rampcnn_frame(path, *, radar=None, frameId=None)[source]#

Decode adcData(sample, loop, rx, tx) from a RAMPCNN MAT file.

Parameters:

path (str | Path)
radar (AWR1843Radar | None)
frameId (int | str | None)

Return type:

ADCFrame

pyradar.utils.io.read_tsw1400(path, radar, *, numFrames=None, timestamps=None)[source]#

Read one or more TSW1400 frames using a Radar capture model.

Parameters:

path (str | Path)
radar (Radar)
numFrames (int | None)
timestamps (ArrayLike | None)

Return type:

tuple[ADCFrame, …]

pyradar.utils.io.save_npy(path, array)[source]#

Save an ndarray in NumPy’s portable .npy format.

Parameters:

path (str | Path)
array (ArrayLike)

Return type:

None