1 /*
2 * Copyright (C) 2019 Alberto Irurueta Carro (alberto@irurueta.com)
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package com.irurueta.navigation.frames;
17
18 import com.irurueta.geometry.Point3D;
19 import com.irurueta.units.Distance;
20 import com.irurueta.units.Speed;
21
22 /**
23 * Contains position, velocity and coordinates transformation matrix expressed in ECI frame.
24 * Position and velocity of this frame is expressed along ECI axes as described here:
25 * {@link FrameType#EARTH_CENTERED_INERTIAL_FRAME}.
26 */
27 public class ECIFrame extends ECIorECEFFrame<ECIFrame> implements Cloneable {
28
29 /**
30 * Constructor.
31 * Initializes position and velocity coordinates to zero and the coordinate transformation matrix to the
32 * identity.
33 */
34 public ECIFrame() {
35 super(ECIFrame.class);
36 c = new CoordinateTransformation(FrameType.BODY_FRAME, FrameType.EARTH_CENTERED_INERTIAL_FRAME);
37 }
38
39 /**
40 * Constructor.
41 *
42 * @param c Body to ECI coordinate transformation matrix to be set.
43 * @throws InvalidSourceAndDestinationFrameTypeException if source or destination frame types are invalid.
44 */
45 public ECIFrame(final CoordinateTransformation c) throws InvalidSourceAndDestinationFrameTypeException {
46 super(c);
47 }
48
49 /**
50 * Constructor.
51 *
52 * @param x cartesian x coordinate of body position expressed in meters (m) with respect ECI frame, resolved along
53 * ECI-frame axes.
54 * @param y cartesian y coordinate of body position expressed in meters (m) with respect ECI frame, resolved along
55 * ECI-frame axes.
56 * @param z cartesian z coordinate of body position expressed in meters (m) with respect ECI frame, resolved along
57 * ECI-frame axes.
58 */
59 public ECIFrame(final double x, final double y, final double z) {
60 this();
61 setCoordinates(x, y, z);
62 }
63
64 /**
65 * Constructor.
66 *
67 * @param position body position expressed in meters (m) and resolved along ECI-frame axes.
68 */
69 public ECIFrame(final Point3D position) {
70 this();
71 setPosition(position);
72 }
73
74 /**
75 * Constructor.
76 *
77 * @param positionX cartesian x coordinate of body position to be set resolved along ECI-frame axes.
78 * @param positionY cartesian y coordinate of body position to be set resolved along ECI-frame axes.
79 * @param positionZ cartesian z coordinate of body position to be set resolved along ECI-frame axes.
80 */
81 public ECIFrame(final Distance positionX, final Distance positionY, final Distance positionZ) {
82 this();
83 setPositionCoordinates(positionX, positionY, positionZ);
84 }
85
86 /**
87 * Constructor.
88 *
89 * @param x cartesian x coordinate of body position expressed in meters (m) and resolved along ECI-frame axes.
90 * @param y cartesian y coordinate of body position expressed in meters (m) and resolved along ECI-frame axes.
91 * @param z cartesian z coordinate of body position expressed in meters (m) and resolved along ECI-frame axes.
92 * @param vx x coordinate of velocity of body frame expressed in meters per second (m/s) and resolved along
93 * ECI-frame axes.
94 * @param vy y coordinate of velocity of body frame expressed in meters per second (m/s) and resolved along
95 * ECI-frame axes.
96 * @param vz z coordinate of velocity of body frame expressed in meters per second (m/s) and resolved along
97 * ECI-frame axes.
98 */
99 public ECIFrame(final double x, final double y, final double z,
100 final double vx, final double vy, final double vz) {
101 this(x, y, z);
102 setVelocityCoordinates(vx, vy, vz);
103 }
104
105 /**
106 * Constructor.
107 *
108 * @param position body position expressed in meters (m) and resolved along ECI-frame axes.
109 * @param vx x coordinate of velocity of body frame expressed in meters per second (m/s) and resolved along
110 * ECI-frame axes.
111 * @param vy y coordinate of velocity of body frame expressed in meters per second (m/s) and resolved along
112 * ECI-frame axes.
113 * @param vz z coordinate of velocity of body frame expressed in meters per second (m/s) and resolved along
114 * ECI-frame axes.
115 */
116 public ECIFrame(final Point3D position, final double vx, final double vy, final double vz) {
117 this(position);
118 setVelocityCoordinates(vx, vy, vz);
119 }
120
121 /**
122 * Constructor.
123 *
124 * @param position body position expressed in meters (m) and resolved along ECI-frame axes.
125 * @param speedX x coordinate of velocity to be set resolved along ECI-frame axes.
126 * @param speedY y coordinate of velocity to be set resolved along ECI-frame axes.
127 * @param speedZ z coordinate of velocity to be set resolved along ECI-frame axes.
128 */
129 public ECIFrame(final Point3D position, final Speed speedX, final Speed speedY, final Speed speedZ) {
130 this(position);
131 setSpeedCoordinates(speedX, speedY, speedZ);
132 }
133
134 /**
135 * Constructor.
136 *
137 * @param x cartesian x coordinate of body position expressed in meters (m) with respect ECI frame, resolved
138 * along ECI-frame axes.
139 * @param y cartesian y coordinate of body position expressed in meters (m) with respect ECI frame, resolved
140 * along ECI-frame axes.
141 * @param z cartesian z coordinate of body position expressed in meters (m) with respect ECI frame, resolved
142 * along ECI-frame axes.
143 * @param speedX x coordinate of velocity to be set resolved along ECI-frame axes.
144 * @param speedY y coordinate of velocity to be set resolved along ECI-frame axes.
145 * @param speedZ z coordinate of velocity to be set resolved along ECI-frame axes.
146 */
147 public ECIFrame(final double x, final double y, final double z,
148 final Speed speedX, final Speed speedY, final Speed speedZ) {
149 this(x, y, z);
150 setSpeedCoordinates(speedX, speedY, speedZ);
151 }
152
153 /**
154 * Constructor.
155 *
156 * @param positionX cartesian x coordinate of body position to be set, resolved along ECI-frame axes.
157 * @param positionY cartesian y coordinate of body position to be set, resolved along ECI-frame axes.
158 * @param positionZ cartesian z coordinate of body position to be set, resolved along ECI-frame axes.
159 * @param vx x coordinate of velocity of body frame expressed in meters per second (m/s) and resolved along
160 * ECI-frame axes.
161 * @param vy y coordinate of velocity of body frame expressed in meters per second (m/s) and resolved along
162 * ECI-frame axes.
163 * @param vz z coordinate of velocity of body frame expressed in meters per second (m/s) and resolved along
164 * ECI-frame axes.
165 */
166 public ECIFrame(final Distance positionX, final Distance positionY, final Distance positionZ,
167 final double vx, final double vy, final double vz) {
168 this(positionX, positionY, positionZ);
169 setVelocityCoordinates(vx, vy, vz);
170 }
171
172 /**
173 * Constructor.
174 *
175 * @param positionX cartesian x coordinate of body position to be set, resolved along ECI-frame axes.
176 * @param positionY cartesian y coordinate of body position to be set, resolved along ECI-frame axes.
177 * @param positionZ cartesian z coordinate of body position to be set, resolved along ECI-frame axes.
178 * @param speedX x coordinate of velocity to be set, resolved along ECI-frame axes.
179 * @param speedY y coordinate of velocity to be set, resolved along ECI-frame axes.
180 * @param speedZ z coordinate of velocity to be set, resolved along ECI-frame axes.
181 */
182 public ECIFrame(final Distance positionX, final Distance positionY, final Distance positionZ,
183 final Speed speedX, final Speed speedY, final Speed speedZ) {
184 this(positionX, positionY, positionZ);
185 setSpeedCoordinates(speedX, speedY, speedZ);
186 }
187
188 /**
189 * Constructor.
190 *
191 * @param x cartesian x coordinate of body position expressed in meters (m) with respect ECI frame, resolved along
192 * ECI-frame axes.
193 * @param y cartesian y coordinate of body position expressed in meters (m) with respect ECI frame, resolved along
194 * ECI-frame axes.
195 * @param z cartesian z coordinate of body position expressed in meters (m) with respect ECI frame, resolved along
196 * ECI-frame axes.
197 * @param c Body to ECI coordinate transformation matrix to be set.
198 * @throws InvalidSourceAndDestinationFrameTypeException if source or destination frame types are invalid.
199 */
200 public ECIFrame(final double x, final double y, final double z, final CoordinateTransformation c)
201 throws InvalidSourceAndDestinationFrameTypeException {
202 this(x, y, z);
203 setCoordinateTransformation(c);
204 }
205
206 /**
207 * Constructor.
208 *
209 * @param position body position expressed in meters (m) and resolved along ECI-frame axes.
210 * @param c Body to ECI coordinate transformation matrix to be set.
211 * @throws InvalidSourceAndDestinationFrameTypeException if source or destination frame types are invalid.
212 */
213 public ECIFrame(final Point3D position, final CoordinateTransformation c)
214 throws InvalidSourceAndDestinationFrameTypeException {
215
216 this(position);
217 setCoordinateTransformation(c);
218 }
219
220 /**
221 * Constructor.
222 *
223 * @param positionX cartesian x coordinate of body position to be set, resolved along ECI-frame axes.
224 * @param positionY cartesian y coordinate of body position to be set, resolved along ECI-frame axes.
225 * @param positionZ cartesian z coordinate of body position to be set, resolved along ECI-frame axes.
226 * @param c Body to ECI coordinate transformation matrix to be set.
227 * @throws InvalidSourceAndDestinationFrameTypeException if source or destination frame types are invalid.
228 */
229 public ECIFrame(final Distance positionX, final Distance positionY, final Distance positionZ,
230 final CoordinateTransformation c) throws InvalidSourceAndDestinationFrameTypeException {
231
232 this(positionX, positionY, positionZ);
233 setCoordinateTransformation(c);
234 }
235
236 /**
237 * Constructor.
238 *
239 * @param x cartesian x coordinate of body position expressed in meters (m) with respect ECI frame, resolved along
240 * ECI-frame axes.
241 * @param y cartesian y coordinate of body position expressed in meters (m) with respect ECI frame, resolved along
242 * ECI-frame axes.
243 * @param z cartesian z coordinate of body position expressed in meters (m) with respect ECI frame, resolved along
244 * ECI-frame axes.
245 * @param vx x coordinate of velocity of body frame expressed in meters per second (m/s) and resolved along
246 * ECI-frame axes.
247 * @param vy y coordinate of velocity of body frame expressed in meters per second (m/s) and resolved along
248 * ECI-frame axes.
249 * @param vz z coordinate of velocity of body frame expressed in meters per second (m/s) and resolved along
250 * ECI-frame axes.
251 * @param c Body to ECI coordinate transformation matrix to be set.
252 * @throws InvalidSourceAndDestinationFrameTypeException if source or destination frame types are invalid.
253 */
254 public ECIFrame(final double x, final double y, final double z,
255 final double vx, final double vy, final double vz, final CoordinateTransformation c)
256 throws InvalidSourceAndDestinationFrameTypeException {
257 this(x, y, z, vx, vy, vz);
258 setCoordinateTransformation(c);
259 }
260
261 /**
262 * Constructor.
263 *
264 * @param position body position expressed in meters (m) and resolved along ECI-frame axes.
265 * @param vx x coordinate of velocity of body frame expressed in meters per second (m/s) and resolved along
266 * ECI-frame axes.
267 * @param vy y coordinate of velocity of body frame expressed in meters per second (m/s) and resolved along
268 * ECI-frame axes.
269 * @param vz z coordinate of velocity of body frame expressed in meters per second (m/s) and resolved along
270 * ECI-frame axes.
271 * @param c Body to ECI coordinate transformation matrix to be set.
272 * @throws InvalidSourceAndDestinationFrameTypeException if source or destination frame types are invalid.
273 */
274 public ECIFrame(final Point3D position,
275 final double vx, final double vy, final double vz, final CoordinateTransformation c)
276 throws InvalidSourceAndDestinationFrameTypeException {
277 this(position, vx, vy, vz);
278 setCoordinateTransformation(c);
279 }
280
281 /**
282 * Constructor.
283 *
284 * @param position body position expressed in meters (m) and resolved along ECI-frame axes.
285 * @param speedX x coordinate of velocity to be set, resolved along ECI-frame axes.
286 * @param speedY y coordinate of velocity to be set, resolved along ECI-frame axes.
287 * @param speedZ z coordinate of velocity to be set, resolved along ECI-frame axes.
288 * @param c Body to ECI coordinate transformation matrix to be set.
289 * @throws InvalidSourceAndDestinationFrameTypeException if source or destination frame types are invalid.
290 */
291 public ECIFrame(final Point3D position,
292 final Speed speedX, final Speed speedY, final Speed speedZ, final CoordinateTransformation c)
293 throws InvalidSourceAndDestinationFrameTypeException {
294 this(position, speedX, speedY, speedZ);
295 setCoordinateTransformation(c);
296 }
297
298 /**
299 * Constructor.
300 *
301 * @param x cartesian x coordinate of body position expressed in meters (m) with respect ECI frame, resolved
302 * along ECI-frame axes.
303 * @param y cartesian y coordinate of body position expressed in meters (m) with respect ECI frame, resolved
304 * along ECI-frame axes.
305 * @param z cartesian z coordinate of body position expressed in meters (m) with respect ECI frame, resolved
306 * along ECI-frame axes.
307 * @param speedX x coordinate of velocity to be set, resolved along ECI-frame axes.
308 * @param speedY y coordinate of velocity to be set, resolved along ECI-frame axes.
309 * @param speedZ z coordinate of velocity to be set, resolved along ECI-frame axes.
310 * @param c Body to ECI coordinate transformation matrix to be set.
311 * @throws InvalidSourceAndDestinationFrameTypeException if source or destination frame types are invalid.
312 */
313 public ECIFrame(final double x, final double y, final double z,
314 final Speed speedX, final Speed speedY, final Speed speedZ, final CoordinateTransformation c)
315 throws InvalidSourceAndDestinationFrameTypeException {
316 this(x, y, z, speedX, speedY, speedZ);
317 setCoordinateTransformation(c);
318 }
319
320 /**
321 * Constructor.
322 *
323 * @param positionX cartesian x coordinate of body position to be set, resolved along ECI-frame axes.
324 * @param positionY cartesian y coordinate of body position to be set, resolved along ECI-frame axes.
325 * @param positionZ cartesian z coordinate of body position to be set, resolved along ECI-frame axes.
326 * @param vx x coordinate of velocity of body frame expressed in meters per second (m/s) and resolved along
327 * ECI-frame axes.
328 * @param vy y coordinate of velocity of body frame expressed in meters per second (m/s) and resolved along
329 * ECI-frame axes.
330 * @param vz z coordinate of velocity of body frame expressed in meters per second (m/s) and resolved along
331 * ECI-frame axes.
332 * @param c Body to ECI coordinate transformation matrix to be set.
333 * @throws InvalidSourceAndDestinationFrameTypeException if source or destination frame types are invalid.
334 */
335 public ECIFrame(final Distance positionX, final Distance positionY, final Distance positionZ,
336 final double vx, final double vy, final double vz, final CoordinateTransformation c)
337 throws InvalidSourceAndDestinationFrameTypeException {
338 this(positionX, positionY, positionZ, vx, vy, vz);
339 setCoordinateTransformation(c);
340 }
341
342 /**
343 * Constructor.
344 *
345 * @param positionX cartesian x coordinate of body position to be set, resolved along ECI-frame axes.
346 * @param positionY cartesian y coordinate of body position to be set, resolved along ECI-frame axes.
347 * @param positionZ cartesian z coordinate of body position to be set, resolved along ECI-frame axes.
348 * @param speedX x coordinate of velocity to be set, resolved along ECI-frame axes.
349 * @param speedY y coordinate of velocity to be set, resolved along ECI-frame axes.
350 * @param speedZ z coordinate of velocity to be set, resolved along ECI-frame axes.
351 * @param c Body to ECI coordinate transformation matrix to be set.
352 * @throws InvalidSourceAndDestinationFrameTypeException if source or destination frame types are invalid.
353 */
354 public ECIFrame(final Distance positionX, final Distance positionY, final Distance positionZ,
355 final Speed speedX, final Speed speedY, final Speed speedZ, final CoordinateTransformation c)
356 throws InvalidSourceAndDestinationFrameTypeException {
357 this(positionX, positionY, positionZ, speedX, speedY, speedZ);
358 setCoordinateTransformation(c);
359 }
360
361 /**
362 * Constructor.
363 *
364 * @param input ECI frame to copy data from.
365 */
366 public ECIFrame(final ECIFrame input) {
367 this();
368 copyFrom(input);
369 }
370
371 /**
372 * Gets coordinate transformation matrix.
373 *
374 * @return coordinate transformation matrix.
375 */
376 @Override
377 public CoordinateTransformation getCoordinateTransformation() {
378 final var result = new CoordinateTransformation(FrameType.BODY_FRAME, FrameType.EARTH_CENTERED_INERTIAL_FRAME);
379 getCoordinateTransformation(result);
380 return result;
381 }
382
383 /**
384 * Gets coordinate transformation matrix.
385 *
386 * @param result instance where coordinate transformation matrix will be copied to.
387 */
388 @Override
389 public void getCoordinateTransformation(final CoordinateTransformation result) {
390 c.copyTo(result);
391 }
392
393 /**
394 * Sets coordinate transformation matrix.
395 * Provided value must be a body to ECI transformation matrix.
396 *
397 * @param c coordinate transformation matrix to be set.
398 * @throws InvalidSourceAndDestinationFrameTypeException if source or destination frame types are invalid.
399 */
400 @Override
401 public void setCoordinateTransformation(final CoordinateTransformation c)
402 throws InvalidSourceAndDestinationFrameTypeException {
403 if (!isValidCoordinateTransformation(c)) {
404 throw new InvalidSourceAndDestinationFrameTypeException();
405 }
406
407 this.c = c;
408 }
409
410 /**
411 * Checks whether provided coordinate transformation is valid or not.
412 * Only body to ECI transformation matrices are considered to be valid.
413 *
414 * @param c coordinate transformation matrix to be checked.
415 * @return true if provided value is valid, false otherwise.
416 */
417 public static boolean isValidCoordinateTransformation(final CoordinateTransformation c) {
418 return c.getSourceType() == FrameType.BODY_FRAME
419 && c.getDestinationType() == FrameType.EARTH_CENTERED_INERTIAL_FRAME;
420 }
421
422 /**
423 * Makes a copy of this instance.
424 *
425 * @return a copy of this instance.
426 * @throws CloneNotSupportedException if clone fails for some reason.
427 */
428 @Override
429 protected Object clone() throws CloneNotSupportedException {
430 final var result = (ECIFrame)super.clone();
431 copyTo(result);
432 clazz = ECIFrame.class;
433 return result;
434 }
435 }