001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2003-2023 Open Geospatial Consortium, Inc.
004 *    http://www.geoapi.org
005 *
006 *    Licensed under the Apache License, Version 2.0 (the "License");
007 *    you may not use this file except in compliance with the License.
008 *    You may obtain a copy of the License at
009 *
010 *        http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *    Unless required by applicable law or agreed to in writing, software
013 *    distributed under the License is distributed on an "AS IS" BASIS,
014 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 *    See the License for the specific language governing permissions and
016 *    limitations under the License.
017 */
018package org.opengis.metadata.quality;
019
020import javax.measure.Quantity;
021import org.opengis.annotation.UML;
022import org.opengis.referencing.operation.Matrix;
023
024import static org.opengis.annotation.Specification.*;
025
026
027/**
028 * Closeness of reported coordinate values to values accepted as being true.
029 * Can be used for the following measurement types (non-exhaustive list):
030 * <ul>
031 *   <li>Data quality measures for positional uncertainty in general.</li>
032 *   <li>Height measurements as position observations in one dimension.
033 *       The height may therefore be treated as a one-dimensional random variable.</li>
034 *   <li>Horizontal point locations are defined by a 2D coordinates.
035 *       The uncertainty of any point location can be described using the data quality
036 *       basic measures for 2D random variables.</li>
037 * </ul>
038 *
039 * <h2>Standardized values</h2>
040 * In order to achieve well defined and comparable quality information, it is recommended to
041 * report data quality using {@linkplain Measure quality measures} listed in ISO 19157 annex.
042 * The following table provides a summary adapted to GeoAPI objects;
043 * see ISO 19157 for more complete descriptions and formulas.
044 * All identifiers should be in "ISO 19157" namespace.
045 *
046 * <table class="ogc">
047 *   <caption>Standardized values derived from ISO 19157</caption>
048 *   <tr>
049 *     <th>{@linkplain MeasureReference#getMeasureIdentification() Identifier}</th>
050 *     <th>{@linkplain MeasureReference#getNamesOfMeasure() Name of measure}</th>
051 *     <th>{@linkplain Measure#getAliases() Aliases}</th>
052 *     <th>{@linkplain Measure#getBasicMeasure() Basic measure}</th>
053 *     <th>{@linkplain Measure#getParameters() Parameters}</th>
054 *     <th>{@linkplain Measure#getValueType() Value type}</th>
055 *   </tr><tr>
056 *     <td>28</td>
057 *     <td>mean value of positional uncertainties (1D, 2D and 3D)</td>
058 *     <td></td>
059 *     <td></td>
060 *     <td></td>
061 *     <td>{@link Quantity}</td>
062 *   </tr><tr>
063 *     <td>128</td>
064 *     <td>bias of positions (1D, 2D and 3D)</td>
065 *     <td></td>
066 *     <td></td>
067 *     <td></td>
068 *     <td>{@link Quantity}</td>
069 *   </tr><tr>
070 *     <td>29</td>
071 *     <td>mean value of positional uncertainties excluding outliers (2D)</td>
072 *     <td></td>
073 *     <td></td>
074 *     <td>e<sub>max</sub></td>
075 *     <td>{@link Quantity}</td>
076 *   </tr><tr>
077 *     <td>30</td>
078 *     <td>number of positional uncertainties above a given threshold</td>
079 *     <td></td>
080 *     <td>error count</td>
081 *     <td>e<sub>max</sub></td>
082 *     <td>{@link Quantity}</td>
083 *   </tr><tr>
084 *     <td>31</td>
085 *     <td>rate of positional uncertainties above a given threshold</td>
086 *     <td></td>
087 *     <td></td>
088 *     <td>e<sub>max</sub></td>
089 *     <td>{@link Quantity}</td>
090 *   </tr><tr>
091 *     <td>32</td>
092 *     <td>covariance matrix</td>
093 *     <td>variance-covariance matrix</td>
094 *     <td></td>
095 *     <td></td>
096 *     <td>{@link Matrix}</td>
097 *   </tr><tr>
098 *     <td>33</td>
099 *     <td>linear error probable</td>
100 *     <td>LEP</td>
101 *     <td>LE50 or LE50(r)</td>
102 *     <td></td>
103 *     <td>{@link Quantity}</td>
104 *   </tr><tr>
105 *     <td>34</td>
106 *     <td>standard linear error</td>
107 *     <td>SLE</td>
108 *     <td>LE68.3 or LE68.3(r)</td>
109 *     <td></td>
110 *     <td>{@link Quantity}</td>
111 *   </tr><tr>
112 *     <td>35</td>
113 *     <td>linear map accuracy at 90% significance level</td>
114 *     <td>LMAS 90%</td>
115 *     <td>LE90 or LE90(r)</td>
116 *     <td></td>
117 *     <td>{@link Quantity}</td>
118 *   </tr><tr>
119 *     <td>36</td>
120 *     <td>linear map accuracy at 95% significance level</td>
121 *     <td>LMAS 95%</td>
122 *     <td>LE95 or LE95(r)</td>
123 *     <td></td>
124 *     <td>{@link Quantity}</td>
125 *   </tr><tr>
126 *     <td>37</td>
127 *     <td>linear map accuracy at 99% significance level</td>
128 *     <td>LMAS 99%</td>
129 *     <td>LE99 or LE99(r)</td>
130 *     <td></td>
131 *     <td>{@link Quantity}</td>
132 *   </tr><tr>
133 *     <td>38</td>
134 *     <td>near certainty linear error</td>
135 *     <td></td>
136 *     <td>LE99.8 or LE99.8(r)</td>
137 *     <td></td>
138 *     <td>{@link Quantity}</td>
139 *   </tr><tr>
140 *     <td>39</td>
141 *     <td>root mean square error</td>
142 *     <td>RMS</td>
143 *     <td></td>
144 *     <td></td>
145 *     <td>{@link Quantity}</td>
146 *   </tr><tr>
147 *     <td>40</td>
148 *     <td>absolute linear error at 90% significance level of biased vertical data</td>
149 *     <td>LMAS</td>
150 *     <td></td>
151 *     <td></td>
152 *     <td>{@link Quantity}</td>
153 *   </tr><tr>
154 *     <td>41</td>
155 *     <td>absolute linear error at 90% significance level of biased vertical data</td>
156 *     <td>ALE</td>
157 *     <td></td>
158 *     <td>Sample size</td>
159 *     <td>{@link Quantity}</td>
160 *   </tr><tr>
161 *     <td>42</td>
162 *     <td>circular standard deviation</td>
163 *     <td>Helmert's point error, CSE</td>
164 *     <td>CE39.4</td>
165 *     <td></td>
166 *     <td>{@link Quantity}</td>
167 *   </tr><tr>
168 *     <td>43</td>
169 *     <td>circular error probable</td>
170 *     <td>CEP</td>
171 *     <td>CE50</td>
172 *     <td></td>
173 *     <td>{@link Quantity}</td>
174 *   </tr><tr>
175 *     <td>44</td>
176 *     <td>circular error at 90% significant level</td>
177 *     <td>circular map accuracy standard</td>
178 *     <td>CE90</td>
179 *     <td></td>
180 *     <td>{@link Quantity}</td>
181 *   </tr><tr>
182 *     <td>45</td>
183 *     <td>circular error at 95% significant level</td>
184 *     <td>navigation accuracy</td>
185 *     <td>CE95</td>
186 *     <td></td>
187 *     <td>{@link Quantity}</td>
188 *   </tr><tr>
189 *     <td>46</td>
190 *     <td>circular near certainty error</td>
191 *     <td>CNCE</td>
192 *     <td>CE99.8</td>
193 *     <td></td>
194 *     <td>{@link Quantity}</td>
195 *   </tr><tr>
196 *     <td>47</td>
197 *     <td>root mean square error of planimetry</td>
198 *     <td>RMSEP</td>
199 *     <td></td>
200 *     <td></td>
201 *     <td>{@link Quantity}</td>
202 *   </tr><tr>
203 *     <td>48</td>
204 *     <td>absolute circular error at 90% significance level of biased data</td>
205 *     <td>CMAS</td>
206 *     <td></td>
207 *     <td></td>
208 *     <td>{@link Quantity}</td>
209 *   </tr><tr>
210 *     <td>49</td>
211 *     <td>absolute circular error at 90% significance level of biased data</td>
212 *     <td>ACE</td>
213 *     <td></td>
214 *     <td>Sample size</td>
215 *     <td>{@link Quantity}</td>
216 *   </tr><tr>
217 *     <td>50</td>
218 *     <td>uncertainty ellipse</td>
219 *     <td>standard point error ellipse</td>
220 *     <td></td>
221 *     <td></td>
222 *     <td>(<var>a</var>, <var>b</var>, <var>φ</var>)</td>
223 *   </tr><tr>
224 *     <td>51</td>
225 *     <td>confidence ellipse</td>
226 *     <td>confidence point error ellipse</td>
227 *     <td></td>
228 *     <td>significance level</td>
229 *     <td>(<var>a</var>, <var>b</var>, <var>φ</var>)</td>
230 *   </tr>
231 * </table>
232 *
233 * <p><b>Note:</b>
234 * ISO 19157 declares the <i>covariance matrix</i> value type as "Measure" associated with {@link ValueStructure#MATRIX}.
235 * For an object oriented language like Java, a more natural approach is to use an object of specific type for the value.
236 * </p>
237 *
238 * <p>{@linkplain Measure#getDefinition() Definitions}:</p>
239 * <ol start="28">
240 *   <li>Mean value of the distance between a measured position and what is considered as the corresponding true position.</li>
241 *   <li value="128">Deviation between a measured position and what is considered as the corresponding true position.</li>
242 *   <li value="29">For a set of points where the distance does not exceed a defined threshold, the arithmetical average of distances
243 *       between their measured positions and what is considered as the corresponding true positions.</li>
244 *   <li>Number of positional uncertainties above a given threshold for a set of positions.
245 *       The errors are defined as the distance between a measured position and what is considered as the corresponding true position.</li>
246 *   <li>Number of positional uncertainties above a given threshold for a set of positions in relation to the total number of measured positions.
247 *       The errors are defined as the distance between a measured position and what is considered as the corresponding true position.</li>
248 *   <li>Symmetrical square matrix with variances of point coordinates on the main diagonal and covariance between these coordinates as off-diagonal elements.</li>
249 *   <li>Half length of the interval defined by an upper and a lower limit, in which the true value lies with probability 50%.</li>
250 *   <li>Half length of the interval defined by an upper and a lower limit, in which the true value lies with probability 68.3%.</li>
251 *   <li>Half length of the interval defined by an upper and a lower limit, in which the true value lies with probability 90%.</li>
252 *   <li>Half length of the interval defined by an upper and a lower limit, in which the true value lies with probability 95%.</li>
253 *   <li>Half length of the interval defined by an upper and a lower limit, in which the true value lies with probability 99%.</li>
254 *   <li>Half length of the interval defined by an upper and a lower limit, in which the true value lies with probability 99.8%.</li>
255 *   <li>Linear root mean square error.</li>
256 *   <li>Absolute vertical accuracy of the data’s coordinates, expressed in terms of linear error at 90% probability given that a bias is present.</li>
257 *   <li>Absolute vertical accuracy of the data’s coordinates, expressed in terms of linear error at 90% probability given that a bias is present.</li>
258 *   <li>Radius describing a circle, in which the true point location lies with the probability of 39.4%.</li>
259 *   <li>Radius describing a circle, in which the true point location lies with the probability of 50%.</li>
260 *   <li>Radius describing a circle, in which the true point location lies with the probability of 90%.</li>
261 *   <li>Radius describing a circle, in which the true point location lies with the probability of 95%.</li>
262 *   <li>Radius describing a circle, in which the true point location lies with the probability of 99.8%.</li>
263 *   <li>Radius of a circle around the given point, in which the true value lies with probability P.</li>
264 *   <li>Absolute horizontal accuracy of the data’s coordinates, expressed in terms of circular error at 90% probability given that a bias is present.</li>
265 *   <li>Absolute horizontal accuracy of the data’s coordinates, expressed in terms of circular error at 90% probability given that a bias is present.</li>
266 *   <li>2D ellipse with the two main axes indicating the direction and magnitude of the highest and the lowest uncertainty of a 2D point.</li>
267 *   <li>2D ellipse with the two main axes indicating the direction and magnitude of the highest and the lowest uncertainty of a 2D point.</li>
268 * </ol>
269 *
270 * @author  Martin Desruisseaux (IRD)
271 * @author  Alexis Gaillard (Geomatys)
272 * @version 3.1
273 * @since   2.0
274 */
275@UML(identifier="DQ_AbsoluteExternalPositionalAccuracy", specification=ISO_19157)
276public interface AbsoluteExternalPositionalAccuracy extends PositionalAccuracy {
277}