Commit 5753379e authored by Luc Maisonobe's avatar Luc Maisonobe

Improved documentation.

All these improvements have been contributed by Michael Turner. Many
thanks to him!
parent 9936961f
......@@ -123,10 +123,13 @@
<contributor>
<name>Mathieu Rom&#233;ro</name>
</contributor>
<contributor>
<name>Michael Turner</name>
</contributor>
<contributor>
<name>Evan Ward</name>
</contributor>
</contributors>
</contributors>
<organization>
<name>CS Syst&#232;mes d&#039;Information</name>
......
......@@ -3,7 +3,7 @@ OREKIT
<body>
<h2>1. Purpose</h2>
<p>
OREKIT library is a low level library for space mechanics projects. It is
OREKIT library is a low-level library for space mechanics projects. It is
implemented in the JAVA language.
</p>
<p>OREKIT project was initiated by CS with the following goals in mind:</p>
......@@ -46,7 +46,7 @@ discrete events. Here is a short list of the features offered by the library:</p
<li>predefined frames (EME2000/J2000, ICRF, GCRF, ITRF93, ITRF97, ITRF2000, ITRF2005, ITRF2008 and
intermediate frames, TOD, MOD, GTOD and TEME frames, Veis, topocentric, tnw and qsw local orbital
frames, spacecraft body, Moon, Sun, planets, solar system barycenter, Earth-Moon barycenter)</li>
<li>user extensible (used operationally in real time with a set of about 60 frames on several spacecrafts)</li>
<li>user extensible (used operationally in real time with a set of about 60 frames on several spacecraft)</li>
<li>transparent handling of IERS Earth Orientation Parameters (for both new CIO-based frames following
IERS 2010 conventions and old equinox-based frames)</li>
<li>transparent handling of JPL DE 4xx (405, 406 and more recent) and INPOP ephemerides</li>
......@@ -59,7 +59,7 @@ discrete events. Here is a short list of the features offered by the library:</p
<li>Spacecraft state
<ul>
<li>Cartesian, elliptical Keplerian, circular and equinoctial parameters</li>
<li>Two-Lines Elements</li>
<li>Two-Line Elements</li>
<li>transparent conversion between all parameters</li>
<li>automatic binding with frames</li>
<li>attitude state and derivative</li>
......@@ -93,7 +93,7 @@ discrete events. Here is a short list of the features offered by the library:</p
</li>
<li>state of the art ODE integrators (adaptive stepsize with error control,
continuous output, switching functions, G-stop, step normalization ...)</li>
<li>computation of jacobians with respect to orbital parameters and selected force models parameters</li>
<li>computation of Jacobians with respect to orbital parameters and selected force models parameters</li>
<li>serialization mechanism to store complete results on persistent storage for later use</li>
</ul>
</li>
......@@ -133,7 +133,7 @@ discrete events. Here is a short list of the features offered by the library:</p
<li>impulse maneuvers occurrence</li>
</ul>
</li>
<li>possibility to slightly shift events in time (for example to switch from
<li>possibility of slightly shifting events in time (for example to switch from
solar pointing mode to something else a few minutes before eclipse entry and
reverting to solar pointing mode a few minutes after eclipse exit)</li>
</ul>
......@@ -147,7 +147,7 @@ discrete events. Here is a short list of the features offered by the library:</p
(nadir pointing, center pointing, target pointing,
yaw compensation, yaw-steering)</li>
<li>orbit referenced attitudes (LOF aligned, offset on all axes)</li>
<li>space referenced attitudes (inertial, celestial body pointed, spin stabilized)</li>
<li>space referenced attitudes (inertial, celestial body-pointed, spin-stabilized)</li>
</ul>
</li>
</ul>
......
......@@ -17,8 +17,8 @@ Attitudes
* Attitudes Presentation
Some force models such as the atmospheric drag or the maneuvers need to
know the spacecraft orientation in inertial frame. OREKIT uses a simple
Some force models, such as the atmospheric drag for maneuvers, need to
know the spacecraft orientation in an inertial frame. Orekit uses a simple
container for Attitude which includes both the geometric part (i.e. rotation)
and the kinematic part (i.e. the instant spin axis). The components
held by this container allow to convert vectors from inertial frame to spacecraft
......@@ -27,11 +27,11 @@ Attitudes
In order to represent attitude evolution in time, the AttitudeLaw interface
is available.
At upper level, attitude laws defined by a ground pointing law are also available.
This corresponds to "real" situation where satellite attitude law is defined in order
to perform a mission, i.e. pointing a specified point/area. All these laws are gathered
around an abstract class called "GroundPointing".
At last, there exists attitude laws wrapping a "base" attitude law, and adding to this
At a higher level, attitude laws defined by a ground pointing law are also available.
This corresponds to a "real" situation where satellite attitude law is defined in order
to perform a mission, i.e. pointing a specified point/area. All these laws are collected
under an abstract class called "GroundPointing".
Finally, there exist attitude laws that wrap a "base" attitude law, and add to this
base attitude law a complementary rotation in order to fulfill specific mission constraints.
* Description of attitudes laws
......@@ -47,7 +47,7 @@ Attitudes
** celestial body pointed, i.e satellite pointing axis directed towards given
celestial body.
** spin stabilized law, which is handled as a wrappers for an underlying
** spin stabilized law, which is handled as a wrapper for an underlying
non-rotating law. This underlying law is typically an instance
of CelestialBodyPointed with the pointing axis equal to
the rotation axis, but can in fact be anything...
......@@ -77,34 +77,34 @@ Attitudes
All these ground pointing laws are relative to corresponding body frame,
which is used for their construction. Depending on their nature, each ground pointing
law also have their own specific construction arguments.
law also have its own specific construction arguments.
For each of these laws, satellite attitude state at any time in any given frame
can be computed, as well as observed ground point, or target in body frame.
can be computed, as well as the observed ground point, or a target in the body frame.
** "Complex" pointing laws
Several classes have been implemented in order to represent some attitude law in which a
"base" attitude law is used, and added a "complementary" rotation in order to fulfill specific
Several classes have been implemented in order to represent attitude laws in which a
"base" attitude law is used, and a "complementary" rotation is added in order to fulfill specific
mission constraints. They are gathered under abstract class <GroundPointingWrapper>.
Up to now, implemented laws of this kind are:
At this point, implemented laws of this kind are:
** yaw compensation law: this law is used to fulfill ground observation constraints
which are to reduce geometrical distortion. Yaw angle is changed a little from
that reduce geometrical distortion. Yaw angle is changed a little from
the basic ground pointing attitude, so that the apparent motion of ground points is
along a prescribed axis (orthogonal to the optical sensors rows), taking into account
all effects. It is the impact of earth proper rotation on ground points that is
compensated.
** yaw steering law: this law is mainly used for low Earth orbiting satellites
with no missions-related constraints on yaw angle. It sets the yaw angle in
such a way the solar arrays have maximal lightning without changing the
with no mission-related constraints on yaw angle. It sets the yaw angle in
such a way that the solar arrays have maximal lighting without changing the
roll and pitch.
** Attitude sequence
The <AttitudeSequence> class manages a sequence of different attitude laws activated
in rows according to switching events. Only one attitude law in the sequence is in
an active state. When one of the switch event associated with the active law occurs,
an active state. When one of the switch events associated with the active law occurs,
the active law becomes the one specified with the event.
* Package organization
......
......@@ -13,7 +13,7 @@
Bodies
This package provides interface to represent the position and geometry of
This package provides an interface to representation of the position and geometry of
space objects such as stars, planets or asteroids.
* Position
......@@ -21,7 +21,7 @@ Bodies
The position of celestial bodies is represented by the <CelestialBody> interface.
This interface provides the methods needed to either consider the body as an
external one for its gravity or lighting influence on spacecraft (typically in
perturbing force computation) or as an internal one with its own frame.
perturbing force computations) or as an internal one with its own frame.
The <CelestialBodyFactory> class is a factory providing several predefined instances
implementing the <CelestialBody> interface for the main solar system bodies. The Sun,
......@@ -35,8 +35,8 @@ Bodies
[../images/design/celestial-bodies-class-diagram.png]
As an example, computing the position of the Sun and the Moon in the EME2000 frame,
this done as follows:
As an example, computing the position of the Sun and the Moon, in the EME2000 frame,
is done as follows:
+---------------------
CelestialBody sun = CelestialBodyFactory.getSun();
......@@ -50,7 +50,7 @@ Vector3D moonInEME2000 =
Since the supported bodies implement the <CelestialBody> interface, they all provide
their own body-centered inertial frame, hence adding a few more frames to the ones
provided by the frames package. Since the frames tree is rooted at an Earth-centered
frame, the solar system bodies frames tree does not seems in canonical shape. This of
frame, the solar system bodies frames tree does not seem to be in canonical form. This of
course is only a side effect of the arbitrary choice of GCRF as the root frame and has
no effect at all on computations. The solar system bodies frames tree is shown below:
......@@ -64,11 +64,11 @@ Vector3D moonInEME2000 =
** Implementations
Only one implementation is provided by OREKIT for now: the <OneAxisEllipsoid>
class which represents the natural flattened shape of big space rotating bodies
Only one implementation is provided by Orekit for now: the <OneAxisEllipsoid>
class, which represents the natural flattened shape of big space rotating bodies
like planets or the Sun.
For asteroids, it is expected that users provide their own shape models, for example
For asteroids, it is expected that users will provide their own shape models, for example
based on triangulation. They should implement the <BodyShape> interface in order to
be used by Orekit.
......
......@@ -13,9 +13,9 @@
Errors
The "Errors" package provides classes to generate and handle errors, which are based on
the classical mechanism of exceptions. Errors messages generated are automatically
translated, the languages available are English, French, Galician, German, Italian,
The "Errors" package provides classes to generate and handle errors, based on
the classical mechanism of exceptions. The error messages generated are automatically
translated, with the available languages being English, French, Galician, German, Italian,
Norse and Spanish.
* Authors
......
......@@ -13,7 +13,7 @@
Forces
The "Forces" package provides the interface for force models that will be used by the
The "Forces" package provides the interface for the force models to be used by a
<NumericalPropagator>.
* Forces presentation
......@@ -23,14 +23,14 @@ Forces
The propagator will call at each step the force model contribution computation
method, to be added to its time derivative equations. The force model instance
will extract all the state data it needs (date,position, velocity, frame, attitude,
will extract all the state data it needs (date, position, velocity, frame, attitude,
mass) from the first parameter.
From these state data, it will compute the perturbing acceleration. It
will then add this acceleration to the second parameter which will take thins
will then add this acceleration to the second parameter which will take this
contribution into account and will use the Gauss equations to evaluate its impact
on the global state derivative.
Force models which create discontinuous acceleration patterns (typically for maneuvers
Force models that create discontinuous acceleration patterns (typically for maneuvers
start/stop or solar eclipses entry/exit) must provide one or more events detectors to
the propagator thanks to their <getEventsDetectors()> method. This method
is called once just before propagation starts. The events states will be checked by
......@@ -39,12 +39,12 @@ Forces
* Available force models
The force models implemented are the following ones:
The force models implemented are as follows:
* atmospheric drag forces,
* central gravity forces, including time-dependent parts (linear trends and
pulasation at several different periods). Several attraction model are
pulsation at several different periods). Several attraction models are
available for representing the gravitational field of a celestial body
(the recommended model is Holmes and Featherstone):
......
This diff is collapsed.
......@@ -16,7 +16,7 @@ Orbits
The "Orbits" package provides classes to represent orbits.
It builds the base of all the other space mechanics tools.
This package is the basis for all of the other space mechanics tools.
It provides an abstract class, Orbit, extended in four different ways
corresponding to the different possible representations of orbital parameters.
Since version 3.0, keplerian, circular, equinoctial and cartesian representations
......@@ -26,7 +26,7 @@ Orbits
Early designs for the orbit package were much more complex than the current design.
Looking back at these designs, they tried to do far too much in a single class and
resulted in huge systems which were both difficult to understand, difficult to
resulted in huge systems which were difficult to understand, difficult to
use, difficult to maintain and difficult to reuse. They mixed several different notions:
** representation (keplerian, cartesian ...)
......@@ -37,7 +37,7 @@ Orbits
** filtering (osculating and centered or mean parameters, related to some models)
They also often forgot all frames issues.
They also often neglected all frames issues.
The current design has been reached by progressively removing spurious layers and
setting them apart in dedicated packages. All these notions are now still handled,
......@@ -55,7 +55,7 @@ Orbits
From the early design, the various orbit classes retained only the kinematical
notions at a single time. They basically represent the current state, and
serve as data holder. Most of methods provided by these orbits classes are
serve as data holders. Most of the methods provided by these orbits classes are
getters. Some of them (the non-ambiguous ones that must be always available) are
defined in the top Orbit abstract class (<Orbit.getA()>, <Orbit.getDate()>,
<Orbit.getPVCoordinates()>). The more specific ones depending on the type of
......@@ -68,7 +68,7 @@ Orbits
non-cartesian representation. This choice is a pragmatic one. These parameters
are really used in many places in algorithms, for computation related to
period (setting a convergence threshold or a search interval) or geometry
(computing swath or lightning). A side-effect of this choice is that all orbits
(computing swath or lighting). A side-effect of this choice is that all orbits
do include a value for \u00b5, the acceleration coefficient of the central body.
This value is only used for the representation of the parameters and for conversion
purposes, it is <not> always the same as the value used for propagation (but
......@@ -76,7 +76,7 @@ Orbits
Orbits also include a reference to a date and a defining frame. Only pseudo-inertial
frames can be used to define orbits, as Newtonian mechanics should apply within the
context of the frame. Including frames allow transparent conversions to any other
context of the frame. Including frames allows transparent conversions to any other
frames at given date, without having to externally preserve a mapping between orbits
and their frame: it is already done. As an example, getting the position and velocity
of a satellite given by a circular orbit in a ground station frame is simply a matter
......@@ -88,8 +88,8 @@ Orbits
guaranteed to be immutable. They are small objects and they are shared by
many parts. This change was done in 2006 and tremendously simplified the
library and the users applications that were previously forced to copy orbits
as an application of defensive programming, and that were plagued by difficult
to find bugs when they forgot to copy.
as an application of defensive programming, and that were plagued by
difficult-to-find bugs when they forgot to copy.
For orbit evolution computation, this package is not sufficient. There is a
need to include notions of dynamics, forces models, propagation algorithms ...
......@@ -105,7 +105,7 @@ Orbits
** a : semi-major axis (m)
** e : eccentricity (currently only e smaller than 1.0, i.e elliptical orbits, are supported)
** e : eccentricity (any value of e is supported, i.e. both elliptical and hyperbolic orbits can be used)
** i : inclination (rad)
......@@ -149,7 +149,7 @@ Orbits
mean longitude argument (\u03c9 + \u03a9 + M) or eccentric longitude argument (\u03c9 + \u03a9 + E).
\
* Cartesian orbit, associated to its frame definition, which parameters are:
* Cartesian orbit, associated to its frame definition, the parameters for which are:
** (X, Y, Z) (m) : position vector of the point in given frame
......@@ -178,15 +178,15 @@ Orbits
and when converted back to the original non-ambiguous representation it does give
the right result.
We therefore consider it is the responsibility of the user to be aware of the correct
We therefore consider it the responsibility of the user to be aware of the correct
definition of the different representations and of the singularities relative to each
one of them. If the user really needs to do some conversion (for example to provide
an orbit as Two-Lines Elements later on, remembering than TLE do use keplerian-like
an orbit as Two-Line Elements later on, remembering that TLEs do use keplerian-like
parameters), then he can do so.
The way conversion is handled in OREKIT is very simple and allows easy and transparent
processing. All four parameters type extend the abstract class Orbit,
and every propagation algorithm, be it analytical or numerical, use this abstract class as a
The way conversion is handled in Orekit is very simple and allows easy and transparent
processing. All four parameters type-extend the abstract class Orbit,
and every propagation algorithm, be it analytical or numerical, uses this abstract class as a
parameter, even if internally it relies on a specific representation. As an example, the
Eckstein-Hechler propagator is defined in terms of circular orbit only. So
there is an implicit conversion done at propagator initialization time.
......
......@@ -34,7 +34,7 @@ Propagation
different modes:
* slave mode: This mode is used when the user needs only the final orbit at the target
time. The (slave) propagator is passive: it computes this result and return it to the
time. The (slave) propagator is passive: it computes this result and returns it to the
calling (master) application, without any intermediate feedback. In that case the events
detection is made but the <step handler> does nothing, actions are managed directly by the
calling application.
......@@ -51,9 +51,9 @@ Propagation
sequential order. A typical example is the implementation of search and iterative
algorithms that may navigate forward and backward inside the propagation range before
finding their result.
Beware that this mode cannot support events that modify spacecraft initial state.
Beware that since this mode stores <<all>> intermediate results, it may be memory
intensive for long integration ranges and high precision/short time steps.
CAVEATS: Be aware that this mode cannot support events that modify spacecraft initial state.
Be aware that since this mode stores <<all>> intermediate results, it may be memory-intensive
for long integration ranges and high precision/short time steps.
The recommended mode is master mode. It is very simple to use and allow user to get
rid of concerns about synchronizing force models, file output, discrete events. All
......@@ -82,18 +82,18 @@ Propagation
At each propagation step, the propagator checks the registered events detectors for
the occurrence of some event, as shown in the following squence diagram. If an event
occurs, then the corresponding action is triggered, which can ask the propagator to
resume propagation, possibly with an updated state or to stop propagation.
resume propagation (possibly with an updated state) or to stop propagation.
[../images/design/events-sequence-diagram.png]
Resuming propagation with changed state is used for example in the <ImpulseManeuver>
class. When the maneuver is triggered, the orbit is changed according to the velocity increment
associated with the maneuver and the mass is reduced according to the consumption. This
allows to handle simple maneuvers transparently even inside basic propagators like
allows the handling simple maneuvers transparently even inside basic propagators like
Kepler or Eckstein-Heschler.
Stopping propagation is useful when some specific state is desired but its real occurrence
time is unknown in advance. A typical example would be to find the next ascending node
time is not known in advance. A typical example would be to find the next ascending node
or the next apogee. In this case, we can register a <NodeDetector> or an <ApsideDetector>
object and launch a propagation with a target time far away in the future. When the
event is triggered, it asks the propagator to stop and the returned value is the state
......@@ -120,7 +120,7 @@ Propagation
when some target enters or exits a satellite sensor field of view,
* an <EclipseDetector>, which is triggered when some body enters or exits the umbra or the
penumbra of an other occulting body,
penumbra of another occulting body,
* an <ApsideDetector>, which is triggered at apogee and perigee,
......@@ -150,20 +150,20 @@ Propagation
The <KeplerianPropagator> implements the <Propagator> interface, which ensures
that we can obtain a propagated SpacecraftState at any time once the instance
is initialized with an initial state. This model is based on Keplerian only
is initialized with an initial state. This model is based on Keplerian-only
motion. It depends on \u00b5.
*** Eckstein-Hechler propagation
This analytical model is suited for near circular orbits and inclination neither
This analytical model is suited for near-circular orbits and inclination neither
equatorial nor critical. It considers J2 to J6 potential zonal coefficients,
and uses mean parameters to compute the new position. As the keplerian propagator,
and uses mean parameters to compute the new position. As the Keplerian propagator,
it implements the <Propagator> interface.
*** SGP4/SDP4 propagation
This analytical model is dedicated to Two-Lines Elements (TLE) propagation.
This analytical model is dedicated to Two-Line Elements (TLE) propagation.
*** Differential effects adapter
......@@ -185,7 +185,7 @@ Propagation
*** Simple propagation of equations of motion
The mathematical problem to integrate is a dimension seven time derivative equations
The mathematical problem to integrate is a dimension-seven time-derivative equations
system. The six first elements of the state vector are the orbital parameters, which
may be any orbit type (<KeplerianOrbit>, <CircularOrbit>, <EquinoctialOrbit> or
<CartesianOrbit>) in meters and radians, and the last element is the mass in
......@@ -194,13 +194,13 @@ Propagation
<AdditionalEquations> devoted to integration of Jacobian matrices). The time derivatives are
computed automatically by the Orekit using the Gauss equations for the first parameters
corresponding to the selected orbit type and the flow rate for mass evolution
during maneuvers. The users only needs to register the various force models needed for
during maneuvers. The user only needs to register the various force models needed for
the simulation. Various force models are already available in the library and specialized
ones can be added by users easily for specific needs.
The integrators (<first order integrators>) provided by commons-math need
the state vector at t0, the state vector first time derivative at t0,
and then calculates the next step state vector, and ask for the next first
and then calculates the next step state vector, and asks for the next first
time derivative, etc. until it reaches the final asked date. These underlying numerical
integrators can also be configured. Typical tuning parameters for adaptive stepsize
integrators are the min, max and perhaps start step size as well as the absolute and/or
......
......@@ -13,65 +13,65 @@
Time
The "Time" package is an independent package providing classes to handle epochs,
time scales, and to compare instants between them.
The "Time" package is an independent package providing classes to handle epochs and
time scales, and to compare instants.
* Time Presentation
The principal class is <AbsoluteDate> which represents a unique instant in time,
and to be able to locate it with respect to the many different times scales in
so as to be able to locate it with respect to the many different times scales in
use in the space dynamics and astronomy fields.
This greatly simplifies development as it hides some models internals. For example
when using JPL-based ephemerides, time must be in Terrestrial Time (formerly
known as Ephemeris Time). However, this is a implementation detail and someone
calling Orekit from an high level application should not deal with it. The <<AbsoluteDate>>
known as Ephemeris Time). However, this is an implementation detail and someone
calling Orekit from a high level application should not have to deal with it. The <<AbsoluteDate>>
class allows users to pass a date regardless of the time scale it was defined in,
conversions will be added as required transparently.
conversions will be done as required transparently.
** Time Scales
Dates are commonly defined by specifying a location in a specific <time scale>.
Dates are commonly defined by specifying a point in a specific <time scale>.
For example, the J2000.0 epoch is defined from its calendar components as
2000-01-01T12:00:00 in Terrestrial Time. It is of prime importance to understand
the various available time scales definitions to avoid mistakes. The
<<<TimeScalesFactory>>> class provides several predefined time scales:
** <<International Atomic Time>>,
this is the most accurate and regular time scale that can be used for now at
the surface of the Earth,
this is the most accurate and regular time scale that can be used at
the surface of the Earth.
** <<Terrestrial Time>> as defined by IAU(1991) recommendation IV.
Coordinate time at the surface of the Earth. It is the
successor of Ephemeris Time TE. By convention, TT = TAI + 32.184 s,
successor of Ephemeris Time TE. By convention, TT = TAI + 32.184 s.
** <<Coordinated Universal Time>>. UTC is mainly related to
TAI, but some step adjustments are introduced from time to time to keep take
into account Earth rotation irregularities and preventing the <legal> time to
drift with respect to day and night. The International Earth Rotation Service
into account Earth rotation irregularities and to prevent the <legal> time from
drifting with respect to day and night. The International Earth Rotation Service
(IERS) is in charge of this time-keeping. These adjustments require introduction
of leap seconds, which means some days are not 86400 seconds long,
of leap seconds, which means some days are not 86400 seconds long.
** <<Universal Time 1>>. UT1 is a time scale directly linked to the actual
rotation of the Earth. It is an irregular scale, reflecting Earth irregular
rotation of the Earth. It is an irregular scale, reflecting Earth's irregular
rotation rate. The offset between UT1 and UTCScale is found in the Earth
Orientation Parameters published by IERS,
Orientation Parameters published by IERS.
** <<Geocentric Coordinate Time>>. Coordinate time at the
center of mass of the Earth. This time scale depends linearly from TTScale
(and hence from TAI),
center of mass of the Earth. This time scale depends linearly on TTScale
(and hence on TAI).
** <<Barycentric Dynamic Time>>. Time used to compute ephemerides in the
solar system. This time is offset with respect to TT by small relativistic
corrections due to Earth motion,
corrections due to Earth motion.
** <<Barycentric Coordinate Time>>. Coordinate time used for computations in
the solar system. This time scale depends linearly on TDBScale,
the solar system. This time scale depends linearly on TDBScale.
** <<Global Positioning System reference scale>>. This scale
was equal to UTC at start of the GPS Epoch when UTC was 19 seconds behind TAI,
and stayed parallel to TAI since then (i.e. UTC is now offset from GPS due to
leap seconds). TGPS = TAI - 19 s,
and has stayed parallel to TAI since then (i.e. UTC is now offset from GPS due to
leap seconds). TGPS = TAI - 19 s.
** <<Galileo System reference scale>>. This scale
is equal to UTC + 13s at Galileo epoch (1999-08-22T00:00:00Z). Galileo System Time
......@@ -103,19 +103,19 @@ Time
The first option is the more straightforward one, but is not sufficient for some needs.
The two last options are confusingly similar, because of the complexity of time scales.
Understanding the differences between the two is a key point to avoid large errors.
Understanding the differences between the two is key to avoiding large errors.
An <apparent seconds offset> is the difference between two readings on a clock synchronized
with a time scale. If for example the first reading is 23:59:59 and the second reading is
00:00:00, the the apparent seconds offset is 1 second. An elapsed duration is the count
of seconds that could be measured by a stop watch started at the first instant and stopped
at the second instant. Most of the time, both times are identical. However, if the time scale
is UTC and if the readings are made when a leap second is introduced, then the duration
elapsed between the two events is 2 seconds and not 1 second!
is UTC and if the readings are made when a leap second is introduced, then the
elapsed time between the two events is 2 seconds and not 1 second!
The method <<<offsetFrom>>> method which takes both a date and a time scale as parameters
The method <<<offsetFrom>>> which takes both a date and a time scale as parameters,
computes the apparent offset. The <<<durationFrom>>> method which takes only a date as
parameter computes the elapsed duration. In the exemple above, the first method would return
parameter computes the elapsed duration. In the example above, the first method would return
1 second while the second method would return 2 seconds:
+---------------------
......@@ -126,9 +126,9 @@ System.out.println(stop.offsetFrom(start, utc)); // prints 1.0
System.out.println(stop.durationFrom(start)); // prints 2.0
+---------------------
This property is used in reverse to define dates. We can define the second instant either
as the instance which will occur when the reading of the clock is one second away for the
reading if the first date. We can also define it as the instant occurring when two seconds
This property is used in reverse to define dates. We can define the second instant
as the instant which will occur when the reading of the clock is one second away for the
reading of the first date. We can also define it as the instant occurring when two seconds
have elapsed since the first instant, without any reference to an external clock. Both
approaches are possible, it depends on the available data and its meaning. The following
code shows both approaches:
......@@ -141,7 +141,7 @@ AbsoluteDate date2 = new AbsoluteDate(referenceDate, 2.0);
+---------------------
The two variables <<<date1>>> and <<<date2>>> represent the same instant. The first one has been
defined relatively to a time scale, the second one has been defined independently of any time
defined relative to a time scale, the second one has been defined independently of any time
scale.
** Reference Epochs
......@@ -170,13 +170,13 @@ AbsoluteDate date2 = new AbsoluteDate(referenceDate, 2.0);
* Time Use
Once it is built, an <AbsoluteDate> can be compared to other ones, and converted
and expressed in other time scales. It is used to define states, orbits, frames...
Once it is constructed, an <AbsoluteDate> can be compared to others, and converted to
and expressed in other time scales. It is used to define states, orbits, frames ...
Classes that include a date implement the <<TimeStamped>> interface.
The <<ChronologicalComparator>> singleton can sort objects implementing this
interface chronologically. This is particularly interesting for ephemerides. One trick
that can be used for such collections is too really define them using generic
that can be used for such collections is to actually define them using generic
<<TimeStamped>> instances as in the following example. The trick is that we want to
be allowed to use <<AbsoluteDate>> instances in methods like <<headSet>>, <<tailSet>>
or <<subSet>>.
......
......@@ -13,32 +13,34 @@
TLE
This package provides classes to read and extrapolate Two-Line orbits format.
This package provides classes to read, and extrapolate from, orbital elements in
Two-Line Elements (TLE) format.
* TLE Presentation
TLE orbits are represented by two lines string representation, then data are converted
internally for easier retrieval and future extrapolation.
All the values provided by a TLE only have sense when translated by the correspondent
TLE orbits are supplied in two-line element format, then converted
into an internal format for easier retrieval and future extrapolation.
All the values provided by a TLE only make sense when translated by the corresponding
propagator. Even when no extrapolation in time is needed, state information
(position and velocity coordinates) can only be computed threw the propagator.
(position and velocity coordinates) can only be computed through the propagator.
Untreated values like inclination, RAAN, mean Motion, etc. can't be used by
themselves without loosing precision.
themselves without loss of precision.
Implemented TLE model is conform to new 2006 corrected model.
The implemented TLE model conforms to new 2006 corrected model.
More information on the TLE format can be found on the
{{{http://www.celestrak.com/}CelesTrak website.}}
* Evolution
At present, TLE orbit representation is decorelated from other orbit representations
The TLE orbit representation is de-corelated from other orbit representations
provided by <Orbits> package. It is due to the fact that TLE representation depends on
a very specific dynamic model, which is not compatible with <Orbits> models in present
architecture.
This is a miss and it is due to change, so that representations conversions can be made
automatically and transparently for the user.
It is considered to be closer to a propagation model than to an orbit representation and
has been moved withing the propagation package since 6.0.
* Authors
......
......@@ -13,7 +13,7 @@
Utils
The "Utils" package provides useful objects for mathematical or geometrical handlings.
The "Utils" package provides methods for managing mathematical or geometrical objects.
* Utils Presentation
......
......@@ -32,7 +32,7 @@ Building Orekit
{{http://maven.apache.org/download.html}}, this page also explains the
installation procedure.
As with all maven enabled projects, building Orekit is straightforward. Simply
As with all maven enabled projects, building Orekit is straightforward, simply
run:
+-------
......@@ -66,7 +66,7 @@ mvn install
* Building with Ant
{{{http://ant.apache.org/}Ant}} is another well-known build tool. It is
older than maven and widely used. It does not provide as many
more ancient than maven and widely used. It does not provide as many
features as maven (no site generation for example) but is very extensible.
For systems not providing ant as a package, it can be downloaded from its
......@@ -85,7 +85,7 @@ mvn install
ant
+-------
Just as with maven, this command also retrieves the dependencies from
Just as maven does, this command also retrieves the dependencies from
public repositories, compiles the sources and creates a file named
build/orekit-x.y.jar where x.y is the version number.
......
......@@ -71,7 +71,7 @@ Configuration
In this case, data may be stored in the main operational database, relying on the
existing administration procedures (updates, backup, redundancy ...).
* Simulation tool on a desktop computer for everyday studies
* Simulation tool on a desk computer for everyday studies
For everyday local use of a tool, data will mainly be stored in the user environment.
A traditional architecture will involve two main data stores, one on a network shared
......@@ -96,7 +96,7 @@ Configuration
* Computation service in an application server
A service installed on an application server may be simpler to configure if rather
A service installed on an application server may be simpler to configure if, rather
than using explicit files locations on the server, one stores the data in the
application classpath where it will be managed by the application server together
with the application code itself.
......@@ -173,7 +173,7 @@ Configuration
disk.
Data files may also be compressed using gzip to save some disk space. Compressed files
are also uncompressed directly in memory. Compressing text-based files like bulletinB or EOPC04
are also uncompressed directly in memory. Compressing text-based files like Bulletin B or EOPC04
saves a lot of disk space, but compressing the JPL binary files saves very little space.
Using compressed files inside a zip archive is also irrelevant as zip/jar files are themselves
compressed and stacking compression algorithms only slows down reading speed without saving any disk
......
......@@ -15,8 +15,9 @@ Contacts
* Technical contact
If you want to discuss with the development team for any technically
oriented question, please use the following email address:
If for some reason you cannot use the public lists, you can reach the CS
Systèmes d'Information Orekit team for any question (either technically
oriented or administrative) at the following email address:
{{{mailto:orekit@c-s.fr}orekit@c-s.fr}}
* Administrative contact
......
......@@ -13,12 +13,12 @@
Contributing to Orekit
Orekit is free software, it means you can use it as you want in your
applications, but also that you can improve it and have your code
included in the next mainstream release.
Orekit is free software, which means you can use the source code as you wish,
without charges, in your applications, and that you can improve it and have
your improvements included in the next mainstream release.
If you are interested in participating in the development effort,
subscribe to the mailing lists and step up to discuss about it. The
largest the community will be, the better Orekit will be. The main
subscribe to the mailing lists and step up to discuss it. The
larger the community is, the better Orekit will be. The main