Skip to content

Convolve

Bare correlation kernels (NaN-naive) and their NaN-as-missing renormalized variants, plus a Gaussian kernel constructor.

The kernels are written as correlation (the kernel is not flipped). For a symmetric kernel correlation and convolution coincide; the image.convolve_psf wrapper flips the PSF first to give true convolution.

Gaussian Kernel

gaussian1d(sigma, *, truncate=4.0, sampling='erf_integrated', normalization='sum', dtype=None) builtin

Build a 1-D Gaussian correlation kernel of odd length 2 * ceil(truncate * sigma) + 1, centered at index len // 2.

Parameters:

Name Type Description Default
sigma float

Gaussian sigma in pixels. Must be positive.

 required
truncate float

Half-support in units of sigma. Must be positive. Default 4.0.

 4.0
sampling (erf_integrated, point_sampled)

erf_integrated (default) integrates the unit Gaussian over each tap bin (accurate for narrow sigma); point_sampled evaluates the unnormalized Gaussian at integer offsets (biased for narrow sigma).

 "erf_integrated"
normalization (sum, l2, none)

Kernel normalization. sum (default) is flux-conserving; l2 is matched-filter S/N optimal; none leaves the kernel unscaled.

 "sum"
dtype numpy dtype

Either numpy.float32 or numpy.float64. Default numpy.float64.

 None

Returns:

Type Description
ndarray

1-D Gaussian kernel of odd length.

Raises:

Type Description
ValueError

If sigma or truncate is not positive, if sampling / normalization is invalid, or if dtype is not float32 / float64.

1-D Correlation

conv1d(signal, kernel, *, boundary='zero') builtin

1-D correlation of signal with kernel (the kernel is not flipped — for a symmetric kernel this coincides with convolution). NaN-naive: a non-finite tap propagates into its output element.

Parameters:

Name Type Description Default
signal ndarray

1-D signal, dtype float32 or float64.

 required
kernel ndarray

1-D kernel, same dtype as signal. The center tap is len(kernel) // 2.

 required
boundary (zero, reflect, nearest)

Out-of-bounds tap handling. Default "zero".

 "zero"

Returns:

Type Description
ndarray

Same shape and dtype as signal.

Raises:

Type Description
ValueError

If signal is not a 1-D float32/float64 array, kernel is empty, kernel dtype does not match signal, or boundary is invalid.

conv_axis(image, kernel, *, axis=0, boundary='zero') builtin

Apply [conv1d] independently along axis of a 2-D image.

Parameters:

Name Type Description Default
image ndarray

2-D image, dtype float32 or float64.

 required
kernel ndarray

1-D kernel, same dtype as image.

 required
axis int

0 correlates down each column, 1 along each row. Default 0.

 0
boundary (zero, reflect, nearest)

Out-of-bounds tap handling. Default "zero".

 "zero"

Returns:

Type Description
ndarray

Same shape and dtype as image.

Raises:

Type Description
ValueError

If image is not a 2-D float32/float64 array, kernel is empty or has a mismatched dtype, axis is not 0 or 1, or boundary is invalid.

2-D Correlation

conv2d(image, kernel, *, boundary='zero') builtin

2-D correlation of image with kernel (the kernel is not flipped). NaN-naive.

Parameters:

Name Type Description Default
image ndarray

2-D image, dtype float32 or float64.

 required
kernel ndarray

2-D kernel, same dtype as image. Centered at (nrows // 2, ncols // 2).

 required
boundary (zero, reflect, nearest)

Out-of-bounds tap handling. Default "zero".

 "zero"

Returns:

Type Description
ndarray

Same shape and dtype as image.

Raises:

Type Description
ValueError

If image is not a 2-D float32/float64 array, kernel is empty or has a mismatched dtype, or boundary is invalid.

NaN-as-Missing Renormalized Correlation

conv2d_renorm(image, kernel) builtin

2-D renormalized correlation (NaN-as-missing). Returns (value, weight) where value = N / D over the finite taps and weight = D is the kernel-weighted valid-tap sum. Out-of-bounds is always missing; no boundary switch.

Parameters:

Name Type Description Default
image ndarray

2-D image, dtype float32 or float64. NaN / +-inf are treated as missing.

 required
kernel ndarray

2-D kernel, same dtype as image. Should be non-negative for the renorm semantics to make sense.

 required

Returns:

Type Description
tuple of (ndarray, ndarray)

(value, weight), both same shape and dtype as image. value is NaN where no valid tap contributed.

Raises:

Type Description
ValueError

If image is not a 2-D float32/float64 array, or kernel is empty or has a mismatched dtype.

conv_axis_renorm(image, kernel, *, axis=0) builtin

1-D renormalized correlation along axis of a 2-D image (NaN-as-missing). Returns (value, weight) with the same semantics as [conv2d_renorm].

Parameters:

Name Type Description Default
image ndarray

2-D image, dtype float32 or float64. NaN / +-inf are treated as missing.

 required
kernel ndarray

1-D kernel, same dtype as image. Should be non-negative.

 required
axis int

0 correlates down each column, 1 along each row. Default 0.

 0

Returns:

Type Description
tuple of (ndarray, ndarray)

(value, weight), both same shape and dtype as image.

Raises:

Type Description
ValueError

If image is not a 2-D float32/float64 array, kernel is empty or has a mismatched dtype, or axis is not 0 or 1.