Scale bar nautical miles (#6897)

evil159 · github-actions[bot] · commit 3ae865411ff7 · 2025-09-30T11:41:15.000Z
Adds `ScaleBarSettings.distanceUnits`/`ScaleBarViewOptions.units` along with adding support for nautical scale bar units. Now scale bar supports: metric, imperial and nautical units. Addresses: https://mapbox.atlassian.net/browse/MAPSSDK-869 cc @mapbox/maps-android cc @mapbox/maps-ios cc @mapbox/sdk-ci GitOrigin-RevId: 1abaf1d4b41491333bb9ab5061025ebacc5792b9
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,8 @@ Mapbox welcomes participation and contributions from everyone.
 
 ## main
 
+* Introduced `ScaleBarViewOptions.units` property supporting metric, imperial, and nautical units, replacing the boolean `useMetricUnits` property.
+
 ## 11.16.0-beta.1 - 23 September, 2025
 
 * Added experimental `scaleFactor` param to `MapOptions`, `MapSnapshotOptions` for scaling icons and texts.
diff --git a/Sources/Examples/All Examples/DebugMapExample.swift b/Sources/Examples/All Examples/DebugMapExample.swift
@@ -55,7 +55,7 @@ final class DebugMapExample: UIViewController, ExampleProtocol {
         mapView = MapView(frame: view.bounds)
         let maxFPS = Float(UIScreen.main.maximumFramesPerSecond)
         mapView.preferredFrameRateRange = CAFrameRateRange(minimum: 1, maximum: maxFPS, preferred: maxFPS)
-
+        mapView.ornaments.options.scaleBar.units = .nautical
         view.addSubview(mapView)
         view.backgroundColor = .skyBlue
         mapView.translatesAutoresizingMaskIntoConstraints = false
diff --git a/Sources/MapboxMaps/Ornaments/DistanceFormatter.swift b/Sources/MapboxMaps/Ornaments/DistanceFormatter.swift
@@ -11,23 +11,31 @@ internal class DistanceFormatter: MeasurementFormatter {
     ///
     /// - parameter distance: The distance, measured in meters.
     /// - returns: A localized formatted distance string including units.
-    internal func string(fromDistance distance: CLLocationDistance, useMetricSystem: Bool? = nil) -> String {
+    internal func string(fromDistance distance: CLLocationDistance, units: ScaleBarViewOptions.Units) -> String {
 
         numberFormatter.roundingIncrement = 0.25
 
         var measurement = Measurement(value: distance, unit: UnitLength.meters)
 
-        let shouldUseMetricSystem = useMetricSystem ?? locale.usesMetricSystem
-
-        if shouldUseMetricSystem {
-            unitOptions = [.providedUnit, .naturalScale]
-        } else {
+        switch units {
+        case .imperial:
             unitOptions = .providedUnit
             measurement.convert(to: .miles)
             if measurement.value <= 0.2 {
                 measurement.convert(to: .feet)
             }
+        case .nautical:
+            unitOptions = .providedUnit
+            measurement.convert(to: .nauticalMiles)
+            if measurement.value <= 0.2 {
+                measurement.convert(to: .fathoms)
+            }
+        case .metric:
+            unitOptions = [.providedUnit, .naturalScale]
+        default:
+            unitOptions = [.providedUnit, .naturalScale]
         }
+
         return string(from: measurement)
     }
 }
diff --git a/Sources/MapboxMaps/Ornaments/OrnamentOptions.swift b/Sources/MapboxMaps/Ornaments/OrnamentOptions.swift
@@ -54,6 +54,33 @@ public struct OrnamentOptions: Equatable, Sendable {
 /// Used to configure position, margin, and visibility for the map's scale bar view.
 public struct ScaleBarViewOptions: Equatable, Sendable {
 
+    /// The type of the distance unit the scale bar displays in.
+    public struct Units: RawRepresentable, Equatable, Sendable {
+        public let rawValue: String
+
+        public init(rawValue: String) {
+            self.rawValue = rawValue
+        }
+
+        /// Imperial units using feet for short distances and miles for longer distances.
+        ///
+        /// The scale bar will display distances in feet for small distances
+        /// and automatically switch to miles for longer distances.
+        public static let imperial = Units(rawValue: "imperial")
+
+        /// Metric units using meters and kilometers.
+        ///
+        /// The scale bar will automatically choose between meters and kilometers
+        /// based on the distance being displayed for optimal readability.
+        public static let metric = Units(rawValue: "metric")
+
+        /// Nautical units using fathoms for short distances and nautical miles for longer distances.
+        ///
+        /// The scale bar will display distances in fathoms for small distances
+        /// and automatically switch to nautical miles for longer distances. Commonly used for marine and aviation navigation.
+        public static let nautical = Units(rawValue: "nautical")
+    }
+
     /// The position of the scale bar view.
     ///
     /// The default value for this property is `.topLeading`.
@@ -73,7 +100,30 @@ public struct ScaleBarViewOptions: Equatable, Sendable {
     /// True if the scale bar is using metric units, false if the scale bar is using imperial units.
     ///
     /// The default value for this property is `Locale.current.usesMetricSystem`.
-    public var useMetricUnits: Bool
+    @available(*, deprecated, renamed: "units", message: "Use `units` instead.")
+    public var useMetricUnits: Bool {
+        didSet {
+            guard useMetricUnits != oldValue, !ignoreDeprecatedUnitUpdates else {
+                return
+            }
+            units = useMetricUnits ? .metric : .imperial
+        }
+    }
+
+    /// Specifies the distance units the scale bar uses.
+    ///
+    /// The default value for this property is `.metric`.
+    public var units: Units {
+        didSet {
+            guard units != oldValue else {
+                return
+            }
+            ignoreDeprecatedUnitUpdates = true
+            useMetricUnits = units == .metric
+            ignoreDeprecatedUnitUpdates = false
+        }
+    }
+    private var ignoreDeprecatedUnitUpdates: Bool = false
 
     /// Initializes a `ScaleBarViewOptions`.
     /// - Parameters:
@@ -85,12 +135,20 @@ public struct ScaleBarViewOptions: Equatable, Sendable {
         position: OrnamentPosition = .topLeading,
         margins: CGPoint = .init(x: 8.0, y: 8.0),
         visibility: OrnamentVisibility = .adaptive,
-        useMetricUnits: Bool = Locale.current.usesMetricSystem
+        useMetricUnits: Bool = Locale.current.usesMetricSystem,
+        units: Units? = nil
     ) {
         self.position = position
         self.margins = margins
         self.visibility = visibility
-        self.useMetricUnits = useMetricUnits
+
+        if let units {
+            self.useMetricUnits = units == .metric
+            self.units = units
+        } else {
+            self.useMetricUnits = useMetricUnits
+            self.units = useMetricUnits ? .metric : .imperial
+        }
     }
 }
 
diff --git a/Sources/MapboxMaps/Ornaments/OrnamentsManager.swift b/Sources/MapboxMaps/Ornaments/OrnamentsManager.swift
@@ -229,7 +229,7 @@ public final class OrnamentsManager {
         _compassView.visibility = options.compass.visibility
         _compassView.isHidden = options.compass.visibility == .hidden
         _attributionButton.isHidden = options.attributionButton.visibility == .hidden
-        _scaleBarView.useMetricUnits = options.scaleBar.useMetricUnits
+        _scaleBarView.units = options.scaleBar.units
         if _attributionButton.tintColor != options.attributionButton.tintColor {
             _attributionButton.tintColor = options.attributionButton.tintColor
         }
diff --git a/Sources/MapboxMaps/Ornaments/ScaleBar/MapboxScaleBarConstants.swift b/Sources/MapboxMaps/Ornaments/ScaleBar/MapboxScaleBarConstants.swift
@@ -10,6 +10,9 @@ extension MapboxScaleBarOrnamentView {
         internal static let feetPerMile: Double = 5280
         internal static let feetPerMeter: Double = 3.28084
 
+        internal static let feetPerNauticalMile: Double = 6076.12
+        internal static let feetPerFathom: Double = 6
+
         internal static let barHeight: CGFloat = 4
         internal static let scaleBarLabelWidthHint: CGFloat = 30.0
         internal static let scaleBarMinimumBarWidth: CGFloat = 30.0 // Arbitrary
@@ -99,6 +102,39 @@ extension MapboxScaleBarOrnamentView {
             (distance: 10000*feetPerMile, numberOfBars: 2)
         ]
 
+        internal static let nauticalTable: [Row] = [
+            // Small distances in fathoms
+            (distance: 1*feetPerFathom, numberOfBars: 2),        // 1 fathom
+            (distance: 2*feetPerFathom, numberOfBars: 2),        // 2 fathoms
+            (distance: 3*feetPerFathom, numberOfBars: 3),        // 3 fathoms
+            (distance: 5*feetPerFathom, numberOfBars: 2),        // 5 fathoms
+            (distance: 10*feetPerFathom, numberOfBars: 2),       // 10 fathoms
+            (distance: 20*feetPerFathom, numberOfBars: 2),       // 20 fathoms
+            (distance: 30*feetPerFathom, numberOfBars: 3),       // 30 fathoms
+            (distance: 50*feetPerFathom, numberOfBars: 2),       // 50 fathoms
+            (distance: 100*feetPerFathom, numberOfBars: 2),      // 100 fathoms
+            (distance: 200*feetPerFathom, numberOfBars: 2),      // 200 fathoms
+
+            // Nautical miles
+            (distance: 0.5*feetPerNauticalMile, numberOfBars: 2),   // 1/2 nautical mile
+            (distance: 1*feetPerNauticalMile, numberOfBars: 2),     // 1 nautical mile
+            (distance: 2*feetPerNauticalMile, numberOfBars: 2),     // 2 nautical miles
+            (distance: 3*feetPerNauticalMile, numberOfBars: 3),     // 3 nautical miles
+            (distance: 5*feetPerNauticalMile, numberOfBars: 2),     // 5 nautical miles
+            (distance: 10*feetPerNauticalMile, numberOfBars: 2),    // 10 nautical miles
+            (distance: 20*feetPerNauticalMile, numberOfBars: 2),    // 20 nautical miles
+            (distance: 30*feetPerNauticalMile, numberOfBars: 3),    // 30 nautical miles
+            (distance: 50*feetPerNauticalMile, numberOfBars: 2),    // 50 nautical miles
+            (distance: 100*feetPerNauticalMile, numberOfBars: 2),   // 100 nautical miles
+            (distance: 200*feetPerNauticalMile, numberOfBars: 2),   // 200 nautical miles
+            (distance: 300*feetPerNauticalMile, numberOfBars: 3),   // 300 nautical miles
+            (distance: 500*feetPerNauticalMile, numberOfBars: 2),   // 500 nautical miles
+            (distance: 1000*feetPerNauticalMile, numberOfBars: 2),  // 1000 nautical miles
+            (distance: 2000*feetPerNauticalMile, numberOfBars: 2),  // 2000 nautical miles
+            (distance: 3000*feetPerNauticalMile, numberOfBars: 3),  // 3000 nautical miles
+            (distance: 5000*feetPerNauticalMile, numberOfBars: 2),  // 5000 nautical miles
+        ]
+
         private init() {}
     }
 }
diff --git a/Sources/MapboxMaps/Ornaments/ScaleBar/MapboxScaleBarOrnamentView.swift b/Sources/MapboxMaps/Ornaments/ScaleBar/MapboxScaleBarOrnamentView.swift
@@ -93,7 +93,11 @@ internal class MapboxScaleBarOrnamentView: UIView {
     private var shouldLayoutBars = false
 
     internal var unitsPerPoint: Double {
-        return useMetricUnits ? metersPerPoint : metersPerPoint * Constants.feetPerMeter
+        return switch units {
+        case .imperial, .nautical: metersPerPoint * Constants.feetPerMeter
+        case .metric: metersPerPoint
+        default: metersPerPoint
+        }
     }
 
     internal var maximumWidth: CGFloat {
@@ -103,9 +107,9 @@ internal class MapboxScaleBarOrnamentView: UIView {
         return floor(bounds.width / 2)
     }
 
-    internal var useMetricUnits: Bool = true {
+    internal var units: ScaleBarViewOptions.Units = .metric {
         didSet {
-            guard useMetricUnits != oldValue else {
+            guard units != oldValue else {
                 return
             }
 
@@ -315,7 +319,7 @@ internal class MapboxScaleBarOrnamentView: UIView {
         if let image = labelImageCache[distance] {
             return image
         } else {
-            let text = formatter.string(fromDistance: distance, useMetricSystem: useMetricUnits)
+            let text = formatter.string(fromDistance: distance, units: units)
             let image = renderImageFor(text: text)
             labelImageCache[distance] = image
             return image
@@ -325,8 +329,9 @@ internal class MapboxScaleBarOrnamentView: UIView {
     private func updateLabels() {
         var multiplier = row.distance / Double(row.numberOfBars)
 
-        if !useMetricUnits {
-            multiplier /= Constants.feetPerMeter
+        switch units {
+        case .imperial, .nautical: multiplier /= Constants.feetPerMeter
+        default: break
         }
 
         labelViews.enumerated().forEach {
@@ -388,10 +393,12 @@ internal class MapboxScaleBarOrnamentView: UIView {
 
     private func maxDistanceAndRows() -> (maxDistance: Measurement<UnitLength>, rows: [Row]) {
         let distanceInMeters = Measurement(value: metersPerPoint * maximumWidth, unit: UnitLength.meters)
-        if useMetricUnits {
-            return (distanceInMeters, Constants.metricTable)
-        } else {
-            return (distanceInMeters.converted(to: .feet), Constants.imperialTable)
+
+        return switch units {
+        case .imperial: (distanceInMeters.converted(to: .feet), Constants.imperialTable)
+        case .nautical: (distanceInMeters.converted(to: .feet), Constants.nauticalTable)
+        case .metric: (distanceInMeters, Constants.metricTable)
+        default: (distanceInMeters, Constants.metricTable)
         }
     }
 }
diff --git a/Tests/MapboxMapsTests/Annotations/ViewAnnotationTests.swift b/Tests/MapboxMapsTests/Annotations/ViewAnnotationTests.swift
@@ -1,5 +1,5 @@
 @_spi(Experimental) @testable import MapboxMaps
-import SwiftUICore
+import SwiftUI
 import XCTest
 
 final class ViewAnnotationTests: XCTestCase {
diff --git a/Tests/MapboxMapsTests/Ornaments/DistanceFormatterTests.swift b/Tests/MapboxMapsTests/Ornaments/DistanceFormatterTests.swift
@@ -7,7 +7,7 @@ class DistanceFormatterTests: XCTestCase {
         let sut = DistanceFormatter()
         sut.locale = Locale(identifier: "EN_CA")
 
-        let formattedString = sut.string(fromDistance: 1)
+        let formattedString = sut.string(fromDistance: 1, units: .metric)
 
         XCTAssert(sut.locale.usesMetricSystem, "Selected locale does not use Metric system")
         XCTAssertEqual(formattedString, "1 m", "Meters distance is not formatted correctly!")
@@ -17,7 +17,7 @@ class DistanceFormatterTests: XCTestCase {
         let sut = DistanceFormatter()
         sut.locale = Locale(identifier: "EN_CA")
 
-        let formattedString = sut.string(fromDistance: 1337)
+        let formattedString = sut.string(fromDistance: 1337, units: .metric)
 
         XCTAssert(sut.locale.usesMetricSystem, "Selected locale does not use Metric system")
         XCTAssertEqual(formattedString, "1.25 km", "Kilometers distance is not formatted correctly!")
@@ -27,7 +27,7 @@ class DistanceFormatterTests: XCTestCase {
         let sut = DistanceFormatter()
         sut.locale = Locale(identifier: "EN_US")
 
-        let formattedString = sut.string(fromDistance: 1)
+        let formattedString = sut.string(fromDistance: 1, units: .imperial)
 
         XCTAssert(!sut.locale.usesMetricSystem, "Selected locale does not use Imperial system")
         XCTAssertEqual(formattedString, "3.25 ft", "Feet distance is not formatted correctly!")
@@ -37,7 +37,7 @@ class DistanceFormatterTests: XCTestCase {
         let sut = DistanceFormatter()
         sut.locale = Locale(identifier: "EN_US")
 
-        let formattedString = sut.string(fromDistance: 1337)
+        let formattedString = sut.string(fromDistance: 1337, units: .imperial)
 
         XCTAssert(!sut.locale.usesMetricSystem, "Selected locale does not use Imperial system")
         XCTAssertEqual(formattedString, "0.75 mi", "Miles distance is not formatted correctly!")
@@ -47,7 +47,7 @@ class DistanceFormatterTests: XCTestCase {
         let sut = DistanceFormatter()
         sut.locale = Locale(identifier: "EN_US")
 
-        let formattedString = sut.string(fromDistance: 1337, useMetricSystem: true)
+        let formattedString = sut.string(fromDistance: 1337, units: .metric)
 
         XCTAssertFalse(sut.locale.usesMetricSystem, "Selected locale does not use Metric system")
         XCTAssertEqual(formattedString, "1.25 km", "Kilometers distance is not formatted correctly!")
@@ -57,12 +57,43 @@ class DistanceFormatterTests: XCTestCase {
         let sut = DistanceFormatter()
         sut.locale = Locale(identifier: "EN_CA")
 
-        let formattedString = sut.string(fromDistance: 1337, useMetricSystem: false)
+        let formattedString = sut.string(fromDistance: 1337, units: .imperial)
 
         XCTAssert(sut.locale.usesMetricSystem, "Selected locale does not use Metric system")
         XCTAssertEqual(
             formattedString.trimmingCharacters(in: CharacterSet(charactersIn: ".")),
             "0.75 mi",
             "Miles distance is not formatted correctly!")
     }
+
+    func testFathomsFormat() {
+        let sut = DistanceFormatter()
+        sut.locale = Locale(identifier: "EN_US")
+
+        let formattedString = sut.string(fromDistance: 18.288, units: .nautical) // ~10 fathoms
+
+        XCTAssertEqual(formattedString, "10 fth", "Small nautical distance should be formatted in fathoms")
+    }
+
+    func testNauticalMilesFormat() {
+        let sut = DistanceFormatter()
+        sut.locale = Locale(identifier: "EN_US")
+
+        let formattedString = sut.string(fromDistance: 1852, units: .nautical) // 1 nautical mile
+
+        XCTAssertEqual(formattedString, "1 nmi", "Large nautical distance should be formatted in nautical miles")
+    }
+
+    func testNauticalUnitsFormatting() {
+        let sut = DistanceFormatter()
+        sut.locale = Locale(identifier: "EN_US")
+
+        // Test small distance (should use fathoms)
+        let smallDistance = sut.string(fromDistance: 103, units: .nautical) // ~54 fathoms
+        XCTAssertEqual(smallDistance, "56.25 fth", "Distance under 0.2 nautical miles should use fathoms")
+
+        // Test large distance (should use nautical miles)
+        let largeDistance = sut.string(fromDistance: 5556, units: .nautical) // ~3 nautical miles
+        XCTAssertEqual(largeDistance, "3 nmi", "Distance over 0.2 nautical miles should use nautical miles")
+    }
 }
diff --git a/Tests/MapboxMapsTests/Ornaments/OrnamentManagerTests.swift b/Tests/MapboxMapsTests/Ornaments/OrnamentManagerTests.swift
diff --git a/Tests/MapboxMapsTests/Ornaments/ScaleBar/MapboxScaleBarOrnamentViewTests.swift b/Tests/MapboxMapsTests/Ornaments/ScaleBar/MapboxScaleBarOrnamentViewTests.swift
diff --git a/scripts/api-compatibility-check/breakage_allowlist.txt b/scripts/api-compatibility-check/breakage_allowlist.txt

Original file line number	Diff line number	Diff line change
`@@ -229,7 +229,7 @@ public final class OrnamentsManager {`
`229`	`229`	`_compassView.visibility = options.compass.visibility`
`230`	`230`	`_compassView.isHidden = options.compass.visibility == .hidden`
`231`	`231`	`_attributionButton.isHidden = options.attributionButton.visibility == .hidden`
`232`		`- _scaleBarView.useMetricUnits = options.scaleBar.useMetricUnits`
	`232`	`+ _scaleBarView.units = options.scaleBar.units`
`233`	`233`	`if _attributionButton.tintColor != options.attributionButton.tintColor {`
`234`	`234`	`_attributionButton.tintColor = options.attributionButton.tintColor`
`235`	`235`	`}`