EphemerisFile.java

  1. /* Contributed in the public domain.
  2.  * Licensed to CS Systèmes d'Information (CS) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * CS licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *   http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.orekit.files.general;

  19. import java.util.ArrayList;
  20. import java.util.List;
  21. import java.util.Map;

  23. import org.orekit.errors.OrekitException;
  24. import org.orekit.frames.Frame;
  25. import org.orekit.propagation.BoundedPropagator;
  26. import org.orekit.propagation.Propagator;
  27. import org.orekit.propagation.analytical.AggregateBoundedPropagator;
  28. import org.orekit.time.AbsoluteDate;
  29. import org.orekit.time.TimeScale;
  30. import org.orekit.utils.CartesianDerivativesFilter;
  31. import org.orekit.utils.TimeStampedPVCoordinates;

  33. /**
  34.  * An interface for accessing the data stored in an ephemeris file and using the data to
  35.  * create a working {@link org.orekit.propagation.Propagator Propagator}.
  36.  *
  37.  * <p> An {@link EphemerisFile} consists of one or more satellites each an ID unique
  38.  * within the file. The ephemeris for each satellite consists of one or more segments.
  39.  *
  40.  * <p> Some ephemeris file formats may supply additional information that is not available
  41.  * via this interface. In those cases it is recommended that the parser return a subclass
  42.  * of this interface to provide access to the additional information.
  43.  *
  44.  * @author Evan Ward
  45.  * @see SatelliteEphemeris
  46.  * @see EphemerisSegment
  47.  */
  48. public interface EphemerisFile {

  50.     /**
  51.      * Get the loaded ephemeris for each satellite in the file.
  52.      *
  53.      * @return a map from the satellite's ID to the information about that satellite
  54.      * contained in the file.
  55.      */
  56.     Map<String, ? extends SatelliteEphemeris> getSatellites();

  58.     /**
  59.      * Contains the information about a single satellite from an {@link EphemerisFile}.
  60.      *
  61.      * <p> A satellite ephemeris consists of one or more {@link EphemerisSegment}s.
  62.      * Segments are typically used to split up an ephemeris at discontinuous events, such
  63.      * as a maneuver.
  64.      *
  65.      * @author Evan Ward
  66.      * @see EphemerisFile
  67.      * @see EphemerisSegment
  68.      */
  69.     interface SatelliteEphemeris {

  71.         /**
  72.          * Get the satellite ID. The satellite ID is unique only within the same ephemeris
  73.          * file.
  74.          *
  75.          * @return the satellite's ID, never {@code null}.
  76.          */
  77.         String getId();

  79.         /**
  80.          * Get the standard gravitational parameter for the satellite.
  81.          *
  82.          * @return the gravitational parameter use in {@link #getPropagator()}, in m^3 /
  83.          * s^2.
  84.          */
  85.         double getMu();

  87.         /**
  88.          * Get the segments of the ephemeris.
  89.          *
  90.          * <p> Ephemeris segments are typically used to split an ephemeris around
  91.          * discontinuous events, such as maneuvers.
  92.          *
  93.          * @return the segments contained in the ephemeris file for this satellite.
  94.          */
  95.         List<? extends EphemerisSegment> getSegments();

  97.         /**
  98.          * Get the start date of the ephemeris.
  99.          *
  100.          * <p> The date returned by this method is equivalent to {@code
  101.          * getPropagator().getMinDate()}.
  102.          *
  103.          * @return ephemeris start date.
  104.          */
  105.         AbsoluteDate getStart();

  107.         /**
  108.          * Get the end date of the ephemeris.
  109.          *
  110.          * <p> The date returned by this method is equivalent to {@code
  111.          * getPropagator().getMaxDate()}.
  112.          *
  113.          * @return ephemeris end date.
  114.          */
  115.         AbsoluteDate getStop();

  117.         /**
  118.          * View this ephemeris as a propagator, combining data from all {@link
  119.          * #getSegments() segments}.
  120.          *
  121.          * <p>In order to view the ephemeris for this satellite as a {@link Propagator}
  122.          * several conditions must be met. An Orekit {@link Frame} and {@link TimeScale}
  123.          * must be constructable from the frame and time scale specification in the
  124.          * ephemeris file. This condition is met when {@link EphemerisSegment#getFrame()}
  125.          * and {@link EphemerisSegment#getTimeScale()} return normally for all {@link
  126.          * #getSegments() segments}. If there are multiple segments they must be adjacent
  127.          * such that there are no duplicates or gaps in the ephemeris. The definition of
  128.          * adjacent depends on the ephemeris format as some formats define usable start
  129.          * and stop times that are different from the ephemeris data start and stop times.
  130.          * If these conditions are not met an {@link OrekitException} may be thrown by
  131.          * this method or by one of the methods of the returned {@link Propagator}.
  132.          *
  133.          * <p> Each call to this method creates a new propagator.
  134.          *
  135.          * @return a propagator for all the data in this ephemeris file.
  136.          * @throws OrekitException if any of the conditions are not met.
  137.          */
  138.         default BoundedPropagator getPropagator() throws OrekitException {
  139.             final List<BoundedPropagator> propagators = new ArrayList<>();
  140.             for (final EphemerisSegment segment : this.getSegments()) {
  141.                 propagators.add(segment.getPropagator());
  142.             }
  143.             return new AggregateBoundedPropagator(propagators);
  144.         }

  146.     }

  148.     /**
  149.      * A segment of an ephemeris for a satellite.
  150.      *
  151.      * <p> Segments are typically used to split an ephemeris around discontinuous events
  152.      * such as maneuvers.
  153.      *
  154.      * @author Evan Ward
  155.      * @see EphemerisFile
  156.      * @see SatelliteEphemeris
  157.      */
  158.     interface EphemerisSegment {

  160.         /**
  161.          * Get the standard gravitational parameter for the satellite.
  162.          *
  163.          * @return the gravitational parameter use in {@link #getPropagator()}, in m^3 /
  164.          * s^2.
  165.          */
  166.         double getMu();

  168.         /**
  169.          * Get the name of the center of the coordinate system the ephemeris is provided
  170.          * in.  This may be a natural origin, such as the center of the Earth, another
  171.          * satellite, etc.
  172.          *
  173.          * @return the name of the frame center
  174.          */
  175.         String getFrameCenterString();

  177.         /**
  178.          * Get the defining frame for this ephemeris segment.
  179.          *
  180.          * @return the frame identifier, as specified in the ephemeris file, or {@code
  181.          * null} if the ephemeris file does not specify a frame.
  182.          */
  183.         String getFrameString();

  185.         /**
  186.          * Get the reference frame for this ephemeris segment.
  187.          *
  188.          * @return the reference frame for this segment. Never {@code null}.
  189.          * @throws OrekitException if a frame cannot be created from {@link
  190.          *                         #getFrameString()} and there is no default frame.
  191.          */
  192.         Frame getFrame() throws OrekitException;

  194.         /**
  195.          * Get the time scale for this ephemeris segment.
  196.          *
  197.          * @return the time scale identifier, as specified in the ephemeris file, or
  198.          * {@code null} if the ephemeris file does not specify a time scale.
  199.          */
  200.         String getTimeScaleString();

  202.         /**
  203.          * Get the time scale for this ephemeris segment.
  204.          *
  205.          * @return the time scale for this segment. Never {@code null}.
  206.          * @throws OrekitException if a time scale can not be constructed based on {@link
  207.          *                         #getTimeScaleString()} and there is no default time
  208.          *                         scale.
  209.          */
  210.         TimeScale getTimeScale() throws OrekitException;

  212.         /**
  213.          * Get the number of samples to use in interpolation.
  214.          *
  215.          * @return the number of points to use for interpolation.
  216.          */
  217.         int getInterpolationSamples();

  219.         /**
  220.          * Get which derivatives of position are available in this ephemeris segment.
  221.          *
  222.          * <p> While {@link #getCoordinates()} always returns position, velocity, and
  223.          * acceleration the return value from this method indicates which of those are in
  224.          * the ephemeris file and are actually valid.
  225.          *
  226.          * @return a value indicating if the file contains velocity and/or acceleration
  227.          * data.
  228.          */
  229.         CartesianDerivativesFilter getAvailableDerivatives();

  231.         /**
  232.          * Get the coordinates for this ephemeris segment.
  233.          *
  234.          * @return a list of state vectors in chronological order. The coordinates are not
  235.          * necessarily evenly spaced in time. The value of {@link
  236.          * #getAvailableDerivatives()} indicates if the velocity or accelerations were
  237.          * specified in the file. Any position, velocity, or acceleration coordinates that
  238.          * are not specified in the ephemeris file are zero in the returned values.
  239.          */
  240.         List<? extends TimeStampedPVCoordinates> getCoordinates();

  242.         /**
  243.          * Get the start date of this ephemeris segment.
  244.          *
  245.          * <p> The date returned by this method is equivalent to {@code
  246.          * getPropagator().getMinDate()}.
  247.          *
  248.          * @return ephemeris segment start date.
  249.          */
  250.         AbsoluteDate getStart();

  252.         /**
  253.          * Get the end date of this ephemeris segment.
  254.          *
  255.          * <p> The date returned by this method is equivalent to {@code
  256.          * getPropagator().getMaxDate()}.
  257.          *
  258.          * @return ephemeris segment end date.
  259.          */
  260.         AbsoluteDate getStop();

  262.         /**
  263.          * View this ephemeris segment as a propagator.
  264.          *
  265.          * <p>In order to view the ephemeris for this satellite as a {@link Propagator}
  266.          * several conditions must be met. An Orekit {@link Frame} and {@link TimeScale}
  267.          * must be constructable from the frame and time scale specification in the
  268.          * ephemeris file. This condition is met when {@link EphemerisSegment#getFrame()}
  269.          * and {@link EphemerisSegment#getTimeScale()} return normally. Additionally,
  270.          * {@link #getMu()} must return a valid value. If these conditions are not met an
  271.          * {@link OrekitException} may be thrown by this method or by one of the methods
  272.          * of the returned {@link Propagator}.
  273.          *
  274.          * <p> Each call to this method creates a new propagator.
  275.          *
  276.          * @return a propagator for this ephemeris segment.
  277.          * @throws OrekitException if any of the conditions are not met.
  278.          */
  279.         default BoundedPropagator getPropagator() throws OrekitException {
  280.             return new EphemerisSegmentPropagator(this);
  281.         }

  283.     }

  285. }
Created with JaCoCo 0.7.9.201702052155