01 /*
02 * Java GPX Library (jpx-3.1.0).
03 * Copyright (c) 2016-2023 Franz Wilhelmstötter
04 *
05 * Licensed under the Apache License, Version 2.0 (the "License");
06 * you may not use this file except in compliance with the License.
07 * You may obtain a copy of the License at
08 *
09 * 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 * Author:
18 * Franz Wilhelmstötter (franz.wilhelmstoetter@gmail.com)
19 */
20 package io.jenetics.jpx;
21
22 import java.time.Instant;
23 import java.util.Optional;
24
25 import io.jenetics.jpx.geom.Geoid;
26
27 /**
28 * A geographic point with optional elevation and time.
29 *
30 * @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
31 * @version 3.0
32 * @since 1.0
33 */
34 public interface Point {
35
36 /**
37 * The latitude of the point, WGS84 datum.
38 *
39 * @return the latitude of the point
40 */
41 Latitude getLatitude();
42
43 /**
44 * The longitude of the point, WGS84 datum.
45 *
46 * @return the longitude of the point
47 */
48 Longitude getLongitude();
49
50 /**
51 * The elevation (in meters) of the point.
52 *
53 * @return the elevation (in meters) of the point
54 */
55 default Optional<Length> getElevation() {
56 return Optional.empty();
57 }
58
59 /**
60 * Creation/modification timestamp for the point.
61 *
62 * @return creation/modification timestamp for the point
63 */
64 default Optional<Instant> getTime() {
65 return Optional.empty();
66 }
67
68 /**
69 * Calculate the distance between points on the default ellipsoidal earth
70 * model
71 * <a href="https://en.wikipedia.org/wiki/World_Geodetic_System#A_new_World_Geodetic_System:_WGS_84">
72 * WGS-84</a>.
73 *
74 * @see <a href="http://www.ngs.noaa.gov/PUBS_LIB/inverse.pdf">DIRECT AND
75 * INVERSE SOLUTIONS OF GEODESICS 0 THE ELLIPSOID
76 * WITH APPLICATION OF NESTED EQUATIONS</a>
77 * @see <a href="http://www.movable-type.co.uk/scripts/latlong-vincenty.html">
78 * Vincenty solutions of geodesics on the ellipsoid</a>
79 *
80 * @param end the end point
81 * @return the distance between {@code this} and {@code end} in meters
82 * @throws NullPointerException if the {@code end} point is {@code null}
83 */
84 default Length distance(final Point end) {
85 return Geoid.DEFAULT.distance(this, end);
86 }
87
88 }
|