1 /* Copyright 2002-2016 CS Systèmes d'Information
2 * Licensed to CS Systèmes d'Information (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.frames;
18
19 import java.io.Serializable;
20
21 import org.orekit.errors.OrekitIllegalArgumentException;
22 import org.orekit.errors.OrekitException;
23 import org.orekit.errors.OrekitMessages;
24 import org.orekit.time.AbsoluteDate;
25
26
27 /** Tridimensional references frames class.
28 *
29 * <h5> Frame Presentation </h5>
30 * <p>This class is the base class for all frames in OREKIT. The frames are
31 * linked together in a tree with some specific frame chosen as the root of the tree.
32 * Each frame is defined by {@link Transform transforms} combining any number
33 * of translations and rotations from a reference frame which is its
34 * parent frame in the tree structure.</p>
35 * <p>When we say a {@link Transform transform} t is <em>from frame<sub>A</sub>
36 * to frame<sub>B</sub></em>, we mean that if the coordinates of some absolute
37 * vector (say the direction of a distant star for example) has coordinates
38 * u<sub>A</sub> in frame<sub>A</sub> and u<sub>B</sub> in frame<sub>B</sub>,
39 * then u<sub>B</sub>={@link
40 * Transform#transformVector(org.apache.commons.math3.geometry.euclidean.threed.Vector3D)
41 * t.transformVector(u<sub>A</sub>)}.
42 * <p>The transforms may be constant or varying, depending on the implementation of
43 * the {@link TransformProvider transform provider} used to define the frame. For simple
44 * fixed transforms, using {@link FixedTransformProvider} is sufficient. For varying
45 * transforms (time-dependent or telemetry-based for example), it may be useful to define
46 * specific implementations of {@link TransformProvider transform provider}.</p>
47 *
48 * @author Guylaine Prat
49 * @author Luc Maisonobe
50 * @author Pascal Parraud
51 */
52 public class Frame implements Serializable {
53
54 /** Serializable UID. */
55 private static final long serialVersionUID = -6981146543760234087L;
56
57 /** Parent frame (only the root frame doesn't have a parent). */
58 private final Frame parent;
59
60 /** Depth of the frame with respect to tree root. */
61 private final int depth;
62
63 /** Provider for transform from parent frame to instance. */
64 private final TransformProvider transformProvider;
65
66 /** Instance name. */
67 private final String name;
68
69 /** Indicator for pseudo-inertial frames. */
70 private final boolean pseudoInertial;
71
72 /** Private constructor used only for the root frame.
73 * @param name name of the frame
74 * @param pseudoInertial true if frame is considered pseudo-inertial
75 * (i.e. suitable for propagating orbit)
76 */
77 private Frame(final String name, final boolean pseudoInertial) {
78 parent = null;
79 depth = 0;
80 transformProvider = new FixedTransformProvider(Transform.IDENTITY);
81 this.name = name;
82 this.pseudoInertial = pseudoInertial;
83 }
84
85 /** Build a non-inertial frame from its transform with respect to its parent.
86 * <p>calling this constructor is equivalent to call
87 * <code>{link {@link #Frame(Frame, Transform, String, boolean)
88 * Frame(parent, transform, name, false)}</code>.</p>
89 * @param parent parent frame (must be non-null)
90 * @param transform transform from parent frame to instance
91 * @param name name of the frame
92 * @exception IllegalArgumentException if the parent frame is null
93 */
94 public Frame(final Frame parent, final Transform transform, final String name)
95 throws IllegalArgumentException {
96 this(parent, transform, name, false);
97 }
98
99 /** Build a non-inertial frame from its transform with respect to its parent.
100 * <p>calling this constructor is equivalent to call
101 * <code>{link {@link #Frame(Frame, Transform, String, boolean)
102 * Frame(parent, transform, name, false)}</code>.</p>
103 * @param parent parent frame (must be non-null)
104 * @param transformProvider provider for transform from parent frame to instance
105 * @param name name of the frame
106 * @exception IllegalArgumentException if the parent frame is null
107 */
108 public Frame(final Frame parent, final TransformProvider transformProvider, final String name)
109 throws IllegalArgumentException {
110 this(parent, transformProvider, name, false);
111 }
112
113 /** Build a frame from its transform with respect to its parent.
114 * <p>The convention for the transform is that it is from parent
115 * frame to instance. This means that the two following frames
116 * are similar:</p>
117 * <pre>
118 * Frame frame1 = new Frame(FramesFactory.getGCRF(), new Transform(t1, t2));
119 * Frame frame2 = new Frame(new Frame(FramesFactory.getGCRF(), t1), t2);
120 * </pre>
121 * @param parent parent frame (must be non-null)
122 * @param transform transform from parent frame to instance
123 * @param name name of the frame
124 * @param pseudoInertial true if frame is considered pseudo-inertial
125 * (i.e. suitable for propagating orbit)
126 * @exception IllegalArgumentException if the parent frame is null
127 */
128 public Frame(final Frame parent, final Transform transform, final String name,
129 final boolean pseudoInertial)
130 throws IllegalArgumentException {
131 this(parent, new FixedTransformProvider(transform), name, pseudoInertial);
132 }
133
134 /** Build a frame from its transform with respect to its parent.
135 * <p>The convention for the transform is that it is from parent
136 * frame to instance. This means that the two following frames
137 * are similar:</p>
138 * <pre>
139 * Frame frame1 = new Frame(FramesFactory.getGCRF(), new Transform(t1, t2));
140 * Frame frame2 = new Frame(new Frame(FramesFactory.getGCRF(), t1), t2);
141 * </pre>
142 * @param parent parent frame (must be non-null)
143 * @param transformProvider provider for transform from parent frame to instance
144 * @param name name of the frame
145 * @param pseudoInertial true if frame is considered pseudo-inertial
146 * (i.e. suitable for propagating orbit)
147 * @exception IllegalArgumentException if the parent frame is null
148 */
149 public Frame(final Frame parent, final TransformProvider transformProvider, final String name,
150 final boolean pseudoInertial)
151 throws IllegalArgumentException {
152
153 if (parent == null) {
154 throw new OrekitIllegalArgumentException(OrekitMessages.NULL_PARENT_FOR_FRAME, name);
155 }
156 this.parent = parent;
157 this.depth = parent.depth + 1;
158 this.transformProvider = transformProvider;
159 this.name = name;
160 this.pseudoInertial = pseudoInertial;
161
162 }
163
164 /** Get the name.
165 * @return the name
166 */
167 public String getName() {
168 return this.name;
169 }
170
171 /** Check if the frame is pseudo-inertial.
172 * <p>Pseudo-inertial frames are frames that do have a linear motion and
173 * either do not rotate or rotate at a very low rate resulting in
174 * neglectible inertial forces. This means they are suitable for orbit
175 * definition and propagation using Newtonian mechanics. Frames that are
176 * <em>not</em> pseudo-inertial are <em>not</em> suitable for orbit
177 * definition and propagation.</p>
178 * @return true if frame is pseudo-inertial
179 */
180 public boolean isPseudoInertial() {
181 return pseudoInertial;
182 }
183
184 /** New definition of the java.util toString() method.
185 * @return the name
186 */
187 public String toString() {
188 return this.name;
189 }
190
191 /** Get the parent frame.
192 * @return parent frame
193 */
194 public Frame getParent() {
195 return parent;
196 }
197
198 /** Get the depth of the frame.
199 * <p>
200 * The depth of a frame is the number of parents frame between
201 * it and the frames tree root. It is 0 for the root frame, and
202 * the depth of a frame is the depth of its parent frame plus one.
203 * </p>
204 * @return depth of the frame
205 */
206 public int getDepth() {
207 return depth;
208 }
209
210 /** Get the n<sup>th</sup> ancestor of the frame.
211 * @param n index of the ancestor (0 is the instance, 1 is its parent,
212 * 2 is the parent of its parent...)
213 * @return n<sup>th</sup> ancestor of the frame (must be between 0
214 * and the depth of the frame)
215 * @exception IllegalArgumentException if n is larger than the depth
216 * of the instance
217 */
218 public Frame getAncestor(final int n) throws IllegalArgumentException {
219
220 // safety check
221 if (n > depth) {
222 throw new OrekitIllegalArgumentException(OrekitMessages.FRAME_NO_NTH_ANCESTOR,
223 name, depth, n);
224 }
225
226 // go upward to find ancestor
227 Frame current = this;
228 for (int i = 0; i < n; ++i) {
229 current = current.parent;
230 }
231
232 return current;
233
234 }
235
236 /** Get the transform from the instance to another frame.
237 * @param destination destination frame to which we want to transform vectors
238 * @param date the date (can be null if it is sure than no date dependent frame is used)
239 * @return transform from the instance to the destination frame
240 * @exception OrekitException if some frame specific error occurs
241 */
242 public Transform getTransformTo(final Frame destination, final AbsoluteDate date)
243 throws OrekitException {
244
245 if (this == destination) {
246 // shortcut for special case that may be frequent
247 return Transform.IDENTITY;
248 }
249
250 // common ancestor to both frames in the frames tree
251 final Frame common = findCommon(this, destination);
252
253 // transform from common to instance
254 Transform commonToInstance = Transform.IDENTITY;
255 for (Frame frame = this; frame != common; frame = frame.parent) {
256 commonToInstance =
257 new Transform(date, frame.transformProvider.getTransform(date), commonToInstance);
258 }
259
260 // transform from destination up to common
261 Transform commonToDestination = Transform.IDENTITY;
262 for (Frame frame = destination; frame != common; frame = frame.parent) {
263 commonToDestination =
264 new Transform(date, frame.transformProvider.getTransform(date), commonToDestination);
265 }
266
267 // transform from instance to destination via common
268 return new Transform(date, commonToInstance.getInverse(), commonToDestination);
269
270 }
271
272 /** Get the provider for transform from parent frame to instance.
273 * @return provider for transform from parent frame to instance
274 */
275 public TransformProvider getTransformProvider() {
276 return transformProvider;
277 }
278
279 /** Find the deepest common ancestor of two frames in the frames tree.
280 * @param from origin frame
281 * @param to destination frame
282 * @return an ancestor frame of both <code>from</code> and <code>to</code>
283 */
284 private static Frame findCommon(final Frame from, final Frame to) {
285
286 // select deepest frames that could be the common ancestor
287 Frame currentF = from.depth > to.depth ? from.getAncestor(from.depth - to.depth) : from;
288 Frame currentT = from.depth > to.depth ? to : to.getAncestor(to.depth - from.depth);
289
290 // go upward until we find a match
291 while (currentF != currentT) {
292 currentF = currentF.parent;
293 currentT = currentT.parent;
294 }
295
296 return currentF;
297
298 }
299
300 /** Determine if a Frame is a child of another one.
301 * @param potentialAncestor supposed ancestor frame
302 * @return true if the potentialAncestor belongs to the
303 * path from instance to the root frame, excluding itself
304 */
305 public boolean isChildOf(final Frame potentialAncestor) {
306 if (depth <= potentialAncestor.depth) {
307 return false;
308 }
309 return getAncestor(depth - potentialAncestor.depth) == potentialAncestor;
310 }
311
312 /** Get the unique root frame.
313 * @return the unique instance of the root frame
314 */
315 protected static Frame getRoot() {
316 return LazyRootHolder.INSTANCE;
317 }
318
319 /** Get a new version of the instance, frozen with respect to a reference frame.
320 * <p>
321 * Freezing a frame consist in computing its position and orientation with respect
322 * to another frame at some freezing date and fixing them so they do not depend
323 * on time anymore. This means the frozen frame is fixed with respect to the
324 * reference frame.
325 * </p>
326 * <p>
327 * One typical use of this method is to compute an inertial launch reference frame
328 * by freezing a {@link TopocentricFrame topocentric frame} at launch date
329 * with respect to an inertial frame. Another use is to freeze an equinox-related
330 * celestial frame at a reference epoch date.
331 * </p>
332 * <p>
333 * Only the frame returned by this method is frozen, the instance by itself
334 * is not affected by calling this method and still moves freely.
335 * </p>
336 * @param reference frame with respect to which the instance will be frozen
337 * @param freezingDate freezing date
338 * @param frozenName name of the frozen frame
339 * @return a frozen version of the instance
340 * @exception OrekitException if transform between reference frame and instance
341 * cannot be computed at freezing frame
342 */
343 public Frame getFrozenFrame(final Frame reference, final AbsoluteDate freezingDate,
344 final String frozenName) throws OrekitException {
345 return new Frame(reference, reference.getTransformTo(this, freezingDate).freeze(),
346 frozenName, reference.isPseudoInertial());
347 }
348
349 // We use the Initialization on demand holder idiom to store
350 // the singletons, as it is both thread-safe, efficient (no
351 // synchronization) and works with all versions of java.
352
353 /** Holder for the root frame singleton. */
354 private static class LazyRootHolder {
355
356 /** Unique instance. */
357 private static final Frame INSTANCE = new Frame("GCRF", true) {
358
359 /** Serializable UID. */
360 private static final long serialVersionUID = -2654403496396721543L;
361
362 /** Replace the instance with a data transfer object for serialization.
363 * <p>
364 * This intermediate class serializes nothing.
365 * </p>
366 * @return data transfer object that will be serialized
367 */
368 private Object writeReplace() {
369 return new DataTransferObject();
370 }
371
372 };
373
374 /** Private constructor.
375 * <p>This class is a utility class, it should neither have a public
376 * nor a default constructor. This private constructor prevents
377 * the compiler from generating one automatically.</p>
378 */
379 private LazyRootHolder() {
380 }
381
382 }
383
384 /** Internal class used only for serialization. */
385 private static class DataTransferObject implements Serializable {
386
387 /** Serializable UID. */
388 private static final long serialVersionUID = 4067764035816491212L;
389
390 /** Simple constructor.
391 */
392 private DataTransferObject() {
393 }
394
395 /** Replace the deserialized data transfer object with a {@link FactoryManagedFrame}.
396 * @return replacement {@link FactoryManagedFrame}
397 */
398 private Object readResolve() {
399 return getRoot();
400 }
401
402 }
403
404 }