Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/features/geodesy.rst
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,10 @@ Other Geodetic Functions

.. autofunction:: geodepy.geodesy.line_sf

.. autofunction:: geodepy.geodesy.height_sf

.. autofunction:: geodepy.geodesy.combined_sf

.. autofunction:: geodepy.geodesy.rho

.. autofunction:: geodepy.geodesy.nu
Expand Down
111 changes: 111 additions & 0 deletions geodepy/geodesy.py
Original file line number Diff line number Diff line change
Expand Up @@ -498,6 +498,117 @@ def line_sf(
return projection.cmscale * (1 + k1 * (1 + k2))


def height_sf(
zone1,
east1,
north1,
height1,
zone2=None,
east2=None,
north2=None,
height2=None,
hemisphere="south",
ellipsoid=grs80,
projection=utm,
):
"""
Computes the Height Scale Factor. If two points are provided, the Height Scale
Factor is computed using the radius of curvature at point 1 of the normal section
in the direction of the azimuth between points 1 and 2

Ref: Deakin 2006, Traverse Computations on the UTM Projection for Surveys
of Limited Extent, pp 13
Ref: GDA2020 Technical Manual v1.8, Section 5.1.1 pp 51-53

Note: This function ignores the deflection of the vertical and assumes that the ellipsoid
normal is parallel to the geoid normal. For larger-extent or geoid-sensitive surveys, the
deflection of the vertical should be considered when computing the height scale factor/combined
scale factor.

:param zone1: Station 1 Zone Number - 1 to 60
:param east1: Station 1 Easting (m, within 3330km of Central Meridian)
:param north1: Station 1 Northing (m, 0 to 10,000,000m)
:param height1: Station 1 Ellipsoid Height (m)
:param zone2: Station 2 Zone Number - 1 to 60
:param east2: Station 2 Easting (m, within 3330km of Central Meridian)
:param north2: Station 2 Northing (m, 0 to 10,000,000m)
:param height2: Station 2 Ellipsoid Height (m)
:param hemisphere: String - 'North' or 'South'(default)
:param ellipsoid: Ellipsoid Object (default GRS80)
:param projection: Projection Object (default Universal Transverse Mercator)
:return: Height Scale Factor
"""
point2_args = (zone2, east2, north2, height2)
if any(a is not None for a in point2_args) and not all(a is not None for a in point2_args):
raise ValueError("zone2, east2, north2 and height2 must all be provided for a two-point solution")

lat1, lon1 = grid2geo(zone1, east1, north1, hemisphere, ellipsoid, projection)[:2]
rho1 = rho(lat1, ellipsoid)
nu1 = nu(lat1, ellipsoid)

if zone2 is not None: # Using Radius of Curvature in the Azimuth of the Line between Points 1 & 2 - Tech Manual Formula 64
lat2, lon2 = grid2geo(zone2, east2, north2, hemisphere, ellipsoid, projection)[:2]
az1to2 = vincinv(lat1, lon1, lat2, lon2, ellipsoid)[1]
arc_rad = (rho1 * nu1) / ((rho1 * sin(radians(az1to2))**2) + (nu1 * cos(radians(az1to2))**2))
return arc_rad / (arc_rad + ((height1 + height2) / 2))
else: # Using Geometric Mean Radius of Curvature - Tech Manual Formula 63
arc_rad = sqrt(rho1 * nu1)
return arc_rad / (arc_rad + height1)


def combined_sf(
zone1,
east1,
north1,
height1,
zone2=None,
east2=None,
north2=None,
height2=None,
hemisphere="south",
ellipsoid=grs80,
projection=utm,
):
"""
Computes the Combined Scale Factor. If two points are provided, the result is the product
of the Line Scale Factor and Height Factor. If one point is provided, the result is the
product of the Point Scale Factor and Height Factor.

Ref: Deakin 2006, Traverse Computations on the UTM Projection for Surveys
of Limited Extent, pp 13

Note: This function ignores the deflection of the vertical and assumes that the ellipsoid
normal is parallel to the geoid normal. For larger-extent or geoid-sensitive surveys, the
deflection of the vertical should be considered when computing the height scale factor/combined
scale factor.

:param zone1: Station 1 Zone Number - 1 to 60
:param east1: Station 1 Easting (m, within 3330km of Central Meridian)
:param north1: Station 1 Northing (m, 0 to 10,000,000m)
:param height1: Station 1 Ellipsoid Height (m)
:param zone2: Station 2 Zone Number - 1 to 60
:param east2: Station 2 Easting (m, within 3330km of Central Meridian)
:param north2: Station 2 Northing (m, 0 to 10,000,000m)
:param height2: Station 2 Ellipsoid Height (m)
:param hemisphere: String - 'North' or 'South'(default)
:param ellipsoid: Ellipsoid Object (default GRS80)
:param projection: Projection Object (default Universal Transverse Mercator)
:return: Combined Scale Factor
"""
point2_args = (zone2, east2, north2, height2)
if any(a is not None for a in point2_args) and not all(a is not None for a in point2_args):
raise ValueError("zone2, east2, north2 and height2 must all be provided for a two-point solution")

hsf = height_sf(zone1, east1, north1, height1, zone2, east2, north2, height2, hemisphere, ellipsoid, projection)

if zone2 is not None:
lsf = line_sf(zone1, east1, north1, zone2, east2, north2, hemisphere, ellipsoid, projection)
return lsf * hsf
else:
psf = grid2geo(zone1, east1, north1, hemisphere, ellipsoid, projection)[2]
return psf * hsf


def rho(lat, ellipsoid=grs80):
"""
Return the radius of curvature of the ellipsoid in the meridian plane
Expand Down
105 changes: 104 additions & 1 deletion geodepy/tests/test_geodesy.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,18 @@
llh2xyz,
DMSAngle,
)
from geodepy.geodesy import vincinv, vincdir, vincinv_utm, vincdir_utm, enu2xyz, xyz2enu
from geodepy.geodesy import (
vincinv,
vincdir,
vincinv_utm,
vincdir_utm,
enu2xyz,
xyz2enu,
height_sf,
combined_sf,
rho,
nu,
)


class TestGeodesy(unittest.TestCase):
Expand Down Expand Up @@ -263,6 +274,98 @@ def test_equality_vincentys(self):
)
np.testing.assert_almost_equal(vincinv_result[:, 2], vincdir_result[:, 2])

# Worked example from Deakin 2006, Traverse Computation on the UTM
# Projection for Surveys of Limited Extent, Steeles Road traverse
# (pp 16-18). Coordinates are MGA Zone 55; Reduced Levels (RL's, AHD
# heights) are from the diagram on page 16, and converted to ellipsoidal
# heights using h = AHD height + N with an average geoid-ellipsoid
# separation N = 6 m (Step 6, "say 6 m (nearest metre)").
N_VALUE = 6
STATIONS = {
"PM32": (55, 233624.855, 5848077.325, 525),
"PT_A": (55, 234085, 5847363, 520),
"PT_B": (55, 233971, 5846869, 500),
"PT_C": (55, 234622, 5846238, 480),
"PT_D": (55, 235474, 5846317, 460),
"PM47": (55, 235549.870, 5845514.270, 480),
}

def _station_args(self, name):
zone, east, north, rl = self.STATIONS[name]
return zone, east, north, rl + self.N_VALUE

def test_height_sf(self):
# (station1, station2, expected Height Scale Factor) from the
# paper's Step 6 table
lines = (
("PM32", "PT_A", 0.9999171),
("PT_A", "PT_B", 0.9999190),
("PT_B", "PT_C", 0.9999221),
("PT_C", "PT_D", 0.9999253),
("PT_D", "PM47", 0.9999253),
)
for station1, station2, expected_hsf in lines:
with self.subTest(station1=station1, station2=station2):
zone1, east1, north1, height1 = self._station_args(station1)
zone2, east2, north2, height2 = self._station_args(station2)
hsf = height_sf(
zone1, east1, north1, height1, zone2, east2, north2, height2
)
self.assertAlmostEqual(hsf, expected_hsf, 6)

# Single point solution: not covered by a worked example in Deakin
# 2006 (all of its examples are line-based), so this is instead
# checked for self-consistency against the Height Scale Factor
# formula (R = sqrt(rho * nu), HSF = R / (R + h)) documented in both
# Deakin 2006 Eq. 11 and GDA2020 Technical Manual v1.8 Eq. 63,
# computed independently here using the module's rho() and nu()
zone1, east1, north1, height1 = self._station_args("PM32")
lat1 = grid2geo(zone1, east1, north1)[0]
r = (rho(lat1) * nu(lat1)) ** 0.5
expected_hsf = r / (r + height1)
self.assertAlmostEqual(
height_sf(zone1, east1, north1, height1), expected_hsf, 9
)

def test_height_sf_requires_all_point2_args(self):
pm32 = self._station_args("PM32")
with self.assertRaises(ValueError):
height_sf(*pm32, zone2=55, east2=234085)

def test_combined_sf(self):
# (station1, station2, expected Combined Scale Factor) from the
# paper's Step 6 table
lines = (
("PM32", "PT_A", 1.0003897),
("PT_A", "PT_B", 1.0003904),
("PT_B", "PT_C", 1.0003918),
("PT_C", "PT_D", 1.0003901),
("PT_D", "PM47", 1.0003871),
)
for station1, station2, expected_csf in lines:
with self.subTest(station1=station1, station2=station2):
zone1, east1, north1, height1 = self._station_args(station1)
zone2, east2, north2, height2 = self._station_args(station2)
csf = combined_sf(
zone1, east1, north1, height1, zone2, east2, north2, height2
)
self.assertAlmostEqual(csf, expected_csf, 6)

# Single point solution: no published worked example exists in
# Deakin 2006, so this checks self-consistency against Point Scale
# Factor x Height Scale Factor using grid2geo() and height_sf()
zone1, east1, north1, height1 = self._station_args("PM32")
psf1 = grid2geo(zone1, east1, north1)[2]
expected_csf = psf1 * height_sf(zone1, east1, north1, height1)
self.assertAlmostEqual(
combined_sf(zone1, east1, north1, height1), expected_csf, 9
)

def test_combined_sf_requires_all_point2_args(self):
pm32 = self._station_args("PM32")
with self.assertRaises(ValueError):
combined_sf(*pm32, zone2=55, east2=234085)

def test_vincinv_edgecases(self):
lat1 = -32.153892
lon1 = -15.394827
Expand Down
Loading