@rnmapbox/maps 10.0.0-beta.70 → 10.0.0-beta.71

package/ios/RCTMGL-v10/RCTMGLCamera.swift

@@ -107,57 +107,67 @@ open class RCTMGLMapComponentBase : UIView, RCTMGLMapComponent {
 class RCTMGLCamera : RCTMGLMapComponentBase, LocationConsumer {
   var cameraAnimator: BasicCameraAnimator?
   let cameraUpdateQueue = CameraUpdateQueue()
-
+  
   // MARK: React properties
   
   @objc var animationDuration: NSNumber?
+  
   @objc var animationMode: NSString?
+  
   @objc var defaultStop: [String: Any]?
-  @objc var followHeading: NSNumber? {
+  
+  @objc var followUserLocation : Bool = false {
     didSet {
       _updateCameraFromTrackingMode()
     }
   }
-  @objc var followPitch: NSNumber? {
+  
+  @objc var followUserMode: String? {
     didSet {
       _updateCameraFromTrackingMode()
     }
   }
-
-  @objc var followUserMode: String? {
+  
+  @objc var followZoomLevel: NSNumber? {
     didSet {
       _updateCameraFromTrackingMode()
     }
   }
-
-  @objc var followUserLocation : Bool = false {
+  
+  @objc var followPitch: NSNumber? {
     didSet {
       _updateCameraFromTrackingMode()
     }
   }
-
-  @objc var followZoomLevel: NSNumber? {
+  
+  @objc var followHeading: NSNumber? {
     didSet {
       _updateCameraFromTrackingMode()
     }
   }
-
+  
+  @objc var followPadding: NSDictionary? {
+    didSet {
+      _updateCameraFromTrackingMode()
+    }
+  }
+  
   @objc var maxZoomLevel: NSNumber? {
     didSet { _updateMaxBounds() }
   }
-
+  
   @objc var minZoomLevel: NSNumber? {
     didSet { _updateMaxBounds() }
   }
-
+  
   @objc var onUserTrackingModeChange: RCTBubblingEventBlock? = nil
-
+  
   @objc var stop: [String: Any]? {
     didSet {
       _updateCamera()
     }
   }
-
+  
   @objc var maxBounds: String? {
     didSet {
       if let maxBounds = maxBounds {
@@ -288,22 +298,23 @@ class RCTMGLCamera : RCTMGLMapComponentBase, LocationConsumer {
         followOptions.bearing = nil
         trackingModeChanged = true
       }
+      
       if let onUserTrackingModeChange = self.onUserTrackingModeChange {
         if (trackingModeChanged) {
           let event = RCTMGLEvent(type: .onUserTrackingModeChange, payload: ["followUserMode": self.followUserMode ?? "normal", "followUserLocation": self.followUserLocation])
           onUserTrackingModeChange(event.toJSON())
         }
       }
+      
       var _camera = CameraOptions()
-      if let followHeading = self.followHeading as? CGFloat {
-        if (followHeading >= 0.0) {
-          _camera.bearing = followHeading
-        }
-      } else if let stopHeading = self.stop?["heading"] as? CGFloat {
-        if (stopHeading >= 0.0) {
-          _camera.bearing = stopHeading
+      
+      if let zoom = self.followZoomLevel as? CGFloat {
+        if (zoom >= 0.0) {
+          _camera.zoom = zoom
+          followOptions.zoom = zoom
         }
       }
+      
       if let followPitch = self.followPitch as? CGFloat {
         if (followPitch >= 0.0) {
           _camera.pitch = followPitch
@@ -317,14 +328,29 @@ class RCTMGLCamera : RCTMGLMapComponentBase, LocationConsumer {
       } else {
         followOptions.pitch = nil
       }
-
-      if let zoom = self.followZoomLevel as? CGFloat {
-        if (zoom >= 0.0) {
-          _camera.zoom = zoom
-          followOptions.zoom = zoom
+      
+      if let followHeading = self.followHeading as? CGFloat {
+        if (followHeading >= 0.0) {
+          _camera.bearing = followHeading
         }
+      } else if let stopHeading = self.stop?["heading"] as? CGFloat {
+        if (stopHeading >= 0.0) {
+          _camera.bearing = stopHeading
+        }
+      }
+      
+      if let padding = self.followPadding {
+        let edgeInsets = UIEdgeInsets(
+          top: padding["paddingTop"] as? Double ?? 0,
+          left: padding["paddingLeft"] as? Double ?? 0,
+          bottom: padding["paddingBottom"] as? Double ?? 0,
+          right: padding["paddingRight"] as? Double ?? 0
+        )
+        followOptions.padding = edgeInsets
       }
+      
       let followState = map.viewport.makeFollowPuckViewportState(options: followOptions)
+      
       map.viewport.transition(to: followState)
       map.viewport.addStatusObserver(self)
       map.mapboxMap.setCamera(to: _camera)

package/ios/RCTMGL-v10/RCTMGLCameraManager.m

@@ -8,11 +8,14 @@ RCT_EXPORT_VIEW_PROPERTY(maxBounds, NSString)
 RCT_EXPORT_VIEW_PROPERTY(animationDuration, NSNumber)
 RCT_EXPORT_VIEW_PROPERTY(animationMode, NSString)
 RCT_EXPORT_VIEW_PROPERTY(defaultStop, NSDictionary)
-RCT_EXPORT_VIEW_PROPERTY(followHeading, NSNumber)
-RCT_EXPORT_VIEW_PROPERTY(followPitch, NSNumber)
+
 RCT_EXPORT_VIEW_PROPERTY(followUserLocation, BOOL)
 RCT_EXPORT_VIEW_PROPERTY(followUserMode, NSString)
 RCT_EXPORT_VIEW_PROPERTY(followZoomLevel, NSNumber)
+RCT_EXPORT_VIEW_PROPERTY(followPitch, NSNumber)
+RCT_EXPORT_VIEW_PROPERTY(followHeading, NSNumber)
+RCT_EXPORT_VIEW_PROPERTY(followPadding, NSDictionary)
+
 RCT_EXPORT_VIEW_PROPERTY(maxZoomLevel, NSNumber)
 RCT_EXPORT_VIEW_PROPERTY(minZoomLevel, NSNumber)
 RCT_EXPORT_VIEW_PROPERTY(onUserTrackingModeChange, RCTBubblingEventBlock)

package/ios/RCTMGL-v10/RCTMGLImages.swift

@@ -12,7 +12,14 @@ class RCTMGLImages : UIView, RCTMGLMapComponent {
   var images : [String:Any] = [:]
   
   @objc
-  var nativeImages: [String] = []
+  var nativeImages: [Any] = [] {
+    didSet {
+      nativeImageInfos = nativeImages.compactMap { decodeImage($0) }
+    }
+  };
+
+  typealias NativeImageInfo = (name:String, sdf: Bool, stretchX:[(from:Float, to:Float)], stretchY:[(from:Float, to:Float)]);
+  var nativeImageInfos: [NativeImageInfo] = []
   
   // MARK: - RCTMGLMapComponent
 
@@ -24,7 +31,7 @@ class RCTMGLImages : UIView, RCTMGLMapComponent {
     map.images.append(self)
     map.setupEvents()
     
-    self.addNativeImages(style: style, nativeImages: nativeImages)
+    self.addNativeImages(style: style, nativeImages: nativeImageInfos)
     self.addRemoteImages(style: style, remoteImages: images)
   }
   
@@ -57,8 +64,8 @@ class RCTMGLImages : UIView, RCTMGLMapComponent {
   }
   
   public func addMissingImageToStyle(style: Style, imageName: String) -> Bool {
-    if nativeImages.contains(imageName) {
-      addNativeImages(style: style, nativeImages: [imageName])
+    if let nativeImage = nativeImageInfos.first(where: { $0.name == imageName }) {
+      addNativeImages(style: style, nativeImages: [nativeImage])
       return true
     }
     
@@ -77,11 +84,50 @@ class RCTMGLImages : UIView, RCTMGLMapComponent {
     }
   }
   
-  func addNativeImages(style: Style, nativeImages: [String]) {
-    for imageName in nativeImages {
-      if style.styleManager.getStyleImage(forImageId: imageName) == nil {
+  func decodeImage(_ imageNameOrInfo: Any) -> NativeImageInfo? {
+    if let imageName = imageNameOrInfo as? String {
+      return (name: imageName, sdf: false, stretchX:[],stretchY:[])
+    } else if let imageInfo = imageNameOrInfo as? [String:Any] {
+      guard let name = imageInfo["name"] as? String else {
+        Logger.log(level: .warn, message: "NativeImage: \(imageInfo) has no name key")
+        return nil
+      }
+      var sdf = false
+      var stretchX : [(from:Float, to:Float)] = []
+      var stretchY : [(from:Float, to:Float)] = []
+      if let sdfV = imageInfo["sdf"] as? NSNumber {
+        sdf = sdfV.boolValue
+      }
+      
+      if let stretchXV = imageInfo["stretchX"] as? [[NSNumber]] {
+        stretchX = stretchXV.map{ pair in
+          return (from: pair[0].floatValue, to: pair[1].floatValue)
+        }
+      }
+      
+      if let stretchYV = imageInfo["stretchY"] as? [[NSNumber]] {
+        stretchY = stretchYV.map{ pair in
+          return (from: pair[0].floatValue, to: pair[1].floatValue)
+        }
+      }
+      
+      return (name: name, sdf: sdf, stretchX:stretchX,stretchY:stretchY)
+    } else {
+      Logger.log(level: .warn, message: "RCTMGLImage.nativeImage, unexpected image: \(imageNameOrInfo)")
+      return nil
+    }
+  }
+  
+  func addNativeImages(style: Style, nativeImages: [NativeImageInfo]) {
+    for imageInfo in nativeImages {
+      let imageName = imageInfo.name
+      if style.styleManager.getStyleImage(forImageId: imageInfo.name) == nil {
         if let image = UIImage(named: imageName) {
-          try! style.addImage(image, id: imageName, stretchX: [], stretchY: [])
+          logged("RCTMGLImage.addNativeImage: \(imageName)") {
+            try style.addImage(image, id: imageName, sdf: imageInfo.sdf,
+                               stretchX: imageInfo.stretchX.map { v in ImageStretches(first: v.from, second: v.to) },
+                               stretchY: imageInfo.stretchY.map { v in ImageStretches(first: v.from, second: v.to) } )
+          }
         } else {
           Logger.log(level:.error, message: "Cannot find nativeImage named \(imageName)")
         }

package/ios/install.md

@@ -60,7 +60,7 @@ You can also override the version to use. *Warning:* if you set a version, then
 
 ```ruby
 # Warning: only for advanced use cases, only do this if you know what you're doing.
-# $RNMapboxMapsVersion = '~> 10.11.0'
+# $RNMapboxMapsVersion = '~> 10.12.0'
 ```
 
 You will need to authorize your download of the Maps SDK with a secret access token with the `DOWNLOADS:READ` scope. This [guide](https://docs.mapbox.com/ios/maps/guides/install/#configure-credentials) explains how to configure the secret token under section `Configure your secret token`.

package/javascript/components/Camera.tsx

@@ -122,16 +122,18 @@ export type CameraStop = {
 };
 
 export type CameraFollowConfig = {
-  /** The mode used to track the user location on the map. */
-  followUserMode?: UserTrackingMode;
   /** Whether the map orientation follows the user location. */
   followUserLocation?: boolean;
+  /** The mode used to track the user location on the map. */
+  followUserMode?: UserTrackingMode;
   /** The zoom level used when following the user location. */
   followZoomLevel?: number;
   /** The pitch used when following the user location. */
   followPitch?: number;
   /** The heading used when following the user location. */
   followHeading?: number;
+  /** The padding used to position the user location when following. */
+  followPadding?: Partial<CameraPadding>;
 };
 
 export type CameraMinMaxConfig = {
@@ -232,6 +234,7 @@ export const Camera = memo(
         followZoomLevel,
         followPitch,
         followHeading,
+        followPadding,
         defaultSettings,
         allowUpdates = true,
         onUserTrackingModeChange,
@@ -526,9 +529,10 @@ export const Camera = memo(
           defaultStop={nativeDefaultStop}
           followUserLocation={followUserLocation}
           followUserMode={followUserMode}
+          followZoomLevel={followZoomLevel}
           followPitch={followPitch}
           followHeading={followHeading}
-          followZoomLevel={followZoomLevel}
+          followPadding={followPadding}
           minZoomLevel={minZoomLevel}
           maxZoomLevel={maxZoomLevel}
           maxBounds={nativeMaxBounds}

package/javascript/components/Images.tsx

@@ -0,0 +1,133 @@
+import React from 'react';
+import { requireNativeComponent, Image } from 'react-native';
+import { ImageSourcePropType, ImageResolvedAssetSource } from 'react-native';
+
+import { ShapeSource } from './ShapeSource';
+
+export const NATIVE_MODULE_NAME = 'RCTMGLImages';
+
+export type RNMBEvent<PayloadType = { [key: string]: string }> = {
+  payload: PayloadType;
+  type: string;
+};
+
+function _isUrlOrPath(value: string | ImageSourcePropType): value is string {
+  return (
+    (typeof value === 'string' || value instanceof String) &&
+    (value.startsWith('file://') ||
+      value.startsWith('http://') ||
+      value.startsWith('https://') ||
+      value.startsWith('data:') ||
+      value.startsWith('asset://') ||
+      value.startsWith('/'))
+  );
+}
+
+type NativeImage =
+  | string
+  | {
+      name: string;
+      sdf?: boolean;
+      strechX: [number, number][];
+      streacY: [number, number][];
+    };
+
+interface Props {
+  /**
+   * Specifies the external images in key-value pairs required for the shape source.
+   * Keys are names - see iconImage expressions, values can be either urls-s objects
+   * with format {uri: 'http://...'}` or `require('image.png')` or `import 'image.png'`
+   */
+  images?: { [key: string]: ImageSourcePropType };
+
+  /**
+   * If you have an asset under Image.xcassets on iOS and the drawables directory on android
+   * you can specify an array of string names with assets as the key `['pin']`.
+   * Additionally object with keys sdf, and strechX, strechY is supported for [SDF icons](https://docs.mapbox.com/help/troubleshooting/using-recolorable-images-in-mapbox-maps/)
+   */
+  nativeAssetImages?: NativeImage[];
+
+  /**
+   * Gets called when a Layer is trying to render an image whose key is not present in
+   * any of the `Images` component of the Map.
+   */
+  onImageMissing?: (imageKey: string) => void;
+
+  id?: string;
+  children?: React.ReactElement;
+}
+
+/**
+ * Images defines the images used in Symbol etc. layers.
+ */
+class Images extends React.Component<Props> {
+  static NATIVE_ASSETS_KEY = 'assets';
+
+  _getImages() {
+    if (!this.props.images && !this.props.nativeAssetImages) {
+      return {};
+    }
+
+    const images: { [key: string]: string | ImageResolvedAssetSource } = {};
+    let nativeImages: NativeImage[] = [];
+
+    if (this.props.images) {
+      const imageNames = Object.keys(this.props.images);
+      for (const imageName of imageNames) {
+        const value = this.props.images[imageName];
+        if (
+          imageName === ShapeSource.NATIVE_ASSETS_KEY &&
+          Array.isArray(value)
+        ) {
+          console.error(
+            `Use of ${ShapeSource.NATIVE_ASSETS_KEY} in Images#images is not supported use Images#nativeAssetImages`,
+          );
+        } else if (_isUrlOrPath(value)) {
+          images[imageName] = value;
+        } else {
+          const res = Image.resolveAssetSource(value);
+          if (res && res.uri) {
+            images[imageName] = res;
+          }
+        }
+      }
+    }
+
+    if (this.props.nativeAssetImages) {
+      nativeImages = this.props.nativeAssetImages;
+    }
+
+    return {
+      images,
+      nativeImages,
+    };
+  }
+
+  _onImageMissing(event: React.SyntheticEvent<Element, RNMBEvent>) {
+    if (this.props.onImageMissing) {
+      this.props.onImageMissing(event.nativeEvent.payload.imageKey);
+    }
+  }
+
+  render() {
+    const props = {
+      id: this.props.id,
+      hasOnImageMissing: !!this.props.onImageMissing,
+      onImageMissing: this._onImageMissing.bind(this),
+      ...this._getImages(),
+    };
+
+    return <RCTMGLImages {...props}>{this.props.children}</RCTMGLImages>;
+  }
+}
+
+type NativeProps = {
+  hasOnImageMissing: boolean;
+  onImageMissing?: (event: React.SyntheticEvent<Element, RNMBEvent>) => void;
+  images?: { [key: string]: string | ImageResolvedAssetSource };
+  nativeImages?: NativeImage[];
+};
+
+const RCTMGLImages = requireNativeComponent<NativeProps>(NATIVE_MODULE_NAME);
+
+export default Images;

package/javascript/modules/location/{locationManager.js → locationManager.ts}

@@ -1,4 +1,11 @@
-import { NativeModules, NativeEventEmitter, AppState } from 'react-native';
+import {
+  NativeModules,
+  NativeEventEmitter,
+  AppState,
+  NativeEventSubscription,
+  EmitterSubscription,
+  type AppStateStatus,
+} from 'react-native';
 
 const MapboxGL = NativeModules.MGLModule;
 const MapboxGLLocationManager = NativeModules.MGLLocationModule;
@@ -7,13 +14,76 @@ export const LocationModuleEventEmitter = new NativeEventEmitter(
   MapboxGLLocationManager,
 );
 
+/**
+ * Location sent by locationManager
+ */
+interface Location {
+  coords: Coordinates;
+  timestamp?: number;
+}
+
+/**
+ * Coorinates sent by locationManager
+ */
+interface Coordinates {
+  /**
+   * The heading (measured in degrees) relative to true north.
+   * Heading is used to describe the direction the device is pointing to (the value of the compass).
+   * Note that on Android this is incorrectly reporting the course value as mentioned in issue https://github.com/rnmapbox/maps/issues/1213
+   * and will be corrected in a future update.
+   */
+  heading?: number;
+
+  /**
+   * The direction in which the device is traveling, measured in degrees and relative to due north.
+   * The course refers to the direction the device is actually moving (not the same as heading).
+   */
+  course?: number;
+
+  /**
+   * The instantaneous speed of the device, measured in meters per second.
+   */
+  speed?: number;
+
+  /**
+   * The latitude in degrees.
+   */
+  latitude: number;
+
+  /**
+   * The longitude in degrees.
+   */
+  longitude: number;
+
+  /**
+   * The radius of uncertainty for the location, measured in meters.
+   */
+  accuracy?: number;
+
+  /**
+   * The altitude, measured in meters.
+   */
+  altitude?: number;
+}
+
+/**
+ * LocationManager is a singleton, see `locationManager`
+ */
 class LocationManager {
+  _listeners: ((location: Location) => void)[];
+  _lastKnownLocation: Location | null;
+  _isListening: boolean;
+  _requestsAlwaysUse: boolean;
+  subscription: EmitterSubscription | null;
+  _appStateListener: NativeEventSubscription;
+  _minDisplacement?: number;
+
   constructor() {
     this._listeners = [];
     this._lastKnownLocation = null;
     this._isListening = false;
     this._requestsAlwaysUse = false;
-    this.onUpdate = this.onUpdate.bind(this);
+    this._onUpdate = this._onUpdate.bind(this);
     this.subscription = null;
 
     this._appStateListener = AppState.addEventListener(
@@ -45,7 +115,7 @@ class LocationManager {
     return this._lastKnownLocation;
   }
 
-  addListener(listener) {
+  addListener(listener: (location: Location) => void) {
     if (!this._isListening) {
       this.start();
     }
@@ -58,7 +128,7 @@ class LocationManager {
     }
   }
 
-  removeListener(listener) {
+  removeListener(listener: (location: Location) => void) {
     this._listeners = this._listeners.filter((l) => l !== listener);
     if (this._listeners.length === 0) {
       this.stop();
@@ -70,7 +140,7 @@ class LocationManager {
     this.stop();
   }
 
-  _handleAppStateChange(appState) {
+  _handleAppStateChange(appState: AppStateStatus) {
     if (!this._requestsAlwaysUse) {
       if (appState === 'background') {
         this.stop();
@@ -83,23 +153,23 @@ class LocationManager {
   }
 
   start(displacement = -1) {
+    let validDisplacement = 1;
     if (
       displacement === -1 ||
       displacement === null ||
       displacement === undefined
     ) {
-      displacement = this._minDisplacement;
-    }
-    if (displacement == null) {
-      displacement = -1;
+      validDisplacement = this._minDisplacement || -1;
+    } else {
+      validDisplacement = displacement;
     }
 
     if (!this._isListening) {
-      MapboxGLLocationManager.start(displacement);
+      MapboxGLLocationManager.start(validDisplacement);
 
       this.subscription = LocationModuleEventEmitter.addListener(
         MapboxGL.LocationCallbackName.Update,
-        this.onUpdate,
+        this._onUpdate,
       );
 
       this._isListening = true;
@@ -109,36 +179,39 @@ class LocationManager {
   stop() {
     MapboxGLLocationManager.stop();
 
-    if (this._isListening) {
+    if (this._isListening && this.subscription) {
       this.subscription.remove();
     }
 
     this._isListening = false;
   }
 
-  setMinDisplacement(minDisplacement) {
+  setMinDisplacement(minDisplacement: number) {
     this._minDisplacement = minDisplacement;
     MapboxGLLocationManager.setMinDisplacement(minDisplacement);
   }
 
-  setRequestsAlwaysUse(requestsAlwaysUse) {
+  setRequestsAlwaysUse(requestsAlwaysUse: boolean) {
     MapboxGLLocationManager.setRequestsAlwaysUse(requestsAlwaysUse);
     this._requestsAlwaysUse = requestsAlwaysUse;
   }
 
-  onUpdate(location) {
+  _onUpdate(location: Location) {
     this._lastKnownLocation = location;
 
     this._listeners.forEach((l) => l(location));
   }
 
-  _simulateHeading(changesPerSecond, increment) {
+  /**
+   * simulates location updates, experimental  [V10, iOS only]
+   */
+  _simulateHeading(changesPerSecond: number, increment: number) {
     MapboxGLLocationManager.simulateHeading(changesPerSecond, increment);
   }
 
   /**
    * Sets the period at which location events will be sent over the React Native bridge.
-   * The default is 0, aka no limit
+   * The default is 0, aka no limit. [V10, iOS only]
    *
    * @example
    * locationManager.setLocationEventThrottle(500);
@@ -146,7 +219,7 @@ class LocationManager {
    * @param {Number} throttleValue event throttle value in ms.
    * @return {void}
    */
-  setLocationEventThrottle(throttleValue) {
+  setLocationEventThrottle(throttleValue: number) {
     MapboxGLLocationManager.setLocationEventThrottle(throttleValue);
   }
 }

package/javascript/utils/MapboxStyles.d.ts

@@ -113,7 +113,7 @@ type ExpressionField =
   | ExpressionField[]
   | { [key: string]: ExpressionField };
 
-export type Expression = [ExpressionName, ...ExpressionField[]];
+export type Expression = readonly [ExpressionName, ...ExpressionField[]];
 
 export type FilterExpression = Expression;
 
@@ -902,7 +902,7 @@ export interface SymbolLayerStyleProps {
    */
   iconOpacityTransition?: Transition;
   /**
-   * The color of the icon. This can only be used with [SDF icons](/help/troubleshooting/usingRecolorableImagesInMapboxMaps/).
+   * The color of the icon. This can only be used with [SDF icons](https://docs.mapbox.com/help/troubleshooting/using-recolorable-images-in-mapbox-maps/).
    *
    * @requires iconImage
    */
@@ -913,7 +913,7 @@ export interface SymbolLayerStyleProps {
    */
   iconColorTransition?: Transition;
   /**
-   * The color of the icon's halo. Icon halos can only be used with [SDF icons](/help/troubleshooting/usingRecolorableImagesInMapboxMaps/).
+   * The color of the icon's halo. Icon halos can only be used with [SDF icons](https://docs.mapbox.com/help/troubleshooting/using-recolorable-images-in-mapbox-maps/).
    *
    * @requires iconImage
    */

package/javascript/utils/styleMap.ts

@@ -665,7 +665,7 @@ export const SymbolLayerStyleProp = PropTypes.shape({
   }),
 
   /**
-   * The color of the icon. This can only be used with [SDF icons](/help/troubleshooting/usingRecolorableImagesInMapboxMaps/).
+   * The color of the icon. This can only be used with [SDF icons](https://docs.mapbox.com/help/troubleshooting/using-recolorable-images-in-mapbox-maps/).
    *
    * @requires iconImage
    */
@@ -680,7 +680,7 @@ export const SymbolLayerStyleProp = PropTypes.shape({
   }),
 
   /**
-   * The color of the icon's halo. Icon halos can only be used with [SDF icons](/help/troubleshooting/usingRecolorableImagesInMapboxMaps/).
+   * The color of the icon's halo. Icon halos can only be used with [SDF icons](https://docs.mapbox.com/help/troubleshooting/using-recolorable-images-in-mapbox-maps/).
    *
    * @requires iconImage
    */