Skip to main content

drizzle Documentation

Powered by Astropy Badge Drizzle's Coverage Status CI Status Documentation Status PyPI Status Zenodo DOI

The drizzle library is a Python package for combining dithered images into a single image. This library is derived from code used in DrizzlePac. Like DrizzlePac, most of the code is implemented in the C language. The biggest change from DrizzlePac is that this code passes an array that maps the input to output image into the C code, while the DrizzlePac code computes the mapping by using a Python callback. Switching to using an array allowed the code to be greatly simplified.

The DrizzlePac code is currently used in the Space Telescope processing pipelines. This library is forward looking in that it can be used with the new GWCS code.

Requirements

  • Python 3.10 or later

  • Numpy

  • Astropy

The Drizzle Algorithm

This section has been extracted from Chapter 3 of The DrizzlePac Handbook [Driz2025]

There are a family of linear reconstruction techniques that, at two opposite extremes, are represented by the interlacing and shift-and-add techniques, with the Drizzle algorithm representing a continuum between these two extremes.

If the dithers are particularly well-placed, one can simply interlace the pixels from the images onto a finer grid. In the interlacing method, pixels from the independent input images are placed in alternate pixels on the output image according to the alignment of the pixel centers in the original images. However, due to occasional small positioning errors by the telescope, and non-uniform shifts in pixel space across the detector caused by geometric distortion of the optics, true interlacing of images is generally not feasible.

Another standard simple linear technique for combining shifted images, descriptively named “shift-and-add”, has been used for many years to combine dithered infrared data onto finer grids. Each input pixel is block-replicated onto a finer subsampled grid, shifted into place, and added to the output image. Shift-and-add has the advantage of being able to easily handle arbitrary dither positions. However, it convolves the image yet again with the original pixel, thus adding to the blurring of the image and to the correlation of noise in the image. Furthermore, it is difficult to use shift-and-add in the presence of missing data (e.g., from cosmic rays) and geometric distortion.

In response to the limitations of the two techniques described above, an improved method known formally as variable-pixel linear reconstruction, and more commonly referred to as Drizzle, was developed by Andy Fruchter and Richard Hook, initially for the purposes of combining dithered images of the Hubble Deep Field North (HDF-N). This algorithm can be thought of as a continuous set of linear functions that vary smoothly between the optimum linear combination technique (interlacing) and shift-and-add. This often allows an improvement in resolution and a reduction in correlated noise, compared with images produced by only using shift-and-add.

The degree to which the algorithm departs from interlacing and moves towards shift-and-add depends upon how well the PSF is subsampled by the shifts in the input images. In practice, the behavior of the Drizzle algorithm is controlled through the use of a parameter called pixfrac, which can be set to values ranging from 0 to 1, that represents the amount by which input pixels are shrunk before being mapped onto the output image plane.

A key to understanding the use of pixfrac is to realize that a CCD image can be thought of as the true image convolved first by the optics, then by the pixel response function (ideally a square the size of a pixel), and then sampled by a delta-function at the center of each pixel. A CCD image is thus a set of point samples of a continuous two-dimensional function. Hence the natural value of pixfrac is 0, which corresponds to pure interlacing. Setting pixfrac to values greater than 0 causes additional broadening of the output PSF by convolving the original PSF with pixels of non-zero size. Thus, setting pixfrac to its maximum value of 1 is equivalent to shift-and-add, the other extreme of linear combination, in which the output image PSF has been smeared by a convolution with the full size of the original input pixels.

The Drizzle algorithm is conceptually straightforward. Pixels in the original input images are mapped into pixels in the subsampled output image, taking into account shifts and rotations between images and the optical distortion of the camera. However, in order to avoid convolving the image with the large pixel “footprint” of the camera, Drizzle allows the user to shrink the pixel before it is averaged into the output image through the pixfrac parameter.

The flux value of each input pixel is divided up into the output pixels with weights proportional to the area of overlap between the “drop” and each output pixel. If the drop size is too small, not all output pixels have data added to them from each of the input images. One should therefore choose a drop size that is small enough to avoid convolving the image with too large an input pixel footprint, yet sufficiently large to ensure that there is not too much variation in the number of input pixels contributing to each output pixel.

When images are combined using Drizzle, a weight map can be specified for each input image. The weight image contains information about bad pixels in the image (in that bad pixels result in lower weight values). When the final output science image is generated, an output weight map which combines information from all the input weight images, is also saved.

Drizzle has a number of advantages over standard linear reconstruction methods. Since the pixel area can be scaled by the Jacobian of the geometric distortion, it is preserved for surface and absolute photometry. Therefore, the flux in the drizzled image, that was corrected for geometric distortion, can be measured with an aperture size that’s not dependent of its position on the image. Since the Drizzle code anticipates that a given output pixel might not receive any information from an input pixel, missing data does not cause a substantial problem as long as the observer has taken enough dither samples to fill in the missing information.

The blot methods perform the inverse operation of drizzle. That is, blotting performs the inverse mapping to transform the dithered median image back into the coordinate system of the original input image. Blotting is primarily used for identifying cosmic rays in the original image. Blot requires the user to provide the world coordinate system (WCS)-based transformations in the form of a pixel map array as input.

[Driz2025]

Anand, G. S., Mack, J., et al., 2025, “The DrizzlePac Handbook”, Version 3.0, (Baltimore: STScI)

Release files for drizzle 3.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for drizzle 3.0.0
File Size Uploaded
drizzle-3.0.0.tar.gz 132.9 kB Details

Built distributions (wheels)

Table of built distributions (wheels) for drizzle 3.0.0
File
drizzle-3.0.0-cp314-cp314t-win_amd64.whl CPython 3.14 CPython 3.14 free-threading Windows x86-64 Details
drizzle-3.0.0-cp314-cp314t-win32.whl CPython 3.14 CPython 3.14 free-threading Windows x86-32 Details
drizzle-3.0.0-cp314-cp314t-musllinux_1_2_x86_64.whl CPython 3.14 CPython 3.14 free-threading Linux musl 1.2+ x86-64 Details
drizzle-3.0.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl CPython 3.14 CPython 3.14 free-threading Linux glibc 2.17+ x86-64, Linux glibc 2.28+ x86-64 Details
drizzle-3.0.0-cp314-cp314t-macosx_11_0_arm64.whl CPython 3.14 CPython 3.14 free-threading macOS 11.0+ ARM64 Details
drizzle-3.0.0-cp310-abi3-win_amd64.whl CPython 3.10 abi3 Windows x86-64 Details
drizzle-3.0.0-cp310-abi3-win32.whl CPython 3.10 abi3 Windows x86-32 Details
drizzle-3.0.0-cp310-abi3-musllinux_1_2_x86_64.whl CPython 3.10 abi3 Linux musl 1.2+ x86-64 Details
drizzle-3.0.0-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl CPython 3.10 abi3 Linux glibc 2.28+ x86-64, Linux glibc 2.17+ x86-64 Details
drizzle-3.0.0-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details

Total release size: 2.1 MB

Release files / drizzle-3.0.0.tar.gz

Download URL drizzle-3.0.0.tar.gz
Size 132.9 kB
Tags Source
SHA-256 checksum
How to use checksums
ee1c7fde6abf7570e2032d9ad2a5c7969eb3ef1134194818a716f2d76f00f587
BLAKE2b-256 checksum
How to use checksums
90d2d5b0b80db3ca2fb0ec2bca290a132aa5e9b4ebeb857b0a8950474a0efb90
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.13

Release files / drizzle-3.0.0-cp314-cp314t-win_amd64.whl

Download URL drizzle-3.0.0-cp314-cp314t-win_amd64.whl
Size 102.9 kB
Tags CPython 3.14 CPython 3.14 free-threading Windows x86-64
SHA-256 checksum
How to use checksums
3dfa19e6204f5475506f6f872b47493cf845d0b2ecb2aa2611d24f4bde2007d2
BLAKE2b-256 checksum
How to use checksums
bcd33bd532279954c17a76445defdaaf252983a95f28b3c7b8e1665926078d1f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.13

Release files / drizzle-3.0.0-cp314-cp314t-win32.whl

Download URL drizzle-3.0.0-cp314-cp314t-win32.whl
Size 92.7 kB
Tags CPython 3.14 CPython 3.14 free-threading Windows x86-32
SHA-256 checksum
How to use checksums
36f5dc91a18a8c25471c9b9d3ee62182d97856f40522ca40e8c0c2236c95a550
BLAKE2b-256 checksum
How to use checksums
3a3c1b72b4a7c0544b4fc5229ba4620311d0f43b43c8accc16f7e55b91b1b415
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.13

Release files / drizzle-3.0.0-cp314-cp314t-musllinux_1_2_x86_64.whl

Download URL drizzle-3.0.0-cp314-cp314t-musllinux_1_2_x86_64.whl
Size 356.5 kB
Tags CPython 3.14 CPython 3.14 free-threading Linux musl 1.2+ x86-64
SHA-256 checksum
How to use checksums
9eedc21ebde776a2b5d84484c27801705f3101519d76cca42e08be5f40a5be33
BLAKE2b-256 checksum
How to use checksums
bf4a433bcf1fa8ee37f66046dce7d962f6c0899e4d5f48025150372abac6054a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.13

Release files / drizzle-3.0.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl

Download URL drizzle-3.0.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Size 360.6 kB
Tags CPython 3.14 CPython 3.14 free-threading Linux glibc 2.17+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
a272d451ec056842e065e4180dcdd0b10b4d2c2de7156feb98c217ed7aad8553
BLAKE2b-256 checksum
How to use checksums
3fcb68c1ad9185281a5d709195bd3b48b2e9459e5a5cc8e3821630b5e6da9c44
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.13

Release files / drizzle-3.0.0-cp314-cp314t-macosx_11_0_arm64.whl

Download URL drizzle-3.0.0-cp314-cp314t-macosx_11_0_arm64.whl
Size 99.7 kB
Tags CPython 3.14 CPython 3.14 free-threading macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
bb19781e92094cd4013557acd6f4f725d06658028116599054b0332c6b6dda31
BLAKE2b-256 checksum
How to use checksums
c440c041a4238b0935287470962ea5aa85366b9c3c63344b9937131200b48796
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.13

Release files / drizzle-3.0.0-cp310-abi3-win_amd64.whl

Download URL drizzle-3.0.0-cp310-abi3-win_amd64.whl
Size 100.0 kB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
c13d262f872d194c77644a9ee1330c70b88f3d42c4bc1d7b0143c92d277794ac
BLAKE2b-256 checksum
How to use checksums
19be41b52a05d7db67b0bda3020647fe03bcb2d68855129620de75f3b701256c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.13

Release files / drizzle-3.0.0-cp310-abi3-win32.whl

Download URL drizzle-3.0.0-cp310-abi3-win32.whl
Size 90.6 kB
Tags CPython 3.10 Windows x86-32 abi3
SHA-256 checksum
How to use checksums
24255ec0f90628cabf3c30e0ec9f5c1d85b6ad9b795ae430e3e74b8aaa18aac1
BLAKE2b-256 checksum
How to use checksums
707cf4e25bd11f2d3ffa70b94af603e40a89a65880e1d84d44597e5bba35a399
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.13

Release files / drizzle-3.0.0-cp310-abi3-musllinux_1_2_x86_64.whl

Download URL drizzle-3.0.0-cp310-abi3-musllinux_1_2_x86_64.whl
Size 336.5 kB
Tags CPython 3.10 Linux musl 1.2+ x86-64 abi3
SHA-256 checksum
How to use checksums
0616c66815f16a675ddec850b6ae5ab9f9abd9a2897b2f4b947dc4518b1adb46
BLAKE2b-256 checksum
How to use checksums
201c318100987bebc63092ef5943b33aa88668a72ce8ba906019bcf75c5d3eca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.13

Release files / drizzle-3.0.0-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl

Download URL drizzle-3.0.0-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Size 340.3 kB
Tags CPython 3.10 Linux glibc 2.17+ x86-64 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
07eb6787bcdb0847e96ac5ebaec50008f300bc823db26014896638f505fa7d0a
BLAKE2b-256 checksum
How to use checksums
14d6266d51fbadba2fbb6dd47e0b17cf51d6b1ea7e798047be6561970591e867
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.13

Release files / drizzle-3.0.0-cp310-abi3-macosx_11_0_arm64.whl

Download URL drizzle-3.0.0-cp310-abi3-macosx_11_0_arm64.whl
Size 99.1 kB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
31abc77822aaa4f3aa23fae71ac167bafa5109fa3a46e21cc3a0836e2f38607f
BLAKE2b-256 checksum
How to use checksums
ccc5cbddf2c74d2b1972eec555a00a03d75d58dba89c76d885d9a983b51e7dc7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.13

Release history Release notifications | RSS feed

This release

3.0.0 This release

11 release files

2.1.1

31 release files

2.1.0

21 release files

2.0.1

21 release files

2.0.0

21 release files

1.13.3

1 release file

1.13.1

1 release file

1.13

1 release file

1.12

1 release file

1.11

1 release file

1.1

1 release file

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page