Welcome to ska-fastimgproto’s documentation!

Version 0

Contents:

Jupyter Notebook Examples

Kernel Functions

In [1]:

import matplotlib.pyplot as plt
import matplotlib.image as mpimg
import numpy as np
%matplotlib inline
# Plot image pixels in cartesian ordering (i.e. y-positive == upwards):
plt.rcParams['image.origin'] = 'lower'
# Make plots bigger
plt.rcParams['figure.figsize'] = 6, 6

In [2]:

import fastimgproto.gridder.conv_funcs as conv_funcs

In [3]:

triangle3 = conv_funcs.Triangle(half_base_width=3.0)
pillbox = conv_funcs.Pillbox(half_base_width=2.5)
sinc = conv_funcs.Sinc(3)
gauss = conv_funcs.Gaussian(trunc=5.)
g_sinc = conv_funcs.GaussianSinc(trunc=5.)
narrow_g_sinc = conv_funcs.GaussianSinc(trunc=3.)

In [4]:

plot_radius = 10.
x=np.linspace(-plot_radius,plot_radius,501)

In [5]:

# %matplotlib notebook

# plt.plot(x, pillbox(x), color='r')
# plt.plot(x, triangle3(x), color='g')
plt.plot(x, sinc(x), color='b')
plt.plot(x, gauss(x), color='m')
plt.plot(x, g_sinc(x), color='k', ls=':')
plt.plot(x, narrow_g_sinc(x), color='k', ls='--')
plt.ylim(-0.5,1.1)

Out[5]:

(-0.5, 1.1)

API Reference

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)

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)

The convolution function to be evaluated and truncated

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

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)

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)

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)

Sinc function (with truncation).

class fastimgproto.gridder.conv_funcs.Triangle(half_base_width)

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)

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:

oversampled_kernel_idx – 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, oversampling=None, raise_bounds=True)

Grid visibilities, calculating the exact kernel distribution for each.

If oversampling=None 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. If an integer value is supplied, then 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,).
• oversampling (int) – (Or None). Controls kernel-generation, see function description for details.
• raise_bounds (bool) – Raise an exception if any of the UV samples lie outside (or too close to the edge) of the grid.

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)

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:

cache – 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)

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.

Indices and tables

• Index
• Module Index
• Search Page