K-space Sampling

class Sampler[source]

Sample a k-space (KSpaceLight) complex field at angular / direction queries.

The k-space field is stored on a (kx, ky) grid in radians per meter. Given query angular coordinates (theta, phi) or 3D direction vectors, this sampler converts them to (kx_query, ky_query), normalizes to the [-1, 1] coordinate system expected by torch.nn.functional.grid_sample, and samples the complex field (real/imag separately to preserve autograd).

Note

sample_direction samples the angular / k-space field along a direction. It does NOT compute the coherent field at a physical 3D point; that would require an integral over k-space and is left for a separate, later implementation.

sample_theta_phi(source_field, theta, phi, c=None, mode='bilinear', padding_mode='zeros', align_corners=True, polar_axis='z')[source]

Sample the k-space field at angular coordinates (theta, phi).

Parameters:

  • source_field (KSpaceLight) – k-space field to sample.

  • theta (torch.Tensor) – Query polar angles in radians, shape [H, W] or [B, H, W].

  • phi (torch.Tensor) – Query azimuthal angles in radians, same shape as theta.

  • c (int, optional) – Channel index for multi-wavelength fields.

  • mode (str) – grid_sample interpolation mode.

  • padding_mode (str) – grid_sample out-of-range padding mode.

  • align_corners (bool) – grid_sample align_corners flag.

  • polar_axis (str) – “z” (default) uses theta from the optical z axis and phi from +x toward +y, matching KSpaceLight.get_theta_phi_grid. “y” uses theta from +y and phi from +x toward +z, preserving the validation notebook’s angular layout.

Returns:

Sampled complex field [N, C_out, H, W].

Return type:

torch.Tensor

sample_direction(source_field, dirs, c=None, mode='bilinear', padding_mode='zeros', align_corners=True, normalize=True)[source]

Sample the k-space field along 3D direction vectors.

Coordinate axes must be uniformly sampled. If an axis has length one, queries must match that stored coordinate (torch.isclose tolerance); off-axis queries raise ValueError for every padding mode because no interpolation spacing is defined.

Only the forward hemisphere (dir_z >= 0) is supported. Rear-facing, zero and nonfinite vectors raise ValueError. With normalize=False, vectors must already have unit length. Values within 8 dtype eps of the horizon are treated as horizon roundoff. Validation on CUDA may synchronize with the host.

Parameters:

  • source_field (KSpaceLight) – k-space field to sample.

  • dirs (torch.Tensor) – Direction vectors with last dim 3, shape [H, W, 3] or [B, H, W, 3], representing (dir_x, dir_y, dir_z).

  • c (int, optional) – Channel index for multi-wavelength fields.

  • mode (str) – grid_sample interpolation mode.

  • padding_mode (str) – grid_sample out-of-range padding mode.

  • align_corners (bool) – grid_sample align_corners flag.

  • normalize (bool) – If True, normalize each direction vector to unit length.

Returns:

Sampled complex field [N, C_out, H, W].

Return type:

torch.Tensor