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