stdpipe.astrometry module

stdpipe.astrometry.get_frame_center(filename=None, header=None, wcs=None, width=None, height=None, shape=None)

Returns image center RA, Dec, and angular radius in degrees.

Parameters:

filenamestr, optional

Path to FITS file.

headerastropy.io.fits.Header, optional

FITS header containing WCS keywords.

wcsastropy.wcs.WCS, optional

WCS object.

widthint, optional

Image width in pixels. Read from header if not provided.

heightint, optional

Image height in pixels. Read from header if not provided.

shapetuple of int, optional

Image shape (height, width). Used if width/height not given.

Returns:

rafloat or None

Right Ascension of frame center in degrees.

decfloat or None

Declination of frame center in degrees.

srfloat or None

Angular radius from center to corner in degrees.

stdpipe.astrometry.get_pixscale(wcs=None, filename=None, header=None)

Returns pixel scale of an image in degrees per pixel.

Parameters:

wcsastropy.wcs.WCS, optional

WCS object.

filenamestr, optional

Path to FITS file.

headerastropy.io.fits.Header, optional

FITS header containing WCS keywords.

Returns:

float

Pixel scale in degrees per pixel.

stdpipe.astrometry.radectoxyz(ra, dec)

stdpipe.astrometry.xyztoradec(xyz)

stdpipe.astrometry.spherical_distance(ra1, dec1, ra2, dec2)

Compute spherical distance between two points or sets of points.

Parameters:

ra1float or array_like

First point or set of points RA in degrees.

dec1float or array_like

First point or set of points Dec in degrees.

ra2float or array_like

Second point or set of points RA in degrees.

dec2float or array_like

Second point or set of points Dec in degrees.

Returns:

float or ndarray

Spherical distance in degrees.

stdpipe.astrometry.spherical_match(ra1, dec1, ra2, dec2, sr=0.0002777777777777778)

Positional match on the sphere for two lists of coordinates.

Aimed to be a direct replacement for esutil.htm.HTM.match() method with maxmatch=0.

Parameters:

ra1array_like

First set of points RA in degrees.

dec1array_like

First set of points Dec in degrees.

ra2array_like

Second set of points RA in degrees.

dec2array_like

Second set of points Dec in degrees.

srfloat, optional

Maximal acceptable pair distance to be considered a match, in degrees. Default is 1/3600 (1 arcsecond).

Returns:

idx1ndarray of int

Indices into the first list for matched pairs.

idx2ndarray of int

Indices into the second list for matched pairs.

distndarray of float

Pairwise distances in degrees.

stdpipe.astrometry.planar_match(x1, y1, x2, y2, sr=1)

Positional match on the plane for two lists of coordinates.

Parameters:

x1array_like

First set of points X coordinates.

y1array_like

First set of points Y coordinates.

x2array_like

Second set of points X coordinates.

y2array_like

Second set of points Y coordinates.

srfloat, optional

Maximal acceptable pair distance to be considered a match. Default is 1.

Returns:

idx1ndarray of int

Indices into the first list for matched pairs.

idx2ndarray of int

Indices into the second list for matched pairs.

distndarray of float

Pairwise distances.

stdpipe.astrometry.get_objects_center(obj, col_ra='ra', col_dec='dec')

Returns the center RA, Dec, and radius in degrees for a cloud of objects on the sky.

stdpipe.astrometry.blind_match_objects(obj, order=2, update=False, sn=20, get_header=False, width=None, height=None, center_ra=None, center_dec=None, radius=None, scale_lower=None, scale_upper=None, scale_units='arcsecperpix', config=None, extra={}, _workdir=None, _tmpdir=None, _exe=None, verbose=False)

Thin wrapper for blind plate solving using local Astrometry.Net and a list of detected objects.

It requires solve-field binary from Astrometry.Net and some index files to be locally available.

Parameters:

objastropy.table.Table

List of objects on the frame, must contain at least x, y, and flux columns.

orderint, optional

Order for the SIP spatial distortion polynomial.

updatebool, optional

If True, the object list will be updated in-place with correct ra and dec sky coordinates.

snfloat, optional

If provided, only objects with S/N exceeding this value will be used for matching.

get_headerbool, optional

If True, return the FITS header object instead of WCS solution.

widthint, optional

Image width in pixels, used for guessing the frame center.

heightint, optional

Image height in pixels, used for guessing the frame center.

center_rafloat, optional

Approximate center RA of the field in degrees.

center_decfloat, optional

Approximate center Dec of the field in degrees.

radiusfloat, optional

Search radius in degrees around the specified center.

scale_lowerfloat, optional

Lower limit for the pixel scale.

scale_upperfloat, optional

Upper limit for the pixel scale.

scale_unitsstr, optional

Units for scale_lower/scale_upper. One of arcsecperpix, arcminwidth, or degwidth.

configstr, optional

Path to config file for solve-field.

extradict, optional

Additional parameters to pass to solve-field binary.

_workdirstr, optional

If specified, all temporary files will be kept in this directory after the run.

_tmpdirstr, optional

If specified, temporary files will be created inside this path.

_exestr, optional

Full path to solve-field executable. Auto-detected from PATH if not provided.

verbosebool or callable, optional

Whether to show verbose messages. May be boolean or a print-like callable.

Returns:

astropy.wcs.WCS or astropy.io.fits.Header or None

Astrometric solution, or FITS header if get_header=True, or None on failure.

stdpipe.astrometry.blind_match_astrometrynet(obj, order=2, update=False, sn=20, get_header=False, width=None, height=None, solve_timeout=600, api_key=None, center_ra=None, center_dec=None, radius=None, scale_lower=None, scale_upper=None, scale_units='arcsecperpix', **kwargs)

Thin wrapper for remote plate solving using Astrometry.Net and a list of detected objects.

Most parameters are passed directly to astroquery.astrometrynet.AstrometryNet.solve_from_source_list. API key may be provided as an argument or set in ~/.astropy/config/astroquery.cfg.

Parameters:

objastropy.table.Table

List of objects on the frame, must contain at least x, y, and flux columns.

orderint, optional

Order for the SIP spatial distortion polynomial.

updatebool, optional

If True, the object list will be updated in-place with correct ra and dec sky coordinates.

snfloat, optional

If provided, only objects with S/N exceeding this value will be used for matching.

get_headerbool, optional

If True, return the FITS header object instead of WCS solution.

widthint, optional

Image width in pixels, used for guessing the frame center.

heightint, optional

Image height in pixels, used for guessing the frame center.

solve_timeoutfloat, optional

Timeout in seconds to wait for the solution from the remote server.

api_keystr, optional

Astrometry.Net API key. If not set, must be configured in ~/.astropy/config/astroquery.cfg.

center_rafloat, optional

Approximate center RA of the field in degrees.

center_decfloat, optional

Approximate center Dec of the field in degrees.

radiusfloat, optional

Search radius in degrees around the specified center.

scale_lowerfloat, optional

Lower limit for the pixel scale.

scale_upperfloat, optional

Upper limit for the pixel scale.

scale_unitsstr, optional

Units for scale_lower/scale_upper. One of arcsecperpix, arcminwidth, or degwidth.

Returns:

astropy.wcs.WCS or astropy.io.fits.Header or None

Astrometric solution, or FITS header if get_header=True, or None on failure.

stdpipe.astrometry.refine_wcs_simple(obj, cat, order=2, match=True, sr=0.0008333333333333334, update=False, cat_col_ra='RAJ2000', cat_col_dec='DEJ2000', method='astropy', _tmpdir=None, verbose=False)

Refine the WCS using detected objects and a reference catalogue.

Parameters:

objastropy.table.Table

List of detected objects with at least x, y, ra, dec columns.

catastropy.table.Table

Reference astrometric catalogue.

orderint, optional

SIP polynomial order for distortion solution.

matchbool, optional

If True, perform nearest-neighbor matching between objects and catalogue. If False, assume they are already matched line by line.

srfloat, optional

Matching radius in degrees. Default is 3/3600 (3 arcseconds).

updatebool, optional

If True, update object sky coordinates in-place using the new WCS.

cat_col_rastr, optional

Catalogue column name for Right Ascension.

cat_col_decstr, optional

Catalogue column name for Declination.

methodstr, optional

Fitting method. Either 'astropy' or 'astrometrynet'.

_tmpdirstr, optional

If specified, temporary files will be created inside this path.

verbosebool or callable, optional

Whether to show verbose messages. May be boolean or a print-like callable.

Returns:

astropy.wcs.WCS or None

Refined WCS solution, or None on failure.

stdpipe.astrometry.clear_wcs(header, remove_comments=False, remove_history=False, remove_underscored=False, copy=False)

Clear WCS-related keywords from a FITS header.

Parameters:

headerastropy.io.fits.Header

Header to operate on.

remove_commentsbool, optional

If True, also remove COMMENT keywords.

remove_historybool, optional

If True, also remove HISTORY keywords.

remove_underscoredbool, optional

If True, also remove all keywords starting with underscore (often added by Astrometry.Net).

copybool, optional

If True, operate on a copy and leave the original unchanged.

Returns:

astropy.io.fits.Header

Modified FITS header.

stdpipe.astrometry.wcs_pv2sip(header, order=None, accuracy=0.0001)

Convert a WCS header from any projection to TAN-SIP representation.

The original WCS is sampled on a dense pixel grid and SIP polynomial coefficients (A, B for the forward distortion and AP, BP for the reverse) are fitted to reproduce the same pixel→sky mapping via least squares.

Works for any input projection (TPV, ZPN, ZEA, etc.).

Parameters:

header~astropy.io.fits.Header

Input FITS header with WCS keywords.

orderint or None

SIP polynomial order. If None (default), the order is chosen automatically (2 through 6) to achieve accuracy on the fitting grid.

accuracyfloat

Target accuracy in arcseconds for automatic order selection (default 1e-4, i.e. 0.1 mas).

Returns:

header~astropy.io.fits.Header

New header with TAN-SIP WCS (CTYPE RA---TAN-SIP).

stdpipe.astrometry.wcs_sip2pv(header)

Convert a WCS header from SIP (or any projection) to TPV representation.

The original WCS is sampled on a dense pixel grid and TPV polynomial coefficients are fitted to reproduce the same pixel→sky mapping via least squares. Works for any projection type (TAN-SIP, ZPN-SIP, etc.) with sub-milliarcsecond accuracy.

Parameters:

headerastropy.io.fits.Header

Input FITS header with WCS keywords.

Returns:

astropy.io.fits.Header

New header with TPV WCS (CTYPE set to RA---TPV).

stdpipe.astrometry.table_to_ldac(table, header=None, writeto=None)

stdpipe.astrometry.refine_wcs_scamp(obj, cat=None, wcs=None, header=None, sr=0.0005555555555555556, order=3, cat_col_ra='RAJ2000', cat_col_dec='DEJ2000', cat_col_ra_err='e_RAJ2000', cat_col_dec_err='e_DEJ2000', cat_col_mag='rmag', cat_col_mag_err='e_rmag', cat_mag_lim=99, sn=None, position_maxerr=None, posangle_maxerr=None, pixscale_maxerr=None, match_flipped=False, extra={}, get_header=False, update=False, _workdir=None, _tmpdir=None, _exe=None, verbose=False)

Wrapper for running SCAMP to get a refined astrometric solution.

Parameters:

objastropy.table.Table

List of objects on the frame, must contain at least x, y, and flux columns.

catastropy.table.Table or str, optional

Reference astrometric catalogue, or a SCAMP network catalogue name (e.g. 'GAIA-DR2').

wcsastropy.wcs.WCS, optional

Initial WCS solution.

headerastropy.io.fits.Header, optional

FITS header containing the initial astrometric solution.

srfloat, optional

Matching radius in degrees. Controls SCAMP’s CROSSID_RADIUS.

orderint, optional

Polynomial order for PV distortion solution (1 or greater).

cat_col_rastr, optional

Catalogue column name for Right Ascension.

cat_col_decstr, optional

Catalogue column name for Declination.

cat_col_ra_errstr, optional

Catalogue column name for Right Ascension error.

cat_col_dec_errstr, optional

Catalogue column name for Declination error.

cat_col_magstr, optional

Catalogue column name for magnitude.

cat_col_mag_errstr, optional

Catalogue column name for magnitude error.

cat_mag_limfloat or sequence of float, optional

Magnitude limit(s) for catalogue stars. A single value is used as an upper limit; two values [min, max] define a range.

snfloat or sequence of float, optional

S/N threshold(s) for SCAMP (passed as SN_THRESHOLDS).

position_maxerrfloat, optional

Maximum positional uncertainty of the initial WCS in arcminutes. Controls the search range for field center offset during pattern matching. Default is SCAMP’s built-in default of 1 arcmin.

posangle_maxerrfloat, optional

Maximum position angle uncertainty in degrees. Default is SCAMP’s built-in default of 5 degrees.

pixscale_maxerrfloat, optional

Maximum pixel scale uncertainty as a multiplicative factor (>1.0). E.g. 1.2 means ±20% around the initial scale. Default is SCAMP’s built-in default of 1.2.

match_flippedbool, optional

If True, also try matching with flipped (mirrored) axes. Default is False.

extradict, optional

Additional parameters to pass to the SCAMP binary.

get_headerbool, optional

If True, return the FITS header object instead of WCS solution.

updatebool, optional

If True, update object sky coordinates in-place using the new WCS.

_workdirstr, optional

If specified, all temporary files will be kept in this directory after the run.

_tmpdirstr, optional

If specified, temporary files will be created inside this path.

_exestr, optional

Full path to the SCAMP executable. Auto-detected from PATH if not provided.

verbosebool or callable, optional

Whether to show verbose messages. May be boolean or a print-like callable.

Returns:

astropy.wcs.WCS or astropy.io.fits.Header or None

Refined astrometric solution, or FITS header if get_header=True, or None on failure.

stdpipe.astrometry.store_wcs(filename, wcs, overwrite=True)

Store WCS information in an (empty) FITS file.

Parameters:

filenamestr

Path to the output FITS file.

wcsastropy.wcs.WCS

WCS object to store.

overwritebool, optional

If True, overwrite an existing file. Default is True.

stdpipe.astrometry.upscale_wcs(wcs, scale=2, will_rebin=False)

Return a WCS corresponding to a frame upscaled by a given factor.

Parameters:

wcsastropy.wcs.WCS

Input WCS to upscale.

scalefloat, optional

Upscaling factor (not necessarily integer). Default is 2.

will_rebinbool, optional

If True, adjust CRPIX so that rebinning the result back to original resolution with utils.rebin_image() will not introduce a shift.

Returns:

astropy.wcs.WCS

WCS corresponding to the upscaled frame.

stdpipe.astrometry.fit_astrometric_residuals(x_obs, y_obs, x_pred, y_pred, *, image_shape=None, backend='grid', **smoother_kwargs)

Fit a smooth (dx, dy) correction field for astrometric residuals.

Given matched pairs of observed and WCS-predicted pixel positions of the same sources, fit a smooth two-component field that maps any predicted position to the corresponding observed one. The returned callable applies the additive correction at arbitrary positions.

Parameters:

x_obs, y_obsarray-like, shape (N,)

Observed pixel positions of matched sources (e.g. SEP centroids).

x_pred, y_predarray-like, shape (N,)

WCS-predicted pixel positions of the same sources from a reference catalogue. x_obs - x_pred is the residual being modelled.

image_shape(H, W), optional

Forwarded to the grid backend; ignored by LOESS.

backend{“grid”, “loess”}

Smoothing backend; see stdpipe.smoothing.fit_vector_field_2d(). Default "grid" because the typical astrometric-residual workflow evaluates the correction at far more positions than were used to fit it (e.g. forced-position photometry of large catalogues), where grid lookup is ~600–1000x faster than LOESS prediction.

**smoother_kwargs

Forwarded to fit_vector_field_2d(). Grid backend keys: grid_shape, min_per_cell, smooth_sigma. LOESS backend keys: scales, k, robust_iters, …

Returns:

correctcallable

correct(x, y) -> (x_corrected, y_corrected): adds the smooth (dx, dy) field at (x, y). Has a .smoother attribute holding the underlying field model for diagnostics.

stdpipe.astrometry.refine_positions_from_catalog(match, obj, cat, wcs, *, obj_col_x='x', obj_col_y='y', cat_col_ra='ra', cat_col_dec='dec', image_shape=None, backend='grid', **smoother_kwargs)

Build an astrometric residual correction from a match dict.

Wraps fit_astrometric_residuals() with the column-extraction boilerplate needed when the matches come from stdpipe.pipeline.calibrate_photometry() or stdpipe.photometry.match(). Returns the correction callable plus a small dictionary of pre/post-correction residual statistics.

Parameters:

matchdict

Cross-match dictionary with at least the keys idx (boolean mask of accepted matches), oidx (object indices into obj), and cidx (catalogue indices into cat).

obj, catastropy.table.Table

Object and catalogue tables matched by match.

wcsastropy.wcs.WCS

WCS used to project catalogue positions into pixel coordinates.

obj_col_x, obj_col_ystr

Column names for observed pixel positions in obj.

cat_col_ra, cat_col_decstr

Column names for sky positions in cat.

image_shape(H, W), optional

Forwarded to the smoothing backend.

backend{“grid”, “loess”}

Smoothing backend.

**smoother_kwargs

Forwarded to fit_astrometric_residuals().

Returns:

correctcallable

Same as fit_astrometric_residuals().

infodict

n_matched, n_used, raw_median_dr_pix, corrected_median_dr_pix, raw_q90_dr_pix, corrected_q90_dr_pix. The corrected statistics are evaluated at the same matched positions used for the fit (in-sample), so they over-state the gain; for an unbiased estimate, subset match['idx'] into a holdout mask before calling this.