1   /* Copyright 2002-2026 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   */
17  
18  package org.orekit.files.ccsds.ndm.odm.ocm;
19  
20  import java.util.ArrayList;
21  import java.util.List;
22  import java.util.Optional;
23  
24  import org.orekit.annotation.Nullable;
25  import org.orekit.files.ccsds.definitions.CcsdsFrameMapper;
26  import org.orekit.files.ccsds.definitions.FrameFacade;
27  import org.orekit.files.ccsds.definitions.OrbitRelativeFrame;
28  import org.orekit.files.ccsds.section.CommentsContainer;
29  import org.orekit.frames.Frame;
30  import org.orekit.time.AbsoluteDate;
31  import org.orekit.utils.units.Unit;
32  
33  /** Metadata for covariance 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 OrbitCovarianceHistoryMetadata extends CommentsContainer {
52  
53      /** For creating a {@link Frame}. */
54      private final CcsdsFrameMapper frameMapper;
55  
56      /** Covariance identification number. */
57      @Nullable
58      private String covID;
59  
60      /** Identification number of previous covariance. */
61      @Nullable
62      private String covPrevID;
63  
64      /** Identification number of next covariance. */
65      @Nullable
66      private String covNextID;
67  
68      /** Basis of this covariance time history data. */
69      @Nullable
70      private String covBasis;
71  
72      /** Identification number of the covariance determination or simulation upon which this covariance is based. */
73      @Nullable
74      private String covBasisID;
75  
76      /** Reference frame of the covariance. */
77      private FrameFacade covReferenceFrame;
78  
79      /** Epoch of the covariance reference frame. */
80      private AbsoluteDate covFrameEpoch;
81  
82      /** Minimum scale factor to apply to achieve realism. */
83      @Nullable
84      private Double covScaleMin;
85  
86      /** Maximum scale factor to apply to achieve realism. */
87      @Nullable
88      private Double covScaleMax;
89  
90      /** Measure of confidence in covariance error matching reality. */
91      @Nullable
92      private Double covConfidence;
93  
94      /** Covariance element set type. */
95      private OrbitElementsType covType;
96  
97      /** Covariance ordering. */
98      private Ordering covOrdering;
99  
100     /** Units of covariance element set. */
101     private List<Unit> covUnits;
102 
103     /**
104      * Simple constructor.
105      *
106      * @param epochT0     T0 epoch from file metadata
107      * @param frameMapper for creating a {@link Frame}.
108      * @since 13.1.5
109      */
110     public OrbitCovarianceHistoryMetadata(final AbsoluteDate epochT0,
111                                           final CcsdsFrameMapper frameMapper) {
112         // we don't call the setXxx() methods in order to avoid
113         // calling refuseFurtherComments as a side effect
114         this.frameMapper  = frameMapper;
115         covReferenceFrame = new FrameFacade(null, null,
116                                             OrbitRelativeFrame.TNW_INERTIAL, null,
117                                             OrbitRelativeFrame.TNW_INERTIAL.name());
118         covUnits      = new ArrayList<>();
119         covFrameEpoch = epochT0;
120         covType       = OrbitElementsType.CARTPV;
121         covOrdering   = Ordering.LTM;
122     }
123 
124     /** {@inheritDoc} */
125     @Override
126     public void validate(final double version) {
127         super.validate(version);
128         if (!covUnits.isEmpty()) {
129             Unit.ensureCompatible(covType.toString(), covType.getUnits(), false, covUnits);
130         }
131     }
132 
133     /** Get covariance identification number.
134      * @return covariance identification number
135      */
136     public Optional<String> getCovID() {
137         return Optional.ofNullable(covID);
138     }
139 
140     /** Set covariance identification number.
141      * @param covID covariance identification number
142      */
143     public void setCovID(final String covID) {
144         refuseFurtherComments();
145         this.covID = covID;
146     }
147 
148     /** Get identification number of previous covariance.
149      * @return identification number of previous covariance
150      */
151     public Optional<String> getCovPrevID() {
152         return Optional.ofNullable(covPrevID);
153     }
154 
155     /** Set identification number of previous covariance.
156      * @param covPrevID identification number of previous covariance
157      */
158     public void setCovPrevID(final String covPrevID) {
159         refuseFurtherComments();
160         this.covPrevID = covPrevID;
161     }
162 
163     /** Get identification number of next covariance.
164      * @return identification number of next covariance
165      */
166     public Optional<String> getCovNextID() {
167         return Optional.ofNullable(covNextID);
168     }
169 
170     /** Set identification number of next covariance.
171      * @param covNextID identification number of next covariance
172      */
173     public void setCovNextID(final String covNextID) {
174         refuseFurtherComments();
175         this.covNextID = covNextID;
176     }
177 
178     /** Get basis of this covariance time history data.
179      * @return basis of this covariance time history data
180      */
181     public Optional<String> getCovBasis() {
182         return Optional.ofNullable(covBasis);
183     }
184 
185     /** Set basis of this covariance time history data.
186      * @param covBasis basis of this covariance time history data
187      */
188     public void setCovBasis(final String covBasis) {
189         refuseFurtherComments();
190         this.covBasis = covBasis;
191     }
192 
193     /** Get identification number of the orbit determination or simulation upon which this covariance is based.
194      * @return identification number of the orbit determination or simulation upon which this covariance is based
195      */
196     public Optional<String> getCovBasisID() {
197         return Optional.ofNullable(covBasisID);
198     }
199 
200     /** Set identification number of the orbit determination or simulation upon which this covariance is based.
201      * @param covBasisID identification number of the orbit determination or simulation upon which this covariance is based
202      */
203     public void setCovBasisID(final String covBasisID) {
204         refuseFurtherComments();
205         this.covBasisID = covBasisID;
206     }
207 
208     /** Get reference frame of the covariance.
209      * @return reference frame of the covariance
210      */
211     public FrameFacade getCovReferenceFrame() {
212         return covReferenceFrame;
213     }
214 
215     /** Set reference frame of the covariance.
216      * @param covReferenceFrame the reference frame to be set
217      */
218     public void setCovReferenceFrame(final FrameFacade covReferenceFrame) {
219         refuseFurtherComments();
220         this.covReferenceFrame = covReferenceFrame;
221     }
222 
223     /** Get epoch of the {@link #getCovReferenceFrame() covariance reference frame}.
224      * @return epoch of the {@link #getCovReferenceFrame() covariance reference frame}
225      */
226     public AbsoluteDate getCovFrameEpoch() {
227         return covFrameEpoch;
228     }
229 
230     /** Set epoch of the {@link #getCovReferenceFrame() covariance reference frame}.
231      * @param covFrameEpoch epoch of the {@link #getCovReferenceFrame() covariance reference frame}
232      */
233     public void setCovFrameEpoch(final AbsoluteDate covFrameEpoch) {
234         refuseFurtherComments();
235         this.covFrameEpoch = covFrameEpoch;
236     }
237 
238     /**
239      * Get the mapping between a CCSDS frame and a {@link Frame}.
240      *
241      * @return the frame mapper.
242      * @since 13.1.5
243      */
244     public CcsdsFrameMapper getFrameMapper() {
245         return frameMapper;
246     }
247 
248     /**
249      * Get the frame in which this covariance matrix is defined. Note that only
250      * the orientation of the returned frame is significant, the position of the
251      * returned frame is irrelevant and should be ignored.
252      *
253      * @return Orekit frame for this covariance history.
254      * @see #getCovReferenceFrame()
255      * @see #getCovFrameEpoch()
256      * @see #getFrameMapper()
257      * @since 13.1.5
258      */
259     public Frame getCovFrame() {
260         return getFrameMapper()
261                 .buildCcsdsFrame(getCovReferenceFrame(), getCovFrameEpoch());
262     }
263 
264     /** Set the minimum scale factor to apply to achieve realism.
265      * @param covScaleMin minimum scale factor to apply to achieve realism
266      */
267     public void setCovScaleMin(final double covScaleMin) {
268         this.covScaleMin = covScaleMin;
269     }
270 
271     /** Get the minimum scale factor to apply to achieve realism.
272      * @return minimum scale factor to apply to achieve realism
273      */
274     public Optional<Double> getCovScaleMin() {
275         return Optional.ofNullable(covScaleMin);
276     }
277 
278     /** Set the maximum scale factor to apply to achieve realism.
279      * @param covScaleMax maximum scale factor to apply to achieve realism
280      */
281     public void setCovScaleMax(final double covScaleMax) {
282         this.covScaleMax = covScaleMax;
283     }
284 
285     /** Get the maximum scale factor to apply to achieve realism.
286      * @return maximum scale factor to apply to achieve realism
287      */
288     public Optional<Double> getCovScaleMax() {
289         return Optional.ofNullable(covScaleMax);
290     }
291 
292     /** Set the measure of confidence in covariance error matching reality.
293      * @param covConfidence measure of confidence in covariance error matching reality
294      */
295     public void setCovConfidence(final double covConfidence) {
296         this.covConfidence = covConfidence;
297     }
298 
299     /** Get the measure of confidence in covariance error matching reality.
300      * @return measure of confidence in covariance error matching reality
301      */
302     public Optional<Double> getCovConfidence() {
303         return Optional.ofNullable(covConfidence);
304     }
305 
306     /** Get covariance element set type.
307      * @return covariance element set type
308      */
309     public OrbitElementsType getCovType() {
310         return covType;
311     }
312 
313     /** Set covariance element set type.
314      * @param covType covariance element set type
315      */
316     public void setCovType(final OrbitElementsType covType) {
317         refuseFurtherComments();
318         this.covType = covType;
319     }
320 
321     /** Get covariance ordering.
322      * @return covariance ordering
323      */
324     public Ordering getCovOrdering() {
325         return covOrdering;
326     }
327 
328     /** Set covariance ordering.
329      * @param covOrdering covariance ordering
330      */
331     public void setCovOrdering(final Ordering covOrdering) {
332         refuseFurtherComments();
333         this.covOrdering = covOrdering;
334     }
335 
336     /** Get covariance element set units.
337      * @return covariance element set units
338      */
339     public List<Unit> getCovUnits() {
340         return covUnits;
341     }
342 
343     /** Set covariance element set units.
344      * @param covUnits covariance element set units
345      */
346     public void setCovUnits(final List<Unit> covUnits) {
347         refuseFurtherComments();
348         this.covUnits = covUnits;
349     }
350 
351 }