Orbit Visualization Tool User Guide
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.
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.
The graphics window shows objects in one of five geocentric Cartesian coordinates described
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).
- GEI: Geocentric Equatorial Inertial
- X-axis points toward the first point of Aries (the position of Sun at vernal equinox).
- Z-axis points toward geographic north.
- GEO: Geographic
- Z-axis along the geographic north pole.
- X-axis lies in the equatorial plane and points to the Greenwich meridian (longitude=0).
- GSM: Geocentric Solar Magnetospheric
- X-axis points toward the Sun.
- Y-axis is perpendicular to the Earth magnetic dipole and the Sun direction(Y=DxX).
- SMC: Solar Magnetic Coordinates
- GSE: Geocentric Solar Ecliptic.
- X-axis points toward the Sun.
- Z-axis points toward the ecliptic north.
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
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:
- GEI (J2000.0): Geocentric Equatorial Inertial (J2000.0)
- X-axis pointing toward the first point of Aries (the position of Sun at vernal equinox) at J2000.0.
- Z-axis points toward geographic north.
- GEI (epoch-of-date): Geocentric Equatorial Inertial (epoch-of-date)
- X-axis pointing toward the first point of Aries (the position of Sun at vernal equinox) at the time the coordinate system is evaluated.
- Z-axis points toward geographic north.
- Note: This coordinate system is not strictly inertial, despite its name.
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:
- Make sure that you have a pre-existing install of OVT 3.0 and that OVT 3.0 is not running.
- Find the old “ovt.jar” file in the OVT 3.0 install directory.
- Replace the file with the new, updated
The downloaded file must first be renamed to “ovt.jar”.
The “ovt.jar” file is the same for all supported platforms.
- Launch OVT 3.0 and verify that new update is working. This can be done by either of two methods:
- Verify that the updated OVT software version is listed as “build 10” or later on the upper window bar/edge.
(The official OVT 3.0 release was “build 7”.)
- Verify that the coordinate system selector menu at the bottom left corner of the main
OVT window contains two coordinate systems labelled “GEI (J2000.0)” and
- The magnetic field models include standard internal field model IGRF 1950-2000 and
Tsyganenko models of the external magnetospheric field: T87, T89, T96 and T2001.
- The bow shock model is according to Farris et al, GRL, v. 18, p.1821,
1991, and Cairns et al., JGR, v.100, p.47, 1995
- The magnetopause model is according to Shue et al., JGR, v. 103, p. 17691, 1998.
- The electric potential model is according to D. Weimer, GRL, 23, 2549, 1996.
All these model implementations have user-editable time-dependent parameter data.
The user interface consists of one visualization window integrated with a
control panel. Objects in the visualization window are mouse
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.
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.
The orbital module includes a standard ESOC program for computing
and velocity of Cluster, Double Star or any other s/c with the orbital
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 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 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
Note: The OMNI2 data are automatically downloaded as files (each covering a year) from
NASA's Space Physics Data Facility (SPDF),
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
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
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.
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
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
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 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).
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
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
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
||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.
||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.
||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
||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
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,
Distances between satellites shows the distances between every pair of CLUSTER spacecraft.
||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.
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.
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
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.
- Mac OS X: Library/ovt/<OVT version number>/
- Linux, Windows: .ovt/<OVT version number>/
The Earth can be shown either as continents, or as
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.
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
Last modified on 2022-11-30.
OVT Team, 2000-2016.