A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
geographic-positions.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2014 University of Washington
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Benjamin Cizdziel <ben.cizdziel@gmail.com>
7 */
8
9#include <ns3/random-variable-stream.h>
10#include <ns3/vector.h>
11
12#ifndef GEOGRAPHIC_POSITIONS_H
13#define GEOGRAPHIC_POSITIONS_H
14
15namespace ns3
16{
17
18/**
19 * \ingroup mobility
20 *
21 * Consists of methods dealing with Earth geographic coordinates and locations.
22 */
24{
25 public:
26 /**
27 * Spheroid model to use for earth: perfect sphere (SPHERE), Geodetic
28 * Reference System 1980 (GRS80), or World Geodetic System 1984 (WGS84)
29 *
30 * Moritz, H. "Geodetic Reference System 1980." GEODETIC REFERENCE SYSTEM 1980.
31 * <https://web.archive.org/web/20170712034716/http://www.gfy.ku.dk/~iag/HB2000/part4/grs80_corr.htm>.
32 *
33 * "Department of Defense World Geodetic System 1984." National Imagery and
34 * Mapping Agency, 1 Jan. 2000.
35 * <https://web.archive.org/web/20200729203634/https://earth-info.nga.mil/GandG/publications/tr8350.2/wgs84fin.pdf>.
36 */
37
38 /// Earth's radius in meters if modeled as a perfect sphere
39 static constexpr double EARTH_SPHERE_RADIUS = 6371e3;
40
41 /// Earth's eccentricity if modeled as a perfect sphere
42 static constexpr double EARTH_SPHERE_ECCENTRICITY = 0;
43
44 /// Earth's flattening if modeled as a perfect sphere
45 static constexpr double EARTH_SPHERE_FLATTENING = 0;
46
47 /// <Earth's semi-major axis in meters as defined by both GRS80 and WGS84
48 /// https://en.wikipedia.org/wiki/World_Geodetic_System
49 static constexpr double EARTH_SEMIMAJOR_AXIS = 6378137;
50
51 /// Earth's first eccentricity as defined by GRS80
52 /// https://en.wikipedia.org/wiki/Geodetic_Reference_System_1980
53 static constexpr double EARTH_GRS80_ECCENTRICITY = 0.0818191910428158;
54
55 /// Earth's first flattening as defined by GRS80
56 /// https://en.wikipedia.org/wiki/Geodetic_Reference_System_1980
57 static constexpr double EARTH_GRS80_FLATTENING = 0.003352810681183637418;
58
59 /// Earth's first eccentricity as defined by
60 /// https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84
61 static constexpr double EARTH_WGS84_ECCENTRICITY = 0.0818191908426215;
62
63 /// Earth's first flattening as defined by WGS84
64 /// https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84
65 static constexpr double EARTH_WGS84_FLATTENING = 0.00335281;
66
67 /// The possible Earth spheroid models. .
74
75 /**
76 * Converts earth geographic/geodetic coordinates (latitude and longitude in
77 * degrees) with a given altitude above earth's surface (in meters) to Earth
78 * Centered Earth Fixed (ECEF) Cartesian coordinates (x, y, z in meters),
79 * where origin (0, 0, 0) is the center of the earth.
80 *
81 * @param latitude earth-referenced latitude (in degrees) of the point
82 * @param longitude earth-referenced longitude (in degrees) of the point
83 * @param altitude height of the point (in meters) above earth's surface
84 * @param sphType earth spheroid model to use for conversion
85 *
86 * @return a vector representing the Cartesian coordinates (x, y, z referenced
87 * in meters) of the point (origin (0, 0, 0) is center of earth)
88 */
89 static Vector GeographicToCartesianCoordinates(double latitude,
90 double longitude,
91 double altitude,
92 EarthSpheroidType sphType);
93
94 /**
95 * Inverse of GeographicToCartesianCoordinates using [1]
96 *
97 * This function iteratively converts cartesian (ECEF) coordinates to
98 * geographic coordinates. The residual delta is 1 m, which is approximately
99 * 1 / 30 arc seconds or 9.26e-6 deg.
100 *
101 * @param pos a vector representing the Cartesian coordinates (x, y, z referenced
102 * in meters) of the point (origin (0, 0, 0) is center of earth)
103 * @param sphType earth spheroid model to use for conversion
104 *
105 * @return Vector position where x = latitude (deg), y = longitude (deg),
106 * z = altitude above the ellipsoid (m)
107 *
108 * [1] "Ellipsoidal and Cartesian Coordinates Conversion", Navipedia,
109 * European Space Agency, Jul 8, 2019.
110 * <https://gssc.esa.int/navipedia/index.php/Ellipsoidal_and_Cartesian_Coordinates_Conversion>
111 */
112 static Vector CartesianToGeographicCoordinates(Vector pos, EarthSpheroidType sphType);
113
114 /**
115 * Conversion from geographic to topocentric coordinates.
116 *
117 * Conversion formulas taken from [1, Sec. 4.1.3 "Geographic/topocentric conversions"].
118 * [1] IOGP. Geomatics guidance note 7, part 2: coordinate conversions & transformations
119 * including formulas. IOGP Publication 373-7-2, International Association For Oil And Gas
120 * Producers, Sep. 2019
121 * https://www.iogp.org/bookstore/product/coordinate-conversions-and-transformation-including-formulas/
122 *
123 * @param pos a vector representing the Geographic coordinates (latitude, longitude, altitude)
124 * in degrees (lat/lon) and meters (altitude).
125 * @param refPoint a vector representing the reference point (latitude, longitude, altitude) in
126 * degrees (lat/lon) and meters (altitude). Default is (0,0,0)
127 * @param sphType earth spheroid model to use for conversion
128 *
129 * @return Vector position in meters and using planar Cartesian coordinates, i.e., ns-3's
130 * defaults
131 */
132 static Vector GeographicToTopocentricCoordinates(Vector pos,
133 Vector refPoint,
134 EarthSpheroidType sphType);
135
136 /**
137 * Conversion from topocentric to geographic.
138 *
139 * Conversion formulas taken from [1, Sec. 4.1.3 "Geographic/topocentric conversions"].
140 * [1] IOGP. Geomatics guidance note 7, part 2: coordinate conversions & transformations
141 * including formulas. IOGP Publication 373-7-2, International Association For Oil And Gas
142 * Producers, Sep. 2019
143 * https://www.iogp.org/bookstore/product/coordinate-conversions-and-transformation-including-formulas/
144 *
145 * @param pos a vector representing the topocentric coordinates (u, v, w) in meters, which
146 * represent the cartesian coordinates along the xEast, yNorth and zUp axes, respectively..
147 * @param refPoint a vector representing the reference point (latitude, longitude, altitude) in
148 * degrees (lat/lon) and meters (altitude). Default is (0,0,0)
149 * @param sphType earth spheroid model to use for conversion
150 *
151 * @return Vector position (latitude, longitude, altitude) in degrees (lat/lon) and meters
152 * (altitude) converted to geographic coordinates
153 */
154 static Vector TopocentricToGeographicCoordinates(Vector pos,
155 Vector refPoint,
156 EarthSpheroidType sphType);
157
158 /**
159 * Generates uniformly distributed random points (in ECEF Cartesian
160 * coordinates) within a given altitude above earth's surface centered around
161 * a given origin point (on earth's surface, in geographic/geodetic coordinates)
162 * within a given distance radius (using arc length of earth's surface, not
163 * pythagorean distance).
164 * Distance radius is measured as if all generated points are on earth's
165 * surface (with altitude = 0).
166 * Assumes earth is a perfect sphere.
167 *
168 * @param originLatitude origin point latitude in degrees
169 * @param originLongitude origin point longitude in degrees
170 * @param maxAltitude maximum altitude in meters above earth's surface with
171 * which random points can be generated
172 * @param numPoints number of points to generate
173 * @param maxDistFromOrigin max distance in meters from origin with which
174 * random transmitters can be generated (all transmitters are less than or
175 * equal to this distance from the origin, relative to points being on earth's
176 * surface)
177 * @param uniRand pointer to the uniform random variable to use for random
178 * location and altitude generation
179 *
180 * @return a list containing the vectors (x, y, z location referenced in
181 * meters from origin at center of earth) of each point generated
182 */
183 static std::list<Vector> RandCartesianPointsAroundGeographicPoint(
184 double originLatitude,
185 double originLongitude,
186 double maxAltitude,
187 int numPoints,
188 double maxDistFromOrigin,
190
191 /**
192 * @param type the type of model which is used to model the Earth
193 *
194 * @return the corresponding radius (in meters), first eccentricity and first flattening values
195 */
196 static std::tuple<double, double, double> GetRadiusEccentFlat(EarthSpheroidType type);
197};
198
199} // namespace ns3
200
201#endif /* GEOGRAPHIC_POSITIONS_H */
Consists of methods dealing with Earth geographic coordinates and locations.
static std::list< Vector > RandCartesianPointsAroundGeographicPoint(double originLatitude, double originLongitude, double maxAltitude, int numPoints, double maxDistFromOrigin, Ptr< UniformRandomVariable > uniRand)
Generates uniformly distributed random points (in ECEF Cartesian coordinates) within a given altitude...
static constexpr double EARTH_SPHERE_FLATTENING
Earth's flattening if modeled as a perfect sphere.
static constexpr double EARTH_SPHERE_ECCENTRICITY
Earth's eccentricity if modeled as a perfect sphere.
static constexpr double EARTH_SPHERE_RADIUS
Spheroid model to use for earth: perfect sphere (SPHERE), Geodetic Reference System 1980 (GRS80),...
EarthSpheroidType
The possible Earth spheroid models. .
static constexpr double EARTH_GRS80_FLATTENING
Earth's first flattening as defined by GRS80 https://en.wikipedia.org/wiki/Geodetic_Reference_System_...
static constexpr double EARTH_WGS84_ECCENTRICITY
Earth's first eccentricity as defined by https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84.
static Vector TopocentricToGeographicCoordinates(Vector pos, Vector refPoint, EarthSpheroidType sphType)
Conversion from topocentric to geographic.
static Vector GeographicToCartesianCoordinates(double latitude, double longitude, double altitude, EarthSpheroidType sphType)
Converts earth geographic/geodetic coordinates (latitude and longitude in degrees) with a given altit...
static constexpr double EARTH_WGS84_FLATTENING
Earth's first flattening as defined by WGS84 https://en.wikipedia.org/wiki/World_Geodetic_System#WGS8...
static Vector GeographicToTopocentricCoordinates(Vector pos, Vector refPoint, EarthSpheroidType sphType)
Conversion from geographic to topocentric coordinates.
static Vector CartesianToGeographicCoordinates(Vector pos, EarthSpheroidType sphType)
Inverse of GeographicToCartesianCoordinates using [1].
static constexpr double EARTH_SEMIMAJOR_AXIS
<Earth's semi-major axis in meters as defined by both GRS80 and WGS84 https://en.wikipedia....
static std::tuple< double, double, double > GetRadiusEccentFlat(EarthSpheroidType type)
static constexpr double EARTH_GRS80_ECCENTRICITY
Earth's first eccentricity as defined by GRS80 https://en.wikipedia.org/wiki/Geodetic_Reference_Syste...
Smart pointer class similar to boost::intrusive_ptr.
Every class exported by the ns3 library is enclosed in the ns3 namespace.