Blog - Posts in Tutorial

Artemis II Solar Eclipse

2026-04-09T00:00:00+00:00

The Artemis II mission recently completed its landmark voyage around the Moon, marking the first departure of humans from Earth orbit in over fifty years. Soon after Artemis II set the record of human distance from Earth, the astronauts took stunning photos of the the solar eclipse they observed on April 6 (EDT) / April 7 (UTC). We highly recommend watching the recording of the eclipse on YouTube; the reactions and descriptions of the astronauts are worth it.

Image credit NASA

On the SunPy blog, we rarely miss the opportunity to talk about a solar eclipse. So when we saw the eclipse photos taken by the astronauts, we immediately wanted to use SunPy to compare them to other images of the solar corona. Here is one of the amazing photos that has been shared:

Image credit NASA

This photo is particularly well suited to comparison with other solar observations because the limb of the Moon is clearly visible, and there are stars and planets in the image we can use as references. Understanding the coordinate system of the photo will allow us to overlay images taken by solar observatories.

The following images in this post, and the code to generate them, are from these two examples in the SunPy gallery:

Visualize the path of Artemis II

We can use JPL Horizons to obtain the trajectory of Artemis II and to confirm the time range of the solar eclipse. The sunpy/astropy coordinates framework enables visualizing the trajectory in any desired coordinate frame, and our example shows it in the frame co-rotating with the Moon’s orbit around the Earth.

Visualization of the Artemis II trajectory with the eclipse highlighted.

Also in our example, we confirm that the total eclipse started around 00:34 UTC and ended around 01:29 UTC.

Determine the coordinate system of the photo

To be able to compare this image with other observations of the Sun, we need to identify where the camera was pointed and how it was oriented. To do this we perform the following steps:

Extract the time information from the metadata stored in the image.
Use the time information to look up the exact position of Artemis II.
Fit the edge of the Moon to identify the center of the Moon, and the size of the Moon in the image.
Use the three planets visible in the lower right of the image to determine the rotation angle.
Use the planets to fit the distortion of the lens.

The following is an abridged version of the code in our example.

Find the position of Artemis II

The first step is to know the time the image is taken; we can extract this from the EXIF metadata. As with the trajectory above, we use JPL Horizons to obtain the position of Artemis II at a specific time.

from sunpy.coordinates import get_horizons_coord

artemis2_coord = get_horizons_coord("Artemis II" , "2026-04-07 01:06:19")

Locate the Moon

The next step is to use a known location in the image as a reference point. The easiest one for us to use is the center of the Moon, which we find by doing edge detection and Hough filtering, using scikit-image.

import numpy as np

from skimage.feature import canny, peak_local_max
from skimage.transform import hough_circle, hough_circle_peaks

edges = canny(eclipse_image, sigma=2)

h, w = eclipse_image.shape
radii = np.arange(0.25*h, 0.4*h, 10)

hough_res = hough_circle(edges, radii)
accums, cx, cy, rad = hough_circle_peaks(hough_res, radii, total_num_peaks=1)

A cropped view of the Moon, showing the results of the canny edge detection algorithm and the Hough filter.

Calculate the image scale

Based on the determined center of the Moon and its radius in the image we can construct an initial coordinate system for the image.

from astropy.coordinates import SkyCoord
import astropy.units as u

moon = SkyCoord(coords["moon"], observer=coords["artemis_ii"])
R_moon = 0.2725076 *  u.R_earth  # IAU mean radius
dist_moon = SkyCoord(coords["artemis_ii"]).separation_3d(moon)

moon_angular_width = np.arcsin(R_moon / dist_moon).to(u.arcsec)
im_radius = rad * u.pix
plate_scale = moon_angular_width / im_radius

We can now construct a sunpy Map using this information and overplot the anticipated location of the planets:

Initial coordinate system fit to image, notice that the locations of the highlighted planets are incorrect.

Determine the camera orientation

It’s clear from the previous image that we still need to correct for the camera orientation. Having the camera at a specific orientation is tricky even when using a tripod on the Earth’s surface, and we imagine is even trickier when flying through space! Fortunately, the planets serve as excellent reference points.

We determine the camera orientation by using a peak finding algorithm to locate the planets in the image and comparing these positions to the planets coordinates extracted from JPL Horizons. Doing this gives a \(-21.2^\circ\) roll angle which we can add to our Map metadata.

Image showing the expected positions of the planets and the detected (peaks) positions of the planets, from which the roll angle is calculated.

Account for lens distortion

The final correction to apply to our fitted coordinate system is the distortion of the camera lens (a Nikkor AF 135mm f/2D DC). This makes objects distant from the center of the image appear even more distant than they should. We can quantify exactly how much the image has been distorted by comparing the expected versus actual positions of Mars and Mercury (not Saturn as it is too close to the center of the image). We add this distortion to our coordinate system and our planets now appear in the correct place.

Coordinate system fit with additional correction for lens distortion.

Overplotting Coronagraph Images

Now that we have established the coordinate system for the eclipse photo, we can compare this observation of the corona to other data. To do this we are going to use the coronagraph (the LASCO instrument) on the Solar and Heliospheric Observatory (SOHO) which is located around the Sun-Earth L1 point. We reproject (or re-grid) these images to the fitted coordinate system of the Artemis II image to compensate for differences in satellite location and point of view, and then crop them to the limb of the moon.

The Artemis II solar eclipse photo with the positions of Mercury, Mars and Saturn highlighted, and coronagraph images from SOHO’s LASCO instrument plotted over the disc of the Moon.

The coronal structure visible in the LASCO image is not visible in the Artemis II eclipse photo, but the former has undergone significant image processing, and the latter is mostly straight out of the camera. A more scientific comparison may be possible when additional imagery from Artemis II is released in the future.

Closing thoughts

We think this post is a striking demonstration of what sunpy makes possible. By combining image metadata, spacecraft ephemerides, and coordinate-aware reprojection, we can place the astronauts’ eclipse photo and SOHO/LASCO coronagraph data into the same physical frame and compare views of the same corona from two very different vantage points. As a reminder, you can find the full code behind this post in these two examples in the SunPy gallery: Artemis II trajectory and Artemis-II Solar Eclipse.

If you are lucky enough to observe the total solar eclipse which will be visible from parts of Europe on August 12, 2026, remember you can try this type of analysis with your own photos by following our previous blog post!

Process Your Solar Eclipse Photos with SunPy!

2024-04-03T00:00:00+00:00

This blog post was written in a Jupyter notebook. Click here for an interactive version:

On April 8th, 2024, a total solar eclipse will pass over North America. A total solar eclipse happens when the Moon passes between the Sun and Earth, completely blocking the face of the Sun. Only during totality, when the bright disk is completely obscured, is it possible to see with the naked eye the solar corona, the outermost layer of the Sun’s atmosphere. The total solar eclipse will give millions across North America the chance to see and photograph the solar corona.

In this blog post, we will show how you can use SunPy to process your photos of the eclipse. To do this, we will use an image from the 2017 solar eclipse that also passed over North America, the so-called “Great American Eclipse”. We will walk through processing this image with SunPy as well as other Python libraries, so that you can generate a coordinate system for your image. As we will show, this allows you to combine your eclipse images with solar observations such as those from NASA’s Solar Dynamics Observatory.

[1]:

from pathlib import Path

import astropy.units as u
import exifread
import matplotlib.image
import matplotlib.pyplot as plt
import numpy as np
import sunpy.coordinates
import sunpy.coordinates.sun
from astropy.constants import R_earth
from astropy.coordinates import CartesianRepresentation, EarthLocation, SkyCoord

# We have defined a few helper functions in this `eclipse_helpers.py` file.
from eclipse_helpers import SOLAR_ECLIPSE_IMAGE, get_camera_metadata
from matplotlib.patches import Circle
from scipy import ndimage
from skimage.color import rgb2gray
from skimage.feature import peak_local_max
from skimage.transform import hough_circle, hough_circle_peaks
from sunpy.map.header_helper import make_fitswcs_header
from sunpy.net import Fido
from sunpy.net import attrs as a
from sunpy.time import parse_time

Read in Your Eclipse Photo

The first step is to read in our image. As mentioned above, we will be using an image taken during the 2017 eclipse taken with a consumer-grade camera. When reading in our image data, we’ll invert the y-axis and convert it to a grayscale image.

[2]:

im_rgb = np.flipud(matplotlib.image.imread(SOLAR_ECLIPSE_IMAGE))
im = rgb2gray(im_rgb)

/Users/nabil/micromamba/envs/sunpy-dev/lib/python3.13/site-packages/skimage/color/colorconv.py:984: RuntimeWarning: divide by zero encountered in matmul
  return rgb @ coeffs
/Users/nabil/micromamba/envs/sunpy-dev/lib/python3.13/site-packages/skimage/color/colorconv.py:984: RuntimeWarning: overflow encountered in matmul
  return rgb @ coeffs
/Users/nabil/micromamba/envs/sunpy-dev/lib/python3.13/site-packages/skimage/color/colorconv.py:984: RuntimeWarning: invalid value encountered in matmul
  return rgb @ coeffs

[3]:

plt.imshow(im, origin="lower", cmap="gray")
plt.show()

In order to be able to align our image with solar images from NASA, we will also need some additional metadata from our image. The two most important things we need to know are:

the GPS coordinates of where the photo was taken and
the time the image was taken

We can pull this metadata from the file and then use an additional function we wrote to process this metadata into a Python dictionary.

[4]:

with Path(SOLAR_ECLIPSE_IMAGE).open("rb") as f:
    tags = exifread.process_file(f)

[5]:

camera_metadata = get_camera_metadata(tags)

As it turns out, the time on the camera used to take this eclipse photo was wrong, we have to manually correct it.

[6]:

camera_metadata["time"] = parse_time("2017-08-21 17:27:13")

Find the Moon

Now that we’ve loaded our image and accompanying metadata, the next step is to locate the edge of the Moon in our image. This allows us to find the center of the Moon, which is needed when aligning our data, as well as allowing us to determine the scale of the Moon in the image. In order to do this we are going to use several different image manipulation techniques.

We start with applying a Gaussian blur to help segment the lunar disk from the corona and mask all parts of the image above a given threshold.

[7]:

blur_im = ndimage.gaussian_filter(im, 8)
mask = blur_im > blur_im.mean() * 3
plt.imshow(mask)
plt.show()

We then label those masked regions and select only the parts of the image that correspond to the bright, diffuse corona.

[8]:

label_im, nb_labels = ndimage.label(mask)
slice_y, slice_x = ndimage.find_objects(label_im == 1)[0]
roi = blur_im[slice_y, slice_x]

The next step is to detect the inner edge of the bright corona. To do this, we apply a Sobel filter in both the x and y directions, and then calculate a single image from the two directions.

[9]:

sx = ndimage.sobel(roi, axis=1, mode="constant")
sy = ndimage.sobel(roi, axis=0, mode="constant")
sob = np.hypot(sx, sy)

Finally, we use scikit-image to apply the Hough Transform to identify circles in the image. We then use this to extract the size in pixels of the lunar disk and its center.

[10]:

hough_radii = np.arange(np.floor(np.mean(sob.shape) / 4), np.ceil(np.mean(sob.shape) / 2), 10)
hough_res = hough_circle(sob > (sob.mean() * 5), hough_radii)

# Select the most prominent circle
accums, cx, cy, radii = hough_circle_peaks(hough_res, hough_radii, total_num_peaks=1)

As shown below, we now have a list of pixel coordinates corresponding to the solar limb in our image. The first frame is the cropped original image. The middle frame is the Sobel filtered image used to apply the Hough transform. The right frame is the fitted circle on the original image.

[11]:

fig, ax = plt.subplots(ncols=3, nrows=1, figsize=(9.5, 6))
ax[0].imshow(im[slice_y, slice_x])
ax[0].set_title("Original")
ax[1].imshow(sob > (sob.mean() * 5))
ax[1].set_title("Sobel")
circ = Circle(
    [cx, cy], radius=radii, facecolor="none", edgecolor="red", linewidth=2, linestyle="dashed", label="Hough fit"
)
ax[2].imshow(im[slice_y, slice_x])
ax[2].add_patch(circ)
ax[2].set_title("Original with fit")
plt.legend()
plt.show()

Lastly, let’s add units to our circle that we fit the lunar limb.

[12]:

im_cx = (cx[0] + slice_x.start) * u.pix
im_cy = (cy[0] + slice_y.start) * u.pix
im_radius = radii[0] * u.pix

Make a SunPy `Map`

At this point, we have our image data, it’s metadata and we’ve located the Moon. Now we are ready to load our eclipse photograph into a SunPy Map! A Map allows us to carry around both the data and metadata of our image together and, importantly, makes it easy to combine solar observations from multiple observatories.

First, we define the observer location (i.e., where on Earth did we take our picture?) and the orientation of the Sun in the sky. For the observer location, we can use the GPS coordinates from our image metadata.

[13]:

loc = EarthLocation(lat=camera_metadata["gps"][0], lon=camera_metadata["gps"][1], height=camera_metadata["gps"][2])
observer = loc.get_itrs(camera_metadata["time"])

Second, we determine the angular size of the Moon using its radius and its distance from the observer.

[14]:

moon = SkyCoord(sunpy.coordinates.get_body_heliographic_stonyhurst("moon", camera_metadata["time"], observer=observer))
R_moon = 0.2725076 * R_earth  # IAU mean radius
dist_moon = SkyCoord(observer).separation_3d(moon)
moon_obs = np.arcsin(R_moon / dist_moon).to("arcsec")
print(moon_obs)

2025-06-23 09:08:55 - sunpy - INFO: Apparent body location accounts for 1.23 seconds of light travel time

INFO: Apparent body location accounts for 1.23 seconds of light travel time [sunpy.coordinates.ephemeris]
975.9073137731282 arcsec

Combining this angular radius with the radius of the lunar disk in pixels gives us the angular size of the pixels in the image. In the parlance of astronomical imaging, this is often referred to as the plate scale.

[15]:

plate_scale = moon_obs / im_radius
print(plate_scale)

4.356729079344322 arcsec / pix

We also use the observer location to calculate the orientation of the Sun as seen from that location on Earth. This gives us a rotation angle between our image coordinate system and the solar north pole. If your camera is not perfectly horizontal then you may need to fudge this value slightly.

[16]:

solar_rotation_angle = sunpy.coordinates.sun.orientation(loc, camera_metadata["time"])
print(solar_rotation_angle)

-54d19m44.13467961s

Finally we have all the information we need to build a sunpy Map for our eclipse image.

[17]:

frame = sunpy.coordinates.Helioprojective(observer=observer, obstime=camera_metadata["time"])
moon_hpc = moon.transform_to(frame)

header = make_fitswcs_header(
    im,
    moon_hpc,
    reference_pixel=u.Quantity([im_cx, im_cy]),
    scale=u.Quantity([plate_scale, plate_scale]),
    rotation_angle=solar_rotation_angle,
    exposure=camera_metadata.get("exposure_time"),
    instrument=camera_metadata.get("camera_model"),
    observatory=camera_metadata.get("author"),
)

[18]:

eclipse_map = sunpy.map.Map(im, header)

[19]:

fig = plt.figure(figsize=(9, 9))
ax = plt.subplot(projection=eclipse_map)
eclipse_map.plot(axes=ax)
plt.show()

Find a Star

Though we already have all of the metadata we need to make a SunPy Map, we can further improve the accuracy by locating a known star in the image and using that to determine the rotation angle. In the case of the 2017 eclipse the very bright star (magnitude 1.4) Regulus was close to the Sun and in the field of view of our photograph. For the 2024 eclipse, no such bright star will be visible, which may make this method of aligning your image challenging. The best candidate looks to be Alpha Piscium which is a binary system with a combined magnitude of 3.82, significantly dimmer than Regulus. You can see the stars close to the Sun by using Stellarium.

As Regulus is a well known star, we can create a coordinate object for it, including its distance.

[20]:

regulus = SkyCoord(ra="10h08m22.311s", dec="11d58m01.95s", distance=79.3 * u.lightyear, frame="icrs")
print(regulus)

<SkyCoord (ICRS): (ra, dec, distance) in (deg, deg, lyr)
    (152.0929625, 11.96720833, 79.3)>

We can then plot the expected location of Regulus on our eclipse image. We set the scaling such that it make Regulus more visible and zoom in on the relevant part of the field of view. You can see that the expected location and the actual location are quite different.

[21]:

fig = plt.figure(figsize=(9, 9))
ax = plt.subplot(projection=eclipse_map)
eclipse_map.plot(axes=ax, clip_interval=(0, 90) * u.percent)
ax.plot_coord(
    regulus, "o", markeredgewidth=0.5, markeredgecolor="w", markerfacecolor="None", markersize=10, label="Regulus"
)
plt.legend()
plt.xlim(100, 500)
plt.ylim(0, 500)
plt.show()

Given this offset, we want to fix our image metadata such that the actual and expected locations of Regulus are line up. We can calculate the expected distance from the center of the Sun to Regulus in pixels.

[22]:

regulus_pixel = CartesianRepresentation(*eclipse_map.wcs.world_to_pixel(regulus), 0) * u.pix
sun_pixel = (
    CartesianRepresentation(*eclipse_map.wcs.world_to_pixel(SkyCoord(0 * u.arcsec, 0 * u.arcsec, frame=frame)), 0)
    * u.pix
)
regulus_r = (regulus_pixel - sun_pixel).norm()
print(regulus_r)

1084.0811009031981 pix

We then use this to find Regulus in our image, by filtering out all pixels which are closer to the Sun than this.

[23]:

pix_x = np.arange(eclipse_map.dimensions[0].value) * u.pix - sun_pixel.x
pix_y = np.arange(eclipse_map.dimensions[1].value) * u.pix - sun_pixel.y
xx, yy = np.meshgrid(pix_x, pix_y)
r = np.sqrt(xx**2 + yy**2)

filter_r = regulus_r - (regulus_r / 5)

masked = im.copy()
masked[r < filter_r] = masked.min()

Having masked out most of the Sun and its corona, we now find the highest peak remaining, which should be Regulus.

[24]:

regulus_y, regulus_x = peak_local_max(masked, min_distance=2, num_peaks=1)[0]
actual_regulus_pixel = CartesianRepresentation(regulus_x, regulus_y, 0) * u.pix

We can now compare the identified pixel coordinates of Regulus to the expected coordinates assuming the camera was exactly horizontal.

[25]:

print(actual_regulus_pixel)
print(regulus_pixel)

(372., 247., 0.) pix
(339.45349652, 307.65804366, 0.) pix

Finally, we calculate the angular offset between our expected location and our identified location and then add this difference to correct our solar rotation angle.

[26]:

vec_expected = regulus_pixel - sun_pixel
vec_actual = actual_regulus_pixel - sun_pixel
fudge_angle = -np.arccos(vec_expected.dot(vec_actual) / (vec_expected.norm() * vec_actual.norm()))
print(fudge_angle.to(u.deg))

-3.5738144694153595 deg

We then use this correction factor to build a new Map for our image with updated metadata.

[27]:

header = make_fitswcs_header(
    im,
    moon_hpc,
    reference_pixel=u.Quantity([im_cx, im_cy]),
    scale=u.Quantity([plate_scale, plate_scale]),
    rotation_angle=solar_rotation_angle + fudge_angle,
    exposure=camera_metadata["exposure_time"],
    instrument=camera_metadata["camera_model"],
)

[28]:

eclipse_map = sunpy.map.Map(im, header)

Plotting our image again, we now find that the identified location of Regulus and our image line up much better.

[29]:

fig = plt.figure(figsize=(9, 9))
ax = plt.subplot(projection=eclipse_map)
eclipse_map.plot(axes=ax, clip_interval=(0, 90) * u.percent)
ax.plot_coord(
    regulus, "o", markeredgewidth=0.5, markeredgecolor="w", markerfacecolor="None", markersize=10, label="Regulus"
)
plt.legend()
plt.xlim(100, 500)
plt.ylim(0, 500)
plt.show()

Combine your Image with NASA Data

As mentioned above, one of the main advantages of having data in a Map is that it is then easy to combine observations from multiple different sources. Let’s overlay an AIA image from the SDO satellite. We’ll choose an image that shows extreme ultraviolet emission from the corona, revealing plasma that is around one million degrees. Fortunately, all SDO data is publicly available and SunPy provides a convenient interface for searching for and downloading this data.

[30]:

aia_result = Fido.search(
    a.Time("2017-08-21 17:27:00", "2017-08-21 17:45:00", eclipse_map.date),
    a.Instrument("AIA"),
    a.Wavelength(171 * u.Angstrom),
)
print(aia_result)

Results from 1 Provider:

1 Results from the VSOClient:
Source: https://sdac.virtualsolar.org/cgi/search
Data retrieval status: https://docs.virtualsolar.org/wiki/VSOHealthReport
Total estimated size: 67.789 Mbyte

       Start Time               End Time        Source Instrument   Wavelength   Provider  Physobs  Wavetype Extent Width Extent Length Extent Type   Size
                                                                     Angstrom                                                                        Mibyte
----------------------- ----------------------- ------ ---------- -------------- -------- --------- -------- ------------ ------------- ----------- --------
2017-08-21 17:27:09.000 2017-08-21 17:27:10.000    SDO        AIA 171.0 .. 171.0     JSOC intensity   NARROW         4096          4096    FULLDISK 64.64844

[31]:

aia_result[0, 0]

[31]:

QueryResponseRow index=0

Start Time	End Time	Source	Instrument	Wavelength	Provider	Physobs	Wavetype	Extent Width	Extent Length	Extent Type	Size	fileid
				Angstrom							Mibyte
Time	Time	str3	str3	float64[2]	str4	str9	str6	str4	str4	str8	float64	str24
2017-08-21 17:27:09.000	2017-08-21 17:27:10.000	SDO	AIA	171.0 .. 171.0	JSOC	intensity	NARROW	4096	4096	FULLDISK	64.64844	aia__lev1:171:1282411667

[32]:

files = Fido.fetch(aia_result[0, 0], site="NSO")

[33]:

files

[33]:

<parfive.results.Results object at 0x158950690>
['/Users/nabil/sunpy/data/aia.lev1.171A_2017_08_21T17_27_09.35Z.image_lev1.fits']

Having downloaded this data we create a SunPy Map and then plot it on top of our eclipse image. Note that despite not being in the same coordinate system, our AIA Map is automatically transformed to the coordinate system of our image before plotting.

[34]:

aia_map = sunpy.map.Map(files[0])

[35]:

fig = plt.figure(figsize=(9, 9))
ax = plt.subplot(projection=eclipse_map)
eclipse_map.plot(axes=ax)
aia_map.plot(axes=ax, autoalign=True)
aia_map.draw_grid(axes=ax)
plt.show()

2025-06-23 09:09:07 - sunpy - INFO: Using mesh-based autoalignment

INFO: Using mesh-based autoalignment [sunpy.map.mapbase]

Conclusion

In this blog post, we demonstrated how to read your eclipse images into a SunPy Map and how to combine your own photographs with data from NASA observations of the Sun. Though this post used data from the 2017 eclipse, you should be able to use the same techniques to process your 2024 eclipse observations. Happy eclipse viewing!

Modeling Coronal Loops in 3D with sunpy.coordinates

2018-07-25T00:00:00+00:00

This blog post was written in a Jupyter notebook. Click here for an interactive version:

Will Barnes is a fifth-year PhD student in the Department of Physics and Astronomy at Rice University in Houston, TX, USA. Will is a frequent user of the SunPy package and is the developer of fiasco, a Python interface to the CHIANTI atomic database. You can find him on GitHub @wtbarnes and Twitter @wtbarnes_.

Updated on 25 July 2018

The first version of this post contained an error in the scaling laws used to compute the loop temperature from a heating rate. This has now been corrected.

Coronal loops are the building blocks of the solar corona, the outermost layer of the Sun’s atmosphere. Because the pressure exerted by the coronal magnetic field is much stronger than the pressure of the surrounding gas, hot plasma is forced to flow along the magnetic field lines, creating bright arches, or loops, that extend high above the solar surface. As a result, the corona is often modeled as an ensemble of one-dimensional loop structures rather than a three-dimensional box of magnetized plasma. This allows for detailed simulations over massive spatial scales that are not accessible by 3D MHD simulations due to their massive computational cost. This review paper provides an excellent overview of both the observational and modeling sides of coronal loop physics.

The sunpy.coordinates module is a useful tool for expressing locations on the Sun in various coordinate systems. While most often used in the context of analyzing and manipulating observational data, we can also use this module to build three-dimensional models of loops in the corona.

Getting the Coordinates of a Single Loop

Let’s consider a semi-circular loop with both footpoints rooted on the surface of the Sun with a length \(L=500\) Mm and centered at a latitude of \(\Theta=30^{\circ}\). We have to do a bit of algebra to find these coordinates, but all we are doing is expressing them in terms of a spherical coordinate system, more specifically the Heliographic Stonyhurst coordinate system, \((r,\Theta,\Phi)\). For a comprehensive overview of solar coordinate systems, see Thompson (2006).

[2]:

def semi_circular_loop(length, theta0=0 * u.deg):
    r_1 = const.R_sun

    def r_2_func(x):
        return np.arccos(0.5 * x / r_1.to(u.cm).value) - np.pi + length.to(u.cm).value / 2.0 / x

    r_2 = scipy.optimize.bisect(r_2_func, length.to(u.cm).value / (2 * np.pi), length.to(u.cm).value / np.pi) * u.cm
    alpha = np.arccos(0.5 * (r_2 / r_1).decompose())
    phi = np.linspace(-np.pi * u.rad + alpha, np.pi * u.rad - alpha, 2000)
    # Quadratic formula to find r
    a = 1.0
    b = -2 * (r_1.to(u.cm) * np.cos(phi.to(u.radian)))
    c = r_1.to(u.cm) ** 2 - r_2.to(u.cm) ** 2
    r = (-b + np.sqrt(b**2 - 4 * a * c)) / 2 / a
    # Choose only points above the surface
    i_r = np.where(r > r_1)
    r = r[i_r]
    phi = phi[i_r]
    hcc_frame = Heliocentric(observer=SkyCoord(lon=0 * u.deg, lat=theta0, radius=r_1, frame="heliographic_stonyhurst"))
    return SkyCoord(
        x=r.to(u.cm) * np.sin(phi.to(u.radian)),
        y=u.Quantity(r.shape[0] * [0 * u.cm]),
        z=r.to(u.cm) * np.cos(phi.to(u.radian)),
        frame=hcc_frame,
    ).transform_to("heliographic_stonyhurst")

[3]:

loop = semi_circular_loop(500 * u.Mm, theta0=30 * u.deg)

[4]:

loop[[0, -1]]  # First and last points

[4]:

<SkyCoord (HeliographicStonyhurst: obstime=None): (lon, lat, radius) in (deg, deg, km)
    [(-14.09138695, 29.2478234, 698633.18692374),
     ( 14.09138695, 29.2478234, 698633.18692374)]>

Notice that this function returns an Astropy SkyCoord object. You can read more about these in the Astropy docs. Simply put, a SkyCoord object allows us to specify a coordinate-aware set of points in the sky, specifically on the Sun. SunPy provides many of the commonly used solar coordinate systems to be used by SkyCoord. You can read more about them here.

To plot our loop, we need to construct a dummy sunpy.map.Map object. This just provides a projected coordinate system so that we can plot our loop in two dimensions.

[5]:

data = np.ones((10, 10))
time_now = astropy.time.Time.now()
meta = MetaDict(
    {
        "ctype1": "HPLN-TAN",
        "ctype2": "HPLT-TAN",
        "cunit1": "arcsec",
        "cunit2": "arcsec",
        "crpix1": (data.shape[0] + 1) / 2.0,
        "crpix2": (data.shape[1] + 1) / 2.0,
        "cdelt1": 1.0,
        "cdelt2": 1.0,
        "crval1": 0.0,
        "crval2": 0.0,
        "hgln_obs": 0.0,
        "hglt_obs": 0.0,
        "dsun_obs": const.au.to(u.m).value,
        "dsun_ref": const.au.to(u.m).value,
        "rsun_ref": const.R_sun.to(u.m).value,
        "rsun_obs": ((const.R_sun / const.au).decompose() * u.radian).to(u.arcsec).value,
        "t_obs": time_now.iso,
        "date-obs": time_now.iso,
    }
)
dummy_map = GenericMap(data, meta)

[6]:

fig = plt.figure(figsize=(10, 10))
ax = fig.gca(projection=dummy_map)
dummy_map.plot(alpha=0, extent=[-1000, 1000, -1000, 1000], title=False)
ax.plot_coord(loop.transform_to(dummy_map.coordinate_frame), color="C0", lw=2)
dummy_map.draw_grid(grid_spacing=10 * u.deg, color="k", axes=ax)

[6]:

<astropy.visualization.wcsaxes.coordinates_map.CoordinatesMap at 0x7f9e6a3ea898>

Computing the Density and Emission Measure

We want to model the thermodynamics of our loop in the field-aligned direction. Assuming hydrostatic equilibrium, we can write down the balance between thermal and gravitational pressure in the radial direction,

\[\frac{dP}{dr} = -m_in g_{\odot}\left(\frac{R_{\odot}}{r}\right)^2\]

where \(g_{\odot}\) and \(R_{\odot}\) are the surface gravity and radius of the Sun, respectively, \(n\) is the density, and \(m_i\) is the ion mass. We want to find the density as a function of \(s\), the coordinate along the loop. We can rewrite the above equation in terms of \(s\),

\[\frac{dP}{ds} = \frac{dP}{dr}\frac{dr}{ds} = -m_in g_{\odot}\left(\frac{R_{\odot}}{r(s)}\right)^2\frac{dr}{ds}\]

Using the ideal gas law (\(P=2k_BnT\)) and assuming an isothermal loop, we can integrate both sides and find an expression for the density \(n\) as a function of the field-aligned coordinate \(s\),

\[n(s) = n_0\exp\left[-\frac{R_{\odot}^2}{\lambda_P}\int_0^s\mathrm{d}s^{\prime}\frac{dr/ds^{\prime}}{r^2(s^{\prime})}\right]\]

where \(\lambda_P=2k_BT/m_ig_{\odot}\) is the pressure scale height and \(n_0\) is the density at \(s=0\), i.e. at the footpoint. This gives us the number density at each point along our loop. Let’s write a function to compute the density for a given \(L\), \(n_0\), and \(T\).

[7]:

def isothermal_density(loop, length, n0=1e12 * u.cm ** (-3), t=1 * u.MK):
    s = np.linspace(0 * length.unit, length, loop.radius.shape[0]).to(u.cm)
    r = loop.radius.to(u.cm)
    lambda_p = 2 * const.k_B * t / (const.m_p * sun_const.surface_gravity)
    integral = (np.gradient(r.value, (s[1] - s[0]).value) / (r.value**2) * np.gradient(s.value)).cumsum() / u.cm
    exp_term = (const.R_sun**2) / lambda_p * integral
    return n0 * np.exp(-exp_term)

We can then evaluate the the density along the loop that we created above, using a footpoint density of \(n_0=10^{11}\) cm\(^{-3}\) and temperature \(T=10^6\) K.

[8]:

density = isothermal_density(loop, 500 * u.Mm, T=1 * u.MK, n0=1e11 / (u.cm**3))

A commonly studied quantity in coronal loop physics is the emission measure distribution,

\[\mathrm{EM} = \int_{LOS}\mathrm{d}h\,n^2\]

Notice that this quantity is computed by integrating along the line of sight from the observer to the feature on the Sun. That means we need both the density (which we computed above) as well as the location of the loop with respect to some observer.

Projecting and Binning

Now that we have the loop coordinates and the density along the loop, we need to project the loop on the plane of the sky and integrate along the line of sight.

First, let’s choose an observing location. We can specify our observer using the same kind of SkyCoord object that we used to express our loop coordinates! We’ll place our observer at \((1\,\mathrm{AU},0^{\circ},0^{\circ})\), i.e. pointing right at the center of the Sun at a distance of 1 AU.

[9]:

observer = SkyCoord(lon=0 * u.deg, lat=0 * u.deg, radius=const.au, frame="heliographic_stonyhurst")

Next, we convert the loop to a Helioprojective coordinate system as defined by our observer.

[10]:

coords = loop.transform_to(Helioprojective(observer=observer))

To compute the line-of-sight emission measure, we’ll use a two-dimensional histogram and bin the \((\theta_x,\theta_y)\) coordinates, using \(n^2\Delta h\) as the weights. First, we need to set up the bins for our histogram.

[11]:

res_x, res_y = 5 * u.arcsec / u.pixel, 5 * u.arcsec / u.pixel
pad_x, pad_y = res_x * 5 * u.pixel, res_y * 5 * u.pixel
min_x, max_x = coords.Tx.min() - pad_x, coords.Tx.max() + pad_x
min_y, max_y = coords.Ty.min() - pad_y, coords.Ty.max() + pad_y
min_z, max_z = coords.distance.min(), coords.distance.max()
bins_x = np.ceil((max_x - min_x) / res_x)
bins_y = np.ceil((max_y - min_y) / res_y)
bins_z = max(bins_x, bins_y)

Next, we can compute the weights.

[12]:

dz = (max_z - min_z).cgs / bins_z * (1.0 * u.pixel)
em = density**2 * dz.value

We’ll exploit our helioprojective coordinate system to figure out what coordinates are blocked by the solar disk. First we need to figure out the angular size of the solar disk as seen by our observer.

[13]:

rsun_obs = ((const.R_sun / (observer.radius - const.R_sun)).decompose() * u.radian).to(u.arcsec)

Our loop will only be visible if it is in front of the disk or off the limb. Otherwise, we set it to zero visibility.

[14]:

off_disk = np.sqrt(coords.Tx**2 + coords.Ty**2) > rsun_obs
in_front_of_disk = coords.distance - observer.radius < 0.0
mask = np.any(np.stack([off_disk, in_front_of_disk], axis=1), axis=1)

[15]:

weights = em * mask

We can now use the histogram2d function in Numpy to bin our loop coordinates, weighted by the visible emission measure distribution, using the appropriate number of bins and ranges.

[16]:

hist, _, _ = np.histogram2d(
    coords.Tx.value,
    coords.Ty.value,
    bins=(bins_x.value, bins_y.value),
    range=((min_x.value, max_x.value), (min_y.value, max_y.value)),
    weights=weights,
)

We’ll also apply a Gaussian filter, with widths of 1 pixel in both directions, to simulate the point spread function of an instrument.

[17]:

em_hist = gaussian_filter(hist.T, (1.0, 1.0))

In order to make this into a sunpy.map.Map object, we also need to construct a header based on the observer location and the field of view of our observed loop.

[18]:

header = MetaDict(
    {
        "crval1": (min_x + (max_x - min_x) / 2).value,
        "crval2": (min_y + (max_y - min_y) / 2).value,
        "cunit1": coords.Tx.unit.to_string(),
        "cunit2": coords.Ty.unit.to_string(),
        "hglt_obs": observer.lat.to(u.deg).value,
        "hgln_obs": observer.lon.to(u.deg).value,
        "ctype1": "HPLN-TAN",
        "ctype2": "HPLT-TAN",
        "dsun_obs": observer.radius.to(u.m).value,
        "rsun_obs": ((const.R_sun / (observer.radius - const.R_sun)).decompose() * u.radian).to(u.arcsec).value,
        "cdelt1": res_x.value,
        "cdelt2": res_y.value,
        "crpix1": (bins_x.value + 1.0) / 2.0,
        "crpix2": (bins_y.value + 1.0) / 2.0,
    }
)

[19]:

em_map = GenericMap(em_hist, header)

Finally, let’s plot our loop emission measure!

[20]:

fig = plt.figure(figsize=(15, 10))
ax = fig.gca(projection=em_map)
im = em_map.plot(
    cmap="magma",
    title=False,
    norm=matplotlib.colors.SymLogNorm(1, vmin=1e27, vmax=5e29),
)
ax.plot_coord(SkyCoord(-300 * u.arcsec, 300 * u.arcsec, frame=em_map.coordinate_frame), alpha=0)
ax.plot_coord(SkyCoord(300 * u.arcsec, 900 * u.arcsec, frame=em_map.coordinate_frame), alpha=0)
em_map.draw_grid(grid_spacing=10 * u.deg, color="w", axes=ax)
ax.grid(alpha=0)
ax.set_facecolor("k")
fig.colorbar(im, ax=ax)

[20]:

<matplotlib.colorbar.Colorbar at 0x7f9e68aeeb00>

Extending to Many Loops

One loop is not very exciting. Instead, let’s model an arcade of loops, choose their lengths from a power-law distribution, and place them over a range of latitudes.

Let’s write a function that generates the coordinates and densities for a lot of loops.

[21]:

def loop_arcade(n_loops, length_min=10 * u.Mm, length_max=100 * u.Mm, theta_min=-10 * u.deg, theta_max=10 * u.deg):
    # Generate loops
    rnd_gen = np.random.Generator(np.random.PCG64())
    x = rnd_gen.random(n_loops)
    alpha = -1.5
    lengths = ((length_max ** (alpha + 1.0) - length_min ** (alpha + 1.0)) * x + length_min ** (alpha + 1.0)) ** (
        1.0 / (alpha + 1.0)
    )
    thetas = np.linspace(theta_min, theta_max, n_loops)
    loops = [semi_circular_loop(l, theta0=th) for l, th in zip(lengths, thetas)]
    # Get densities
    ## Choose heating rate, get T from RTV scaling laws
    e = 1e-4 * u.erg / (u.cm**3) / u.s
    t = (1.83e3) * (e.value / 5.09e4 * (lengths.to(u.cm).value ** 2)) ** (2 / 7) * u.K
    density = np.hstack(
        [
            isothermal_density(loop, length, t=t.to(u.MK), n0=1e11 / (u.cm**3))
            for loop, length, t in zip(loops, lengths, t)
        ]
    )
    density = u.Quantity(density.value, "cm^-3")
    # Stack coordinates
    lon = u.Quantity(np.hstack([l.lon.value for l in loops]), loops[0].lon.unit)
    lat = u.Quantity(np.hstack([l.lat.value for l in loops]), loops[0].lat.unit)
    radius = u.Quantity(np.hstack([l.radius.value for l in loops]), loops[0].radius.unit)
    coords = SkyCoord(lon=lon, lat=lat, radius=radius, frame=loops[0].frame)

    return coords, density

[22]:

coords, densities = loop_arcade(
    1000, length_min=50 * u.Mm, length_max=500 * u.Mm, theta_min=-10 * u.deg, theta_max=10 * u.deg
)

Now that we’ve got the coordinates and densities for our arcade of loops, we need to bin them and convert them to a map. Let’s write another function that just encapsulates all of the steps that we walked through in the previous section.

[23]:

def arcade_to_map(coords, densities, observer):
    coords = coords.transform_to(Helioprojective(observer=observer))
    # Setup Bins
    res_x, res_y = 5 * u.arcsec / u.pixel, 5 * u.arcsec / u.pixel
    pad_x, pad_y = res_x * 5 * u.pixel, res_y * 5 * u.pixel
    min_x, max_x = coords.Tx.min() - pad_x, coords.Tx.max() + pad_x
    min_y, max_y = coords.Ty.min() - pad_y, coords.Ty.max() + pad_y
    min_z, max_z = coords.distance.min(), coords.distance.max()
    bins_x = np.ceil((max_x - min_x) / res_x)
    bins_y = np.ceil((max_y - min_y) / res_y)
    bins_z = max(bins_x, bins_y)
    # Compute Weights
    dz = (max_z - min_z).cgs / bins_z * (1.0 * u.pixel)
    em = densities**2 * dz.value
    rsun_obs = ((const.R_sun / (observer.radius - const.R_sun)).decompose() * u.radian).to(u.arcsec)
    off_disk = np.sqrt(coords.Tx**2 + coords.Ty**2) > rsun_obs
    in_front_of_disk = coords.distance - observer.radius < 0.0
    mask = np.any(np.stack([off_disk, in_front_of_disk], axis=1), axis=1)
    weights = em * mask
    # Bin values
    hist, _, _ = np.histogram2d(
        coords.Tx.value,
        coords.Ty.value,
        bins=(bins_x.value, bins_y.value),
        range=((min_x.value, max_x.value), (min_y.value, max_y.value)),
        weights=weights,
    )
    hist = gaussian_filter(hist.T, (1.0, 1.0))
    # Make header
    header = MetaDict(
        {
            "crval1": (min_x + (max_x - min_x) / 2).value,
            "crval2": (min_y + (max_y - min_y) / 2).value,
            "cunit1": coords.Tx.unit.to_string(),
            "cunit2": coords.Ty.unit.to_string(),
            "hglt_obs": observer.lat.to(u.deg).value,
            "hgln_obs": observer.lon.to(u.deg).value,
            "ctype1": "HPLN-TAN",
            "ctype2": "HPLT-TAN",
            "dsun_obs": observer.radius.to(u.m).value,
            "rsun_obs": ((const.R_sun / (observer.radius - const.R_sun)).decompose() * u.radian).to(u.arcsec).value,
            "cdelt1": res_x.value,
            "cdelt2": res_y.value,
            "crpix1": (bins_x.value + 1.0) / 2.0,
            "crpix2": (bins_y.value + 1.0) / 2.0,
        }
    )
    plot_settings = {"cmap": "magma", "title": False, "norm": matplotlib.colors.SymLogNorm(1, vmin=5e29, vmax=2e32)}
    return GenericMap(hist, header, plot_settings=plot_settings)

Let’s start by observing our arcade with the same observer that we defined in the previous section.

[24]:

arcade_map = arcade_to_map(coords, densities, observer)

[25]:

fig = plt.figure(figsize=(15, 10))
ax = fig.gca(projection=arcade_map)
im = arcade_map.plot()
ax.plot_coord(SkyCoord(-900 * u.arcsec, -900 * u.arcsec, frame=arcade_map.coordinate_frame), alpha=0)
ax.plot_coord(SkyCoord(900 * u.arcsec, 900 * u.arcsec, frame=arcade_map.coordinate_frame), alpha=0)
em_map.draw_grid(grid_spacing=10 * u.deg, color="w", axes=ax)
ax.grid(alpha=0)
ax.set_facecolor("k")
fig.colorbar(im, ax=ax)

[25]:

<matplotlib.colorbar.Colorbar at 0x7f9e68728400>

Looking straight at disk center is still a bit boring. Let’s choose a more interesting viewing angle by moving our observer to \((\Phi,\Theta)=(-25^{\circ},-25^{\circ})\)

[26]:

observer = SkyCoord(lon=-25 * u.deg, lat=-25 * u.deg, radius=const.au, frame="heliographic_stonyhurst")
arcade_map = arcade_to_map(coords, densities, observer)

[27]:

fig = plt.figure(figsize=(15, 10))
ax = fig.gca(projection=arcade_map)
im = arcade_map.plot()
arcade_map.draw_grid(grid_spacing=10 * u.deg, color="w", axes=ax)
ax.plot_coord(SkyCoord(-900 * u.arcsec, -900 * u.arcsec, frame=arcade_map.coordinate_frame), color="w", alpha=0)
ax.plot_coord(SkyCoord(900 * u.arcsec, 900 * u.arcsec, frame=arcade_map.coordinate_frame), color="w", alpha=0)
ax.grid(alpha=0)
ax.set_facecolor("k")
fig.colorbar(im, ax=ax)

[27]:

<matplotlib.colorbar.Colorbar at 0x7f9e681bed68>

Note that we did not change our loop coordinates or the values of the densities. We only changed the location of the observer that defined our two-dimensional projected coordinate system.

The power of this approach is that our loop coordinates are independent of any one coordinate frame and we can define varying two-dimensional projections simply by varying the location of our observer. We don’t even need to think about transformation matrices, rotation matrices, etc. SunPy and Astropy provide all of this machinery for us!

Let’s move our observer to the south pole such that we are looking through the arcade of loops.

[28]:

observer = SkyCoord(lon=0 * u.deg, lat=-90 * u.deg, radius=const.au, frame="heliographic_stonyhurst")
arcade_map = arcade_to_map(coords, densities, observer)

[29]:

fig = plt.figure(figsize=(18, 10))
ax = fig.gca(projection=arcade_map)
im = arcade_map.plot()
arcade_map.draw_grid(grid_spacing=10 * u.deg, color="w", axes=ax)
ax.plot_coord(SkyCoord(-450 * u.arcsec, 600 * u.arcsec, frame=arcade_map.coordinate_frame), color="w", alpha=0)
ax.plot_coord(SkyCoord(450 * u.arcsec, 1200 * u.arcsec, frame=arcade_map.coordinate_frame), color="w", alpha=0)
ax.grid(alpha=0)
ax.set_facecolor("k")
fig.colorbar(im, ax=ax)

[29]:

<matplotlib.colorbar.Colorbar at 0x7f9e686deb70>

We can even observe the loops off limb just by setting \(\Phi\ge90^{\circ}\).

[30]:

observer = SkyCoord(lon=-90 * u.deg, lat=0 * u.deg, radius=const.au, frame="heliographic_stonyhurst")
arcade_map = arcade_to_map(coords, densities, observer)

[31]:

fig = plt.figure(figsize=(18, 10))
ax = fig.gca(projection=arcade_map)
im = arcade_map.plot()
arcade_map.draw_grid(grid_spacing=10 * u.deg, color="w", axes=ax)
ax.plot_coord(SkyCoord(700 * u.arcsec, -300 * u.arcsec, frame=arcade_map.coordinate_frame), color="w", alpha=0)
ax.plot_coord(SkyCoord(1300 * u.arcsec, 300 * u.arcsec, frame=arcade_map.coordinate_frame), color="w", alpha=0)
ax.grid(alpha=0)
ax.set_facecolor("k")
fig.colorbar(im, ax=ax)

[31]:

<matplotlib.colorbar.Colorbar at 0x7f9e68173630>

Notice that because of our viewing angle, the far footpoints are masked by the disk and thus are not visible.

Conclusion

The sunpy.coordinates module can be a powerful tool for observers and modelers alike. Understanding how observed features on the Sun vary depending on the location of the observer is especially critical in the optically thin corona where many structures may be emitting along any given line of sight. Often it is difficult to disentangle distinct features in an observation and models become important in interpreting the underlying physics. Overall, the coordinates module in Astropy, combined with the solar-specific coordinate frames in sunpy.coordinates, provide an intuitive and powerful way to express locations on the Sun in a frame-independent manner.

Blog - Posts in Tutorial

Artemis II Solar Eclipse

Visualize the path of Artemis II

Determine the coordinate system of the photo

Find the position of Artemis II

Locate the Moon

Calculate the image scale

Determine the camera orientation

Account for lens distortion

Overplotting Coronagraph Images

Closing thoughts

Process Your Solar Eclipse Photos with SunPy!

Read in Your Eclipse Photo

Find the Moon

Make a SunPy Map

Find a Star

Combine your Image with NASA Data

Conclusion

Modeling Coronal Loops in 3D with sunpy.coordinates

Getting the Coordinates of a Single Loop

Computing the Density and Emission Measure

Projecting and Binning

Extending to Many Loops

Conclusion

Make a SunPy `Map`