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}<{@link Derivative}>.
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