fovi.sensing.coords

class fovi.sensing.coords.SamplingCoords(fov, cmf_a, res, device='cpu', style='isotropic', dtype=torch.float, max_val=1)[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.

__init__(fov, cmf_a, res, device='cpu', style='isotropic', dtype=torch.float, max_val=1)[source]

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) – Distance to extend beyond the current sampling area.
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)[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, circular=True, device='cpu', constant_num_angles=False, force_n_points=None, max_norm_rad=1)[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.
circular (bool, optional) – If True, the sampling is circular, otherwise it is square. Defaults to True.
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.

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_logpolar_image_sampling_coords(fov, cmf_a, res, device='cpu', force_n_points=None, max_norm_rad=1)[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.

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.num_sampling_coords_isotropic(fov, cmf_a, res, circular=True, device='cpu')[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.
circular (bool, optional) – If True, use circular sampling. Defaults to True.
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)[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)[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 (‘isotropic’, ‘logpolar’, ‘isotropic_fixn’, ‘uniform’, ‘uniform_as_grid’, ‘logpolar_as_grid’).
max_val (float, optional) – Maximum x/y value. Defaults to 1.

Returns:

A tuple containing:

torch.Tensor: Cartesian coordinates.
torch.Tensor: Polar coordinates.
torch.Tensor: Plotting coordinates.

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')[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)[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