1 /*
2 * Copyright (C) 2018 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;
17
18 import com.irurueta.algebra.Matrix;
19 import com.irurueta.algebra.NonSymmetricPositiveDefiniteMatrixException;
20 import com.irurueta.units.Distance;
21 import com.irurueta.units.DistanceUnit;
22
23 /**
24 * Base class representing the confidence of provided accuracy from a covariance matrix
25 * expressed in the distance unit of such matrix.
26 * This class contains utility methods to convert covariance matrices into geometric figures
27 * with the requested confidence.
28 *
29 * @param <A> type of internal accuracy.
30 */
31 public abstract class Accuracy<A extends com.irurueta.geometry.Accuracy> {
32
33 /**
34 * Internal accuracy reference.
35 */
36 protected A internalAccuracy;
37
38 /**
39 * Constructor.
40 */
41 protected Accuracy() {
42 }
43
44 /**
45 * Constructor.
46 *
47 * @param internalAccuracy internal accuracy to be set.
48 */
49 Accuracy(final A internalAccuracy) {
50 this.internalAccuracy = internalAccuracy;
51 }
52
53 /**
54 * Gets covariance matrix representing the accuracy of an estimated point or measure.
55 *
56 * @return covariance matrix representing the accuracy of an estimated point or measure.
57 */
58 public Matrix getCovarianceMatrix() {
59 return internalAccuracy.getCovarianceMatrix();
60 }
61
62 /**
63 * Sets covariance matrix representing the accuracy of an estimated point or measure.
64 *
65 * @param covarianceMatrix covariance matrix representing the accuracy of an estimated
66 * point or measure.
67 * @throws IllegalArgumentException if provided matrix is not square (it must also be
68 * positive definite to be properly converted to a geometric
69 * figure - e.g. an ellipse or an ellipsoid).
70 * @throws NonSymmetricPositiveDefiniteMatrixException if provided matrix is not symmetric
71 * and positive definite.
72 */
73 public void setCovarianceMatrix(final Matrix covarianceMatrix) throws NonSymmetricPositiveDefiniteMatrixException {
74 internalAccuracy.setCovarianceMatrix(covarianceMatrix);
75 }
76
77 /**
78 * Gets standard deviation factor to account for a given accuracy confidence.
79 * Typically, a factor of 2.0 will be used, which means that accuracy can be drawn as
80 * a geometric figure of size equal to 2 times the standard deviation. Assuming a
81 * Gaussian distribution this is equivalent to providing a 95.44% confidence on provided
82 * accuracy.
83 *
84 * @return standard deviation factor.
85 */
86 public double getStandardDeviationFactor() {
87 return internalAccuracy.getStandardDeviationFactor();
88 }
89
90 /**
91 * Sets standard deviation factor to account for a given accuracy confidence.
92 * Typically, a factor of 2.0 will be used, which means that accuracy can be drawn as
93 * a geometric figure of size equal to 2 times the standard deviation. Assuming a
94 * Gaussian distribution this is equivalent to providing a 95.44% confidence on provided
95 * accuracy.
96 *
97 * @param standardDeviationFactor standard deviation factor to be set.
98 * @throws IllegalArgumentException if provided value is zero or negative.
99 */
100 public void setStandardDeviationFactor(final double standardDeviationFactor) {
101 internalAccuracy.setStandardDeviationFactor(standardDeviationFactor);
102 }
103
104 /**
105 * Gets confidence of provided accuracy of estimated point or measure.
106 * This is expressed as a value between 0 and 1, where 1 indicates a 100% confidence
107 * that the real point or measure is within provided accuracy.
108 *
109 * @return confidence of provided accuracy of estimated point or measure.
110 */
111 public double getConfidence() {
112 return internalAccuracy.getConfidence();
113 }
114
115 /**
116 * Sets confidence of provided accuracy of estimated point or measure.
117 * This is expressed as a value between 0 and 1, where 1 indicates a 100% confidence
118 * that the real point or measure is within provided accuracy.
119 *
120 * @param confidence confidence of provided accuracy of estimated point or measure.
121 * @throws IllegalArgumentException if provided value is not within 0 and 1.
122 */
123 public void setConfidence(final double confidence) {
124 internalAccuracy.setConfidence(confidence);
125 }
126
127 /**
128 * Gets smallest (best) accuracy in any direction (i.e. either 2D or 3D).
129 * This value is represented by the smallest semi axis representing the ellipse or ellipsoid of accuracy.
130 *
131 * @return smallest accuracy in any direction.
132 */
133 public Distance getSmallestAccuracy() {
134 return new Distance(getSmallestAccuracyMeters(), DistanceUnit.METER);
135 }
136
137 /**
138 * Gets smallest (best) accuracy in any direction (i.e. either 2D or 3D)
139 * expressed in meters.
140 * This value is represented by the smallest semi axis representing the ellipse or ellipsoid of accuracy.
141 *
142 * @return smallest accuracy in any direction expressed in meters.
143 */
144 public double getSmallestAccuracyMeters() {
145 return internalAccuracy.getSmallestAccuracy();
146 }
147
148 /**
149 * Gets largest (worse) accuracy in any direction (i.e. either 2D or 3D).
150 * This value is represented by the largest semi axis representing the ellipse or ellipsoid of accuracy.
151 *
152 * @return largest accuracy in any direction.
153 */
154 public Distance getLargestAccuracy() {
155 return new Distance(getLargestAccuracyMeters(), DistanceUnit.METER);
156 }
157
158 /**
159 * Gets largest (worse) accuracy in any direction (i.e. either 2D or 3D)
160 * expressed in meters.
161 * This value is represented by the largest semi axis representing the ellipse or ellipsoid of accuracy.
162 *
163 * @return largest accuracy in any direction expressed in meters.
164 */
165 public double getLargestAccuracyMeters() {
166 return internalAccuracy.getLargestAccuracy();
167 }
168
169 /**
170 * Gets average accuracy among all directions.
171 * This value is equal to the average value of all semi axes representing the ellipse or ellipsoid of
172 * accuracy.
173 *
174 * @return average accuracy among all directions.
175 */
176 public Distance getAverageAccuracy() {
177 return new Distance(getAverageAccuracyMeters(), DistanceUnit.METER);
178 }
179
180 /**
181 * Gets average accuracy among all directions expressed in meters.
182 * This value is equal to the average value of all semi axes representing the ellipse or ellipsoid of
183 * accuracy.
184 *
185 * @return average accuracy among all directions expressed in meters.
186 */
187 public double getAverageAccuracyMeters() {
188 return internalAccuracy.getAverageAccuracy();
189 }
190
191 /**
192 * Gets number of dimensions.
193 * This is equal to 2 for 2D, and 3 for 3D.
194 *
195 * @return number of dimensions.
196 */
197 public int getNumberOfDimensions() {
198 return internalAccuracy.getNumberOfDimensions();
199 }
200 }