lsst.meas.extensions.astrometryNet.anetAstrometry.ANetAstrometryTask Class Reference

Use astrometry.net to match input sources with a reference catalog and solve for the Wcs. More...

Inheritance diagram for lsst.meas.extensions.astrometryNet.anetAstrometry.ANetAstrometryTask:

Public Member Functions
def	__init__ (self, schema, refObjLoader=None, kwds)
	Create the astrometric calibration task. More...
def	run (self, exposure, sourceCat)
	Load reference objects, match sources and optionally fit a WCS. More...
def	solve (self, exposure, sourceCat)
	Match with reference sources and calculate an astrometric solution. More...
def	distort (self, sourceCat, exposure)
	Calculate distorted source positions. More...
def	loadAndMatch (self, exposure, sourceCat, bbox=None)
	Load reference objects overlapping an exposure and match to sources detected on that exposure. More...
def	refitWcs (self, sourceCat, exposure, matches)
	A final Wcs solution after matching and removing distortion. More...

Public Attributes
	distortedName
	centroidXKey
	centroidYKey
	centroidXErrKey
	centroidYErrKey
	centroidFlagKey
	centroidKey
	centroidErrKey
	solver

Static Public Attributes
	ConfigClass = ANetAstrometryConfig

Detailed Description

Use astrometry.net to match input sources with a reference catalog and solve for the Wcs.

The actual matching and solving is done by the 'solver'; this Task serves as a wrapper for taking into account the known optical distortion.

Contents

• Description
• Task initialisation
• Invoking the Task
• Configuration parameters
• Debug variables
• A complete example of using ANetAstrometryTask

Description

Use astrometry.net to match input sources with a reference catalog and solve for the Wcs.

Task initialisation

Create the astrometric calibration task. Most arguments are simply passed onto pipe.base.Task.

Parameters

schema	An lsst::afw::table::Schema used to create the output lsst.afw.table.SourceCatalog
refObjLoader	The AstrometryTask constructor requires a refObjLoader. In order to make this task retargettable for AstrometryTask it needs to take the same arguments. This argument will be ignored since it uses its own internal loader.
**kwds	keyword arguments to be passed to the lsst.pipe.base.task.Task constructor

A centroid field "centroid.distorted" (used internally during the Task's operation) will be added to the schema.

Invoking the Task

Load reference objects, match sources and optionally fit a WCS. This is a thin layer around solve or loadAndMatch, depending on config.forceKnownWcs

Parameters

[in,out]	exposure	exposure whose WCS is to be fit The following are read only: bbox photoCalib (may be absent) filter (may be unset) detector (if wcs is pure tangent; may be absent) The following are updated: wcs (the initial value is used as an initial guess, and is required)
[in]	sourceCat	catalog of sourceCat detected on the exposure (an lsst.afw.table.SourceCatalog)

Returns

an lsst.pipe.base.Struct with these fields:

• refCat reference object catalog of objects that overlap the exposure (with some margin) (an lsst::afw::table::SimpleCatalog)
• matches astrometric matches, a list of lsst.afw.table.ReferenceMatch
• matchMeta metadata about the field (an lsst.daf.base.PropertyList)

Configuration parameters

See ANetAstrometryConfig

Debug variables

The command line task interface supports a flag -d to import debug.py from your PYTHONPATH; see Using lsstDebug to control debugging output for more about debug.py files.

The available variables in ANetAstrometryTask are:

display

If True call showAstrometry while iterating ANetAstrometryConfig.rejectIter times, and also after converging; and call displayAstrometry after applying the distortion correction.

frame

display frame to use in showAstrometry and displayAstrometry

pause

Pause after showAstrometry and displayAstrometry?

A complete example of using ANetAstrometryTask

See A complete example of using PhotoCalTask.

To investigate the Debug variables, put something like

import lsstDebug
def DebugInfo(name):
    di = lsstDebug.getInfo(name)        # N.b. lsstDebug.Info(name) would call us recursively
    if name in ("lsst.pipe.tasks.anetAstrometry", "lsst.pipe.tasks.anetBasicAstrometry"):
        di.display = 1
        di.frame = 1
        di.pause = True

    return di

lsstDebug.Info = DebugInfo

into your debug.py file and run photoCalTask.py with the –debug flag.

Definition at line 72 of file anetAstrometry.py.

Constructor & Destructor Documentation

__init__()

def lsst.meas.extensions.astrometryNet.anetAstrometry.ANetAstrometryTask.__init__	(		self,
			schema,
			refObjLoader = None,
			kwds
	)

Create the astrometric calibration task.

Most arguments are simply passed onto pipe.base.Task.

Parameters

schema	An lsst::afw::table::Schema used to create the output lsst.afw.table.SourceCatalog
refObjLoader	The AstrometryTask constructor requires a refObjLoader. In order to make this task retargettable for AstrometryTask it needs to take the same arguments. This argument will be ignored since it uses its own internal loader.
**kwds	keyword arguments to be passed to the lsst.pipe.base.task.Task constructor

A centroid field "centroid.distorted" (used internally during the Task's operation) will be added to the schema.

Definition at line 145 of file anetAstrometry.py.

    def __init__(self, schema, refObjLoader=None, **kwds):
        r"""!Create the astrometric calibration task.  Most arguments are simply passed onto pipe.base.Task.

        \param schema An lsst::afw::table::Schema used to create the output lsst.afw.table.SourceCatalog
        \param refObjLoader The AstrometryTask constructor requires a refObjLoader.  In order to make this
        task retargettable for AstrometryTask it needs to take the same arguments.  This argument will be
        ignored since it uses its own internal loader.
        \param **kwds keyword arguments to be passed to the lsst.pipe.base.task.Task constructor

        A centroid field "centroid.distorted" (used internally during the Task's operation)
        will be added to the schema.
        """
        pipeBase.Task.__init__(self, **kwds)
        self.distortedName = "astrom_distorted"
        self.centroidXKey = schema.addField(self.distortedName + "_x", type="D",
                                            doc="centroid distorted for astrometry solver")
        self.centroidYKey = schema.addField(self.distortedName + "_y", type="D",
                                            doc="centroid distorted for astrometry solver")
        self.centroidXErrKey = schema.addField(self.distortedName + "_xErr", type="F",
                                               doc="centroid distorted err for astrometry solver")
        self.centroidYErrKey = schema.addField(self.distortedName + "_yErr", type="F",
                                               doc="centroid distorted err for astrometry solver")
        self.centroidFlagKey = schema.addField(self.distortedName + "_flag", type="Flag",
                                               doc="centroid distorted flag astrometry solver")
        self.centroidKey = Point2DKey(self.centroidXKey, self.centroidYKey)
        self.centroidErrKey = CovarianceMatrix2fKey((self.centroidXErrKey, self.centroidYErrKey))
        # postpone making the solver subtask because it may not be needed and is expensive to create
        self.solver = None

Member Function Documentation

distort()

def lsst.meas.extensions.astrometryNet.anetAstrometry.ANetAstrometryTask.distort	(		self,
			sourceCat,
			exposure
	)

Calculate distorted source positions.

CCD images are often affected by optical distortion that makes the astrometric solution higher order than linear. Unfortunately, most (all?) matching algorithms require that the distortion be small or zero, and so it must be removed. We do this by calculating (un-)distorted positions, based on a known optical distortion model in the Ccd.

The distortion correction moves sources, so we return the distorted bounding box.

Parameters

[in]	exposure	Exposure to process
[in,out]	sourceCat	SourceCatalog; getX() and getY() will be used as inputs, with distorted points in "centroid.distorted" field.

Returns

bounding box of distorted exposure

Definition at line 236 of file anetAstrometry.py.

    def distort(self, sourceCat, exposure):
        r"""!Calculate distorted source positions

        CCD images are often affected by optical distortion that makes
        the astrometric solution higher order than linear.  Unfortunately,
        most (all?) matching algorithms require that the distortion be
        small or zero, and so it must be removed.  We do this by calculating
        (un-)distorted positions, based on a known optical distortion model
        in the Ccd.

        The distortion correction moves sources, so we return the distorted bounding box.

        \param[in]     exposure Exposure to process
        \param[in,out] sourceCat  SourceCatalog; getX() and getY() will be used as inputs,
                                with distorted points in "centroid.distorted" field.
        \return bounding box of distorted exposure
        """
        detector = exposure.getDetector()
        pixToTanXYTransform = None
        if detector is None:
            self.log.warn("No detector associated with exposure; assuming null distortion")
        else:
            pixToTanXYTransform = detector.getTransform(PIXELS, TAN_PIXELS)

        if pixToTanXYTransform is None:
            self.log.info("Null distortion correction")
            for s in sourceCat:
                s.set(self.centroidKey, s.getCentroid())
                s.set(self.centroidErrKey, s.getCentroidErr())
                s.set(self.centroidFlagKey, s.getCentroidFlag())
            return exposure.getBBox()

        # Distort source positions
        self.log.info("Applying distortion correction")
        for s in sourceCat:
            centroid = pixToTanXYTransform.forwardTransform(s.getCentroid())
            s.set(self.centroidKey, centroid)
            s.set(self.centroidErrKey, s.getCentroidErr())
            s.set(self.centroidFlagKey, s.getCentroidFlag())

        # Get distorted image size so that astrometry_net does not clip.
        bboxD = afwGeom.Box2D()
        for corner in detector.getCorners(TAN_PIXELS):
            bboxD.include(corner)

        if lsstDebug.Info(__name__).display:
            frame = lsstDebug.Info(__name__).frame
            pause = lsstDebug.Info(__name__).pause
            displayAstrometry(sourceCat=sourceCat, distortedCentroidKey=self.centroidKey,
                              exposure=exposure, frame=frame, pause=pause)

        return afwGeom.Box2I(bboxD)

loadAndMatch()

def lsst.meas.extensions.astrometryNet.anetAstrometry.ANetAstrometryTask.loadAndMatch	(		self,
			exposure,
			sourceCat,
			bbox = None
	)

Load reference objects overlapping an exposure and match to sources detected on that exposure.

Parameters

[in]	exposure	exposure whose WCS is to be fit
[in]	sourceCat	catalog of sourceCat detected on the exposure (an lsst.afw.table.SourceCatalog)
[in]	bbox	bounding box go use for finding reference objects; if None, use exposure's bbox

Returns

an lsst.pipe.base.Struct with these fields:

• refCat reference object catalog of objects that overlap the exposure (with some margin) (an lsst::afw::table::SimpleCatalog)
• matches astrometric matches, a list of lsst.afw.table.ReferenceMatch
• matchMeta metadata about the field (an lsst.daf.base.PropertyList)

Note

ignores config.forceKnownWcs

Definition at line 290 of file anetAstrometry.py.

    def loadAndMatch(self, exposure, sourceCat, bbox=None):
        """!Load reference objects overlapping an exposure and match to sources detected on that exposure

        @param[in] exposure  exposure whose WCS is to be fit
        @param[in] sourceCat  catalog of sourceCat detected on the exposure (an lsst.afw.table.SourceCatalog)
        @param[in] bbox  bounding box go use for finding reference objects; if None, use exposure's bbox

        @return an lsst.pipe.base.Struct with these fields:
        - refCat  reference object catalog of objects that overlap the exposure (with some margin)
            (an lsst::afw::table::SimpleCatalog)
        - matches  astrometric matches, a list of lsst.afw.table.ReferenceMatch
        - matchMeta  metadata about the field (an lsst.daf.base.PropertyList)

        @note ignores config.forceKnownWcs
        """
        bbox = exposure.getBBox()
        if not self.solver:
            self.makeSubtask("solver")

        astrom = self.solver.useKnownWcs(
            sourceCat=sourceCat,
            exposure=exposure,
            bbox=bbox,
            calculateSip=False,
        )

        if astrom is None or astrom.getWcs() is None:
            raise RuntimeError("Unable to solve astrometry")

        matches = astrom.getMatches()
        matchMeta = astrom.getMatchMetadata()
        if matches is None or len(matches) == 0:
            raise RuntimeError("No astrometric matches")
        self.log.info("%d astrometric matches", len(matches))

        if self._display:
            frame = lsstDebug.Info(__name__).frame
            displayAstrometry(exposure=exposure, sourceCat=sourceCat, matches=matches,
                              frame=frame, pause=False)

        return pipeBase.Struct(
            refCat=astrom.refCat,
            matches=matches,
            matchMeta=matchMeta,
        )

refitWcs()

def lsst.meas.extensions.astrometryNet.anetAstrometry.ANetAstrometryTask.refitWcs	(		self,
			sourceCat,
			exposure,
			matches
	)

A final Wcs solution after matching and removing distortion.

Specifically, fitting the non-linear part, since the linear part has been provided by the matching engine.

Parameters

sourceCat	Sources on exposure, an lsst.afw.table.SourceCatalog
exposure	Exposure of interest, an lsst.afw.image.ExposureF or D
matches	Astrometric matches, as a list of lsst.afw.table.ReferenceMatch

Returns

the resolved-Wcs object, or None if config.solver.calculateSip is False.

Definition at line 382 of file anetAstrometry.py.

    def refitWcs(self, sourceCat, exposure, matches):
        """!A final Wcs solution after matching and removing distortion

        Specifically, fitting the non-linear part, since the linear
        part has been provided by the matching engine.

        @param sourceCat Sources on exposure, an lsst.afw.table.SourceCatalog
        @param exposure Exposure of interest, an lsst.afw.image.ExposureF or D
        @param matches Astrometric matches, as a list of lsst.afw.table.ReferenceMatch

        @return the resolved-Wcs object, or None if config.solver.calculateSip is False.
        """
        sip = None
        if self.config.solver.calculateSip:
            self.log.info("Refitting WCS")
            origMatches = matches
            wcs = exposure.getWcs()

            import lsstDebug
            display = lsstDebug.Info(__name__).display
            frame = lsstDebug.Info(__name__).frame
            pause = lsstDebug.Info(__name__).pause

            def fitWcs(initialWcs, title=None):
                """!Do the WCS fitting and display of the results"""
                sip = makeCreateWcsWithSip(matches, initialWcs, self.config.solver.sipOrder)
                resultWcs = sip.getNewWcs()
                if display:
                    showAstrometry(exposure, resultWcs, origMatches, matches, frame=frame,
                                   title=title, pause=pause)
                return resultWcs, sip.getScatterOnSky()

            numRejected = 0
            try:
                for i in range(self.config.rejectIter):
                    wcs, scatter = fitWcs(wcs, title="Iteration %d" % i)

                    ref = np.array([wcs.skyToPixel(m.first.getCoord()) for m in matches])
                    src = np.array([m.second.getCentroid() for m in matches])
                    diff = ref - src
                    rms = diff.std()
                    trimmed = []
                    for d, m in zip(diff, matches):
                        if np.all(np.abs(d) < self.config.rejectThresh*rms):
                            trimmed.append(m)
                        else:
                            numRejected += 1
                    if len(matches) == len(trimmed):
                        break
                    matches = trimmed

                # Final fit after rejection iterations
                wcs, scatter = fitWcs(wcs, title="Final astrometry")

            except lsst.pex.exceptions.LengthError as e:
                self.log.warn("Unable to fit SIP: %s", e)

            self.log.info("Astrometric scatter: %f arcsec (%d matches, %d rejected)",
                          scatter.asArcseconds(), len(matches), numRejected)
            exposure.setWcs(wcs)

            # Apply WCS to sources
            updateSourceCoords(wcs, sourceCat)
        else:
            self.log.warn("Not calculating a SIP solution; matches may be suspect")

        if self._display:
            frame = lsstDebug.Info(__name__).frame
            displayAstrometry(exposure=exposure, sourceCat=sourceCat, matches=matches,
                              frame=frame, pause=False)

        return sip

run()

def lsst.meas.extensions.astrometryNet.anetAstrometry.ANetAstrometryTask.run	(		self,
			exposure,
			sourceCat
	)

Load reference objects, match sources and optionally fit a WCS.

This is a thin layer around solve or loadAndMatch, depending on config.forceKnownWcs

Parameters

[in,out]	exposure	exposure whose WCS is to be fit The following are read only: bbox photoCalib (may be absent) filter (may be unset) detector (if wcs is pure tangent; may be absent) The following are updated: wcs (the initial value is used as an initial guess, and is required)
[in]	sourceCat	catalog of sourceCat detected on the exposure (an lsst.afw.table.SourceCatalog)

Returns

an lsst.pipe.base.Struct with these fields:

• refCat reference object catalog of objects that overlap the exposure (with some margin) (an lsst::afw::table::SimpleCatalog)
• matches astrometric matches, a list of lsst.afw.table.ReferenceMatch
• matchMeta metadata about the field (an lsst.daf.base.PropertyList)

Definition at line 175 of file anetAstrometry.py.

    def run(self, exposure, sourceCat):
        """!Load reference objects, match sources and optionally fit a WCS

        This is a thin layer around solve or loadAndMatch, depending on config.forceKnownWcs

        @param[in,out] exposure  exposure whose WCS is to be fit
            The following are read only:
            - bbox
            - photoCalib (may be absent)
            - filter (may be unset)
            - detector (if wcs is pure tangent; may be absent)
            The following are updated:
            - wcs (the initial value is used as an initial guess, and is required)
        @param[in] sourceCat  catalog of sourceCat detected on the exposure (an lsst.afw.table.SourceCatalog)
        @return an lsst.pipe.base.Struct with these fields:
        - refCat  reference object catalog of objects that overlap the exposure (with some margin)
            (an lsst::afw::table::SimpleCatalog)
        - matches  astrometric matches, a list of lsst.afw.table.ReferenceMatch
        - matchMeta  metadata about the field (an lsst.daf.base.PropertyList)
        """
        if self.config.forceKnownWcs:
            return self.loadAndMatch(exposure=exposure, sourceCat=sourceCat)
        else:
            return self.solve(exposure=exposure, sourceCat=sourceCat)

solve()

def lsst.meas.extensions.astrometryNet.anetAstrometry.ANetAstrometryTask.solve	(		self,
			exposure,
			sourceCat
	)

Match with reference sources and calculate an astrometric solution.

Parameters

[in,out]	exposure	Exposure to calibrate; wcs is updated
[in]	sourceCat	catalog of measured sources (an lsst.afw.table.SourceCatalog)

Returns

a pipeBase.Struct with fields:

• refCat reference object catalog of objects that overlap the exposure (with some margin) (an lsst::afw::table::SimpleCatalog)
• matches astrometric matches, a list of lsst.afw.table.ReferenceMatch
• matchMeta metadata about the field (an lsst.daf.base.PropertyList)

The reference catalog actually used is up to the implementation of the solver; it will be manifested in the returned matches as a list of lsst.afw.table.ReferenceMatch objects (i.e. of lsst.afw.table.Match with first being of type lsst.afw.table.SimpleRecord and second type lsst.afw.table.SourceRecord — the reference object and matched object respectively).

Note

The input sources have the centroid slot moved to a new column "centroid.distorted" which has the positions corrected for any known optical distortion; the 'solver' (which is instantiated in the 'astrometry' member) should therefore simply use the centroids provided by calling afw.table.Source.getCentroid() on the individual source records. This column must be present in the sources table.

ignores config.forceKnownWcs

Definition at line 201 of file anetAstrometry.py.

    def solve(self, exposure, sourceCat):
        r"""!Match with reference sources and calculate an astrometric solution

        \param[in,out] exposure Exposure to calibrate; wcs is updated
        \param[in] sourceCat catalog of measured sources (an lsst.afw.table.SourceCatalog)
        \return a pipeBase.Struct with fields:
        - refCat  reference object catalog of objects that overlap the exposure (with some margin)
            (an lsst::afw::table::SimpleCatalog)
        - matches  astrometric matches, a list of lsst.afw.table.ReferenceMatch
        - matchMeta  metadata about the field (an lsst.daf.base.PropertyList)

        The reference catalog actually used is up to the implementation
        of the solver; it will be manifested in the returned matches as
        a list of lsst.afw.table.ReferenceMatch objects (\em i.e. of lsst.afw.table.Match with
        \c first being of type lsst.afw.table.SimpleRecord and \c second type lsst.afw.table.SourceRecord ---
        the reference object and matched object respectively).

        \note
        The input sources have the centroid slot moved to a new column "centroid.distorted"
        which has the positions corrected for any known optical distortion;
        the 'solver' (which is instantiated in the 'astrometry' member)
        should therefore simply use the centroids provided by calling
        afw.table.Source.getCentroid() on the individual source records.  This column \em must
        be present in the sources table.

        \note ignores config.forceKnownWcs
        """
        results = self._astrometry(sourceCat=sourceCat, exposure=exposure)

        if results.matches:
            self.refitWcs(sourceCat=sourceCat, exposure=exposure, matches=results.matches)

        return results

Member Data Documentation

centroidErrKey

lsst.meas.extensions.astrometryNet.anetAstrometry.ANetAstrometryTask.centroidErrKey

Definition at line 170 of file anetAstrometry.py.

centroidFlagKey

lsst.meas.extensions.astrometryNet.anetAstrometry.ANetAstrometryTask.centroidFlagKey

Definition at line 167 of file anetAstrometry.py.

centroidKey

lsst.meas.extensions.astrometryNet.anetAstrometry.ANetAstrometryTask.centroidKey

Definition at line 169 of file anetAstrometry.py.

centroidXErrKey

lsst.meas.extensions.astrometryNet.anetAstrometry.ANetAstrometryTask.centroidXErrKey

Definition at line 163 of file anetAstrometry.py.

centroidXKey

lsst.meas.extensions.astrometryNet.anetAstrometry.ANetAstrometryTask.centroidXKey

Definition at line 159 of file anetAstrometry.py.

centroidYErrKey

lsst.meas.extensions.astrometryNet.anetAstrometry.ANetAstrometryTask.centroidYErrKey

Definition at line 165 of file anetAstrometry.py.

centroidYKey

lsst.meas.extensions.astrometryNet.anetAstrometry.ANetAstrometryTask.centroidYKey

Definition at line 161 of file anetAstrometry.py.

ConfigClass

lsst.meas.extensions.astrometryNet.anetAstrometry.ANetAstrometryTask.ConfigClass = ANetAstrometryConfig

static

Definition at line 142 of file anetAstrometry.py.

distortedName

lsst.meas.extensions.astrometryNet.anetAstrometry.ANetAstrometryTask.distortedName

Definition at line 158 of file anetAstrometry.py.

solver

lsst.meas.extensions.astrometryNet.anetAstrometry.ANetAstrometryTask.solver

Definition at line 172 of file anetAstrometry.py.

---

The documentation for this class was generated from the following file:

• /j/snowflake/release/lsstsw/stack/Linux64/meas_extensions_astrometryNet/18.1.0/python/lsst/meas/extensions/astrometryNet/anetAstrometry.py