TrajectoryStateHistoryMetadata.java

  1. /* Copyright 2002-2025 CS GROUP
  2.  * Licensed to CS GROUP (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.  */

  18. package org.orekit.files.ccsds.ndm.odm.ocm;

  20. import java.util.List;

  22. import org.orekit.data.DataContext;
  23. import org.orekit.errors.OrekitException;
  24. import org.orekit.errors.OrekitMessages;
  25. import org.orekit.files.ccsds.definitions.BodyFacade;
  26. import org.orekit.files.ccsds.definitions.CelestialBodyFrame;
  27. import org.orekit.files.ccsds.definitions.FrameFacade;
  28. import org.orekit.files.ccsds.ndm.odm.oem.InterpolationMethod;
  29. import org.orekit.files.ccsds.section.CommentsContainer;
  30. import org.orekit.time.AbsoluteDate;
  31. import org.orekit.utils.units.Unit;

  33. /** Metadata for trajectory state history.
  34.  * <p>
  35.  * Beware that the Orekit getters and setters all rely on SI units. The parsers
  36.  * and writers take care of converting these SI units into CCSDS mandatory units.
  37.  * The {@link org.orekit.utils.units.Unit Unit} class provides useful
  38.  * {@link org.orekit.utils.units.Unit#fromSI(double) fromSi} and
  39.  * {@link org.orekit.utils.units.Unit#toSI(double) toSI} methods in case the callers
  40.  * already use CCSDS units instead of the API SI units. The general-purpose
  41.  * {@link org.orekit.utils.units.Unit Unit} class (without an 's') and the
  42.  * CCSDS-specific {@link org.orekit.files.ccsds.definitions.Units Units} class
  43.  * (with an 's') also provide some predefined units. These predefined units and the
  44.  * {@link org.orekit.utils.units.Unit#fromSI(double) fromSi} and
  45.  * {@link org.orekit.utils.units.Unit#toSI(double) toSI} conversion methods are indeed
  46.  * what the parsers and writers use for the conversions.
  47.  * </p>
  48.  * @author Luc Maisonobe
  49.  * @since 11.0
  50.  */
  51. public class TrajectoryStateHistoryMetadata extends CommentsContainer {

  53.     /** Default interpolation method.
  54.      * @since 12.0
  55.      */
  56.     public static final InterpolationMethod DEFAULT_INTERPOLATION_METHOD = InterpolationMethod.HERMITE;

  58.     /** Default interpolation degree.
  59.      * @since 12.0
  60.      */
  61.     public static final int DEFAULT_INTERPOLATION_DEGREE = 3;

  63.     /** Trajectory identification number. */
  64.     private String trajID;

  66.     /** Identification number of previous trajectory. */
  67.     private String trajPrevID;

  69.     /** Identification number of next trajectory. */
  70.     private String trajNextID;

  72.     /** Basis of this trajectory state time history data. */
  73.     private String trajBasis;

  75.     /** Identification number of the orbit determination or simulation upon which this trajectory is based. */
  76.     private String trajBasisID;

  78.     /** Interpolation method. */
  79.     private InterpolationMethod interpolationMethod;

  81.     /** Interpolation degree. */
  82.     private int interpolationDegree;

  84.     /** Orbit propagator used to generate this trajectory.
  85.      * @since 11.2
  86.      */
  87.     private String propagator;

  89.     /** Origin of reference frame. */
  90.     private BodyFacade center;

  92.     /** Reference frame of the trajectory. */
  93.     private FrameFacade trajReferenceFrame;

  95.     /** Epoch of the trajectory reference frame. */
  96.     private AbsoluteDate trajFrameEpoch;

  98.     /** Start of useable time span covered by ephemerides data, it may be
  99.      * necessary to allow for proper interpolation. */
  100.     private AbsoluteDate useableStartTime;

  102.     /** End of useable time span covered by ephemerides data, it may be
  103.      * necessary to allow for proper interpolation. */
  104.     private AbsoluteDate useableStopTime;

  106.     /** Integer orbit revolution number. */
  107.     private int orbRevNum;

  109.     /** Basis for orbit revolution counter (i.e is first launch/deployment on orbit 0 or 1). */
  110.     private int orbRevNumBasis;

  112.     /** Trajectory element set type. */
  113.     private OrbitElementsType trajType;

  115.     /** Type of averaging (Osculating, mean Brouwer, other...). */
  116.     private String orbAveraging;

  118.     /** Units of trajectory element set. */
  119.     private List<Unit> trajUnits;

  121.     /** Data context.
  122.      * @since 12.0
  123.      */
  124.     private final DataContext dataContext;

  126.     /** Simple constructor.
  127.      * @param epochT0 T0 epoch from file metadata
  128.      * @param dataContext data context
  129.      */
  130.     public TrajectoryStateHistoryMetadata(final AbsoluteDate epochT0, final DataContext dataContext) {
  131.         // we don't call the setXxx() methods in order to avoid
  132.         // calling refuseFurtherComments as a side effect
  133.         trajBasis           = null;
  134.         interpolationMethod = DEFAULT_INTERPOLATION_METHOD;
  135.         interpolationDegree = DEFAULT_INTERPOLATION_DEGREE;
  136.         orbAveraging        = "OSCULATING";
  137.         center              = new BodyFacade("EARTH",
  138.                                              dataContext.getCelestialBodies().getEarth());
  139.         trajReferenceFrame  = new FrameFacade(dataContext.getFrames().getICRF(),
  140.                                               CelestialBodyFrame.ICRF, null, null,
  141.                                               CelestialBodyFrame.ICRF.name());
  142.         trajFrameEpoch      = epochT0;
  143.         trajType            = OrbitElementsType.CARTPV;
  144.         orbRevNum           = -1;
  145.         orbRevNumBasis      = -1;

  147.         this.dataContext    = dataContext;

  149.     }

  151.     /** {@inheritDoc} */
  152.     @Override
  153.     public void validate(final double version) {
  154.         checkMandatoryEntriesExceptOrbitsCounter(version);
  155.         if (orbRevNum >= 0 && orbRevNumBasis < 0) {
  156.             throw new OrekitException(OrekitMessages.UNINITIALIZED_VALUE_FOR_KEY,
  157.                                       TrajectoryStateHistoryMetadataKey.ORB_REVNUM_BASIS.name());
  158.         }
  159.     }

  161.     /** Check is mandatory entries EXCEPT orbits counters have been initialized.
  162.      * <p>
  163.      * This method should throw an exception if some mandatory entry is missing
  164.      * </p>
  165.      * @param version format version
  166.      */
  167.     private void checkMandatoryEntriesExceptOrbitsCounter(final double version) {
  168.         super.validate(version);
  169.         if (trajType != OrbitElementsType.CARTP   &&
  170.             trajType != OrbitElementsType.CARTPV  &&
  171.             trajType != OrbitElementsType.CARTPVA) {
  172.             checkNotNull(orbAveraging, TrajectoryStateHistoryMetadataKey.ORB_AVERAGING.name());
  173.         }
  174.         if (trajUnits != null) {
  175.             Unit.ensureCompatible(trajType.toString(), trajType.getUnits(), false, trajUnits);
  176.         }
  177.     }

  179.     /** Increments a trajectory ID.
  180.      * <p>
  181.      * The trajectory blocks metadata contains three identifiers ({@code TRAJ_ID},
  182.      * {@code TRAJ_PREV_ID}, {@code TRAJ_NEXT_ID}) that link the various blocks together.
  183.      * This helper method allows to update one identifier based on the value of another
  184.      * identifier. The update is performed by looking for an integer suffix at the end
  185.      * of the {@code original} identifier and incrementing it by one, taking care to use
  186.      * at least the same number of digits. If for example the original identifier is set
  187.      * to {@code trajectory 037}, then the updated identifier will be {@code trajectory 038}.
  188.      * </p>
  189.      * <p>
  190.      * This helper function is intended to be used by ephemeris generators like {@link EphemerisOcmWriter}
  191.      * and {@link StreamingOcmWriter}, allowing users to call only {@link #setTrajBasisID(String)}
  192.      * in the trajectory metadata template. The ephemeris generators call {@code
  193.      * template.setTrajNextID(TrajectoryStateHistoryMetadata.incrementTrajID(template.getTrajID()))}
  194.      * before generating each trajectory block and call both {@code template.setTrajPrevID(template.getTrajID()))}
  195.      * and {@code template.setTrajID(template.getTrajNextID()))} after having generated each block.
  196.      * </p>
  197.      * @param original original ID (may be null)
  198.      * @return incremented ID, or null if original was null
  199.      */
  200.     public static String incrementTrajID(final String original) {

  202.         if (original == null) {
  203.             // no trajectory ID at all
  204.             return null;
  205.         }

  207.         // split the ID into prefix and numerical index
  208.         int end = original.length();
  209.         while (end > 0 && Character.isDigit(original.charAt(end - 1))) {
  210.             --end;
  211.         }
  212.         final String prefix   = original.substring(0, end);
  213.         final int    index    = end < original.length() ? Integer.parseInt(original.substring(end)) : 0;

  215.         // build offset index, taking care to use at least the same number of digits
  216.         final String newIndex = String.format(String.format("%%0%dd", original.length() - end),
  217.                                               index + 1);

  219.         return prefix + newIndex;

  221.     }

  223.     /** Get trajectory identification number.
  224.      * @return trajectory identification number
  225.      */
  226.     public String getTrajID() {
  227.         return trajID;
  228.     }

  230.     /** Set trajectory identification number.
  231.      * @param trajID trajectory identification number
  232.      */
  233.     public void setTrajID(final String trajID) {
  234.         refuseFurtherComments();
  235.         this.trajID = trajID;
  236.     }

  238.     /** Get identification number of previous trajectory.
  239.      * @return identification number of previous trajectory
  240.      */
  241.     public String getTrajPrevID() {
  242.         return trajPrevID;
  243.     }

  245.     /** Set identification number of previous trajectory.
  246.      * @param trajPrevID identification number of previous trajectory
  247.      */
  248.     public void setTrajPrevID(final String trajPrevID) {
  249.         refuseFurtherComments();
  250.         this.trajPrevID = trajPrevID;
  251.     }

  253.     /** Get identification number of next trajectory.
  254.      * @return identification number of next trajectory
  255.      */
  256.     public String getTrajNextID() {
  257.         return trajNextID;
  258.     }

  260.     /** Set identification number of next trajectory.
  261.      * @param trajNextID identification number of next trajectory
  262.      */
  263.     public void setTrajNextID(final String trajNextID) {
  264.         refuseFurtherComments();
  265.         this.trajNextID = trajNextID;
  266.     }

  268.     /** Get basis of this trajectory state time history data.
  269.      * @return basis of this trajectory state time history data
  270.      */
  271.     public String getTrajBasis() {
  272.         return trajBasis;
  273.     }

  275.     /** Set basis of this trajectory state time history data.
  276.      * @param trajBasis basis of this trajectory state time history data
  277.      */
  278.     public void setTrajBasis(final String trajBasis) {
  279.         refuseFurtherComments();
  280.         this.trajBasis = trajBasis;
  281.     }

  283.     /** Get identification number of the orbit determination or simulation upon which this trajectory is based.
  284.      * @return identification number of the orbit determination or simulation upon which this trajectory is based
  285.      */
  286.     public String getTrajBasisID() {
  287.         return trajBasisID;
  288.     }

  290.     /** Set identification number of the orbit determination or simulation upon which this trajectory is based.
  291.      * @param trajBasisID identification number of the orbit determination or simulation upon which this trajectory is based
  292.      */
  293.     public void setTrajBasisID(final String trajBasisID) {
  294.         refuseFurtherComments();
  295.         this.trajBasisID = trajBasisID;
  296.     }

  298.     /** Get the interpolation method to be used.
  299.      * @return the interpolation method
  300.      */
  301.     public InterpolationMethod getInterpolationMethod() {
  302.         return interpolationMethod;
  303.     }

  305.     /** Set the interpolation method to be used.
  306.      * @param interpolationMethod the interpolation method to be set
  307.      */
  308.     public void setInterpolationMethod(final InterpolationMethod interpolationMethod) {
  309.         refuseFurtherComments();
  310.         this.interpolationMethod = interpolationMethod;
  311.     }

  313.     /** Get the interpolation degree.
  314.      * @return the interpolation degree
  315.      */
  316.     public int getInterpolationDegree() {
  317.         return interpolationDegree;
  318.     }

  320.     /** Set the interpolation degree.
  321.      * @param interpolationDegree the interpolation degree to be set
  322.      */
  323.     public void setInterpolationDegree(final int interpolationDegree) {
  324.         refuseFurtherComments();
  325.         this.interpolationDegree = interpolationDegree;
  326.     }

  328.     /** Get the orbit propagator used to generate this trajectory.
  329.      * @return orbit propagator used to generate this trajectory
  330.      * @since 11.2
  331.      */
  332.     public String getPropagator() {
  333.         return propagator;
  334.     }

  336.     /** Set the orbit propagator used to generate this trajectory.
  337.      * @param propagator orbit propagator used to generate this trajectory
  338.      * @since 11.2
  339.      */
  340.     public void setPropagator(final String propagator) {
  341.         refuseFurtherComments();
  342.         this.propagator = propagator;
  343.     }

  345.     /** Get the origin of reference frame.
  346.      * @return the origin of reference frame.
  347.      */
  348.     public BodyFacade getCenter() {
  349.         return center;
  350.     }

  352.     /** Set the origin of reference frame.
  353.      * @param center origin of reference frame to be set
  354.      */
  355.     public void setCenter(final BodyFacade center) {
  356.         refuseFurtherComments();
  357.         this.center = center;
  358.     }

  360.     /** Get reference frame of the trajectory.
  361.      * @return reference frame of the trajectory
  362.      */
  363.     public FrameFacade getTrajReferenceFrame() {
  364.         return trajReferenceFrame;
  365.     }

  367.     /** Set reference frame of the trajectory.
  368.      * @param trajReferenceFrame the reference frame to be set
  369.      */
  370.     public void setTrajReferenceFrame(final FrameFacade trajReferenceFrame) {
  371.         refuseFurtherComments();
  372.         this.trajReferenceFrame = trajReferenceFrame;
  373.     }

  375.     /** Get epoch of the {@link #getTrajReferenceFrame() trajectory reference frame}.
  376.      * @return epoch of the {@link #getTrajReferenceFrame() trajectory reference frame}
  377.      */
  378.     public AbsoluteDate getTrajFrameEpoch() {
  379.         return trajFrameEpoch;
  380.     }

  382.     /** Set epoch of the {@link #getTrajReferenceFrame() trajectory reference frame}.
  383.      * @param trajFrameEpoch epoch of the {@link #getTrajReferenceFrame() trajectory reference frame}
  384.      */
  385.     public void setTrajFrameEpoch(final AbsoluteDate trajFrameEpoch) {
  386.         refuseFurtherComments();
  387.         this.trajFrameEpoch = trajFrameEpoch;
  388.     }

  390.     /** Get start of useable time span covered by ephemerides data, it may be
  391.      * necessary to allow for proper interpolation.
  392.      * @return the useable start time
  393.      */
  394.     public AbsoluteDate getUseableStartTime() {
  395.         return useableStartTime;
  396.     }

  398.     /** Set start of useable time span covered by ephemerides data, it may be
  399.      * necessary to allow for proper interpolation.
  400.      * @param useableStartTime the time to be set
  401.      */
  402.     public void setUseableStartTime(final AbsoluteDate useableStartTime) {
  403.         refuseFurtherComments();
  404.         this.useableStartTime = useableStartTime;
  405.     }

  407.     /** Get end of useable time span covered by ephemerides data, it may be
  408.      * necessary to allow for proper interpolation.
  409.      * @return the useable stop time
  410.      */
  411.     public AbsoluteDate getUseableStopTime() {
  412.         return useableStopTime;
  413.     }

  415.     /** Set end of useable time span covered by ephemerides data, it may be
  416.      * necessary to allow for proper interpolation.
  417.      * @param useableStopTime the time to be set
  418.      */
  419.     public void setUseableStopTime(final AbsoluteDate useableStopTime) {
  420.         refuseFurtherComments();
  421.         this.useableStopTime = useableStopTime;
  422.     }

  424.     /** Get the integer orbit revolution number.
  425.      * @return integer orbit revolution number (-1 if not set)
  426.      */
  427.     public int getOrbRevNum() {
  428.         return orbRevNum;
  429.     }

  431.     /** Set the integer orbit revolution number.
  432.      * @param orbRevNum integer orbit revolution number
  433.      */
  434.     public void setOrbRevNum(final int orbRevNum) {
  435.         this.orbRevNum = orbRevNum;
  436.     }

  438.     /** Get the basis for orbit revolution number.
  439.      * <p>
  440.      * This specifies if first launch/deployment is on orbit 0 or 1.
  441.      * </p>
  442.      * @return basis for orbit revolution number (-1 if not set)
  443.      */
  444.     public int getOrbRevNumBasis() {
  445.         return orbRevNumBasis;
  446.     }

  448.     /** Set the basis for orbit revolution number.
  449.      * <p>
  450.      * This specifies if first launch/deployment is on orbit 0 or 1.
  451.      * </p>
  452.      * @param orbRevNumBasis basis for orbit revolution number
  453.      */
  454.     public void setOrbRevNumBasis(final int orbRevNumBasis) {
  455.         this.orbRevNumBasis = orbRevNumBasis;
  456.     }

  458.     /** Get type of averaging (Osculating, mean Brouwer, other.
  459.      * @return type of averaging (Osculating, mean Brouwer, other)
  460.      */
  461.     public String getOrbAveraging() {
  462.         return orbAveraging;
  463.     }

  465.     /** Set type of averaging (Osculating, mean Brouwer, other.
  466.      * @param orbAveraging type of averaging (Osculating, mean Brouwer, other).
  467.      */
  468.     public void setOrbAveraging(final String orbAveraging) {
  469.         refuseFurtherComments();
  470.         this.orbAveraging = orbAveraging;
  471.     }

  473.     /** Get trajectory element set type.
  474.      * @return trajectory element set type
  475.      */
  476.     public OrbitElementsType getTrajType() {
  477.         return trajType;
  478.     }

  480.     /** Set trajectory element set type.
  481.      * @param trajType trajectory element set type
  482.      */
  483.     public void setTrajType(final OrbitElementsType trajType) {
  484.         refuseFurtherComments();
  485.         this.trajType = trajType;
  486.     }

  488.     /** Get trajectory element set units.
  489.      * @return trajectory element set units
  490.      */
  491.     public List<Unit> getTrajUnits() {
  492.         return trajUnits;
  493.     }

  495.     /** Set trajectory element set units.
  496.      * @param trajUnits trajectory element set units
  497.      */
  498.     public void setTrajUnits(final List<Unit> trajUnits) {
  499.         refuseFurtherComments();
  500.         this.trajUnits = trajUnits;
  501.     }

  503.     /** Copy the instance, making sure mandatory fields have been initialized.
  504.      * <p>
  505.      * Dates and orbit counter are not copied.
  506.      * </p>
  507.      * @param version format version
  508.      * @return a new copy
  509.      * @since 12.0
  510.      */
  511.     public TrajectoryStateHistoryMetadata copy(final double version) {

  513.         checkMandatoryEntriesExceptOrbitsCounter(version);

  515.         // allocate new instance
  516.         final TrajectoryStateHistoryMetadata copy = new TrajectoryStateHistoryMetadata(trajFrameEpoch, dataContext);

  518.         // copy comments
  519.         for (String comment : getComments()) {
  520.             copy.addComment(comment);
  521.         }

  523.         // copy metadata
  524.         copy.setTrajPrevID(getTrajPrevID());
  525.         copy.setTrajID(getTrajID());
  526.         copy.setTrajNextID(getTrajNextID());
  527.         copy.setTrajBasis(getTrajBasis());
  528.         copy.setTrajBasisID(getTrajBasisID());
  529.         copy.setInterpolationMethod(getInterpolationMethod());
  530.         copy.setInterpolationDegree(getInterpolationDegree());
  531.         copy.setPropagator(getPropagator());
  532.         copy.setCenter(getCenter());
  533.         copy.setTrajReferenceFrame(getTrajReferenceFrame());
  534.         copy.setTrajFrameEpoch(getTrajFrameEpoch());
  535.         copy.setOrbRevNumBasis(getOrbRevNumBasis());
  536.         copy.setOrbAveraging(getOrbAveraging());
  537.         copy.setTrajType(getTrajType());
  538.         copy.setTrajUnits(getTrajUnits());

  540.         return copy;

  542.     }

  544. }
Created with JaCoCo 0.8.12.202403310830