User guide#
The user guide explains skyplothelper subsystem by subsystem. Each page describes what that part of the package does, how it relates to the rest, short examples of the common operations, and the caveats worth knowing — a searchable reference for what exists and how it fits together. For extended, end-to-end worked examples, see the tutorials.
If you’re new, start with the quickstart. If the
astropy/matplotlib substrate is also new — SkyCoord, WCSAxes, the
transform= keyword — read Foundations: SkyCoord, WCS & matplotlib transforms first; then Core concepts & conventions,
which covers the conventions (longitude direction, coordinate frames, units)
that every other page builds on.
- Quickstart
- Foundations: SkyCoord, WCS & matplotlib transforms
- Core concepts & conventions
- Frames & projections
- Ticks, grids & labels
- Overlays & annotations
- Regions & spherical geometry
- Images & FITS
- HEALPix
- Globe & planet plots
- Cone frames
- Catalogs & queries
- Vectors & sky kinematics
- Multi-channel legends
- Styling & themes
- Interactive plots (plotly)
- Writing a custom overlay
Orientation#
Foundations. Foundations: SkyCoord, WCS & matplotlib transforms is a crash course in the astropy +
matplotlib layer sph sits on — units, SkyCoord, matplotlib’s transform=,
and astropy’s WCS/WCSAxes — for readers new to sky/WCS-aware plotting.
Core concepts & conventions then explains the package-wide model: every plot starts from a
frame (a WCSAxes wired to a sky projection), everything else draws onto
frames through one shared projection pipeline, and a handful of conventions
(astro east-left longitude, ICRS default, auto tick units) apply everywhere.
Frames & projections covers building those frames across ~30 projections.
Dressing the frame. Ticks, grids & labels (tick formats, grids, second coordinate overlays), Overlays & annotations (beams, rulers, reticles, compasses, scale bars, coordinate planes, survey footprints, constellations), and Styling & themes (themes, palettes, publication presets) control how a plot reads.
Putting data on the sky. Images & FITS (stretching, quicklook, and reprojection of FITS and RGB images), HEALPix (binning catalogs and rendering HEALPix maps), Regions & spherical geometry (geodesic circles, bands, polygons, and set-algebraic compound regions), and Vectors & sky kinematics (proper motions, displacement fields, vector spherical harmonics, station co-visibility). Multi-channel legends builds compact multi-channel keys — one block per encoded dimension — for the busy maps those tools produce.
Specialized frames. Globe & planet plots (orthographic globe views of the sky and of solid bodies — including tilted-Earth orientation — with surface features, nightshade, and inset axes) and Cone frames (cosmology z-RA wedge diagrams, single or double-sided).
Beyond matplotlib. Catalogs & queries (name resolution, SIMBAD/NED/VizieR, sky-survey image downloads) and Interactive plots (plotly) (the interactive web-export backend and Dash FITS viewer).
Extending it. Writing a custom overlay is the contract for writing your own overlay — the three primitives (frame, projection, theme color) the bundled decorations use, on both backends — so an extension behaves like a built-in.