TrajectoryStateHistoryMetadata.java

/* Copyright 2002-2024 CS GROUP
 * Licensed to CS GROUP (CS) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * CS licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

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

import java.util.List;

import org.orekit.data.DataContext;
import org.orekit.errors.OrekitException;
import org.orekit.errors.OrekitMessages;
import org.orekit.files.ccsds.definitions.BodyFacade;
import org.orekit.files.ccsds.definitions.CelestialBodyFrame;
import org.orekit.files.ccsds.definitions.FrameFacade;
import org.orekit.files.ccsds.ndm.odm.oem.InterpolationMethod;
import org.orekit.files.ccsds.section.CommentsContainer;
import org.orekit.time.AbsoluteDate;
import org.orekit.utils.units.Unit;

/** Metadata for trajectory state history.
 * @author Luc Maisonobe
 * @since 11.0
 */
public class TrajectoryStateHistoryMetadata extends CommentsContainer {

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    /** Data context.
     * @since 12.0
     */
    private final DataContext dataContext;

    /** Simple constructor.
     * @param epochT0 T0 epoch from file metadata
     * @param dataContext data context
     */
    public TrajectoryStateHistoryMetadata(final AbsoluteDate epochT0, final DataContext dataContext) {
        // we don't call the setXxx() methods in order to avoid
        // calling refuseFurtherComments as a side effect
        trajBasis           = "PREDICTED";
        interpolationMethod = DEFAULT_INTERPOLATION_METHOD;
        interpolationDegree = DEFAULT_INTERPOLATION_DEGREE;
        orbAveraging        = "OSCULATING";
        center              = new BodyFacade("EARTH",
                                             dataContext.getCelestialBodies().getEarth());
        trajReferenceFrame  = new FrameFacade(dataContext.getFrames().getICRF(),
                                              CelestialBodyFrame.ICRF, null, null,
                                              CelestialBodyFrame.ICRF.name());
        trajFrameEpoch      = epochT0;
        trajType            = OrbitElementsType.CARTPV;
        orbRevNum           = -1;
        orbRevNumBasis      = -1;

        this.dataContext    = dataContext;

    }

    /** {@inheritDoc} */
    @Override
    public void validate(final double version) {
        checkMandatoryEntriesExceptOrbitsCounter(version);
        if (orbRevNum >= 0 && orbRevNumBasis < 0) {
            throw new OrekitException(OrekitMessages.UNINITIALIZED_VALUE_FOR_KEY,
                                      TrajectoryStateHistoryMetadataKey.ORB_REVNUM_BASIS.name());
        }
    }

    /** Check is mandatory entries EXCEPT orbits counters have been initialized.
     * <p>
     * This method should throw an exception if some mandatory entry is missing
     * </p>
     * @param version format version
     */
    private void checkMandatoryEntriesExceptOrbitsCounter(final double version) {
        super.validate(version);
        if (trajType != OrbitElementsType.CARTP   &&
            trajType != OrbitElementsType.CARTPV  &&
            trajType != OrbitElementsType.CARTPVA) {
            checkNotNull(orbAveraging, TrajectoryStateHistoryMetadataKey.ORB_AVERAGING.name());
        }
        if (trajUnits != null) {
            Unit.ensureCompatible(trajType.toString(), trajType.getUnits(), false, trajUnits);
        }
    }

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

        if (original == null) {
            // no trajectory ID at all
            return null;
        }

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

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

        return prefix + newIndex;

    }

    /** Get trajectory identification number.
     * @return trajectory identification number
     */
    public String getTrajID() {
        return trajID;
    }

    /** Set trajectory identification number.
     * @param trajID trajectory identification number
     */
    public void setTrajID(final String trajID) {
        refuseFurtherComments();
        this.trajID = trajID;
    }

    /** Get identification number of previous trajectory.
     * @return identification number of previous trajectory
     */
    public String getTrajPrevID() {
        return trajPrevID;
    }

    /** Set identification number of previous trajectory.
     * @param trajPrevID identification number of previous trajectory
     */
    public void setTrajPrevID(final String trajPrevID) {
        refuseFurtherComments();
        this.trajPrevID = trajPrevID;
    }

    /** Get identification number of next trajectory.
     * @return identification number of next trajectory
     */
    public String getTrajNextID() {
        return trajNextID;
    }

    /** Set identification number of next trajectory.
     * @param trajNextID identification number of next trajectory
     */
    public void setTrajNextID(final String trajNextID) {
        refuseFurtherComments();
        this.trajNextID = trajNextID;
    }

    /** Get basis of this trajectory state time history data.
     * @return basis of this trajectory state time history data
     */
    public String getTrajBasis() {
        return trajBasis;
    }

    /** Set basis of this trajectory state time history data.
     * @param trajBasis basis of this trajectory state time history data
     */
    public void setTrajBasis(final String trajBasis) {
        refuseFurtherComments();
        this.trajBasis = trajBasis;
    }

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

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

    /** Get the interpolation method to be used.
     * @return the interpolation method
     */
    public InterpolationMethod getInterpolationMethod() {
        return interpolationMethod;
    }

    /** Set the interpolation method to be used.
     * @param interpolationMethod the interpolation method to be set
     */
    public void setInterpolationMethod(final InterpolationMethod interpolationMethod) {
        refuseFurtherComments();
        this.interpolationMethod = interpolationMethod;
    }

    /** Get the interpolation degree.
     * @return the interpolation degree
     */
    public int getInterpolationDegree() {
        return interpolationDegree;
    }

    /** Set the interpolation degree.
     * @param interpolationDegree the interpolation degree to be set
     */
    public void setInterpolationDegree(final int interpolationDegree) {
        refuseFurtherComments();
        this.interpolationDegree = interpolationDegree;
    }

    /** Get the orbit propagator used to generate this trajectory.
     * @return orbit propagator used to generate this trajectory
     * @since 11.2
     */
    public String getPropagator() {
        return propagator;
    }

    /** Set the orbit propagator used to generate this trajectory.
     * @param propagator orbit propagator used to generate this trajectory
     * @since 11.2
     */
    public void setPropagator(final String propagator) {
        refuseFurtherComments();
        this.propagator = propagator;
    }

    /** Get the origin of reference frame.
     * @return the origin of reference frame.
     */
    public BodyFacade getCenter() {
        return center;
    }

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

    /** Get reference frame of the trajectory.
     * @return reference frame of the trajectory
     */
    public FrameFacade getTrajReferenceFrame() {
        return trajReferenceFrame;
    }

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

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

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

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

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

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

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

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

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

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

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

    /** Get type of averaging (Osculating, mean Brouwer, other.
     * @return type of averaging (Osculating, mean Brouwer, other)
     */
    public String getOrbAveraging() {
        return orbAveraging;
    }

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

    /** Get trajectory element set type.
     * @return trajectory element set type
     */
    public OrbitElementsType getTrajType() {
        return trajType;
    }

    /** Set trajectory element set type.
     * @param trajType trajectory element set type
     */
    public void setTrajType(final OrbitElementsType trajType) {
        refuseFurtherComments();
        this.trajType = trajType;
    }

    /** Get trajectory element set units.
     * @return trajectory element set units
     */
    public List<Unit> getTrajUnits() {
        return trajUnits;
    }

    /** Set trajectory element set units.
     * @param trajUnits trajectory element set units
     */
    public void setTrajUnits(final List<Unit> trajUnits) {
        refuseFurtherComments();
        this.trajUnits = trajUnits;
    }

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

        checkMandatoryEntriesExceptOrbitsCounter(version);

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

        // copy comments
        for (String comment : getComments()) {
            copy.addComment(comment);
        }

        // copy metadata
        copy.setTrajPrevID(getTrajPrevID());
        copy.setTrajID(getTrajID());
        copy.setTrajNextID(getTrajNextID());
        copy.setTrajBasis(getTrajBasis());
        copy.setTrajBasisID(getTrajBasisID());
        copy.setInterpolationMethod(getInterpolationMethod());
        copy.setInterpolationDegree(getInterpolationDegree());
        copy.setPropagator(getPropagator());
        copy.setCenter(getCenter());
        copy.setTrajReferenceFrame(getTrajReferenceFrame());
        copy.setTrajFrameEpoch(getTrajFrameEpoch());
        copy.setOrbRevNumBasis(getOrbRevNumBasis());
        copy.setOrbAveraging(getOrbAveraging());
        copy.setTrajType(getTrajType());
        copy.setTrajUnits(getTrajUnits());

        return copy;

    }

}