From 4093a85ace990ac93e882687f2967d2b17580af8 Mon Sep 17 00:00:00 2001 From: BatchelorJ Date: Thu, 5 Nov 2026 16:11:26 +1100 Subject: [PATCH 1/3] Add height scale factor and combined scale factor to geodesy module --- geodepy/geodesy.py | 89 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/geodepy/geodesy.py b/geodepy/geodesy.py index 237f73a..9bc4fd4 100644 --- a/geodepy/geodesy.py +++ b/geodepy/geodesy.py @@ -498,6 +498,95 @@ 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 + + :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 + """ + rho1 = rho(grid2geo(zone1, east1, north1, hemisphere, ellipsoid, projection)[0]) + nu1 = nu(grid2geo(zone1, east1, north1, hemisphere, ellipsoid, projection)[0]) + if zone2 is not None: # 2 point solution + az1to2 = vincinv_utm(zone1, east1, north1, zone2, east2, north2, hemisphere, 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: # single point solution + 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 + + :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 + """ + 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 From dee0389bf724d2517bbe9612b29eefcf95ba5e0b Mon Sep 17 00:00:00 2001 From: BatchelorJ Date: Sat, 7 Nov 2026 20:22:23 +1100 Subject: [PATCH 2/3] Refine functionality, add test coverage for height_sf and combined_sf --- geodepy/geodesy.py | 34 +++++++++-- geodepy/tests/test_geodesy.py | 105 +++++++++++++++++++++++++++++++++- 2 files changed, 132 insertions(+), 7 deletions(-) diff --git a/geodepy/geodesy.py b/geodepy/geodesy.py index 9bc4fd4..35f04e9 100644 --- a/geodepy/geodesy.py +++ b/geodepy/geodesy.py @@ -518,6 +518,12 @@ def height_sf( 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) @@ -532,13 +538,20 @@ def height_sf( :param projection: Projection Object (default Universal Transverse Mercator) :return: Height Scale Factor """ - rho1 = rho(grid2geo(zone1, east1, north1, hemisphere, ellipsoid, projection)[0]) - nu1 = nu(grid2geo(zone1, east1, north1, hemisphere, ellipsoid, projection)[0]) - if zone2 is not None: # 2 point solution - az1to2 = vincinv_utm(zone1, east1, north1, zone2, east2, north2, hemisphere, ellipsoid)[1] + 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: # single point solution + else: # Using Geometric Mean Radius of Curvature - Tech Manual Formula 63 arc_rad = sqrt(rho1 * nu1) return arc_rad / (arc_rad + height1) @@ -564,6 +577,11 @@ def combined_sf( 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) @@ -577,7 +595,11 @@ def combined_sf( :param projection: Projection Object (default Universal Transverse Mercator) :return: Combined Scale Factor """ - hsf = height_sf(zone1, east1, north1, height1, zone2, east2, north2, height2, hemisphere,ellipsoid, projection) + 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) diff --git a/geodepy/tests/test_geodesy.py b/geodepy/tests/test_geodesy.py index bf96c81..247b961 100644 --- a/geodepy/tests/test_geodesy.py +++ b/geodepy/tests/test_geodesy.py @@ -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): @@ -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 From 281f1143bb40f8114f5754d464f5529082cea3fe Mon Sep 17 00:00:00 2001 From: BatchelorJ Date: Wed, 11 Nov 2026 08:44:24 +1100 Subject: [PATCH 3/3] Add height_sf and combined_sf to docs --- docs/features/geodesy.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/features/geodesy.rst b/docs/features/geodesy.rst index b37aa29..37a0e04 100644 --- a/docs/features/geodesy.rst +++ b/docs/features/geodesy.rst @@ -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