Orbit Visualization Tool User Guide

Version 3.0

Contents:
    What is OVT?

The Orbit Visualization Tool (OVT) is a software for visualization of satellite orbits in the Earth's magnetic field. The program can display satellite orbits in five coordinate systems (GEI, GEO, GSM, SMC, GSE), satellite footprints projected on the Earth's surface and shown in either geographic (GEO) or geomagnetic (SMC) coordinates. The software can load orbits on file as well as use online orbit data via NASA's Satellite Situation Center's (SSC) Web Services. In addition to satellite orbits the software computes and displays various models of magnetospheric structures, magnetopause, bow shock and electric potential, geomagnetic activity, and interplanetary field conditions. The models are time-dependent through either user-editable activity table files, or online magnetospheric data via NASA's Space Physics Data Facility's (SPDF) OMNI2 data, which control the model's structure and properties. The program can be used to plan operations or interpret measurements from scientific satellites, to prepare ground-based satellite coordination, or as an educational tool in astronomy and geophysics.


    Operating system and graphics

OVT can be installed on Linux, Mac OS X, and Windows (see release notes). The graphics used in this program is based on a Visualization Toolkit (VTK), which uses 3D accelerating hardware if present, but will still work with a simple 2D graphics card.


    Coordinate systems

The graphics window shows objects in one of five geocentric Cartesian coordinates described below. S denotes the unit vector toward the Sun. D denotes the unit vector along the magnetic dipole axis (positive northward). The third axis, not mentioned in the coordinate systems below, is always the axis that that completes the right-handed Cartesian triad (X,Y,Z).

Footnote: The difference between GSM and SMC is rotation around the common Y axis by the dipole tilt angle.

The footprint projections on the Earth are shown at an altitude of 100 km above the average sphere of 6373.2 km in two coordinates system: geographic GEO (longitude and latitude), and magnetic SMC (magnetic local time and magnetic latitude). Field line tracing is done with the selected magnetospheric model (internal + external). Please note that in SMC coordinates footprints are shown as MLT (magnetic local time) and MLAT (magnetic latitude) that are equivalent to dipole geomagnetic coordinates. The corrected geomagnetic coordinates are not used for display purposes because they do not represent an orthogonal transformation and therefore cannot be included in the global coordinate transformation matrices.

OVT update to support GEI (J2000.0) and GEI (epoch-of-date) coordinate systems (updated November 2nd, 2022):

There is an available OVT update that replaces the old GEI coordinate system (above) and with two variants of GEI (below), which in turn improves the accuracy of some coordinate transformations. For the Cluster spacecraft, this OVT update gives a discrepancy in GSE position of 10-20 km with respect to Cluster auxiliary data. This includes an absolute discrepancy of 1-2 km due to the Sun's position being calculated using UTC instead of ephemeris time. The error in relative distance between the spacecraft is much smaller.

The justification for this update is that the GEI coordinate system described above is not entirely well-defined since it can not be exactly inertial since the first point of Aries moves, albeit slowly. There are at least two known variants of the GEI coordinate system, both of which are included in this update:

There is no executable installer for this update. Instead, the update is available in the form of an updated “ovt.jar” file which can be used for manually updating a pre-existing install of OVT 3.0. To install and verify the update, follow below steps:

  1. Make sure that you have a pre-existing install of OVT 3.0 and that OVT 3.0 is not running.
  2. Find the old “ovt.jar” file in the OVT 3.0 install directory.
  3. Replace the file with the new, updated “ovt.jar” file. The downloaded file must first be renamed to “ovt.jar”. The “ovt.jar” file is the same for all supported platforms.
  4. Launch OVT 3.0 and verify that new update is working. This can be done by either of two methods:

    Models

All these model implementations have user-editable time-dependent parameter data.


    User Interface

The user interface consists of one visualization window integrated with a tree-like control panel. Objects in the visualization window are mouse manoeuvrable: The graphics is mouse manoeuverable: primary mouse button to rotate the visualization in 3D, CTRL+primary mouse button to rotate the visualization in 2D, secondary mouse button to zoom in and out, and SHIFT+primary mouse button to move the focus.



    Actors and Scene



The picture above shows the main window displaying the orbit of the Cluster1 satellite in GSM coordinates, current satellite position at time 2001-03-02T21:00:00Z and the magnetic field line passing through the satellite at this position. The footprints are shown in GEO coordinates. The position and size of the labels can be controlled by the user.

The left-side panel shows list of actors that can be displayed on the right-hand side scene. Each actor has some editable properties and can be shown/hidden on the scene. This popup menu is activated with the right (secondary) mouse button, after a selection click with the left (primary) button.


    Satellite Orbits and Attitude

The orbital module includes a standard ESOC program for computing position and velocity of Cluster, Double Star or any other s/c with the orbital parameters defined in the Long Term Orbit File (LTOF) format. For orbits defined by TLE (two-line elements) the SGP4/SDP4 orbit propagator is used. The location accuracy is however reduced for TLE files. The OVT distribution in itself includes orbit files for the Cluster, Double Star, and Freja satellites. To make a satellite orbit data file available from inside the GUI, click on the menu item Satellites -> Import Satellite File... and select a .tle or .ltof orbit file. The latest Cluster orbit files can be downloaded from http://jsoc1.bnsc.rl.ac.uk/pub/fd_files/ltof/. Orbital elements for civilian satellites can be obtained from e.g. CelesTrak.

It is also possible to add satellites using online orbit data from NASA's Satellite Situation Center's (SSC) Web Services. These satellites can be recognized in the interface tree by their name being prefixed with "(SSC)". Displaying orbit data using this feature may lead to slight delays when new orbit data is downloaded. Also, while this feature works most of the time, the remote online orbit database may on rare occasions be "locked" (usually briefly) or be offline. This is of course beyond the control of OVT but is ameliorated by OVT's internal caching of SSC orbit data. Selecting the menu item Satellites -> Select SSC-based Satellites... in the main window displays the SSC-based satellite selection window depicted below. Satellites checked in the "Bookmarked" column are also represented under the Satellites menu in the main window for easier access (add/remove). Satellites checked in the "Added" column are added to the main interface tree directly. Note that all columns can be sorted for easier navigation.


Information about the start and stop time of the available orbit data as well as a spacecraft's automatically estimated approximate period of revolution is available in the satellite's Info window.

Note: A spacecraft for which there is not enough orbit data to cover the entire currently selected time period is automatically unchecked in the interface tree (and can not be manually re-checked) and thus automatically disappears from the visualization. Hence, every plotted orbit covers the entire currently selected time interval. A spacecraft for which there is no orbit data for the current time interval has its name written in italics in the interface tree.

If a spin data file (e.g SatelliteName.spin) is present in the odata/ directory (see Data directories), then it is is used to compute the orientation of the spin axis with respect to the magnetic field, velocity vector, and the sun direction. The .spin files must be in the format required for CLUSTER project, i.e.

1 P 1994-09-01T00:00:00Z 1994-09-07T12:30:00Z 341.00 77.00 14.ffffff 333.800 776.1 0.0 0.0 0.00 0.00 1994-09-01T01:10:00Z


     The bow shock and the magnetopause
The bow shock and the magnetopause have editable properties that control their shape and positions. SWP is the solar wind pressure (nPa) and IMF stands for Interplanetary Magnetic Field.
    Magnetic Field Models
Magnetic field models are controlled by the window shown in the left. Each model has an associated set of parameters which values can be configured to come either from user-controlled tables, or (for most of them) from online OMNI2 data, see below. At present we have four versions of the Tsyganenko models, which can be combined with IGRF or dipole internal field models.

Tsyganenko 2001: The two IMF-related indices G1 and G2 take into account the IMF and solar wind conditions during the preceding 1-hour interval; their exact definition is given in the paper by N.A. Tsyganenko "A new data-based model of the near magnetosphere magnetic field. 2. Parameterization and fitting to observations".

The checked MP clipping means that the terrestrial magnetic field lines are not allowed to go outside the model MP surface (more than 0.5 Re).

For each type of activity data there is an associated user-controlled table which can be manually edited using the data editor. If the particular type of activity data can also be retrieved from OMNI2 data, then there is a checkbox signalling whether or not the corresponding data are retrieved from OMNI2 data instead of the table. When data for a given point in time is requested from the table, then the data record with the time earlier or equal to the requested time is taken from the data editor. If the requested time is earlier then the time of the first record - the first record is used.
The picture to the left depicts the OMNI2 Data Settings window accessible from the menu item Settings -> OMNI2 Settings... The activity checkboxes signal whether or not the corresponding activity data are retrieved from OMNI2 data instead of the corresponding user-controlled tables and are equivalent to the checkboxes in the data editors. For convenience and as a reality check, the current values as understood by OVT are displayed (unless the feature is disabled by the corresponding checkbox).

Note: The OMNI2 data are automatically downloaded as files (each covering a year) from NASA's Space Physics Data Facility (SPDF), a public online source, and are then cached locally on disk. OVT will however always try to silently replace cached files when it thinks the current ones are too old. As with NASA SSC online orbit data, there may be noticeable delays when OVT downloads new data and the online source may be offline which leads to error beyond OVT's control.

Solving problems with automatically downloading OMNI2 data (updated March 13th, 2017): Since OVT 3.0 was published, NASA SPDF has changed the web location (the URL) of its OMNI2 data files. Therefore OVT by default tries to download data from the wrong location. There are multiple ways to solve or work around this problem.

The exact URL used for downloading is specified by the OMNI2.hourlyAveraged.urlPattern variable in the conf/ovt.conf (see Data directories) but it is also displayed (not editable) in the OMNI2 Data Settings window. It can be set to an http://, ftp://, or file:// URL. Note that the string given in ovt.conf is not the exact string used as a URL: (1) the colon is escaped (prefixed by backslash) and potentially other characters too depending on the URL actually used, and (2) the year in the filename is represented by a special code. Footnote: There is a similar variable OMNI2.hourlyAveraged.localCacheFileNamePattern which specifies the filenames used for saving and reading cached OMNI2 data files. It does not need to be changed but is there in case NASA SPDF ever modifies the OMNI data file naming scheme, so that automatically and manually downloaded files can use the same file naming scheme.

Note that ovt.conf is read from, and written to when OVT launches and exits. It must therefore only be edited when OVT is not running. Consider keeping a copy of the original file before editing it, just in case OVT can not read the modified file.

  • Complete solution (when it works): Set OMNI2.hourlyAveraged.urlPattern to something that works. Note: The actual string put into ovt.conf must still be modified for special characters as mentioned above.
  • Workarounds:
    • Manually download OMNI2 files and place them in the cache directory where OVT expects to find them (cache/OMNI2/; create the data directory it if it does not already exist). Note: OVT will eventually try to re-download the files when it thinks they are too old (more than a year old except for recent data points) and might then again trigger a download error.
    • Set OMNI2.hourlyAveraged.urlPattern to a URL pointing to a repository of OMNI2 file available on the local file system, i.e. a URL beginning with file://. The user must still manually download the OMNI2 files and make sure they are available from that location. The advantage of this compared to downloading files into the OVT cache directory directly in the workaround above is that (1) it can not confuse OVT's attempts at redownloading cached OMNI2 files when it thinks they are old, and (2) such a local OMNI2 data file repository could be maintained by one person and shared by multiple users over a local network if mounted on the local file system.
  • Other sources of confusion: When OVT uses the obsolete URL, or possibly any other faulty URL, it may download faulty OMNI data files which are in reality HTML files representing error messages or similar. Therefore, clear out files from the OVT cache directory that are not genuine OMNI2 data files if such exist (cache/OMNI2/ if it exists; see data directory).

     Magnetospheric structure
Click on the image to enlarge it Magnetospheric structure represents a shell of outermost field-lines which are determined from current magnetic field model. If magnetopause (MP) clipping is set, the field lines are not permitted to extend outside the MP model. If the MP clipping is off, then the field-lines derived from the magnetospheric model can extend significantly beyond the MP model. However in such a case their footprint is very narrow and corresponds to the topological magnetic cusp (for models T87, T89).

Fieldline thickness can be specified (view the image).

     Fieldline Mapping

View from -Y    View from Z 		On this pictures you can see magnetopause, in a wireframe representation, and a surface created from two fieldlines, starting form the Earth.

     Ionospheric Electric Potential
Click on the image to enlarge it Electric potential.

     Data Visualization
To visualize data click on the satellite with the right (secondary) mouse button and choose "Load Data..."
Load Data Wizard will apear.

The data file should contain two columns:

  • 1-st - Time
  • 2-nd - Magnitude

    Time can be specified as DATE-TIME pair or in days/hours/minutes/seconds. In the last case you will be asked by OVT to specify the offset time.

    DATE format: YYYY-MM-DD or YYYY/MM/DD or YYYY/DDD
    TIME format: hh:mm or hh:mm:ss or hh.hhhh or sssss.ss

    Data file example:
    	# comment - this is a Polar current magnitude data
	2001-12-30 12:00:00	4.5
	2001-12-30 12:01:00	5.6
	.........

    • Visualization of data on orbit example
    Visualization of data on fieldlines example

         Time and Time Control
    OVT operates by always having a currently selected time interval (used for e.g. plotting segments of orbits) as well as a currently selected point in time within the currently selected time interval (used for e.g. drawing satellites, or the exact rotation of the Earth). The time settings window (left) can be display when clicking the time (clock) symbol in the tool bar at the bottom of the main window. The window displays the currently selected time interval in the form of the interval's start time (Start), it's length (Interval), and in how small pieces of time it will be subdivided (Tracing Step) for various purposes: stepping, labels, orbit spline interpolation (for graphic representation of orbit only). "<<" and ">>" buttons are used to shift the start time backward or forward in time by the length of interval. Keyboard shortcuts <modifier>+<left/right arrow> correspond to the graphical buttons, but the <modifier> key may differ between platforms (e.g. Alt on Linux). Similarily, <modifier>+<ENTER> corresponds to the "Apply" button for convenience.

    In the tool bar at the bottom of the main window, the time advance arrows < and > step backward or forward in time by one step within the current time interval. Double arrows << and >> change the current time to the beginning or end of the currently selected time interval.

        Orbit Monitor
    The orbit monitor can be accessed via any satellite's pop-up menu. The orbit monitor shows among other variables the current satellite position, velocity, distance from the center of the earth, magnetic field conditions (derived from the magnetic field model), and footprint coordinates. The footprints are shown for both hemispheres, when they exist. In addition, the orbit monitor shows the estimated radial distance to the current model of the magnetopause and the angle of the satellite spin axes with respect to the magnetic field vector, satellite velocity, and the sun direction. The later data require presence of the spin axis attitude file in the odata/ directory (see Data directories). The spin attitude file has suffix .spin and must be in the format required by the CLUSTER project. The .spin files included in the distribution contain artificial data for demonstration purposes. They should be removed or replaced by real data. Use the tooltips to find out the meaning of values.

    Dumping of orbit data

    The dumper panel is expanded if "Dump >>" is pressed;
    "Log" will dump the data specified in the Dumper Settings Window to a selected file.
    "Log All" will dump the data for the whole orbit.
    "Settings" button pops-up dumper settings window.

    Data available for dumping: data from the orbit monitor, Bx, By, Bz, Dipole Tilt angle.

        Footprints
    Click on the image to enlarge it The picture shows footprint of CLUSTER1
    over northern polar regions with time lables. The tic marks are every 5 minutes.

    Footprints can be shown either in GEO or in SMC coordinates.

        CLUSTER Configuration
    Cluster Satellites Zooming at the CLUSTER spacecraft shows the spacecraft trajectories (red, black, green, magenta) and the threading field-lines (green). The satellite is depicted as a sphere or as cylinders with a small pyramid, depending on the absence or presence of the spin attitude files. In the later case, the pyramid shows the actual orientation of the spin axis.

    The color convention:
    • Cluster 1 - red
    • Cluster 2 - black
    • Cluster 3 - green
    • Cluster 4 - magenta

     

    Cluster Configuration Window The CLUSTER configuration window shows configuration parameters of the four spacecraft.
    XYZ box shows the minimum box size in current coordinates that will confine all four spacecraft.
    Ellipsoid shows three axes of an ellipsoid that will confine all spacecraft.
    FAC box shows a box in local field-aligned coordinates (FAC) around the gravity centre that will confine four spacecraft: dB-along the field-lines, dA-in the azimuthal (LT) direction, and dR-in the dBxdA, pseudo-radial direction.
    Distances between satellites shows the distances between every pair of CLUSTER spacecraft.

         View Control
    View Control Window Control of the viewer position which can be selected as a top of any of the axes X, Y, Z, or the direction perpendicular to the orbit. The focal point can be a particular satellite, center of the Earth, or a given geographic point.

    Projection method can be parallel or perspective.

        Printing

    When printing or saving image make sure that the graphics is not covered by other window. The resolution of the hard copy corresponds to the resolution of screen objects. One can export image to a file and print or edit it with another program.


        Data directories

    Miscellaneous data (settings, cache, imported orbit files, IGRF model constants etc.) are installed to, written to (e.g. when importing satellite orbit files), and read from a directory .ovt/<OVT version number>/ and its subdirectories ("mdata", "conf", "docs" etc. ), located somewhere under the user directory. Previous versions of OVT may have used the application directory and subdirectories under it for the same purpose. OVT should/might still be able to read files from the corresponding subdirectories under the application directory if the corresponding file(s) can not be found under ".ovt" under the user directory. The user is adviced to be aware of this to avoid confusion on which files are actually being read by the OVT. This can be an issue if installing OVT into the directory of an old OVT installation. The ".ovt" directory can be deleted after uninstalling OVT.

    The exact OVT data directories relative to the home directory are:

    Note: The initial period in .ovt is omitted on Mac OS X.

        Miscellaneous

    The Earth can be shown either as continents, or as geographic/polar grid.
    The XYZ axis can be hidden/shown and refer to the current selection of coordinate system.
    Frame grid in three space planes can be also shown in the picture. Frame properties are editable.
    Caption text can be included in the graphics window. Font and size of the text can be changed by the user.

        Unsolved software problems: Can not run on macOS Ventura (version 13)

    OVT 3.0 can be installed on macOS Ventura (version 13), but it has been observed that it can not run correctly: it initially appears to launch but the graphical user interface never appears. There is currently no known solution to this problem. The only known way of mitigating this problem is to run OVT inside of a virtual machine and using a guest OS on which OVT 3.0 can run. While not known at the time of writing, it is likely that this problem will also apply to any later macOS version.

    Top of page

    https://
    Last modified on 2022-11-30.

    Copyright © OVT Team, 2000-2016.