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  package org.orekit.utils;
18  
19  import org.hipparchus.analysis.differentiation.Derivative;
20  import org.hipparchus.geometry.euclidean.threed.FieldVector3D;
21  import org.hipparchus.geometry.euclidean.threed.Vector3D;
22  import org.orekit.annotation.DefaultDataContext;
23  import org.orekit.errors.OrekitIllegalArgumentException;
24  import org.orekit.errors.OrekitMessages;
25  import org.orekit.frames.Frame;
26  import org.orekit.frames.Transform;
27  import org.orekit.time.AbsoluteDate;
28  import org.orekit.time.TimeOffset;
29  import org.orekit.time.TimeScale;
30  import org.orekit.time.TimeScalesFactory;
31  import org.orekit.time.TimeStamped;
32  
33  /** Position - Velocity - Acceleration linked to a date and a frame.
34   */
35  public class AbsolutePVCoordinates
36          implements ShiftablePVCoordinatesHolder<AbsolutePVCoordinates>, TimeStamped, PVCoordinatesProvider {
37  
38      /** Frame in which are defined the coordinates. */
39      private final Frame frame;
40  
41      /** Position-velocity-acceleration vector. */
42      private final TimeStampedPVCoordinates timeStampedPVCoordinates;
43  
44      /** Build from position, velocity, acceleration.
45       * @param frame the frame in which the coordinates are defined
46       * @param date coordinates date
47       * @param position the position vector (m)
48       * @param velocity the velocity vector (m/s)
49       * @param acceleration the acceleration vector (m/sÂý)
50       */
51      public AbsolutePVCoordinates(final Frame frame, final AbsoluteDate date,
52                                   final Vector3D position, final Vector3D velocity, final Vector3D acceleration) {
53          this.timeStampedPVCoordinates = new TimeStampedPVCoordinates(date, position, velocity, acceleration);
54          this.frame = frame;
55      }
56  
57      /** Build from position and velocity. Acceleration is set to zero.
58       * @param frame the frame in which the coordinates are defined
59       * @param date coordinates date
60       * @param position the position vector (m)
61       * @param velocity the velocity vector (m/s)
62       */
63      public AbsolutePVCoordinates(final Frame frame, final AbsoluteDate date,
64                                   final Vector3D position,
65                                   final Vector3D velocity) {
66          this(frame, date, position, velocity, Vector3D.ZERO);
67      }
68  
69      /** Build from frame, date and PVA coordinates.
70       * @param frame the frame in which the coordinates are defined
71       * @param date date of the coordinates
72       * @param pva TimeStampedPVCoordinates
73       */
74      public AbsolutePVCoordinates(final Frame frame, final AbsoluteDate date, final PVCoordinates pva) {
75          this(frame, new TimeStampedPVCoordinates(date, pva));
76      }
77  
78      /** Build from frame and TimeStampedPVCoordinates.
79       * @param frame the frame in which the coordinates are defined
80       * @param pva TimeStampedPVCoordinates
81       */
82      public AbsolutePVCoordinates(final Frame frame, final TimeStampedPVCoordinates pva) {
83          this.timeStampedPVCoordinates = pva;
84          this.frame = frame;
85      }
86  
87      /** Multiplicative constructor.
88       * <p>Build a AbsolutePVCoordinates from another one and a scale factor.</p>
89       * <p>The TimeStampedPVCoordinates built will be a * AbsPva</p>
90       * @param date date of the built coordinates
91       * @param a scale factor
92       * @param absPva base (unscaled) AbsolutePVCoordinates
93       */
94      public AbsolutePVCoordinates(final AbsoluteDate date,
95                                   final double a, final AbsolutePVCoordinates absPva) {
96          this(absPva.getFrame(), new TimeStampedPVCoordinates(date, a, absPva.getPVCoordinates()));
97      }
98  
99      /** Subtractive constructor.
100      * <p>Build a relative AbsolutePVCoordinates from a start and an end position.</p>
101      * <p>The AbsolutePVCoordinates built will be end - start.</p>
102      * <p>In case start and end use two different pseudo-inertial frames,
103      * the new AbsolutePVCoordinates arbitrarily be defined in the start frame. </p>
104      * @param date date of the built coordinates
105      * @param start Starting AbsolutePVCoordinates
106      * @param end ending AbsolutePVCoordinates
107      */
108     public AbsolutePVCoordinates(final AbsoluteDate date,
109                                  final AbsolutePVCoordinates start, final AbsolutePVCoordinates end) {
110         this(start.getFrame(), new TimeStampedPVCoordinates(date, start.getPVCoordinates(), end.getPVCoordinates()));
111         ensureIdenticalFrames(start, end);
112     }
113 
114     /** Linear constructor.
115      * <p>Build a AbsolutePVCoordinates from two other ones and corresponding scale factors.</p>
116      * <p>The AbsolutePVCoordinates built will be a1 * u1 + a2 * u2</p>
117      * <p>In case the AbsolutePVCoordinates use different pseudo-inertial frames,
118      * the new AbsolutePVCoordinates arbitrarily be defined in the first frame. </p>
119      * @param date date of the built coordinates
120      * @param a1 first scale factor
121      * @param absPv1 first base (unscaled) AbsolutePVCoordinates
122      * @param a2 second scale factor
123      * @param absPv2 second base (unscaled) AbsolutePVCoordinates
124      */
125     public AbsolutePVCoordinates(final AbsoluteDate date,
126                                  final double a1, final AbsolutePVCoordinates absPv1,
127                                  final double a2, final AbsolutePVCoordinates absPv2) {
128         this(absPv1.getFrame(), new TimeStampedPVCoordinates(date, a1, absPv1.getPVCoordinates(), a2, absPv2.getPVCoordinates()));
129         ensureIdenticalFrames(absPv1, absPv2);
130     }
131 
132     /** Linear constructor.
133      * <p>Build a AbsolutePVCoordinates from three other ones and corresponding scale factors.</p>
134      * <p>The AbsolutePVCoordinates built will be a1 * u1 + a2 * u2 + a3 * u3</p>
135      * <p>In case the AbsolutePVCoordinates use different pseudo-inertial frames,
136      * the new AbsolutePVCoordinates arbitrarily be defined in the first frame. </p>
137      * @param date date of the built coordinates
138      * @param a1 first scale factor
139      * @param absPv1 first base (unscaled) AbsolutePVCoordinates
140      * @param a2 second scale factor
141      * @param absPv2 second base (unscaled) AbsolutePVCoordinates
142      * @param a3 third scale factor
143      * @param absPv3 third base (unscaled) AbsolutePVCoordinates
144      */
145     public AbsolutePVCoordinates(final AbsoluteDate date,
146                                  final double a1, final AbsolutePVCoordinates absPv1,
147                                  final double a2, final AbsolutePVCoordinates absPv2,
148                                  final double a3, final AbsolutePVCoordinates absPv3) {
149         this(absPv1.getFrame(), new TimeStampedPVCoordinates(date, a1, absPv1.getPVCoordinates(), a2,
150                 absPv2.getPVCoordinates(), a3, absPv3.getPVCoordinates()));
151         ensureIdenticalFrames(absPv1, absPv2);
152         ensureIdenticalFrames(absPv1, absPv3);
153     }
154 
155     /** Linear constructor.
156      * <p>Build a AbsolutePVCoordinates from four other ones and corresponding scale factors.</p>
157      * <p>The AbsolutePVCoordinates built will be a1 * u1 + a2 * u2 + a3 * u3 + a4 * u4</p>
158      * <p>In case the AbsolutePVCoordinates use different pseudo-inertial frames,
159      * the new AbsolutePVCoordinates arbitrarily be defined in the first frame. </p>
160      * @param date date of the built coordinates
161      * @param a1 first scale factor
162      * @param absPv1 first base (unscaled) AbsolutePVCoordinates
163      * @param a2 second scale factor
164      * @param absPv2 second base (unscaled) AbsolutePVCoordinates
165      * @param a3 third scale factor
166      * @param absPv3 third base (unscaled) AbsolutePVCoordinates
167      * @param a4 fourth scale factor
168      * @param absPv4 fourth base (unscaled) AbsolutePVCoordinates
169      */
170     public AbsolutePVCoordinates(final AbsoluteDate date,
171                                  final double a1, final AbsolutePVCoordinates absPv1,
172                                  final double a2, final AbsolutePVCoordinates absPv2,
173                                  final double a3, final AbsolutePVCoordinates absPv3,
174                                  final double a4, final AbsolutePVCoordinates absPv4) {
175         this(absPv1.getFrame(), new TimeStampedPVCoordinates(date, a1, absPv1.getPVCoordinates(), a2,
176                 absPv2.getPVCoordinates(), a3, absPv3.getPVCoordinates(), a4, absPv4.getPVCoordinates()));
177         ensureIdenticalFrames(absPv1, absPv2);
178         ensureIdenticalFrames(absPv1, absPv3);
179         ensureIdenticalFrames(absPv1, absPv4);
180     }
181 
182     /** Builds a AbsolutePVCoordinates triplet from  a {@link FieldVector3D}&lt;{@link Derivative}&gt;.
183      * <p>
184      * The vector components must have time as their only derivation parameter and
185      * have consistent derivation orders.
186      * </p>
187      * @param frame the frame in which the parameters are defined
188      * @param date date of the built coordinates
189      * @param p vector with time-derivatives embedded within the coordinates
190      * @param <U> type of the derivative
191      */
192     public <U extends Derivative<U>> AbsolutePVCoordinates(final Frame frame, final AbsoluteDate date,
193                                                            final FieldVector3D<U> p) {
194         this(frame, new TimeStampedPVCoordinates(date, p));
195     }
196 
197     /** Ensure that the frames from two AbsolutePVCoordinates are identical.
198      * @param absPv1 first AbsolutePVCoordinates
199      * @param absPv2 first AbsolutePVCoordinates
200      * @throws OrekitIllegalArgumentException if frames are different
201      */
202     private static void ensureIdenticalFrames(final AbsolutePVCoordinates absPv1, final AbsolutePVCoordinates absPv2)
203         throws OrekitIllegalArgumentException {
204         if (!absPv1.frame.equals(absPv2.frame)) {
205             throw new OrekitIllegalArgumentException(OrekitMessages.INCOMPATIBLE_FRAMES,
206                                                      absPv1.frame.getName(), absPv2.frame.getName());
207         }
208     }
209 
210     /** Get a time-shifted state.
211      * <p>
212      * The state can be slightly shifted to close dates. This shift is based on
213      * a simple Taylor expansion. It is <em>not</em> intended as a replacement for
214      * proper orbit propagation (it is not even Keplerian!) but should be sufficient
215      * for either small time shifts or coarse accuracy.
216      * </p>
217      * @param dt time shift in seconds
218      * @return a new state, shifted with respect to the instance (which is immutable)
219      */
220     public AbsolutePVCoordinates shiftedBy(final double dt) {
221         final TimeStampedPVCoordinates spv = timeStampedPVCoordinates.shiftedBy(dt);
222         return new AbsolutePVCoordinates(frame, spv);
223     }
224 
225     /** Get a time-shifted state.
226      * <p>
227      * The state can be slightly shifted to close dates. This shift is based on
228      * a simple Taylor expansion. It is <em>not</em> intended as a replacement for
229      * proper orbit propagation (it is not even Keplerian!) but should be sufficient
230      * for either small time shifts or coarse accuracy.
231      * </p>
232      * @param dt time shift in seconds
233      * @return a new state, shifted with respect to the instance (which is immutable)
234      * @since 13.0
235      */
236     @Override
237     public AbsolutePVCoordinates shiftedBy(final TimeOffset dt) {
238         final TimeStampedPVCoordinates spv = timeStampedPVCoordinates.shiftedBy(dt);
239         return new AbsolutePVCoordinates(frame, spv);
240     }
241 
242     /** Create a local provider using simply Taylor expansion through {@link #shiftedBy(double)}.
243      * <p>
244      * The time evolution is based on a simple Taylor expansion. It is <em>not</em> intended as a
245      * replacement for proper orbit propagation (it is not even Keplerian!) but should be sufficient
246      * for either small time shifts or coarse accuracy.
247      * </p>
248      * @return provider based on Taylor expansion, for small time shifts around instance date
249      */
250     public PVCoordinatesProvider toTaylorProvider() {
251         return this;
252     }
253 
254     /** Get the frame in which the coordinates are defined.
255      * @return frame in which the coordinates are defined
256      */
257     public Frame getFrame() {
258         return frame;
259     }
260 
261     /** {@inheritDoc} */
262     @Override
263     public AbsoluteDate getDate() {
264         return getPVCoordinates().getDate();
265     }
266 
267     /** Get the TimeStampedPVCoordinates.
268      * @return TimeStampedPVCoordinates
269      */
270     public TimeStampedPVCoordinates getPVCoordinates() {
271         return timeStampedPVCoordinates;
272     }
273 
274     /**
275      * Method returning the position vector in a specific frame.
276      * @param outputFrame target frame
277      * @return position vector
278      */
279     public Vector3D getPosition(final Frame outputFrame) {
280         return getPosition(getDate(), outputFrame);
281     }
282 
283     /** {@inheritDoc} */
284     @Override
285     public Vector3D getPosition(final AbsoluteDate otherDate, final Frame outputFrame) {
286         final double duration = otherDate.durationFrom(getDate());
287         final Vector3D position = duration == 0. ? getPosition() : getPVCoordinates().positionShiftedBy(duration);
288         if (outputFrame == frame) {
289             return position;
290         }
291         return frame.getStaticTransformTo(outputFrame, otherDate).transformPosition(position);
292     }
293 
294     /**
295      * Method returning the velocity vector in a specific frame.
296      * @param outputFrame target frame
297      * @return velocity vector
298      */
299     public Vector3D getVelocity(final Frame outputFrame) {
300         return getVelocity(getDate(), outputFrame);
301     }
302 
303     /**
304      * Method returning the position-velocity vector in a specific frame.
305      * @param outputFrame target frame
306      * @return position velocity vector
307      */
308     public TimeStampedPVCoordinates getPVCoordinates(final Frame outputFrame) {
309         if (outputFrame == getFrame()) {
310             return getPVCoordinates();
311         }
312         final Transform transform = getFrame().getTransformTo(outputFrame, getDate());
313         return transform.transformPVCoordinates(getPVCoordinates());
314     }
315 
316     /** {@inheritDoc} */
317     @Override
318     public TimeStampedPVCoordinates getPVCoordinates(final AbsoluteDate otherDate, final Frame outputFrame) {
319         final TimeStampedPVCoordinates pv = shiftedBy(otherDate.accurateDurationFrom(getDate())).getPVCoordinates();
320         if (outputFrame == getFrame()) {
321             return pv;
322         }
323         final Transform transform = getFrame().getTransformTo(outputFrame, otherDate);
324         return transform.transformPVCoordinates(pv);
325     }
326 
327     /** {@inheritDoc} */
328     @Override
329     @DefaultDataContext
330     public String toString() {
331         return toString(TimeScalesFactory.getUTC());
332     }
333 
334     /**
335      * Return a string representation of this date, position, velocity, and acceleration.
336      *
337      * @param utc time scale used to print the date.
338      * @return string representation of this.
339      */
340     public String toString(final TimeScale utc) {
341         return timeStampedPVCoordinates.toString(utc);
342     }
343 }
344 
345 
346