0
# Image Convolution
1
2
Convolution and filtering operations for astronomical images with kernels optimized for astronomical data analysis.
3
4
## Core Imports
5
6
```python
7
from astropy.convolution import convolve, convolve_fft
8
from astropy.convolution import Kernel, Gaussian2DKernel, Box2DKernel
9
```
10
11
## Capabilities
12
13
### Convolution Functions
14
15
Core convolution functions for filtering astronomical images with custom kernels, supporting different boundary conditions and optimized algorithms.
16
17
```python { .api }
18
def convolve(array, kernel, boundary='fill', fill_value=0.0, nan_treatment='interpolate', preserve_nan=False, mask=None, normalize_kernel=True):
19
"""
20
Convolve an array with a kernel.
21
22
Parameters:
23
- array: input array to convolve
24
- kernel: convolution kernel (Kernel instance or array)
25
- boundary: boundary condition ('fill', 'wrap', 'extend')
26
- fill_value: value to use for 'fill' boundary condition
27
- nan_treatment: how to handle NaN values ('interpolate', 'fill')
28
- preserve_nan: whether to preserve NaN values in output
29
- mask: mask array for input data
30
- normalize_kernel: whether to normalize kernel
31
32
Returns:
33
array: convolved array
34
"""
35
36
def convolve_fft(array, kernel, boundary='fill', fill_value=0.0, nan_treatment='interpolate', preserve_nan=False, mask=None, normalize_kernel=True):
37
"""
38
Convolve an array with a kernel using FFT.
39
40
Same parameters as convolve() but uses FFT for potentially faster computation
41
on large arrays.
42
"""
43
44
def interpolate_replace_nans(array, kernel, boundary='fill', fill_value=0.0):
45
"""
46
Replace NaN values in array using convolution-based interpolation.
47
48
Parameters:
49
- array: input array containing NaN values
50
- kernel: convolution kernel for interpolation
51
- boundary: boundary condition
52
- fill_value: fill value for boundary
53
54
Returns:
55
array: array with NaN values replaced
56
"""
57
```
58
59
### Kernel Base Classes
60
61
Base classes for creating convolution kernels with proper normalization and array handling.
62
63
```python { .api }
64
class Kernel:
65
"""
66
Base class for convolution kernels.
67
68
Parameters:
69
- array: kernel array data
70
"""
71
def __init__(self, array): ...
72
73
def normalize(self, mode='integral'):
74
"""Normalize the kernel."""
75
76
@property
77
def array(self):
78
"""The kernel array."""
79
80
@property
81
def separable(self):
82
"""Whether the kernel is separable."""
83
84
class Kernel1D(Kernel):
85
"""Base class for 1D kernels."""
86
87
class Kernel2D(Kernel):
88
"""Base class for 2D kernels."""
89
```
90
91
### Built-in Kernels
92
93
Pre-defined kernels commonly used in astronomical image processing.
94
95
```python { .api }
96
class Gaussian1DKernel(Kernel1D):
97
"""
98
1D Gaussian filter kernel.
99
100
Parameters:
101
- stddev: standard deviation of the Gaussian
102
- x_size: size of the kernel (optional)
103
- mode: discretization mode ('center', 'linear_interp', 'oversample', 'integrate')
104
- factor: oversampling factor for 'oversample' mode
105
"""
106
def __init__(self, stddev, x_size=None, mode='center', factor=10): ...
107
108
class Gaussian2DKernel(Kernel2D):
109
"""
110
2D Gaussian filter kernel.
111
112
Parameters:
113
- stddev: standard deviation (scalar or 2-element array)
114
- x_size: x-size of the kernel (optional)
115
- y_size: y-size of the kernel (optional)
116
- theta: rotation angle in radians
117
- mode: discretization mode
118
- factor: oversampling factor
119
"""
120
def __init__(self, stddev, x_size=None, y_size=None, theta=0.0, mode='center', factor=10): ...
121
122
class Box1DKernel(Kernel1D):
123
"""
124
1D Box filter kernel.
125
126
Parameters:
127
- width: width of the box
128
"""
129
def __init__(self, width): ...
130
131
class Box2DKernel(Kernel2D):
132
"""
133
2D Box filter kernel.
134
135
Parameters:
136
- width: width of the box (scalar or 2-element array)
137
"""
138
def __init__(self, width): ...
139
140
class Tophat2DKernel(Kernel2D):
141
"""
142
2D circular tophat filter kernel.
143
144
Parameters:
145
- radius: radius of the tophat
146
"""
147
def __init__(self, radius): ...
148
149
class AiryDisk2DKernel(Kernel2D):
150
"""
151
2D Airy disk kernel.
152
153
Parameters:
154
- radius: radius of the first zero of the Airy function
155
"""
156
def __init__(self, radius): ...
157
158
class Moffat2DKernel(Kernel2D):
159
"""
160
2D Moffat kernel.
161
162
Parameters:
163
- gamma: core width of the Moffat function
164
- alpha: power index of the Moffat function
165
"""
166
def __init__(self, gamma, alpha): ...
167
168
class TrapezoidDisk2DKernel(Kernel2D):
169
"""
170
2D trapezoidal disk kernel.
171
172
Parameters:
173
- radius: outer radius of the trapezoid
174
- slope: slope of the trapezoid sides
175
"""
176
def __init__(self, radius, slope): ...
177
178
class Ring2DKernel(Kernel2D):
179
"""
180
2D ring kernel.
181
182
Parameters:
183
- radius_in: inner radius of the ring
184
- width: width of the ring
185
"""
186
def __init__(self, radius_in, width): ...
187
```
188
189
### Custom Kernels
190
191
Tools for creating custom convolution kernels from arrays or astropy models.
192
193
```python { .api }
194
class CustomKernel(Kernel):
195
"""
196
Custom kernel from user-provided array.
197
198
Parameters:
199
- array: kernel array data
200
"""
201
def __init__(self, array): ...
202
203
class Model1DKernel(Kernel1D):
204
"""
205
Create 1D kernel from astropy model.
206
207
Parameters:
208
- model: astropy 1D model instance
209
- x_size: size of the kernel
210
- mode: discretization mode
211
"""
212
def __init__(self, model, x_size, mode='center'): ...
213
214
class Model2DKernel(Kernel2D):
215
"""
216
Create 2D kernel from astropy model.
217
218
Parameters:
219
- model: astropy 2D model instance
220
- x_size: x-size of the kernel
221
- y_size: y-size of the kernel
222
- mode: discretization mode
223
"""
224
def __init__(self, model, x_size, y_size=None, mode='center'): ...
225
```
226
227
## Usage Examples
228
229
### Basic Convolution
230
231
```python
232
import numpy as np
233
from astropy.convolution import convolve, Gaussian2DKernel
234
235
# Create sample data
236
data = np.random.random((100, 100))
237
238
# Create Gaussian kernel
239
kernel = Gaussian2DKernel(stddev=2.0)
240
241
# Convolve data
242
smoothed = convolve(data, kernel)
243
```
244
245
### Custom Kernel Creation
246
247
```python
248
from astropy.convolution import CustomKernel, convolve
249
250
# Create custom kernel array
251
kernel_array = np.array([[0, 1, 0],
252
[1, 4, 1],
253
[0, 1, 0]]) / 8.0
254
255
# Create custom kernel
256
custom_kernel = CustomKernel(kernel_array)
257
258
# Apply convolution
259
result = convolve(data, custom_kernel)
260
```
261
262
### Handling NaN Values
263
264
```python
265
from astropy.convolution import interpolate_replace_nans, Gaussian2DKernel
266
267
# Data with NaN values
268
data_with_nans = np.random.random((50, 50))
269
data_with_nans[20:30, 20:30] = np.nan
270
271
# Replace NaN values using interpolation
272
kernel = Gaussian2DKernel(stddev=1.0)
273
cleaned_data = interpolate_replace_nans(data_with_nans, kernel)
274
```
275
276
## Types
277
278
```python { .api }
279
# Kernel types
280
Kernel = astropy.convolution.Kernel
281
Kernel1D = astropy.convolution.Kernel1D
282
Kernel2D = astropy.convolution.Kernel2D
283
284
# Built-in kernel types
285
Gaussian1DKernel = astropy.convolution.Gaussian1DKernel
286
Gaussian2DKernel = astropy.convolution.Gaussian2DKernel
287
Box1DKernel = astropy.convolution.Box1DKernel
288
Box2DKernel = astropy.convolution.Box2DKernel
289
Tophat2DKernel = astropy.convolution.Tophat2DKernel
290
AiryDisk2DKernel = astropy.convolution.AiryDisk2DKernel
291
Moffat2DKernel = astropy.convolution.Moffat2DKernel
292
```