auromat.draw module

This module provides various functions for visualizing mappings, astrometric solutions, and distortion profiles.

The return value is nearly always a tuple consisting of a matplotlib figure and axes object. This can then be further modified or saved as an image file with saveFig().

auromat.draw.drawAstrometryPixelScales(wcsHeaders, x=None, xlabel='Frame - 1st Frame', ylabel='Pixel scale (arcsec/px)', title='Celestial Sphere Pixel Scale ($\\sqrt{CD_{11}^2 + CD_{21}^2}$)', retscatter=False, **kw)[source]

Draws a scatter plot of the celestial pixel scales of the given astrometric solutions.

Parameters:
  • wcsHeaders – iterable of either WCS header objects or paths to .wcs files or astrometry-based mappings
  • x – values to use for the x axis; if not given, then x simply increase from 0 to len(wcsHeaders)
  • retscatter (bool) – whether to return the PathCollection of scatter points
Return type:

tuple(Figure,Axes[,PathCollection])
auromat.draw.drawAstrometryRotationAngles(wcsHeaders, x=None, xlabel='Time', ylabel='Rotation angle (deg)', title='Rotation Angle ($\\operatorname{atan}(CD_{21}, CD_{11})$)', retline=False, **kw)[source]

Draws a line plot of the celestial rotation angles of the given astrometric solutions.

Parameters:
  • wcsHeaders – iterable of either WCS header objects or paths to .wcs files or astrometry-based mappings
  • x – values to use for the x axis; if not given, then x will be the time axis
  • retline (bool) – whether to return the matplotlib Line object
  • kw – additional keywords are handed over to drawLinePlot()
Return type:

tuple(Figure,Axes[,Line])
auromat.draw.drawAzimuthPlotsCo(*args, **kwargs)[source]

Draws various plots based on the centroid of each mapping.

Parameters:
  • outputFileAzCentroid – azimuth (‘flying’ direction) of the centroids
  • outputFileAzCentroidFromCam – azimuth (‘flying’ direction) of the recalculated centroids (using camera footpoints)
  • outputFileLatLonCentroid – latitude-longitude plot of centroids
  • outputFileLatLonCentroidFromAz – latitude-longitude plot of recalculated centroids (using camera footpoints)
  • outputFileLatLonCamFoot – latitude-longitude plot of camera footpoints

See saveFig() for other parameters.

auromat.draw.drawCD11CD21(wcsHeaders, xlabel='$CD_{11}$', ylabel='$CD_{21}$', title='WCS Transformation Matrix Values', retline=False, **kw)[source]

Draws a line plot of the CD11 and CD21 values of the given astrometric solutions together with a reference circle derived from a fixed (median) celestial pixel scale.

Parameters:
  • wcsHeaders – iterable of either WCS header objects or paths to .wcs files or astrometry-based mappings
  • retline (bool) – whether to return the matplotlib Line object
  • kw – additional keywords are handed over to drawLinePlot()
Return type:

tuple(Figure,Axes[,Line])
auromat.draw.drawCameraFootpoints(mappings, xlabel='Longitude (deg)', ylabel='Latitude (deg)', title='Camera Footpoints', retline=False, **kw)[source]

Draws a line plot of the camera footpoints of the given mappings.

Parameters:
  • mapping – iterable of mappings
  • retline (bool) – whether to return the matplotlib Line object
  • kw – additional keywords are handed over to drawLinePlot()
Return type:

tuple(Figure,Axes[,Line])
auromat.draw.drawConstellations(figax, wcsPath, clipPoly=None, labels=True, lineStyles=('-', ':'), lineThickness=5, fontsize=70, colors=None, alpha=0.5, padding=10)[source]

Plot constellation patterns.

This does not provide extraordinarily high precision; it’s just a cosmetic display that sketches out the appropriate stick figures on the sky.

Based on IDL constellations.pro by Marshall Perrin. Constellation data is taken from Xephem, courtesy of Elwood Downey.

See auromat.coordinates.constellations module for licence text.

See:

https://github.com/mperrin/misc_astro/blob/master/constellations.py
Parameters:
  • figax – figimage, as produced by auromat.draw_helpers.loadFigImage()
  • wcsPath – path to FITS file containing WCS header
  • clipPoly – (n,2) x,y polygon points; restricts drawing to the region of the polygon
  • label – whether to draw labels
  • lineStyles – tuple(standard style, dotted style)
  • lineThickness –
  • colors (string|list|dict) –
    color of lines and labels, can be:
    • single color name
    • list of color names which will be cycled
    • mapping from constellation name to color name

    The default is a list of 9 colours.

  • alpha – alpha of lines and labels
  • padding – spacing at line ends in pixels
auromat.draw.drawCorrPlot(corrPaths, title='Distances between corresponding stars: $\\mu={:0.2f}$, $\\sigma={:0.2f}$')[source]

Draws a histogram of distances between corresponding stars from an astrometry.net .corr file.

Parameters:corrPaths – path to .corr file or list of paths (histograms are merged)
Return type:tuple(Figure,Axes)
auromat.draw.drawCorrSeqPlot(corrPaths, x=None, xlabel='Frame', retline=False)[source]

Draws the mean distance of corresponding stars from astrometry.net’s .corr files for each given file.

Parameters:
  • corrPaths – list of .corr paths
  • x – x axis values
Return type:

tuple(Figure,Axes[,Line])
auromat.draw.drawDate(figax, mapping, color='white')[source]

Writes the mapping date in the top center of the image.

Parameters:figax – figimage, as produced by draw_helpers.loadFigImage()
auromat.draw.drawDeclination(wcsHeaders, x=None, xlabel='Time', ylabel='Declination (deg)', title='Declination of Image Centers', retline=False, **kw)[source]

Draws a line plot of the declination values of the given astrometric solutions.

Note:

Assumes that CRPIX1,CRPIX2 are the image center.
Parameters:
  • wcsHeaders – iterable of either WCS header objects or paths to .wcs files or astrometry-based mappings
  • x – values to use for the x axis; if not given, then x will be the time axis
  • retline (bool) – whether to return the matplotlib Line object
  • kw – additional keywords are handed over to drawLinePlot()
Return type:

tuple(Figure,Axes[,Line])
auromat.draw.drawHeatmap(data, cbLabel=None, xlabel=None, ylabel=None, figax=None, alpha=1.0)[source]

Draws a 2d-data array as blue-red heatmap.

Parameters:
  • data – 2D array, can contains NaN’s and/or be a masked numpy array
  • cbLabel – data label, written alongside the colorbar
  • figax – a (Figure,Axes) tuple to reuse
  • alpha – alpha value of the drawn heatmap
Return type:

tuple(Figure,Axes)
auromat.draw.drawHeatmaps(mapping, pathPrefix='heat_', xlabel='Image Width (px)', ylabel='Image Height (px)', bgcolor='white', widthPx=None, dpi=None)[source]

Draws latitude, longitude, elevation, azimuth (if available, e.g. MIRACLE mappings) as blue-red heatmaps for the given mapping.

The resulting filenames are:

  • <pathPrefix>lats.png
  • <pathPrefix>lons.png
  • <pathPrefix>elevation.png
  • <pathPrefix>azimuth.png
Parameters:
  • pathPrefix (str) – path prefix for the images that are created
  • bgcolor – plot background color (matplotlib color spec)
  • widthPx – width in pixels of the saved images
  • dpi – dpi of the saved images
auromat.draw.drawHistogram(hist, vlines=[], xlabel=None, ylabel=None, **kw)[source]

Draws a histogram in line-style with unspecified bin boundaries.

Parameters:
  • hist – a one-dimensional array of histogram y-values
  • vlines – a list of (value,color) tuples describing vertical lines to draw
  • xlabel (str) – label of x axis
  • ylabel (str) – label of y axis
Return type:

tuple(Figure,Axes)
auromat.draw.drawHorizon(astrometryMapping, color='blue', channel=None, lineThickness=2, useMappingAltitude=False, figax=None)[source]

Draws the earth horizon of an unresampled astrometry-based mapping on top of the underlying image of the mapping.

Parameters:
  • astrometryMapping (auromat.mapping.astrometry.BaseAstrometryMapping) – the unresampled mapping
  • color – earth horizon line color (matplotlib color spec)
  • channel (str) – if given (r|g|b) then draw only the given channel of the image
  • lineThickness – line width
  • figax – a (Figure,Axes) tuple which shall be used instead of creating a new one; if given, then the mapping image is not drawn
Return type:

tuple(Figure,Axes)
auromat.draw.drawIndxPlot(imagePath, axyPath=None, xylsPath=None, matchPath=None, wcsPath=None, newWcsPathOrHeader=None, maxAxyObjects=40, mask=None, useWebCatalog=False, webCatalogLimit=1000, xylsSources=None, scale=5, figax=None)[source]

Draws reference and/or image-extracted stars from astrometry.net’s .axy and .xyls files, or for reference stars as well using the Vizier webservice with the Tycho-2 catalogue.

The matching star quad as found by astrometry.net and stored in .match files can also be visualized.

Parameters:
  • imagePath (str|array) – the image to use as background, either a path or an RGB/grayscale image array of uint8/uint16 type
  • axyPath (str) – path to .axy file containing extracted stars
  • xylsPath (str) – path to .xyls file containing reference stars
  • matchPath (str) – path to .match file containing the matched quad (see astrometry.net docs)
  • newWcsPathOrHeader (wcsPath,) – if given together with xlysPath, then the xyls pixel positions are recalculated
  • useWebCatalog – if True and wcsPath is given, then astroquery is used to obtain reference stars
  • webCatalogLimit – the maximum number of stars to fetch from the web catalog
  • scale (float) – the size of the circles drawn around stars
  • maxAxyObjects (int) – the maximum number of extracted stars to draw
  • xylsSources (array-like) – an x,y pixel coordinate array to use as reference stars
  • figax – an existing (Figure,Axes) tuple to use; if given, the background image is not drawn; see auromat.draw_helpers.loadFigImage()
  • mask – boolean array of the size of the image, True=don’t draw stars here
Return type:

tuple(Figure,Axes)
auromat.draw.drawKmlImage(mapping)[source]

Draws a mapping onto a figure without borders for use within Google Earth. The extents are identical to the bounding box of the mapping.

Note: When saving, make sure to use transparent=True to make the areas outside the valid data transparent.

Return type:tuple(Figure, Axes)
auromat.draw.drawLensDistortionDerivativePlot(mod)[source]

Draws the lens distortion derivative. This visualizes barrel and pincushion distortion over the sensor radius.

Parameters:mod (lensfunpy.Modifier) – the Modifier object
Return type:tuple(Figure,Axes)
auromat.draw.drawLensDistortionDisplacementPlot(mod)[source]

Draws the displacement in pixels caused by lens distortion as a 2D heatmap.

Parameters:mod (lensfunpy.Modifier) – the Modifier object
Return type:tuple(Figure,Axes)
auromat.draw.drawLinePlot(x, y, xlabel, ylabel, title=None, linecolor=None, linewidth=None, retline=False, **kw)[source]

Draws a line plot.

Parameters:
  • x (array-like) – x values, can be datetime
  • y (array-like) – y values
  • xlabel (str) – label of x axis
  • ylabel (str) – label of y axis
  • title (str) – plot title
  • linecolor – line color (matplotlib color spec)
  • linewidth – line width
  • retline (bool) – if True, then the Line object is returned as last tuple element
  • kw – additional keywords are handed over to matplotlib’s ax.plot function
Return type:

tuple (Figure,Axes[,Line])
auromat.draw.drawMLatMLTPolar(mappings, lineDelta=10, boundingBox=None, figWidth=8.0, figHeight=5.0, rasterized=True)[source]

Draws one or more mappings in the MLat/MLT coordinate system with polar azimuthal equidistant projection.

Parameters:
  • mappings – either a single BaseMapping, a MappingCollection, or a list of both types
  • lineDelta (int) – draw a parallel/meridian every lineDelta degrees
  • boundingBox (BoundingBox) – determines the latitude range from this bounding box
  • figWidth (number) – figure width in inches
  • figHeight (number) – figure height in inches
  • rasterized (bool) – whether to rasterize the polygon mesh when saved as SVG
Return type:

tuple(Figure, Axes, Basemap)
auromat.draw.drawParallelsAndMeridians(mapping, boundingBox=None, labelLon=None, labelLat=None, lineThickness=5, color='white', alpha=0.5, figax=None)[source]

Draws parallels and meridians on top of an unresampled mapping.

Parameters:
  • mapping (auromat.mapping.mapping.BaseMapping) – the unresampled mapping
  • boundingBox – the bounding box for which to draw parallels/meridians (optional)
  • labelLon – the longitude along which the latitude labels are drawn (optional)
  • labelLat – the latitude along which the longitude labels are drawn (optional)
  • lineThickness – line width
  • color – color of the parallels and meridians (matplotlib color spec)
  • alpha – alpha value of the parallels and meridians
  • figax – figimage, as produced by auromat.draw_helpers.loadFigImage()
auromat.draw.drawPlot(mapping)[source]

Draws a single mapping onto a Longitude/Latitude plot equivalent to a rectilinear map projection.

Return type:tuple(Figure, Axes)
auromat.draw.drawRaDec(wcsHeaders, xlabel='Right ascension (deg)', ylabel='Declination (deg)', title='Equatorial Coordinates of Image Centers', retline=False, **kw)[source]

Draws a line plot of the right ascension and declination values of the given astrometric solutions.

Note:

Assumes that CRPIX1,CRPIX2 are the image center.
Parameters:
  • wcsHeaders – iterable of either WCS header objects or paths to .wcs files or astrometry-based mappings
  • retline (bool) – whether to return the matplotlib Line object
  • kw – additional keywords are handed over to drawLinePlot()
Return type:

tuple(Figure,Axes[,Line])
auromat.draw.drawReferenceStars(mapping, **kw)[source]

Draws reference stars on top of the original image of an unresampled astrometry-based mapping by using the Tycho-2 catalogue of the Vizier web service.

Parameters:mapping (auromat.mapping.astrometry.BaseAstrometryMapping) – the mapping
Return type:tuple(Figure,Axes)

For other parameters, see drawIndxPlot().

auromat.draw.drawRightAscension(wcsHeaders, x=None, xlabel='Time', ylabel='Right ascension (deg)', title='Right Ascension of Image Centers', retline=False, **kw)[source]

Draws a line plot of the right ascension values of the given astrometric solutions.

Note:

Assumes that CRPIX1,CRPIX2 are the image center.
Parameters:
  • wcsHeaders – iterable of either WCS header objects or paths to .wcs files or astrometry-based mappings
  • x – values to use for the x axis; if not given, then x will be the time axis
  • retline (bool) – whether to return the matplotlib Line object
  • kw – additional keywords are handed over to drawLinePlot()
Return type:

tuple(Figure,Axes[,Line])
auromat.draw.drawScanLinesCo(*args, **kwargs)[source]

Draws a scanline from each given mapping such that the resulting stereographic map gives a temporal and spatial varying overview of all mappings. Scanlines are spherical rectangles perpendicular to the ‘flying’ direction of the mapping centroids when seen on a map.

Note that the centroid of each mapping becomes the center of each corresponding scanline, therefore the sequence should be masked by elevation before-hand with a sensible value.

The input to this coroutine can either be a sequence of unresampled mappings or a dictionary containing mapping.properties in the ‘props’ key and the masked and resampled mapping in the ‘mapping’ key. In the latter case, the arcsecPerPx parameter is ignored.

Example:

>>> from auromat.util.coroutine import broadcast
>>> seq = ...retrieve mapping sequence
>>> broadcast(seq, drawScanLinesCo('test.png'))
Parameters:
  • arcsecPerPx (number) – spherical resolution used for resampling
  • lineWidthFactor (number) – how much to widen the scanline width relative to the the computed width derived from the first and second mapping; useful if mappings in-between the sequence are missing

For all other parameters, see saveFig() and drawStereographic().

auromat.draw.drawScanLinesMLatMLTCo(*args, **kwargs)[source]

As drawScanLinesCo() but with MLat/MLT as coordinate system.

auromat.draw.drawStereographic(mappings, lat0=None, lon0=None, width=None, height=None, boundingBox=None, sizeFactor=1, lineDelta=10, labelsParallels=[True, False, False, False], labelsMeridians=[False, False, False, True], fmtParallels=None, fmtMeridians=None, bottomTitle=None, drawlsmask=True, drawCities=False, cityAlpha=0.6, figWidth=8.0, figHeight=5.0, rasterized=True)[source]

Draws one or more mappings onto a stereographic map.

Note that when drawing multiple mappings, the resulting bounding box should span less than 180 degrees in longitude.

Parameters:
  • mappings – either a single BaseMapping, a MappingCollection, or a list of both types
  • lat0 (degree|None) – latitude of image center
  • lon0 (degree|None) – longitude of image center
  • width (number|None) – width of map in km
  • height (number|None) – height of map in km
  • boundingBox (BoundingBox) – determine lat0,lon0,width,heigth from this bounding box
  • sizeFactor (number) – how much to zoom out, 1 = everything just fits on the map
  • lineDelta (int) – draw a parallel/meridian every lineDelta degrees
  • labelsParallels – a boolean list [left,right,top,bottom] that determines on which sides to draw labels for parallels
  • labelsMeridians – a boolean list [left,right,top,bottom] that determines on which sides to draw labels for meridians
  • fmtParallels (str|function) – format string or function for parallel labels
  • fmtMeridians (str|function) – format string or function for meridian labels
  • bottomTitle (str) – adds a title below the figure
  • drawlsmask (bool) – whether to draw land-sea mask
  • drawCities (bool) – whether to draw city markers
  • cityAlpha (number) – the alpha value with which to draw the city markers
  • figWidth (number) – figure width in inches
  • figHeight (number) – figure height in inches
  • rasterized (bool) – whether to rasterize the polygon mesh when saved as SVG
Return type:

tuple(Figure, Axes, Basemap)
auromat.draw.drawStereographicMLatMLT(mappings, *args, **kwargs)[source]

Draws one or more mappings in the MLat/MLT coordinate system with stereographic projection.

See drawStereographic() for parameter descriptions.

Return type:tuple(Figure, Axes, Basemap)
auromat.draw.getFixedConstellationColors(colors=None)[source]

Tries to determine a color for each constellation such that neighboring constellations have different colors.

Parameters:colors – set of base colors to use (optional)
Returns:a mapping from constellation names to color strings
Return type:dict
auromat.draw.saveFig(outputFile, figax, bgcolor='white', transparent=False, widthPx=None, heightPx=None, dpi=None, format_=None, dontClose=False)[source]

Saves a matplotlib Figure to a path on disk or a File-like object.

Note:

Only one of widthPx, heightPx, and dpi must be defined. If none is given, then default values from matplotlib are used.
Parameters:
  • outputFile – path to file, or File-like object
  • figax – Figure object, or array-like with Figure,`Axes` as first two elements
  • bgcolor (str) – background color of the plot, ‘white’ or ‘black’
  • transparent (bool) – whether the background outside the plot bounds should be transparent
  • widthPx (int) – width in pixels
  • heightPx (int) – height in pixels
  • dpi (number) – dpi in inches
  • format (str) – file format, e.g. ‘jpg’, ‘png’, ‘svg’; will be derived from extension if outputFile is a path name
  • dontClose (bool) – whether to close the Figure or leave it open for further processing; default is to close it; use plt.close(fig) for manual closing
auromat.draw.setColors(figax, bgcolor='white', transparent=False)[source]

Changes colors of all plot elements to a given color scheme.

Parameters:
  • figax – Figure object, or array-like with Figure,`Axes` as first two elements
  • bgcolor (str) – background color of the plot, ‘white’ or ‘black’
  • transparent (bool) – whether the background outside the plot bounds should be transparent