Target Grid

This module implements grid-based spatial aggregation for ray optics.

Classes:

• Grid: Represents a 2D grid for spatial aggregation and statistics.

• GridSquare: Square variant of Grid for symmetric apertures.

Functions:

• (none at top level)

Example

>>> grid = Grid([0, 1], [0, 1], 10, 10)
>>> area = grid.get_area()

class diffinytrace.target_grid.Grid(y_range, x_range, y_grid_size, x_grid_size)

Bases: object

Represents a 2D grid over a rectangular area with aggregation and indexing utilities.

Parameters:

• y_range (tuple[float, float]) – The range in y-direction, as (y_min, y_max).

• x_range (tuple[float, float]) – The range in x-direction, as (x_min, x_max).

• y_grid_size (int) – Number of grid cells in y-direction.

• x_grid_size (int) – Number of grid cells in x-direction.

get_area()

Computes the total area of the grid.

Returns:

Total area of the grid.

Return type:

float

\[A = (x_{max} - x_{min}) \cdot (y_{max} - y_{min})\]

get_pixel_area()

Returns the area of a single pixel/grid cell.

Returns:

Area of a single grid cell.

Return type:

float

\[A_{pixel} = \Delta x \cdot \Delta y\]

get_yi_xi(local_points, round_to_bounds=True)

Converts 2D local coordinates to integer grid indices.

Parameters:

• local_points (torch.Tensor) – Tensor of shape (N, 2) representing 2D points.

• round_to_bounds (bool) – If True, clamps indices to stay within grid bounds. If False, returns a mask indicating valid indices.

Returns:

Tuple of tensors (yi, xi) of shape (N,).

Return type:

Tuple[torch.Tensor, torch.Tensor]

get_k(local_points, round_to_bounds=True)

Maps local coordinates to flattened grid indices.

Parameters:

• local_points (torch.Tensor) – Tensor of shape (N, 2).

• round_to_bounds (bool) – Whether to clamp indices to grid bounds.

Returns:

• If round_to_bounds is True: Tensor of shape (N,).

• Otherwise: Tuple (indices, validity_mask).

Return type:

Union[torch.Tensor, Tuple[torch.Tensor, torch.Tensor]]

map_matrix_to_ray(local_points, old_matrix)

Maps a matrix defined on the grid to the given local points.

Parameters:

• local_points (torch.Tensor) – Points of shape (N, 2).

• old_matrix (torch.Tensor) – Matrix of shape (H, W, …).

Returns:

Resampled matrix values of shape (N, …).

Return type:

torch.Tensor

sum(local_points: Tensor, values: Tensor, old_matrix=None, round_to_bounds: bool = False)

Sums values over the grid based on point locations.

Parameters:

• local_points (torch.Tensor) – Points of shape (N, 2).

• values (torch.Tensor) – Values of shape (N,) or (N, D).

• old_matrix (torch.Tensor or None) – Previous result for accumulation.

• round_to_bounds (bool) – Clamp indices to bounds if True.

Returns:

Aggregated result of shape (H, W).

Return type:

torch.Tensor

prod(local_points, values, old_matrix=None, round_to_bounds=False)

Multiplies values over the grid based on point locations. :param local_points: Points of shape (N, 2). :type local_points: torch.Tensor :param values: Values of shape (N,) or (N, D). :type values: torch.Tensor :param old_matrix: Previous result for accumulation. :type old_matrix: torch.Tensor or None :param round_to_bounds: Clamp indices to bounds if True. :type round_to_bounds: bool

Returns:

Aggregated result of shape (H, W).

Return type:

torch.Tensor

mean(local_points, values, old_matrix=None, round_to_bounds=False)

Computes the mean of values over the grid based on point locations. :param local_points: Points of shape (N, 2). :type local_points: torch.Tensor :param values: Values of shape (N,) or (N, D). :type values: torch.Tensor :param old_matrix: Previous result for accumulation. :type old_matrix: torch.Tensor or None :param round_to_bounds: Clamp indices to bounds if True. :type round_to_bounds: bool

Returns:

Aggregated result of shape (H, W).

Return type:

torch.Tensor

min(local_points, values, old_matrix=None, return_args=False)

Finds the minimum value for each grid cell based on local points. :param local_points: Points of shape (N, 2). :type local_points: torch.Tensor :param values: Values of shape (N,) or (N, D). :type values: torch.Tensor :param old_matrix: Previous result for accumulation. :type old_matrix: torch.Tensor or None :param return_args: If True, also return indices. :type return_args: bool

Returns:

Minimum values, optionally with indices.

Return type:

torch.Tensor or Tuple[torch.Tensor, torch.Tensor]

max(local_points, values, old_matrix=None, return_args=False)

Finds the maximum value for each grid cell based on local points. :param local_points: Points of shape (N, 2). :type local_points: torch.Tensor :param values: Values of shape (N,) or (N, D). :type values: torch.Tensor :param old_matrix: Previous result for accumulation. :type old_matrix: torch.Tensor or None :param return_args: If True, also return indices. :type return_args: bool

Returns:

Maximum values, optionally with indices.

Return type:

torch.Tensor or Tuple[torch.Tensor, torch.Tensor]

get_y_middle()

get_x_middle()

nearest(local_points, return_args=False)

Finds the nearest pixel for each local point using L2 distance.

Parameters:

• local_points (torch.Tensor) – Tensor of shape (N, 2).

• return_args (bool) – If True, also return indices.

Returns:

Minimum squared distances, optionally with indices.

Return type:

torch.Tensor or Tuple[torch.Tensor, torch.Tensor]

get_pixel_centers()

Returns the 2D center coordinates of each grid cell.

Returns:

Tensor of shape (H, W, 2) with pixel center coordinates.

Return type:

torch.Tensor

get_nearest_ray(local_points)

Finds the index of the nearest ray for each grid cell using sklearn.neighbors.NearestNeighbors.

Parameters:

local_points (torch.Tensor) – Tensor of shape (N, 2) representing sampled rays.

Returns:

Tensor of shape (H, W) with ray indices.

Return type:

torch.Tensor

class diffinytrace.target_grid.GridSquare(aperture_radius, grid_size)

Bases: Grid

Convenience class for square grids centered at the origin.

Parameters:

• aperture_radius (float) – Half-width of the square domain.

• grid_size (int) – Number of grid points in each direction.