Keywords:

Summary

This demo simulates the North American total solar eclipse that occurs on April 8th, 2024. A solar eclipse occurs when the moon transects the sun and casts its shadow on the earth. This DIRSIG simulation models the earth via the EarthGrid plugin and models the moon as an appropriately sized sphere that orbits the earth using the FlexMotion model driven by ECEF coordinates extracted from an external simulation using NASA’s SPICE Toolkit. The point of the simulation is to highlight the global positioning of the sun (via the SpiceEphemeris plugin), the global positioning of the moon and the appropriate interaction of the sun and moon.

Related Materials

The following demos, manuals and tutorials can provide additional information about the topics at the focus of this demo:

Details

A total solar eclipse occurs when moon is close to its minimum distance from the earth, making its apparent size large enough to block the entire solar disk. The 2024 total solar eclipse path transits North America, starting at the western central coast of Mexico, crossing the United States and eventually exiting of Newfoundland, Canada. During the transit the shape of the lunar shadow changes shape base on the relative Sun geometry and position on the earth.

total eclipse map
Figure 1. A map of the 2024 total solar eclipse path transiting North America. Credit: ©2021 Great American Eclipse, LLC. Used without permission.

Important Files

This section highlights key files important to the simulation.

The Moon Setup

Although the SpiceEphemeris plugin predicts the location and phase of the moon, it does not introduce a geometric representation of the moon. In order to simulate the eclipse, a geometric representaion of the moon must transit the sun in order to block the sun and cast a shadow. Therefore, the moon is created as a conventional DIRSIG scene using a GLIST sphere primitive:

The <basegeometry> for the moon in the geometry/moon.glist file.
    <basegeometry>
      <sphere>
        <matid>moon</matid>
        <center><point><x>0</x><y>0</y><z>0.0</z></point></center>
        <radius>1737100</radius>
        <temperature>10</temperature>
      </sphere>
    </basegeometry>

The orbit of the moon about the earth was calculated using NASA’s SPICE Toolkit. The moon location was captured as earth-centered, earth-fixed (ECEF) coordinates at 1 minute intervals for the period of the event. These computed ECEF coordinates are stored in the geometry/moon_waypoints.txt file and used by the FlexMotion waypoint engine in the dynamic instance of the moon geometry:

The <dynamicinstance> for the moon in the geometry/moon.glist file.
    <dynamicinstance>
      <motion type="flexible">
        <locationengine type="waypoints">
          <data source="external" datetime="relative" frame="ecef" delimiter=" ">
            <filename>geometry/moon_waypoints.txt</filename>
          </data>
        </locationengine>
      </motion>
    </dynamicinstance>

The geometry/moon.glist file is included into the moon.scene file as the only geometry in this scene. The materials for the moon are nearly irrelevant and simple:

The simple Ward diffuse moon material description in the moon.mat file.
MATERIAL_ENTRY {
    NAME = gray
    ID = moon
    SURFACE_PROPERTIES {
        REFLECTANCE_PROP_NAME = WardBRDF
        REFLECTANCE_PROP {
            DS_WEIGHTS = 0.2 0.0   
            XY_SIGMAS = 0.0 0.0 
        }
    }
    RAD_SOLVER_NAME = Simple
    RAD_SOLVER {
    }
}

The EarthModel Setup

Rather than create an Earth "scene", this simulation utilizes the EarthGrid plugin to provide the primary geometry for the scene. In this case, the plugin is configured with a image using NASA Blue Marble imagery and the major_lines and minor_lines are setup so that they are not displayed (the half width is set to 0).

The setup using the EarthGrid plugin in the demo.jsim file.
  "plugin_list": [
    {
      "name" : "EarthGrid",
      "inputs" : {
        "background_filename" : "bluemarble.jpg",
        "major_lines" : [180,0,255,255,255],
        "minor_lines" : [ 10,0,255,255,255]
      }
    },
    ...
  ]

The Observing Sensor

The observing sensor in this simulation is a simple, 640 x 480 RGB 2D framing array sensor with a 1 minute read-out interval. The sensor is positioned above a location near Rochester, NY (43.165 +N, -77.611 +E) using the FlexMotion fixed location engine and the lookat orientation engine to create a nadir viewing geometry:

The BasicPlatform demo.motion setup stares at a geographic location near Rochester, NY where the eclipse path will cross.
<motion type="flexible">
  <locationengine type="fixed">
    <location frame="geodetic">
      <latitude>43.165556</latitude>
      <longitude>-77.611389</longitude>
      <altitude>1000000000.000</altitude>
    </location>
  </locationengine>
  <orientationengine type="lookat">
    <locationengine type="fixed" >
      <location frame="geodetic">
        <latitude>43.165556</latitude>
        <longitude>-77.611389</longitude>
        <altitude>0.000</altitude>
      </location>
    </locationengine>
    <up frame="ecef" vector="0,0,1"/>
  </orientationengine>
</motion>

The Atmosphere Setup

The atmospheric modeling setup in this simulation requires a bit of explanation. In this simulation, the sensor is observing an entire hemisphere of the earth. However, the DIRSIG atmosphere plugins are (currently) designed to model a limited region of the earth across which quantities such as the relative solar scattering geometry are constant. In this case, the solar scattering angles vary tremendously due to the curvature of the earth. Hence, for this demonstration a model-driven atmosphere (e.g., the ClassicAtmosphere , NewAtmosphere or FourCurveAtmosphere) is not appropriate. Instead, this simulation uses the SimpleAtmosphere model.

Simulations and Results

The Single-Frame Simulation

The single-frame simulation (see demo.sim) captures a single image when then eclipse is over the Rochester, NY area:

$ dirsig5 demo.jsim

Load the resulting demo-t0000-c000.img radiance file in the DIRSIG image viewer and display the RGB bands using one of the high dynamic range scaling options (e.g., "two sigma" or "two percent" scaling). Alternatively, the image_tool provides the non-linear "gamma" scaling option, which can be used to directly produce a PNG with the following syntax:

$ image_tool convert --autoscale=gamma --gamma=3.0 --format=png demo-t0000-c0000.img
demo
Figure 2. The single-frame simulation.

The Multi-Frame Simulation

The multi-frame simulation (see video.jsim) captures a series of frames as the eclipse traverses the North American continent:

$ dirsig5 video.jsim

All the frames produced by the multi-frame simulation can be scaled in a single execution of the image_tool by using the appropriate wildcards for the image filename and then encoded into a video file with the FFmpeg video encoder:

$ image_tool convert --autoscale=gamma --gamma=3.0 --format=png demo-t0000-c*.img
$ ffmpeg -framerate 30 -i demo-t0000-c%04d.img.png -codec:v libx264 -profile:v high -pix_fmt yuv420p video.mp4
A video of the multi-frame simulation.