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.
registration-alignment.mddocs/
Registration and Alignment
Advanced algorithms for computing offsets between images and reference frames. TweakReg provides robust source-based alignment with multiple fitting algorithms and comprehensive quality assessment, replacing the legacy IRAF tweakshifts task with enhanced capabilities for HST data.
Capabilities
TweakReg - Image Registration
Computes offsets in WCS between images and a reference image or reference frame using source catalogs and various fitting algorithms.
def TweakReg(files=None, editpars=False, configobj=None,
imagefindcfg=None, refimagefindcfg=None, **input_dict):
"""
Main interface for image registration and alignment.
Parameters:
- files: str or list, input images to align
- editpars: bool, allow interactive parameter editing
- configobj: ConfigObj, configuration object with parameters
- imagefindcfg: ConfigObj, parameters for finding sources in input images
- refimagefindcfg: ConfigObj, parameters for finding sources in reference
- **input_dict: dict, parameter overrides
Returns:
None (updates image WCS headers)
"""
def run(configobj):
"""
Primary Python interface for image registration.
Parameters:
- configobj: ConfigObj, configuration with all alignment parameters
Returns:
None (updates image WCS headers)
"""Source Detection and Catalog Generation
Automatic source detection and catalog creation for alignment purposes.
def generateCatalog(wcs, mode='automatic', catalog=None, **kwargs):
"""
Generate source catalogs from images for alignment.
Parameters:
- wcs: WCS object, world coordinate system for image
- mode: str, detection mode ('automatic', 'manual')
- catalog: str, external catalog file path
- **kwargs: dict, source detection parameters
Returns:
Catalog object
"""
class Catalog:
"""
Base catalog class for source management.
"""
class ImageCatalog(Catalog):
"""
Image-derived source catalogs.
"""
class UserCatalog(Catalog):
"""
User-provided source catalogs.
"""
class RefCatalog(UserCatalog):
"""
Reference catalogs for alignment.
"""High-Level Alignment Interface
Enhanced alignment capabilities with quality assessment and multiple fitting methods.
def perform_align(input_list, **pars):
"""
Main alignment function with quality assessment.
Parameters:
- input_list: list, input images to align
- **pars: dict, alignment parameters including:
- catalog: str, reference catalog type
- fit_mode: str, fitting algorithm
- minobj: int, minimum sources required
- searchrad: float, search radius in arcsec
Returns:
dict, alignment results and quality metrics
"""
def check_and_get_data(input_list, **pars):
"""
Data validation and retrieval for alignment.
Parameters:
- input_list: list, input file specifications
- **pars: dict, validation parameters
Returns:
list, validated and processed input data
"""
def determine_fit_quality(**kwargs):
"""
Quality assessment for alignment solutions.
Parameters:
- **kwargs: dict, fit results and quality metrics
Returns:
dict, quality assessment results
"""
def generate_astrometric_catalog(imglist, **pars):
"""
Generate reference catalogs for alignment.
Parameters:
- imglist: list, input image list
- **pars: dict, catalog generation parameters
Returns:
str, reference catalog filename
"""Alignment Methods
Default Fit (General Linear)
Standard linear transformation fitting suitable for most cases:
# Configuration for default fitting
fit_mode = 'default'
fitgeometry = 'rscale' # rotation + scale
minobj = 15 # minimum sources for fitRelative Fit
Relative alignment between images without external reference:
def match_relative_fit(imglist, reference_catalog, **fit_pars):
"""
Relative alignment between images.
Parameters:
- imglist: list, input images to align
- reference_catalog: str, reference catalog for alignment
- **fit_pars: dict, fitting parameters
Returns:
dict, alignment transformation parameters
"""2D Histogram Fit
Advanced fitting method using 2D histograms for robust alignment:
def match_2dhist_fit(imglist, reference_catalog, **fit_pars):
"""
2D histogram-based alignment.
Parameters:
- imglist: list, input images to align
- reference_catalog: str, reference catalog for alignment
- **fit_pars: dict, fitting parameters including:
- searchrad: float, search radius
- tolerance: float, matching tolerance
- use2dhist: bool, enable 2D histogram method
Returns:
dict, alignment transformation parameters
"""Default Fit
Standard alignment algorithm with general linear transformation:
def match_default_fit(imglist, reference_catalog, **fit_pars):
"""
Default alignment algorithm.
Parameters:
- imglist: list, input images to align
- reference_catalog: str, reference catalog for alignment
- **fit_pars: dict, fitting parameters
Returns:
dict, alignment transformation parameters
"""Parameter Configuration
Image Source Finding Parameters
Configuration for detecting sources in input images:
class imagefindpars:
"""
Parameters for finding point sources in input images.
Attributes:
- computesig: bool, compute sigma from image data
- skysigma: float, background sigma value
- conv_width: float, convolution kernel width
- threshold: float, detection threshold
- dqbits: str, DQ bits to ignore
- fwhm: float, expected FWHM of sources
"""Reference Source Finding Parameters
Configuration for detecting sources in reference images:
class refimagefindpars:
"""
Parameters for finding sources in reference images.
Attributes:
- computesig: bool, compute sigma from image data
- skysigma: float, background sigma value
- conv_width: float, convolution kernel width
- threshold: float, detection threshold
- dqbits: str, DQ bits to ignore
- fwhm: float, expected FWHM of sources
"""Usage Examples
Basic TweakReg Alignment
from drizzlepac import tweakreg
# Align multiple images to first image
tweakreg.TweakReg(['j8bt06nyq_flt.fits', 'j8bt06nzq_flt.fits'],
refimage='j8bt06nyq_flt.fits[sci,1]',
fitgeometry='rscale',
minobj=15,
searchrad=1.0,
threshold=4.0,
interactive=False)Advanced Alignment with External Catalog
from drizzlepac import tweakreg, align
# Use external astrometric catalog
align.perform_align(['image1.fits', 'image2.fits'],
catalog='GAIADR2',
clobber=True,
fitgeometry='rscale',
nclip=3,
sigma=3.0)Pipeline Alignment
from drizzlepac.align import perform_align
# Automated alignment for pipeline processing
results = perform_align(input_files,
catalog='GAIADR3',
fit_mode='match_default_fit',
searchrad=250.0, # milliarcsec
minobj=6,
fitgeometry='rscale',
nclip=3,
sigma=3.0)Alignment Quality Assessment
TweakReg provides comprehensive quality metrics:
Fit Statistics
- RMS: Root mean square of residuals
- NMATCHES: Number of matched sources
- FIT_RMS: RMS of final fit
- MAX_RESID: Maximum residual
Quality Flags
- FIT_QUAL: Overall fit quality assessment
- MATCH_QUAL: Source matching quality
- WCS_UPD: WCS update status
WCS Update and Management
Applying Alignment Results
def update_image_wcs_info(tweakwcs_output, headerlet_filenames=None, **kwargs):
"""
Update WCS information after alignment.
Parameters:
- tweakwcs_output: dict, alignment results from TweakWCS
- headerlet_filenames: list, output headerlet file names
- **kwargs: dict, update parameters
Returns:
None (updates image headers)
"""Alignment Tables
class AlignmentTable:
"""
Manage alignment solutions and transformations.
Methods:
- add_fit(): Add alignment fit results
- get_fit(): Retrieve fit parameters
- apply_fit(): Apply transformation to coordinates
- write(): Save alignment table to file
"""Error Handling
Common alignment errors and exceptions:
- ValueError: Insufficient sources for alignment or incompatible parameters
- RuntimeError: Convergence failure in fitting algorithms
- IOError: Missing or corrupted input images
- WCSError: Invalid or incompatible WCS solutions
Quality assessment flags indicate alignment success and reliability for automated processing workflows.
Install with Tessl CLI
npx tessl i tessl/pypi-drizzlepac