tessl/pypi-drizzlepac

HST image combination using the drizzle algorithm to combine astronomical images, to model image distortion, to remove cosmic rays, and generally to improve the fidelity of data in the final image.

Overview

Eval results

Files

WCS and Region Management

Name: tessl/pypi-drizzlepac
Author: tessl

World Coordinate System utilities, region file mapping, and WCS solution management for complex astronomical workflows. These tools provide sophisticated coordinate system handling, region transformation capabilities, and WCS construction for HST observations.

Capabilities

WCS Solution Management

Apply updated WCS solutions from combined images back to constituent individual exposures with comprehensive headerlet management.

def apply_tweak(drz_file, orig_wcs_name, output_wcs_name=None,
               input_files=None, **kwargs):
    """
    Apply WCS solutions from drizzled to individual images.

    Parameters:
    - drz_file: str, drizzled image with updated WCS
    - orig_wcs_name: str, original WCS solution name
    - output_wcs_name: str, name for updated WCS solution
    - input_files: list, specific input files to update
    - **kwargs: dict, additional WCS update parameters

    Returns:
    None (updates input file headers)
    """

def tweakback(drzfile, input=None, origwcs=None, newname=None,
              wcsname=None, extname='SCI', **kwargs):
    """
    Main interface for applying updated WCS solutions.

    Parameters:
    - drzfile: str, combined image filename with reference WCS
    - input: str or list, input exposures to update
    - origwcs: str, original WCS solution identifier
    - newname: str, name for new WCS solution
    - wcsname: str, WCS solution name in drizzled image
    - extname: str, extension name containing WCS
    - **kwargs: dict, processing parameters

    Returns:
    None (modifies input exposure headers)
    """

def run(configobj):
    """
    Processing function for tweakback task.

    Parameters:
    - configobj: ConfigObj, configuration with WCS update parameters

    Returns:
    None (applies WCS updates)
    """

Region File Mapping

Map DS9 region files to multiple images based on WCS information, enabling region analysis across different observations and coordinate systems.

def MapReg(input_reg, images, img_wcs_ext='sci', refimg='',
          ref_wcs_ext='sci', **kwargs):
    """
    Main interface for mapping DS9 regions to images.

    Parameters:
    - input_reg: str, input DS9 region filename
    - images: str or list, target images for region mapping
    - img_wcs_ext: str, WCS extension in target images
    - refimg: str, reference image for coordinate system
    - ref_wcs_ext: str, WCS extension in reference image
    - **kwargs: dict, mapping parameters

    Returns:
    list, output region filenames for each image
    """

def map_region_files(input_reg, images, img_wcs_ext='sci', **kwargs):
    """
    Core region mapping functionality.

    Parameters:
    - input_reg: str, DS9 region file to map
    - images: list, target image list
    - img_wcs_ext: str, WCS extension identifier
    - **kwargs: dict, transformation parameters

    Returns:
    dict, mapping results and statistics
    """

def run(configObj):
    """
    Processing function for mapreg task.

    Parameters:
    - configObj: ConfigObj, configuration with region mapping parameters

    Returns:
    None (creates mapped region files)
    """

WCS Construction and Building

Build custom WCS solutions and reference frames for specialized processing requirements.

def buildwcs(outwcs, configObj=None, editpars=False, **input_dict):
    """
    Main interface for WCS construction.

    Parameters:
    - outwcs: str, output WCS specification
    - configObj: ConfigObj, configuration object
    - editpars: bool, allow interactive parameter editing
    - **input_dict: dict, WCS construction parameters

    Returns:
    None (creates WCS solution)
    """

def build(outname, wcsname, refimage, undistort=False, **kwargs):
    """
    Core WCS building functionality.

    Parameters:
    - outname: str, output WCS filename
    - wcsname: str, WCS solution name
    - refimage: str, reference image for WCS construction
    - undistort: bool, remove distortion from WCS
    - **kwargs: dict, construction parameters

    Returns:
    WCS, constructed world coordinate system
    """

def run(configObj, wcsmap=None):
    """
    Processing function for buildwcs task.

    Parameters:
    - configObj: ConfigObj, configuration with WCS parameters
    - wcsmap: function, optional WCS mapping function

    Returns:
    None (creates WCS products)
    """

Usage Examples

Applying WCS Solutions

from drizzlepac import tweakback

# Apply updated WCS from combined image to input exposures
tweakback.tweakback('combined_drz.fits',
                   input=['exp1_flt.fits', 'exp2_flt.fits'],
                   origwcs='OPUS',
                   newname='TWEAKREG',
                   wcsname='DRZWCS')

# Apply specific WCS solution
tweakback.apply_tweak('j8bt06_drz.fits',
                     orig_wcs_name='OPUS',
                     output_wcs_name='ALIGNED',
                     input_files=['j8bt06nyq_flt.fits', 'j8bt06nzq_flt.fits'])

Mapping DS9 Regions

from drizzlepac import mapreg

# Map regions to multiple images
region_files = mapreg.MapReg('source_regions.reg',
                            images=['image1.fits', 'image2.fits', 'image3.fits'],
                            img_wcs_ext='sci',
                            refimg='image1.fits')

# Map regions with custom parameters
mapreg.map_region_files('apertures.reg',
                       ['acs_1.fits[sci,1]', 'acs_2.fits[sci,1]'],
                       img_wcs_ext='sci',
                       tolerance=0.1)  # arcsec tolerance

Building Custom WCS

from drizzlepac import buildwcs

# Build WCS for custom mosaic
buildwcs.buildwcs('custom_wcs.fits',
                 configobj=None,
                 outnx=4096,
                 outny=4096,
                 scale=0.05,      # arcsec/pixel
                 rot=0.0,         # degrees
                 ra=83.633,       # degrees
                 dec=22.015)      # degrees

# Build undistorted WCS
buildwcs.build('undistorted_wcs.fits',
              'UNDIST',
              'reference_image.fits',
              undistort=True)

DS9 Region Support

Supported Region Types

DrizzlePac region mapping supports standard DS9 region formats:

Circle: circle(ra, dec, radius)
Ellipse: ellipse(ra, dec, semi_major, semi_minor, angle)
Box: box(ra, dec, width, height, angle)
Polygon: polygon(ra1, dec1, ra2, dec2, ...)
Point: point(ra, dec)

Coordinate Systems

Region mapping handles multiple coordinate systems:

FK5: J2000.0 equatorial coordinates
FK4: B1950.0 equatorial coordinates
Galactic: Galactic longitude and latitude
Ecliptic: Ecliptic coordinates
Image: Pixel coordinates

Example Region File

# Region file format: DS9 version 4.1
# Filename: source_apertures.reg
global color=green dashlist=8 3 width=1 font="helvetica 10 normal roman"
fk5
circle(83.633128, 22.014533, 2") # color=red
ellipse(83.630245, 22.012891, 3", 2", 45) # color=blue
box(83.628102, 22.015234, 4", 4", 0) # color=yellow

WCS Headerlet Management

Headerlet Operations

DrizzlePac integrates with STWCS headerlet functionality:

# Create headerlet from current WCS
from stwcs import headerlet

# Extract WCS as headerlet
headerlet.extract_headerlet('image.fits', 'wcs_solution.fits')

# Apply headerlet to image
headerlet.apply_headerlet('image.fits', 'new_wcs.fits')

# Archive WCS solution
headerlet.archive_headerlet('image.fits', 'backup_wcs.fits')

WCS Solution Names

Standard WCS solution naming conventions:

OPUS: Original pipeline WCS from calibration
DRZWCS: WCS from drizzled image combination
TWEAKREG: WCS updated by TweakReg alignment
TWEAK: Updated alignment solution
HSC30: Hubble Source Catalog astrometry

Advanced WCS Operations

Multi-Extension WCS

Handling WCS for multi-extension FITS files:

from drizzlepac import tweakback

# Apply WCS to specific extensions
tweakback.tweakback('mosaic_drz.fits',
                   input='multi_ext.fits',
                   ext_list=[1, 2, 3, 4],  # Process extensions 1-4
                   newname='ALIGNED_WCS')

WCS Transformation Chains

Complex coordinate transformations:

# Chain multiple WCS transformations
from astropy import wcs
from drizzlepac import wcs_functions

# Load WCS solutions
wcs1 = wcs.WCS('image1.fits[sci,1]')
wcs2 = wcs.WCS('image2.fits[sci,1]')

# Transform coordinates through WCS chain
ra, dec = wcs1.all_pix2world(x, y, 1)
x_new, y_new = wcs2.all_world2pix(ra, dec, 1)

Distortion Handling

WCS construction with distortion correction:

from drizzlepac import buildwcs

# Build WCS preserving distortion
buildwcs.build('with_distortion.fits',
              'DISTORTED',
              'reference.fits',
              undistort=False)

# Build linearized WCS
buildwcs.build('linear_wcs.fits',
              'LINEAR',
              'reference.fits',
              undistort=True)

Quality Control

WCS Validation

Validation checks for WCS solutions:

# Check WCS consistency
from drizzlepac import wcs_functions

def validate_wcs(image, tolerance=0.1):
    """
    Validate WCS solution quality.

    Parameters:
    - image: str, image with WCS to validate
    - tolerance: float, allowed coordinate deviation (arcsec)

    Returns:
    bool, WCS validation status
    """
    # Implementation checks coordinate accuracy,
    # distortion model validity, and transformation consistency
    pass

Region Mapping Quality

Quality assessment for region mapping:

Coordinate Accuracy: Verify transformed region positions
Coverage Validation: Check region overlap with image boundaries
Distortion Effects: Account for coordinate transformation accuracy

Error Handling

Common WCS Errors

WCSError: Invalid or missing WCS information
HeaderletError: Headerlet creation or application failures
RegionError: Region file format or coordinate system issues
TransformationError: Coordinate transformation failures

Recovery Strategies

from drizzlepac import tweakback

try:
    tweakback.tweakback('combined.fits', input='exposure.fits')
except Exception as e:
    print(f"WCS update failed: {e}")
    # Fall back to original WCS or alternative solution

Best Practices

WCS Management

Backup original WCS before applying updates
Document WCS solution names and provenance
Validate WCS accuracy after transformations
Use appropriate coordinate systems for scientific analysis

Region Mapping

Verify region coordinate systems match expectations
Account for distortion effects in precise measurements
Validate mapped regions against expected positions
Use appropriate tolerances for coordinate matching

Performance Optimization

Cache WCS solutions for repeated operations
Process regions in batches for efficiency
Use appropriate coordinate precisions for the analysis
Minimize coordinate transformations when possible

Install with Tessl CLI

npx tessl i tessl/pypi-drizzlepac

docs

coordinate-transformations.md

data-quality-calibration.md

hap-processing.md

image-processing.md

index.md

registration-alignment.md

wcs-region-management.md

tile.json