or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

c-extensions.mdcontext-analysis.mdcoordinate-utils.mdindex.mdresampling.md
tile.json

tessl/pypi-drizzle

A package for combining dithered astronomical images into a single image using the Drizzle algorithm

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/drizzle@2.1.x

To install, run

npx @tessl/cli install tessl/pypi-drizzle@2.1.0

index.mddocs/

Drizzle

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.

Package Information

  • Package Name: drizzle
  • Language: Python
  • Installation: pip install drizzle
  • Requirements: Python 3.10+, NumPy

Core Imports

import drizzle

Common usage patterns:

from drizzle.resample import Drizzle, blot_image
from drizzle.utils import calc_pixmap, decode_context

Basic Usage

import numpy as np
from drizzle.resample import Drizzle
from drizzle.utils import calc_pixmap

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

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

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

# Add image to the drizzled output
nmiss, nskip = drizzler.add_image(
    data=data,
    exptime=15.0,
    pixmap=pixmap
)

# Access outputs
output_image = drizzler.out_img
weight_image = drizzler.out_wht
context_image = drizzler.out_ctx
total_exposure = drizzler.total_exptime

Architecture

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

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

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

Capabilities

Image Resampling and Combination

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.

class Drizzle:
    def __init__(
        self,
        kernel: str = "square",
        fillval: Optional[Union[str, float]] = None,
        out_shape: Optional[Tuple[int, int]] = None,
        out_img: Optional[np.ndarray] = None,
        out_wht: Optional[np.ndarray] = None,
        out_ctx: Optional[np.ndarray] = None,
        exptime: float = 0.0,
        begin_ctx_id: int = 0,
        max_ctx_id: Optional[int] = None,
        disable_ctx: bool = False
    ): ...

    def add_image(
        self,
        data: np.ndarray,
        exptime: float,
        pixmap: np.ndarray,
        scale: float = 1.0,
        weight_map: Optional[np.ndarray] = None,
        wht_scale: float = 1.0,
        pixfrac: float = 1.0,
        in_units: str = 'cps',
        xmin: Optional[int] = None,
        xmax: Optional[int] = None,
        ymin: Optional[int] = None,
        ymax: Optional[int] = None
    ) -> Tuple[float, float]: ...

def blot_image(
    data: np.ndarray,
    pixmap: np.ndarray,
    pix_ratio: float,
    exptime: float,
    output_pixel_shape: Tuple[int, int],
    interp: str = 'poly5',
    sinscl: float = 1.0
) -> np.ndarray: ...

Image Resampling

Coordinate Transformation Utilities

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

def calc_pixmap(
    wcs_from,
    wcs_to,
    shape: Optional[Tuple[int, int]] = None,
    disable_bbox: str = "to"
) -> np.ndarray: ...

def estimate_pixel_scale_ratio(
    wcs_from,
    wcs_to,
    refpix_from: Optional[Union[np.ndarray, Tuple, List]] = None,
    refpix_to: Optional[Union[np.ndarray, Tuple, List]] = None
) -> float: ...

Coordinate Utilities

Context Analysis

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

def decode_context(
    context: np.ndarray,
    x: Union[int, List[int], np.ndarray],
    y: Union[int, List[int], np.ndarray]
) -> List[np.ndarray]: ...

Context Analysis

High-Performance C Extensions

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

def tdriz(
    input: np.ndarray,
    weights: np.ndarray,
    pixmap: np.ndarray,
    output: np.ndarray,
    counts: np.ndarray,
    context: Optional[np.ndarray],
    uniqid: int,
    xmin: int,
    xmax: int,
    ymin: int,
    ymax: int,
    scale: float,
    pixfrac: float,
    kernel: str,
    in_units: str,
    expscale: float,
    wtscale: float,
    fillstr: str
) -> Tuple[str, float, float]: ...

def tblot(
    image: np.ndarray,
    pixmap: np.ndarray,
    output: np.ndarray,
    scale: float,
    kscale: float,
    interp: str,
    exptime: float,
    misval: float,
    sinscl: float
) -> None: ...

C Extensions

Types

from typing import Optional, Union, List, Tuple, Literal
import numpy as np

# Type imports needed for API signatures

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

# Supported kernel types
SUPPORTED_DRIZZLE_KERNELS = [
    "square",
    "gaussian",
    "point",
    "turbo",
    "lanczos2",
    "lanczos3"
]

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

# Interpolation methods for blotting
InterpolationMethod = Literal[
    "nearest",
    "linear",
    "poly3",
    "poly5",
    "sinc",
    "lan3",
    "lan5"
]

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