fastimgproto.gridder

Modules

fastimgproto.gridder.conv_funcs module

Convolution functions.

Used for generating the kernel used in convolutional gridding.

We actually paramerize the functions at initialization and return a simple callable with one parameter, the distance in pixels.

This allows us to pass the convolution routine the minimum of extra parameters.

class fastimgproto.gridder.conv_funcs.ConvFuncBase(trunc)[source]

Implements truncation (via __call__), numpy array reshaping.

Always returns 0 outside truncation radius, i.e.:

if np.fabs(x) > trunc:
    conv_func(x)==0 # True
Parameters:trunc – truncation radius.
f(radius)[source]

The convolution function to be evaluated and truncated

class fastimgproto.gridder.conv_funcs.Gaussian(trunc, w=1.0)[source]

Gaussian function (with truncation).

evaluates the function:

exp(-(x/w)**2)

(Using the notation of Taylor 1998, p143, where x = u/delta_u and alpha==2. Default value of w=1).

Parameters:
  • trunc – truncation radius.
  • w (float) – Width normalization of the Gaussian. Default = 1.0
class fastimgproto.gridder.conv_funcs.GaussianSinc(trunc, w1=2.52, w2=1.55)[source]

Gaussian times sinc function (with truncation).

evaluates the function:

exp(-(x/w1)**2) * sinc(x/w2)

(Using the notation of Taylor 1998, p143, where x = u/delta_u and alpha==2. Default values for w1,w2 are chosen according to recommendation therein).

Parameters:
  • trunc – truncation radius.
  • w1 (float) – Width normalization of the Gaussian. Default = 2.52
  • w2 (float) – Width normalization of the sinc. Default = 1.55
class fastimgproto.gridder.conv_funcs.Pillbox(half_base_width)[source]

Valued 1.0 from origin to half_base_width, zero thereafter.

AKA ‘TopHat’ function.

Symmetric about the origin.

Makes a terrible anti-aliasing function. But, because it’s so simple, it’s easy to verify and therefore a useful tool in verifying convolution codes.

Parameters:half_base_width (float) – Half-base width pillbox.
class fastimgproto.gridder.conv_funcs.Sinc(trunc)[source]

Sinc function (with truncation).

class fastimgproto.gridder.conv_funcs.Triangle(half_base_width)[source]

Linearly declines from 1.0 at origin to 0.0 at half_base_width, zero thereafter. “

Symmetric about the origin.

Makes a terrible anti-aliasing function. But, because it’s so simple, it’s easy to verify and therefore a useful tool in verifying convolution codes.

Parameters:half_base_width (float) – Half-base width of the triangle.

fastimgproto.gridder.gridder module

Convolutional gridding of visibilities.

fastimgproto.gridder.gridder.calculate_oversampled_kernel_indices(subpixel_coord, oversampling)[source]

Find the nearest oversampled gridpoint for given sub-pixel offset.

Effectively we are mapping the range [-0.5, 0.5] to the integer range [-oversampling//2, ..., oversampling//2].

Inputs will be between -0.5 and 0.5 inclusive. This is an issue, because inputs at the extreme (e.g. 0.5) might round UP, taking them outside the desired integer output range. We simply correct this edge-case by replacing outlier values before returning.

Parameters:
  • subpixel_coord (numpy.ndarray) – Array of ‘fractional’ co-ords, that is the subpixel offsets from nearest pixel on the regular grid. dtype: float, shape: (n_vis, 2).
  • oversampling (int) – How many oversampled pixels to one regular pixel.
Returns:

Corresponding oversampled pixel indexes. These are in oversampled pixel widths from the kernel centre pixel, to a maximum of half a regular pixel, so they have integer values ranging from -oversampling/2 to oversampling/2. [Dtype: int, shape: (n_vis, 2)].
Return type:

numpy.ndarray
fastimgproto.gridder.gridder.convolve_to_grid(kernel_func, support, image_size, uv, vis, vis_weights, exact=True, oversampling=0, raise_bounds=True, progress_bar=None)[source]

Grid visibilities using convolutional gridding.

Returns the un-normalized weighted visibilities; the weights-renormalization factor can be calculated by summing the sample grid.

If exact == True then exact gridding is used, i.e. the kernel is recalculated for each visibility, with precise sub-pixel offset according to that visibility’s UV co-ordinates. Otherwise, instead of recalculating the kernel for each sub-pixel location, we pre-generate an oversampled kernel ahead of time - so e.g. for an oversampling of 5, the kernel is pre-generated at 0.2 pixel-width offsets. We then pick the pre-generated kernel corresponding to the sub-pixel offset nearest to that of the visibility.

Kernel pre-generation results in improved performance, particularly with large numbers of visibilities and complex kernel functions, at the cost of introducing minor aliasing effects due to the ‘step-like’ nature of the oversampled kernel. This in turn can be minimised (at the cost of longer start-up times and larger memory usage) by pre-generating kernels with a larger oversampling ratio, to give finer interpolation.

Parameters:
  • kernel_func (callable) – Callable object, (e.g. conv_funcs.Pillbox,) that returns a convolution co-efficient for a given distance in pixel-widths.
  • support (int) – Defines the ‘radius’ of the bounding box within which convolution takes place. Box width in pixels = 2*support+1. (The central pixel is the one nearest to the UV co-ordinates.) (This is sometimes known as the ‘half-support’)
  • image_size (int) – Width of the image in pixels. NB we assume the pixel [image_size//2,image_size//2] corresponds to the origin in UV-space.
  • uv (numpy.ndarray) – UV-coordinates of visibilities. 2d array of float_, shape: (n_vis, 2). assumed ordering is u-then-v, i.e. u, v = uv[idx]
  • vis (numpy.ndarray) – Complex visibilities. 1d array, shape: (n_vis,).
  • vis_weights (numpy.ndarray) – Visibility weights. 1d array, shape: (n_vis,).
  • exact (bool) – Calculate exact kernel-values for every UV-sample.
  • oversampling (int) – Controls kernel-generation if exact==False. Larger values give a finer-sampled set of pre-cached kernels.
  • raise_bounds (bool) – Raise an exception if any of the UV samples lie outside (or too close to the edge) of the grid.
  • progress_bar (tqdm.tqdm) – [Optional] progressbar to update.
Returns:

(vis_grid, sampling_grid)

Tuple of ndarrays representing the gridded visibilities and the sampling weights. These are 2d arrays of same dtype as vis, shape (image_size, image_size). Note numpy style index-order, i.e. access like vis_grid[v,u].
Return type:

tuple
fastimgproto.gridder.gridder.populate_kernel_cache(kernel_func, support, oversampling)[source]

Generate a cache of normalised kernels at oversampled-pixel offsets.

We need kernels for offsets of up to oversampling//2 oversampling-pixels in any direction, in steps of one oversampling-pixel (i.e. steps of width 1/oversampling in the original co-ordinate system).

Parameters:
  • kernel_func (callable) – Callable object, (e.g. conv_funcs.Pillbox,) that returns a convolution co-efficient for a given distance in pixel-widths.
  • support (int) – See kernel generation routine.
  • oversampling (int) – Oversampling ratio. cache_size = ((oversampling // 2 * 2) + 1)**2
Returns:

Dictionary mapping oversampling-pixel offsets to normalised kernels.
Return type:

dict

fastimgproto.gridder.kernel_generation module

Generation of convolution kernel arrays, with optional sub-pixel origin offset and and oversampling.

class fastimgproto.gridder.kernel_generation.Kernel(kernel_func, support, offset=(0.0, 0.0), oversampling=None, pad=False, normalize=True)[source]

Generates a 2D array representing a sampled kernel function.

Parameters:
  • kernel_func (callable) – Callable object, (e.g. conv_funcs.Pillbox,) that returns a convolution co-efficient for a given distance in pixel-widths.
  • support (int) – Defines the ‘radius’ of the bounding box within which convolution takes place. Box width in pixels = 2*support+1. (The central pixel is the one nearest to the UV co-ordinates.) For a kernel_func with truncation radius trunc, the support should be set to ceil(trunc+0.5) to ensure that the kernel function is fully supported for all valid subpixel offsets.
  • offset (tuple) – 2-vector subpixel offset from the sampling position of the central pixel to the origin of the kernel function. Ordering is (x_offset,y_offset). Should have values such that fabs(offset) <= 0.5 otherwise the nearest integer grid-point would be different!
  • oversampling (int) – Oversampling ratio, how many kernel pixels to each UV-grid pixel. Defaults to 1 if not given or oversampling=None is passed.
  • pad (bool) – Whether to pad the array by an extra pixel-width. This is used when generating an oversampled kernel that will be used for interpolation.
array

numpy.ndarray – The sampled kernel function.

centre_idx

int – Index of the central pixel

kernel_func, support, offset, oversampling

See params.