0
# Drizzle
1

2
A Python package for combining dithered astronomical images into a single image using the Drizzle algorithm. The package provides advanced image reconstruction capabilities that handle arbitrary dither positions, missing data from cosmic rays, and geometric distortion, implementing variable-pixel linear reconstruction techniques for astronomical image processing.
3

4
## Package Information
5

6
- **Package Name**: drizzle
7
- **Language**: Python
8
- **Installation**: `pip install drizzle`
9
- **Requirements**: Python 3.10+, NumPy
10

11
## Core Imports
12

13
```python
14
import drizzle
15
```
16

17
Common usage patterns:
18

19
```python
20
from drizzle.resample import Drizzle, blot_image
21
from drizzle.utils import calc_pixmap, decode_context
22
```
23

24
## Basic Usage
25

26
```python
27
import numpy as np
28
from drizzle.resample import Drizzle
29
from drizzle.utils import calc_pixmap
30

31
# Simulate input data and pixel mapping
32
data = np.ones((240, 570), dtype=np.float32)
33

34
# For real usage, calc_pixmap would use actual WCS objects:
35
# pixmap = calc_pixmap(input_wcs, output_wcs)
36
# Here we simulate a simple identity mapping
37
y, x = np.indices((240, 570), dtype=np.float64)
38
pixmap = np.dstack([x, y])
39

40
# Initialize Drizzle object
41
drizzler = Drizzle(out_shape=(240, 570))
42

43
# Add image to the drizzled output
44
nmiss, nskip = drizzler.add_image(
45
    data=data,
46
    exptime=15.0,
47
    pixmap=pixmap
48
)
49

50
# Access outputs
51
output_image = drizzler.out_img
52
weight_image = drizzler.out_wht
53
context_image = drizzler.out_ctx
54
total_exposure = drizzler.total_exptime
55
```
56

57
## Architecture
58

59
The drizzle package implements a multi-layer architecture optimized for astronomical image processing performance:
60

61
- **Python Interface Layer**: High-level classes and functions (`Drizzle`, `blot_image`) providing convenient APIs
62
- **C Extension Layer**: Performance-critical algorithms (`cdrizzle` module) implementing core drizzling and blotting operations
63
- **Utility Layer**: Supporting functions for coordinate transformations, context decoding, and pixel scale calculations
64
- **Context Tracking System**: Bit-field encoding system tracking which input images contribute to each output pixel
65

66
This design enables the package to handle large astronomical datasets efficiently while providing flexible Python interfaces for integration with astronomy pipelines.
67

68
## Capabilities
69

70
### Image Resampling and Combination
71

72
Core drizzling functionality for combining multiple dithered images onto a common output grid. Supports various kernels, weight maps, and exposure scaling with comprehensive context tracking.
73

74
```python { .api }
75
class Drizzle:
76
    def __init__(
77
        self,
78
        kernel: str = "square",
79
        fillval: Optional[Union[str, float]] = None,
80
        out_shape: Optional[Tuple[int, int]] = None,
81
        out_img: Optional[np.ndarray] = None,
82
        out_wht: Optional[np.ndarray] = None,
83
        out_ctx: Optional[np.ndarray] = None,
84
        exptime: float = 0.0,
85
        begin_ctx_id: int = 0,
86
        max_ctx_id: Optional[int] = None,
87
        disable_ctx: bool = False
88
    ): ...
89

90
    def add_image(
91
        self,
92
        data: np.ndarray,
93
        exptime: float,
94
        pixmap: np.ndarray,
95
        scale: float = 1.0,
96
        weight_map: Optional[np.ndarray] = None,
97
        wht_scale: float = 1.0,
98
        pixfrac: float = 1.0,
99
        in_units: str = 'cps',
100
        xmin: Optional[int] = None,
101
        xmax: Optional[int] = None,
102
        ymin: Optional[int] = None,
103
        ymax: Optional[int] = None
104
    ) -> Tuple[float, float]: ...
105

106
def blot_image(
107
    data: np.ndarray,
108
    pixmap: np.ndarray,
109
    pix_ratio: float,
110
    exptime: float,
111
    output_pixel_shape: Tuple[int, int],
112
    interp: str = 'poly5',
113
    sinscl: float = 1.0
114
) -> np.ndarray: ...
115
```
116

117
[Image Resampling](./resampling.md)
118

119
### Coordinate Transformation Utilities
120

121
Tools for calculating pixel mappings between different coordinate systems, estimating pixel scale ratios, and working with World Coordinate System (WCS) objects.
122

123
```python { .api }
124
def calc_pixmap(
125
    wcs_from,
126
    wcs_to,
127
    shape: Optional[Tuple[int, int]] = None,
128
    disable_bbox: str = "to"
129
) -> np.ndarray: ...
130

131
def estimate_pixel_scale_ratio(
132
    wcs_from,
133
    wcs_to,
134
    refpix_from: Optional[Union[np.ndarray, Tuple, List]] = None,
135
    refpix_to: Optional[Union[np.ndarray, Tuple, List]] = None
136
) -> float: ...
137
```
138

139
[Coordinate Utilities](./coordinate-utils.md)
140

141
### Context Analysis
142

143
Functions for analyzing and decoding context images to determine which input images contributed to specific output pixels.
144

145
```python { .api }
146
def decode_context(
147
    context: np.ndarray,
148
    x: Union[int, List[int], np.ndarray],
149
    y: Union[int, List[int], np.ndarray]
150
) -> List[np.ndarray]: ...
151
```
152

153
[Context Analysis](./context-analysis.md)
154

155
### High-Performance C Extensions
156

157
Low-level C functions providing optimized implementations of core drizzling algorithms for maximum performance with large astronomical datasets.
158

159
```python { .api }
160
def tdriz(
161
    input: np.ndarray,
162
    weights: np.ndarray,
163
    pixmap: np.ndarray,
164
    output: np.ndarray,
165
    counts: np.ndarray,
166
    context: Optional[np.ndarray],
167
    uniqid: int,
168
    xmin: int,
169
    xmax: int,
170
    ymin: int,
171
    ymax: int,
172
    scale: float,
173
    pixfrac: float,
174
    kernel: str,
175
    in_units: str,
176
    expscale: float,
177
    wtscale: float,
178
    fillstr: str
179
) -> Tuple[str, float, float]: ...
180

181
def tblot(
182
    image: np.ndarray,
183
    pixmap: np.ndarray,
184
    output: np.ndarray,
185
    scale: float,
186
    kscale: float,
187
    interp: str,
188
    exptime: float,
189
    misval: float,
190
    sinscl: float
191
) -> None: ...
192
```
193

194
[C Extensions](./c-extensions.md)
195

196
## Types
197

198
```python { .api }
199
from typing import Optional, Union, List, Tuple, Literal
200
import numpy as np
201

202
# Type imports needed for API signatures
203

204
# Note: drizzle.util module is deprecated since v2.0.0 and will be removed.
205
# It contains only is_blank() function which should be replaced with alternative implementation.
206

207
# Supported kernel types
208
SUPPORTED_DRIZZLE_KERNELS = [
209
    "square",
210
    "gaussian",
211
    "point",
212
    "turbo",
213
    "lanczos2",
214
    "lanczos3"
215
]
216

217
# Input units
218
InputUnits = Literal["cps", "counts"]
219

220
# Interpolation methods for blotting
221
InterpolationMethod = Literal[
222
    "nearest",
223
    "linear",
224
    "poly3",
225
    "poly5",
226
    "sinc",
227
    "lan3",
228
    "lan5"
229
]
230

231
# Bounding box disable options
232
BBoxDisable = Literal["to", "from", "both", "none"]
233
```