Drizzle

2.2.0 verified Fri May 01 auth: no python

A Python package for combining dithered astronomical images into a single image, supporting various kernels and error propagation. Current version is 2.2.0, requires Python >=3.10. Maintenance-led releases from STScI.

pip install drizzle

Common errors

error AttributeError: module 'drizzle' has no attribute 'util' ↓

cause The 'util' module was deprecated and removed in v2.0.0.

fix

Import from other drizzle submodules like cdriz or use the main drizzle.do_drizzle. Do not import from drizzle.util.

error ImportError: cannot import name 'cdriz' from 'drizzle' ↓

cause cdriz is a C extension; incorrect import path if not installed properly or if using an older version.

fix

Run pip install --upgrade drizzle to ensure the C extensions are built. Then use: from drizzle import cdriz

error TypeError: do_drizzle() got an unexpected keyword argument 'fillval' ↓

cause fillval was renamed or removed in a newer version. In 2.0.0, the API changed; fillval might not be a valid argument.

fix

Check the function signature: use positional arguments or check documentation for new argument names like 'fill_value'.

error ValueError: Unsupported kernel 'tophat' ↓

cause The 'tophat' kernel was removed in v2.0.0.

fix

Use kernel='square' (the replacement) or another supported kernel.

Warnings

breaking Version 2.0.0 redesigned the API: removed FITS-specific code, deprecated the 'util' module, removed support for 'tophat' kernel. Backward compatibility maintained only for JWST and Roman pipelines. ↓

fix If upgrading from 1.x, refactor code to remove imports from drizzle.util; use the new I/O agnostic API. For JWST/Roman users, existing code may work; otherwise check pipeline documentation.

deprecated The 'util' module is deprecated since 2.0.0 and will be removed in a future release. Do not import from drizzle.util. ↓

fix Replace imports from drizzle.util with the corresponding public API functions (e.g., cdriz, drizzle.do_drizzle).

gotcha The 'gaussian', 'lanczos2', and 'lanczos3' kernels are not flux conserving. Using them will produce incorrect photometric results. ↓

fix Use 'square', 'point', or 'turbo' kernels for flux conservation. If you must use Lanczos, be aware of the warning and consider calibration.

gotcha The 'pixfrac' parameter is ignored when using the Lanczos kernel, as noted in a warning added in v2.2.0. Specify pixfrac only for other kernels; Lanczos always uses its own interpolation. ↓

fix Do not rely on pixfrac with Lanczos. The warning is emitted automatically.

gotcha The 'tophat' kernel was deprecated in 1.15.0 and removed in 2.0.0. Use 'square' or another supported kernel. ↓

fix Replace kernel='tophat' with kernel='square'.

gotcha Exposure time is undefined when in_units are not 'cps' (counts per second). The code may produce unexpected output if you pass non-cps data without proper scaling. ↓

fix Ensure input images are in units of counts per second (cps) or handle exposure time separately.

Imports

drizzle
```
import drizzle
```
Direct import of the top-level package is the standard entry point.
cdriz
wrong
```
import cdriz
```
correct
```
from drizzle import cdriz
```
cdriz is a submodule; direct import fails.
blot
wrong
```
from drizzle.blot import blot
```
correct
```
from drizzle import blot
```
blot is a high-level function in drizzle, not a submodule.
util
wrong
```
from drizzle import util
```
correct
```
from drizzle import cdriz
```
Module 'util' was deprecated in 2.0.0 and removed; use cdriz or other public APIs.

Quickstart

Minimal drizzling example using synthetic 2x2 images. Adjust WCS parameters for real data.

import numpy as np
from drizzle import drizzle

# Create two simple dither images (2x2 each)
img1 = np.array([[1.0, 2.0], [3.0, 4.0]])
img2 = np.array([[1.5, 2.5], [3.5, 4.5]])

# Define WCS-like parameters: output shape, input/output pixel scales
# This is a minimal example; real usage requires proper WCS objects.
out_shape = (4, 4)
output = np.zeros(out_shape)

# Drizzle the images (example with square kernel)
drizzle.do_drizzle(output, img1, '1,1', '1,1', '1,1', 1.0, 1.0, kernel='square', pixfrac=1.0)
print(output)