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.algebra.Matrix;
19 import com.irurueta.geometry.InvalidRotationMatrixException;
20 import com.irurueta.geometry.Rotation3D;
21
22 /**
23 * Base interface for frames.
24 */
25 public interface Frame {
26
27 /**
28 * Gets coordinate transformation.
29 *
30 * @return coordinate transformation.
31 */
32 CoordinateTransformation getCoordinateTransformation();
33
34 /**
35 * Gets coordinate transformation.
36 *
37 * @param result instance where coordinate transformation will be copied to.
38 */
39 void getCoordinateTransformation(final CoordinateTransformation result);
40
41 /**
42 * Sets coordinate transformation.
43 * Provided value must be a body to ECEF transformation.
44 *
45 * @param c coordinate transformation to be set.
46 * @throws InvalidSourceAndDestinationFrameTypeException if source or destination frame types are invalid.
47 */
48 void setCoordinateTransformation(final CoordinateTransformation c)
49 throws InvalidSourceAndDestinationFrameTypeException;
50
51 /**
52 * Gets coordinate transformation matrix.
53 * This is equivalent to calling getCoordinateTransformation().getMatrix(), but more efficient.
54 *
55 * @return coordinate transformation matrix.
56 */
57 Matrix getCoordinateTransformationMatrix();
58
59 /**
60 * Gets coordinate transformation matrix.
61 * This is equivalent to calling getCoordinateTransformation().getMatrix(), but more efficient
62 *
63 * @param result instance where coordinate transformation matrix will be copied to.
64 */
65 void getCoordinateTransformationMatrix(final Matrix result);
66
67 /**
68 * Sets coordinate transformation matrix keeping current source and destination {@link FrameType}.
69 * This is more efficient than getting a copy of coordinate transformation calling to
70 * {@link #getCoordinateTransformation()}, setting coordinate matrix into copied coordinate transformation and
71 * then setting the coordinate transformation calling
72 * {@link #setCoordinateTransformation(CoordinateTransformation)}.
73 *
74 * @param matrix a 3x3 coordinate transformation matrix to be set.
75 * @param threshold threshold to validate rotation matrix.
76 * @throws InvalidRotationMatrixException if provided matrix is not a valid rotation matrix (3x3 and orthonormal).
77 * @throws IllegalArgumentException if provided threshold is negative.
78 */
79 void setCoordinateTransformationMatrix(final Matrix matrix, final double threshold)
80 throws InvalidRotationMatrixException;
81
82 /**
83 * Sts coordinate transformation matrix keeping current source and destination {@link FrameType}.
84 * This is more efficient than getting a copy of coordinate transformation calling to
85 * {@link #getCoordinateTransformation()}, setting coordinate matrix into copied coordinate transformation and
86 * then setting the coordinate transformation calling
87 * {@link #setCoordinateTransformation(CoordinateTransformation)}.
88 *
89 * @param matrix a 3x3 coordinate transformation matrix to be set.
90 * @throws InvalidRotationMatrixException if provided matrix is not a valid rotation matrix (3x3 and orthonormal).
91 */
92 void setCoordinateTransformationMatrix(final Matrix matrix) throws InvalidRotationMatrixException;
93
94 /**
95 * Gets coordinate transformation as a new 3D rotation instance.
96 * This is equivalent to calling getCoordinateTransformation().asRotation(), but more efficient.
97 *
98 * @return new coordinate transformation as a 3D rotation.
99 * @throws InvalidRotationMatrixException if internal matrix cannot be converted to a 3D rotation.
100 */
101 Rotation3D getCoordinateTransformationRotation() throws InvalidRotationMatrixException;
102
103 /**
104 * Gets coordinate transformation as a 3D rotation.
105 * This is equivalent to calling getCoordinateTransformation().asRotation(), but more efficient.
106 *
107 * @param result instance where coordinate transformation 3D rotation will be copied to.
108 * @throws InvalidRotationMatrixException if internal matrix cannot be converted to a 3D rotation.
109 */
110 void getCoordinateTransformationRotation(final Rotation3D result) throws InvalidRotationMatrixException;
111
112 /**
113 * Sets coordinate transformation from 3D rotation and keeping current source and destination {@link FrameType}.
114 * This is more efficient than getting a copy of coordinate transformation calling to
115 * {@link #getCoordinateTransformation()}, setting rotation into copied coordinate transformation and
116 * then setting the coordinate transformation calling
117 * {@link #setCoordinateTransformation(CoordinateTransformation)}.
118 *
119 * @param rotation set rotation into current coordinate rotation.
120 */
121 void setCoordinateTransformationRotation(final Rotation3D rotation);
122 }