fovi.sensing.coords

class fovi.sensing.coords.SamplingCoords(fov, cmf_a, res, device='cpu', style='isotropic', dtype=torch.float, max_val=1, isotropic_plotting_type='v1like', fov_type='circular', field_geometry='planar', radius_norm=2.0)[source]

Bases: object

Object for storing multiple coordinate systems relevant to a set of visual field samples.

Parameters:

fov (float) – Field-of-view in degrees.
cmf_a (float) – A parameter from the CMF: M(r)=1/(r+a). Smaller a = stronger foveation.
res (int) – Resolution, corresponding to the side length of a cartesian grid or the number of radii in polar (before any adjustments are made to match a target cartesian grid).
device (str) – What device to operate on.
style (str) – What type of sampling.
dtype (torch.dtype) – What data type to use.
fov_type (str) – One of 'circular', 'square', or 'wang'. The last is only valid for warped Cartesian sensor styles.
radius_norm (float) – Norm measuring native-plane radius for warped Cartesian styles. 2.0 gives circular iso-eccentricity shells; inf gives square shells, which pair with fov_type='square' to retain every cell.

__init__(fov, cmf_a, res, device='cpu', style='isotropic', dtype=torch.float, max_val=1, isotropic_plotting_type='v1like', fov_type='circular', field_geometry='planar', radius_norm=2.0)[source]

as_grid(values: Tensor, sample_dim: int = -1) → Tensor[source]

Replace a canonical sample axis with the sensor’s image axes.

Cartesian grids return upright rows down and columns right. Log-polar grids retain their radius/angle ordering. Other axes are unchanged.

Parameters:

values – Tensor with one axis containing all canonical samples.
sample_dim – Sample axis; use zero for coordinates shaped (N, 2).

Returns:

Tensor with the sample axis replaced by height and width.

native_to_visual(coordinates: Tensor) → Tensor[source]

Map (…, 2) native Cartesian warp coordinates to the visual chart.

Visual chart radius one is half the configured FoV. For spherical geometry this is angular eccentricity, not a pinhole projection. The unbounded chart includes masked cells outside the model footprint; renderers must handle their own angular padding domain.

visual_to_native(coordinates: Tensor) → Tensor[source]: Map (…, 2) normalized visual-chart positions to the native grid.

pad_cartesian(padding_distance=0.5, device=None, dtype=None)[source]

Generate additional cartesian coordinates for padding around the sampling grid.

Parameters:

padding_distance (float) – Padding extent in normalized coordinates. For spherical radial grids, measured from the real retinal rim, retaining at least one complete neighboring ring. Planar/legacy radial grids retain the historical interval starting at the first outer ring, which can overshoot the requested rim margin by one ring. Preserve that behavior for checkpoint KNN compatibility. Warped Cartesian and log-polar layouts pad in their own grid coordinates using a whole number of grid intervals.
device (str, optional) – Device to place the coordinates on. Defaults to None.
dtype (torch.dtype, optional) – Data type for the coordinates. Defaults to None.

Returns:

Additional cartesian coordinates for padding.

Return type:

torch.Tensor

get_strided_coords(stride, auto_match_cart_resources=0, in_cart_res=None, force_less_than=True, max_val=1)[source]

Return a strided version of the coordinates.

Parameters:

stride (int) – Stride factor for downsampling coordinates.
auto_match_cart_resources (int) – Automatic matching parameter for cartesian resources.
in_cart_res (int, optional) – Input cartesian resolution. Required for ‘fixn’ style.
force_less_than (bool, optional) – Whether to force less than target resolution. Defaults to True.
max_val (float, optional) – Maximum value for coordinates. Defaults to 1.

Returns:

A tuple containing:

SamplingCoords: New SamplingCoords object with strided coordinates.
int: Number of output radii.
int: Corresponding output cartesian resolution.

Return type:

tuple

to(device=None, dtype=None)[source]

Move the SamplingCoords object to a different device and/or change data type.

Parameters:

device (str, optional) – Target device. Defaults to None.
dtype (torch.dtype, optional) – Target data type. Defaults to None.

Returns:

SamplingCoords object on the specified device/dtype.

Return type:

SamplingCoords

get_scatter_sizes()[source]

Calculate approximate size to be used for plotting in scatter plots.

Scales linearly with eccentricity, as occurs in KNN-sampling of the sensor manifold. However, this is not precisely tuned to the particular warping parameters.

Returns:: Receptive field sizes for each sampling point.
Return type:: torch.Tensor

clone(fov=None, cmf_a=None, resolution=None, device=None, style=None, dtype=None, max_val=None, isotropic_plotting_type=None, fov_type=None, field_geometry=None, radius_norm=None)[source]

Return a deep copy of the SamplingCoords object with optional parameter overrides.

Parameters:

fov (float, optional) – Field-of-view in degrees. Defaults to current value.
cmf_a (float, optional) – A parameter from the CMF. Defaults to current value.
resolution (int, optional) – Resolution parameter. Defaults to current value.
device (str, optional) – Device to place coordinates on. Defaults to current value.
style (str, optional) – Sampling style. Defaults to current value.
dtype (torch.dtype, optional) – Data type. Defaults to current value.
max_val (float, optional) – Maximum coordinate value. Defaults to current value.

Returns:

A new SamplingCoords object with the specified parameters.

Return type:

SamplingCoords

fovi.sensing.coords.get_isotropic_sampling_coords(fov, cmf_a, res, fov_type='circular', device='cpu', constant_num_angles=False, force_n_points=None, max_norm_rad=1, plotting_type='v1like', filter_to_fov=True, return_masked_coords=False, field_geometry='planar')[source]

Sample coordinates isotropically with the cortical magnification function of the complex log mapping w=log(z+a), where z=x+iy.

Parameters:

fov (float) – Field of view diameter in degrees.
cmf_a (float) – A parameter in the CMF controlling foveation; smaller = stronger foveation.
res (int) – Number of sampling points.
fov_type (str, optional) – 'circular' or 'square'. Defaults to 'circular'.
device (str, optional) – Device to run the computation on. Defaults to ‘cpu’.
constant_num_angles (bool, optional) – If True, the number of angles is constant for all radii, implementing log polar image sampling. Defaults to False.
force_n_points (int, optional) – If not None, forces the number of points to exactly this value. Useful for controlled comparisons with other sensors. Defaults to None.
max_norm_rad (float, optional) – Maximum normalized radius. Defaults to 1.
plotting_type (str, optional) –
Layout style for plotting coords. One of: - ‘v1like’: V1-like flat complex-log with inverted hemifields facing outwards. - ‘schwartz’: upright complex-log (Schwartz’s log(z+a) model) with hemifields facing inwards. - ‘warp’: cortical polar disc (log-polar radial warp in a disc, fovea at centre);

matches fovi-rtx samples_uv_cortical_disc layout.
return_masked_coords (bool, optional) – Also return radial-manifold coordinates removed by the square FoV. These can be used as spatial padding candidates by KNN layers. Defaults to False.

Returns:

A tuple containing:

torch.Tensor: Sampling cartesian coordinates in visual space, normalized to (-1,1).
torch.Tensor: Sampling polar coordinates in visual space.
torch.Tensor: Plotting coordinates in complex log space, useful for visualizing the sampling.
torch.Tensor: Masked spatial-padding coordinates, when return_masked_coords is True.

Return type:

tuple

fovi.sensing.coords.get_logpolar_image_sampling_coords(fov, cmf_a, res, device='cpu', force_n_points=None, max_norm_rad=1, fov_type='circular', field_geometry='planar')[source]

Convenience wrapper for log polar image sampling.

Sample coordinates with the cortical magnification function of the complex log mapping w=log(z+a), where z=x+iy. This is not isotropic, rather, it produces a square log polar image using an equal number of angular samples for all radii. Flattened coordinates are emitted in row-major image order with angle as height and eccentricity as width.

Parameters:

fov (float) – Field of view diameter in degrees.
cmf_a (float) – A parameter from the CMF: M(r)=1/(r+a). Smaller a = stronger foveation.
res (int) – Number of sampling points.
device (str, optional) – Device to run the computation on. Defaults to ‘cpu’.
force_n_points (int, optional) – If not None, the number of points is forced to be exactly this, useful for controlled comparisons with other sensors. Defaults to None.
max_norm_rad (float, optional) – Maximum normalized radius. Defaults to 1.

Returns:

A tuple containing:

torch.Tensor: Sampling cartesian coordinates in visual space, normalized to (-1,1).
torch.Tensor: Sampling polar coordinates in visual space.
torch.Tensor: Plotting coordinates in complex log space, useful for visualizing the sampling.

Return type:

tuple

fovi.sensing.coords.get_warped_cartesian_sampling_coords(fov, cmf_a, res, device='cpu', max_val=1, fov_type='circular', return_valid_mask=False, radius_norm=2.0)[source]

Build a regular Cartesian lattice in the radial-CMF warp plane.

Each output location is inverse-mapped analytically into normalized visual coordinates. Circular FoVs retain the mapped circle, square FoVs retain the square circumscribing that circle, and Wang FoVs map the full native square without masking.

radius_norm=inf measures native radius in the infinity norm, so iso-eccentricity shells are squares rather than circles and the native square maps exactly onto the visual square, leaving every cell valid.

fovi.sensing.coords.isotropic_foveal_ring(fov: float, cmf_a: float, res: int, fov_type: str = 'circular', field_geometry: str = 'planar') → Tensor[source]: Return the first noncentral ring as normalized (N, 2) visual coordinates.

fovi.sensing.coords.num_sampling_coords_isotropic(fov, cmf_a, res, fov_type='circular', device='cpu', field_geometry='planar')[source]

Quickly compute the number of sampling coordinates for isotropic sampling.

Useful for optimizing the res (# of radii) to match a certain output n (# of points).

Parameters:

fov (float) – Field of view diameter in degrees.
cmf_a (float) – A parameter from the CMF: M(r)=1/(r+a). Smaller a = stronger foveation.
res (int) – Number of sampling radii.
fov_type (str, optional) – 'circular' or 'square'.
device (str, optional) – Device to run computation on. Defaults to ‘cpu’.

Returns:

Total number of sampling coordinates.

Return type:

int

fovi.sensing.coords.find_desired_res(fov, cmf_a, n_points_desired, style, device='cpu', bounds=(1, 1000), force_less_than=False, quiet=False, fov_type='circular', field_geometry='planar', radius_norm=2.0)[source]

Find the resolution that gives the desired number of sampling points using binary search.

Parameters:

fov (float) – Field of view diameter in degrees.
cmf_a (float) – A parameter from the CMF: M(r)=1/(r+a). Smaller a = stronger foveation.
n_points_desired (int) – Desired number of sampling points.
style (str) – Which sampling style, e.g. ‘isotropic’.
device (str, optional) – Device to run computation on. Defaults to ‘cpu’.
bounds (tuple, optional) – Bounds for resolution search. Defaults to (1,1000).
force_less_than (bool, optional) – Whether to force less than target resolution. Defaults to False.
quiet (bool, optional) – Whether to suppress output. Defaults to False.

Returns:

A tuple containing:

int: Resolution that gives the desired number of points.
int: Actual number of points achieved.

Return type:

tuple

fovi.sensing.coords.get_sampling_coords(fov, cmf_a, res, device='cpu', style='isotropic', max_val=1, isotropic_plotting_type='v1like', fov_type='circular', return_valid_mask=False, return_masked_coords=False, field_geometry='planar', radius_norm=2.0)[source]

Generate sampling coordinates based on the specified style.

Parameters:

fov (float) – Field of view diameter in degrees.
cmf_a (float) – A parameter from the CMF: M(r)=1/(r+a). Smaller a = stronger foveation.
res (int) – Resolution parameter.
device (str, optional) – Device to run computation on. Defaults to ‘cpu’.
style (str) – Sampling style, including isotropic, logpolar, warped_cartesian, and their supported _as_grid variants.
max_val (float, optional) – Maximum x/y value. Defaults to 1.
fov_type (str, optional) – FoV geometry. 'wang' is only valid with a warped-Cartesian sensor style.
return_valid_mask (bool, optional) – Append a validity mask to the returned tuple. Defaults to False.
return_masked_coords (bool, optional) – Append isotropic samples from the radial manifold that are excluded by the square FoV for use as KNN padding candidates. Grid styles retain such samples in-place and return an empty tensor. Defaults to False.

Returns:

A tuple containing:

torch.Tensor: Cartesian coordinates.
torch.Tensor: Polar coordinates.
torch.Tensor: Plotting coordinates.
torch.Tensor: Validity mask, when requested.
torch.Tensor: Masked spatial-padding coordinates, when requested.

Return type:

tuple

fovi.sensing.coords.rowcol_to_xy(coords, do_norm=True, format='01')[source]

Convert row-column coordinates to xy coordinates.

Parameters:

coords (torch.Tensor) – Input coordinates in row-column format.
do_norm (bool, optional) – Whether to normalize coordinates. Defaults to True.
format (str) – Coordinate format (‘01’ for [0,1] or ‘-11’ for [-1,1]). Defaults to ‘01’.

Returns:

Coordinates in xy format.

Return type:

torch.Tensor

fovi.sensing.coords.xy_to_rowcol(coords, do_norm=True, format='01')[source]

Convert xy coordinates to row-column coordinates.

Parameters:

coords (torch.Tensor) – Input coordinates in xy format.
do_norm (bool, optional) – Whether to normalize coordinates. Defaults to True.
format (str) – Coordinate format (‘01’ for [0,1] or ‘-11’ for [-1,1]). Defaults to ‘01’.

Returns:

Coordinates in row-column format.

Return type:

torch.Tensor

fovi.sensing.coords.xy_to_colrow(coords, do_norm=True, format='01')[source]

Convert xy coordinates to column-row coordinates.

Parameters:

coords (torch.Tensor) – Input coordinates in xy format.
do_norm (bool, optional) – Whether to normalize coordinates. Defaults to True.
format (str) – Coordinate format (‘01’ for [0,1] or ‘-11’ for [-1,1]). Defaults to ‘01’.

Returns:

Coordinates in row-column format.

Return type:

torch.Tensor

fovi.sensing.coords.num_sampling_coords(fov, cmf_a, res, style='isotropic', device='cpu', fov_type='circular', field_geometry='planar', radius_norm=2.0)[source]

Calculate the number of sampling coordinates for a given style.

Parameters:

fov (float) – Field of view diameter in degrees.
cmf_a (float) – A parameter from the CMF: M(r)=1/(r+a). Smaller a = stronger foveation.
res (int) – Resolution parameter.
style (str) – Sampling style. Defaults to ‘isotropic’.
device (str, optional) – Device to run computation on. Defaults to ‘cpu’.

Returns:

Number of sampling coordinates.

Return type:

int

fovi.sensing.coords.transform_sampling_grid(sampling_grid, fix_loc, fixation_size, image_size)[source]

Transform sampling grid coordinates from fixation space to full image space.

Parameters:

sampling_grid (torch.Tensor) – Sampling grid of shape (1, n_coords, 2) in [-1, 1] range. It is in (x,y) format.
fix_loc (tuple or torch.Tensor) – Fixation center in normalized image coordinates (h, w), e.g., (0.5, 0.5).
fixation_size (tuple or torch.Tensor) – Size of the fixation region in pixels (fix_h, fix_w).
image_size (tuple) – Full image size (H, W).

Returns:

Transformed sampling grid in the full image space.

Return type:

torch.Tensor

fovi.sensing.coords.auto_match_num_coords(fov, cmf_a, cart_res, style, auto_match_cart_resources, device, force_less_than=True, quiet=False, fov_type='circular', field_geometry='planar', radius_norm=2.0)[source]

Automatically match the number of coordinates to cartesian resolution.

Parameters:

fov (float) – Field of view diameter in degrees.
cmf_a (float) – A parameter from the CMF: M(r)=1/(r+a). Smaller a = stronger foveation.
cart_res (int) – Cartesian resolution.
style (str) – Sampling style.
auto_match_cart_resources (int) – Auto-matching parameter (-1: auto-match in_res, 0: no auto-matching, >0: auto-match everything).
device (str) – Device to run computation on.
force_less_than (bool, optional) – Whether to force less than target resolution. Defaults to True.

Returns:

A tuple containing:

int: Input resolution.
int: Cartesian resolution.

Return type:

tuple

fovi.sensing.coords.logpolar_radius(cartesian, fov, cmf_a)[source]

Utility for computing logpolar radius from normalized cartesian coordinates.

Parameters:

cartesian (torch.Tensor) – (nx2) cartesian coordinates normalized to (-1,1).
fov (float) – Field-of-view diameter in degrees.
cmf_a (float) – A parameter from the CMF: M(r)=1/(r+a). Smaller a = stronger foveation.

Returns:

(nx1) log radius as in logpolar mapping.

Return type:

torch.Tensor

fovi.sensing.coords.cart_to_polar(cartesian)[source]

Convert cartesian coordinates to polar coordinates.

Parameters:: cartesian (torch.Tensor or array-like) – Input cartesian coordinates.
Returns:: Polar coordinates (radius, angle).
Return type:: torch.Tensor

fovi.sensing.coords.polar_to_cart(polar)[source]

Convert polar coordinates to cartesian coordinates.

Parameters:: polar (torch.Tensor or array-like) – Input polar coordinates (radius, angle).
Returns:: Cartesian coordinates (x, y).
Return type:: torch.Tensor

fovi.sensing.coords.cart_to_complex_log(cartesian, fov, cmf_a, postproc=True)[source]

Convert cartesian coordinates to complex log space coordinates.

Parameters:

cartesian (torch.Tensor or array-like) – Input cartesian coordinates.
fov (float) – Field of view diameter in degrees.
cmf_a (float) – A parameter from the CMF: M(r)=1/(r+a). Smaller a = stronger foveation.
postproc (bool, optional) – Whether to apply post-processing for hemisphere separation. Defaults to True.

Returns:

Complex log space coordinates.

Return type:

torch.Tensor