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

Coordinate Transformations

Name: tessl/pypi-drizzlepac
Author: tessl

Bidirectional coordinate transformation capabilities between pixel coordinates, sky coordinates, and different WCS reference frames. These tools provide full distortion correction and support both interactive use and batch processing of coordinate lists.

Capabilities

Pixel to Sky Coordinate Transformation

Convert pixel positions to sky coordinates (RA/Dec) with full distortion correction as appropriate for the instrument and observation.

def xy2rd(input, x=None, y=None, coords=None, coordfile=None,
          colnames=None, separator=None, precision=10, output=None,
          verbose=True):
    """
    Convert pixel positions to sky coordinates.

    Parameters:
    - input: str, input image filename
    - x: float or list, X pixel coordinates
    - y: float or list, Y pixel coordinates
    - coords: str, coordinate string "x,y" format
    - coordfile: str, file containing pixel coordinates
    - colnames: list, column names for coordinate file
    - separator: str, delimiter for coordinate file
    - precision: int, decimal precision for output coordinates
    - output: str, output file name for results
    - verbose: bool, print coordinate transformations

    Returns:
    list, sky coordinates as [(ra, dec), ...] tuples
    """

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

    Parameters:
    - configObj: ConfigObj, configuration with transformation parameters

    Returns:
    None (prints or saves coordinate results)
    """

Sky to Pixel Coordinate Transformation

Convert sky positions (RA/Dec) to pixel positions in an image using the image's WCS information.

def rd2xy(input, ra=None, dec=None, coordfile=None, colnames=None,
          precision=6, output=None, verbose=True):
    """
    Convert sky positions to pixel positions.

    Parameters:
    - input: str, input image filename
    - ra: float or list, Right Ascension coordinates (degrees)
    - dec: float or list, Declination coordinates (degrees)
    - coordfile: str, file containing sky coordinates
    - colnames: list, column names for coordinate file
    - precision: int, decimal precision for output coordinates (default: 6)
    - output: str, output file name for results
    - verbose: bool, print coordinate transformations (default: True)

    Returns:
    tuple, (x, y) arrays or single values in pixels
    """

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

    Parameters:
    - configObj: ConfigObj, configuration with transformation parameters

    Returns:
    None (prints or saves coordinate results)
    """

Pixel-to-Pixel Coordinate Transformation

Transform pixel coordinates from one image to another, accounting for different WCS solutions, orientations, and scales.

def tran(inimage, outimage, direction='forward', x=None, y=None,
         coords=None, coordfile=None, colnames=None, separator=None,
         precision=10, output=None, verbose=True):
    """
    Transform pixel coordinates between images.

    Parameters:
    - inimage: str, input image filename
    - outimage: str, output image filename or WCS reference
    - direction: str, transformation direction ('forward' or 'backward')
    - x: float or list, X pixel coordinates in input image
    - y: float or list, Y pixel coordinates in input image
    - coords: str, coordinate string "x,y" format
    - coordfile: str, file containing pixel coordinates
    - colnames: list, column names for coordinate file
    - separator: str, delimiter for coordinate file
    - precision: int, decimal precision for output coordinates
    - output: str, output file name for results
    - verbose: bool, print coordinate transformations

    Returns:
    list, transformed coordinates as [(x, y), ...] tuples
    """

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

    Parameters:
    - configObj: ConfigObj, configuration with transformation parameters

    Returns:
    None (prints or saves coordinate results)
    """

Usage Examples

Interactive Coordinate Transformation

from drizzlepac import pixtosky, skytopix, pixtopix

# Convert single pixel position to sky coordinates
ra, dec = pixtosky.xy2rd('j8bt06nyq_flt.fits[sci,1]', x=512, y=512)
print(f"RA: {ra[0]:.6f}, Dec: {dec[0]:.6f}")

# Convert sky position back to pixels
x, y = skytopix.rd2xy('j8bt06nyq_flt.fits[sci,1]', ra=ra[0], dec=dec[0])
print(f"X: {x[0]:.2f}, Y: {y[0]:.2f}")

# Transform pixels between different images
x_out, y_out = pixtopix.tran('input.fits[sci,1]', 'output.fits[sci,1]',
                            x=100, y=200)
print(f"Transformed: X={x_out[0]:.2f}, Y={y_out[0]:.2f}")

Batch Coordinate Processing

from drizzlepac import pixtosky

# Process coordinate file
pixtosky.xy2rd('image.fits[sci,1]',
              coordfile='pixels.txt',
              colnames=['X_IMAGE', 'Y_IMAGE'],
              separator=',',
              output='skycoords.txt')

Using Multiple Extensions

from drizzlepac import pixtosky

# Transform coordinates for multiple chip extensions
for ext in range(1, 5):
    ra, dec = pixtosky.xy2rd(f'acs_image.fits[sci,{ext}]',
                            x=512, y=512)
    print(f"Chip {ext}: RA={ra[0]:.6f}, Dec={dec[0]:.6f}")

Coordinate File Formats

Input File Format

Coordinate files can be ASCII text with customizable delimiters:

# X_pixel  Y_pixel
100.5     200.3
250.1     150.7
400.0     300.0

Output File Format

Results include original coordinates and transformed values:

# Input coordinates and transformed sky positions
# X_pixel  Y_pixel  RA_deg      Dec_deg
100.5     200.3    83.633128   22.014533
250.1     150.7    83.630245   22.012891
400.0     300.0    83.628102   22.015234

Supported Extensions and Formats

FITS Extensions

All coordinate transformation tasks support:

Science extensions: [SCI,n]
Primary extensions: [0]
Named extensions: [EXTNAME,EXTVER]

Multi-Extension FITS (MEF)

For instruments with multiple detectors:

ACS/WFC: Extensions 1 and 2 for WFC1 and WFC2
WFC3/UVIS: Extensions 1 and 2 for UVIS1 and UVIS2
WFPC2: Extensions 1-4 for PC1, WF2, WF3, WF4

WCS Distortion Correction

Distortion Models Supported

Simple Imaging Polynomial (SIP): Standard HST distortion correction
Lookup Tables: Pixel-based distortion corrections
Polynomial: Classical polynomial distortion models
Paper IV: Advanced distortion conventions

Instrument-Specific Corrections

Each HST instrument has specialized distortion handling:

ACS: CTE corrections and filter-dependent distortions
WFC3: UVIS and IR channel-specific corrections
WFPC2: Historic distortion models with geometric corrections
STIS: Spectroscopic distortion corrections
NICMOS: IR-specific geometric distortions

Error Handling

Common Exceptions

IOError: Missing or unreadable input images
ValueError: Invalid coordinate values or file formats
WCSError: Corrupted or missing WCS information
KeyError: Missing required FITS header keywords

Error Recovery

from drizzlepac import pixtosky

try:
    ra, dec = pixtosky.xy2rd('image.fits', x=512, y=512)
except Exception as e:
    print(f"Coordinate transformation failed: {e}")
    # Handle error or use alternative method

Validation Checks

Coordinate bounds checking against image dimensions
WCS validity verification
Extension existence validation
Coordinate format validation

Advanced Usage

Custom Column Names

from drizzlepac import skytopix

# Use custom column names in input file
skytopix.rd2xy('image.fits',
              coordfile='catalog.txt',
              colnames=['RA', 'DEC'],
              separator='\t',
              output='pixel_coords.txt')

High Precision Transformations

from drizzlepac import pixtosky

# Maximum precision output
ra, dec = pixtosky.xy2rd('image.fits', x=512.123, y=512.456,
                        precision=12)