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