[maps-ios] Fix PointAnnotation silent-fail for SF Symbol images (MAPSIOS-2182) (#12415)

## Summary

`PointAnnotation.image` and
`StyleManager.addImage(_:id:sdf:contentInsets:)` silently failed for any
`UIImage` whose `size * scale` is fractional. The common trigger is an
SF Symbol passed through `.withTintColor(_:renderingMode:
.alwaysOriginal)` — the usual way to colorize a symbol before using it
as a marker icon.

Two related floating-point-to-integer mismatches combined to produce the
failure — the second was hidden behind the first until the first was
fixed.

### 1. `Data(uiImage:)` fallback redrew at cgImage dimensions

`CoreMapsImage.init?(uiImage:)` declares the image to the native style
API as `uiImage.size * uiImage.scale` pixels. For SF Symbols and
`.withTintColor(...)` results, the backing `cgImage` pixel dimensions
diverge from `size * scale`. The `default:` fallback in
`Data.init(uiImage:)` produced a buffer sized to cgImage dims, so the
byte count did not match the declared dimensions. Core:

```
StyleError(rawValue: "Raster image reference has invalid data size")
```

### 2. Stretches overshoot declared bounds by sub-pixel amounts

With (1) addressed, a second validation surfaced: `ImageProperties`
computed stretch and content-box values as `Float(size) * scale` — a
non-integer when `size * scale` is fractional — while the declared image
width on native is `UInt32(size * scale)`, which truncates. The stretch
right edge then lay 0.x pixels past the declared edge. Core:

```
StyleError(rawValue: "expected stretchX area lies within an image (width 108), got { left: 0, right: 109 }")
```

### Reproduction, from `maps-agent-readiness-test/ios/t3-stretch`

```swift
let config = UIImage.SymbolConfiguration(pointSize: 30, weight: .bold)
let pin = UIImage(systemName: "mappin.circle.fill", withConfiguration: config)!
    .withTintColor(.systemRed, renderingMode: .alwaysOriginal)
annotation.image = .init(image: pin, name: "pin")   // no marker, two warnings in console
```

## Fix

- `Data.init(drawing:)` — now takes a `UIImage` (was `CGImage`),
allocates the buffer at `size * scale`, and uses `UIImage.draw(at:)`
into a `CGContext` scaled by `uiImage.scale` with a flipped Y axis. Fast
paths for PNG/JPEG/padded-row images are untouched.
- `ImageProperties` — floors stretch and content-box values to the same
`Int(size * scale)` bounds the image is declared at, so they cannot
overshoot the declared dimensions for any UIImage.

## Wrong-track note

This supersedes the closed #12390, which misidentified the root cause as
a nil `cgImage` on SF Symbols. `UIImage(systemName:).cgImage` is non-nil
on iOS 14+ (empirically verified against iOS 15.5, 16.4, 18.6
simulators).

## Jira

MAPSIOS-2182

## Test plan

- [x] `xcodebuild test -scheme MapboxTestHost
-only-testing:MapboxMapsTests/ImageTests` — all 7 tests pass, including
two new regressions that exercise the exact t3-stretch repro
(`testSymbolImageRoundTripsWithMatchingDataSize`,
`testImagePropertiesStretchWithinDeclaredBoundsForSymbolImage`).
- [ ] Visually verify in `maps-agent-readiness-test/ios/t3-stretch` by
pointing the app at this local SDK build and confirming the coffee-shop
pins render.
- [ ] Full `make build-source-tests-sim` run.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

cc @mapbox/maps-ios

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Changelog autocreator bot <github-actions[bot]@users.noreply.github.com>
GitOrigin-RevId: 892defc6624da88ae1d521f1e7076ba4e5f3f2b5

Author: 3 people

CHANGELOG.md

@@ -5,6 +5,7 @@ Mapbox welcomes participation and contributions from everyone.
 ## main
 
 * Fix `MapView` rendering blank when attached to an already-active CarPlay scene.
+* Fix SF Symbols silently failing to display when used as style images via `PointAnnotation.image` or `StyleManager.addImage`.
 
 ## Features ✨ and improvements 🏁
 * Expose `FeaturesetFeature.originalFeature` property.

Sources/MapboxMaps/Style/Types/StyleImage.swift

@@ -72,15 +72,27 @@ struct ImageProperties {
     init(uiImage: UIImage, contentInsets: UIEdgeInsets, id: String, sdf: Bool) {
         self.id = id
         self.scale = Float(uiImage.scale)
-        self.stretchXFirst = Float(uiImage.capInsets.left) * scale
-        self.stretchXSecond = Float(uiImage.size.width - uiImage.capInsets.right) * scale
-        self.stretchYFirst = Float(uiImage.capInsets.top) * scale
-        self.stretchYSecond = Float(uiImage.size.height - uiImage.capInsets.bottom) * scale
-
-        let contentBoxLeft = Float(contentInsets.left) * scale
-        let contentBoxRight = Float(uiImage.size.width - contentInsets.right) * scale
-        let contentBoxTop = Float(contentInsets.top) * scale
-        let contentBoxBottom = Float(uiImage.size.height - contentInsets.bottom) * scale
+
+        // Stretch and content-box values in pixels must lie within the
+        // declared image width/height. `CoreMapsImage.init?(uiImage:)` declares
+        // those using `UInt32(size * scale)`, which truncates fractional
+        // results. For UIImages whose `size * scale` is non-integer — notably
+        // SF Symbols at non-integer point sizes — computing stretches as
+        // `Float(size) * scale` left them 0.x pixels past the declared edge,
+        // which the native side rejects with "expected stretchX area lies
+        // within an image". Floor to the same integer bounds the image is
+        // declared at.
+        let widthPx = Float(Int(uiImage.size.width * uiImage.scale))
+        let heightPx = Float(Int(uiImage.size.height * uiImage.scale))
+        self.stretchXFirst = Float(Int(uiImage.capInsets.left * uiImage.scale))
+        self.stretchXSecond = widthPx - Float(Int(uiImage.capInsets.right * uiImage.scale))
+        self.stretchYFirst = Float(Int(uiImage.capInsets.top * uiImage.scale))
+        self.stretchYSecond = heightPx - Float(Int(uiImage.capInsets.bottom * uiImage.scale))
+
+        let contentBoxLeft = Float(Int(contentInsets.left * uiImage.scale))
+        let contentBoxRight = widthPx - Float(Int(contentInsets.right * uiImage.scale))
+        let contentBoxTop = Float(Int(contentInsets.top * uiImage.scale))
+        let contentBoxBottom = heightPx - Float(Int(contentInsets.bottom * uiImage.scale))
         self.contentBox = ImageContent(left: contentBoxLeft,
                                        top: contentBoxTop,
                                        right: contentBoxRight,

Tests/MapboxMapsTests/Style/ImageTests.swift

@@ -139,4 +139,65 @@ final class ImageTests: XCTestCase {
         // The resulting image should not have padded rows.
         XCTAssertEqual(Int(mbmImage.width * mbmImage.height) * bytesPerPixel, mbmImage.data.data.count)
     }
+
+    // Regression test: `PointAnnotation.image = .init(image: sfSymbol, ...)`
+    // previously triggered "Raster image reference has invalid data size" in
+    // the core and rendered nothing. SF Symbols (and the result of
+    // `.withTintColor(...)` on them) have a non-nil cgImage whose pixel
+    // dimensions don't match `uiImage.size * uiImage.scale`. The default
+    // branch in `Data(uiImage:)` used to redraw at cgImage dims, which
+    // produced a buffer shorter than what `CoreMapsImage.init` declared to
+    // the native side. It now redraws at `size * scale`, so declared
+    // dimensions, buffer length, and intended display size agree.
+    func testSymbolImageRoundTripsWithMatchingDataSize() throws {
+        let config = UIImage.SymbolConfiguration(pointSize: 30, weight: .bold)
+        let symbol = try XCTUnwrap(UIImage(systemName: "mappin.circle.fill", withConfiguration: config))
+            .withTintColor(.systemRed, renderingMode: .alwaysOriginal)
+
+        // Preconditions for the regression: cgImage diverges from size*scale.
+        let cgImage = try XCTUnwrap(symbol.cgImage)
+        let declaredW = Int(symbol.size.width * symbol.scale)
+        let declaredH = Int(symbol.size.height * symbol.scale)
+        XCTAssertNotEqual(
+            declaredW * declaredH, cgImage.width * cgImage.height,
+            "Preconditions: SF Symbol cgImage dims should diverge from size*scale")
+
+        let mbmImage = try XCTUnwrap(CoreMapsImage(uiImage: symbol))
+
+        // The native side rejects any mismatch between declared dims and byte count.
+        XCTAssertEqual(Int(mbmImage.width), declaredW)
+        XCTAssertEqual(Int(mbmImage.height), declaredH)
+        XCTAssertEqual(Int(mbmImage.width * mbmImage.height) * 4, mbmImage.data.data.count)
+    }
+
+    // Second half of the SF-Symbol regression: stretch and content-box
+    // bounds must lie within the declared image dimensions. For a UIImage
+    // whose `size * scale` is not integer (common for SF Symbols at
+    // non-integer point sizes), stretchXSecond used to overshoot the
+    // truncated UInt32 image width by sub-pixel amounts, producing
+    // `StyleError("expected stretchX area lies within an image")`.
+    func testImagePropertiesStretchWithinDeclaredBoundsForSymbolImage() throws {
+        let config = UIImage.SymbolConfiguration(pointSize: 30, weight: .bold)
+        let symbol = try XCTUnwrap(UIImage(systemName: "mappin.circle.fill", withConfiguration: config))
+            .withTintColor(.systemRed, renderingMode: .alwaysOriginal)
+
+        // Preconditions: size*scale is non-integer — without this, the
+        // original float-scaled stretch logic would work.
+        let fractionalWidth = symbol.size.width * symbol.scale
+        XCTAssertNotEqual(fractionalWidth, fractionalWidth.rounded(.down),
+                          "Preconditions: SF Symbol size*scale should be non-integer")
+
+        let props = ImageProperties(uiImage: symbol, contentInsets: .zero, id: "pin", sdf: false)
+
+        let declaredW = Float(UInt32(symbol.size.width * symbol.scale))
+        let declaredH = Float(UInt32(symbol.size.height * symbol.scale))
+        XCTAssertGreaterThanOrEqual(props.stretchXFirst, 0)
+        XCTAssertLessThanOrEqual(props.stretchXSecond, declaredW)
+        XCTAssertGreaterThanOrEqual(props.stretchYFirst, 0)
+        XCTAssertLessThanOrEqual(props.stretchYSecond, declaredH)
+        XCTAssertGreaterThanOrEqual(props.contentBox.left, 0)
+        XCTAssertLessThanOrEqual(props.contentBox.right, declaredW)
+        XCTAssertGreaterThanOrEqual(props.contentBox.top, 0)
+        XCTAssertLessThanOrEqual(props.contentBox.bottom, declaredH)
+    }
 }