RD-1319: Add hillshade layer (#219)

Author: sasaprodribaba

Examples/Hillshade+SwiftUI.swift

@@ -0,0 +1,49 @@
+//
+//  Hillshade+SwiftUI.swift
+//  MapTilerSDK Examples
+//
+
+import SwiftUI
+import MapTilerSDK
+
+/// Demonstrates adding a hillshade layer sourced from Terrain RGB DEM tiles.
+struct HillshadeExample: View {
+    @State private var referenceStyle: MTMapReferenceStyle = .basic
+    @State private var styleVariant: MTMapStyleVariant? = .defaultVariant
+    @State private var mapView = MTMapView(options: MTMapOptions(zoom: 3.0))
+
+    init() {
+        Task { await MTConfig.shared.setAPIKey("YOUR_API_KEY") }
+    }
+
+    var body: some View {
+        MTMapViewContainer(map: mapView) {}
+            .referenceStyle(referenceStyle)
+            .styleVariant(styleVariant)
+            .didInitialize { Task { await addHillshade() } }
+    }
+
+    private func addHillshade() async {
+        guard let style = mapView.style else { return }
+
+        guard let apiKey = await MTConfig.shared.getAPIKey() else { return }
+
+        guard let url = URL(
+            string: "https://api.maptiler.com/tiles/terrain-rgb-v2/tiles.json?key=\(apiKey)"
+        ) else { return }
+
+        let dem = MTRasterDEMSource(identifier: "hillshadeSource", url: url)
+
+        do {
+            try await style.addSource(dem)
+
+            var hills = MTHillshadeLayer(identifier: "hills", sourceIdentifier: dem.identifier)
+            hills.visibility = .visible
+            hills.shadowColor = UIColor(hex: "#473B24")
+
+            try await style.addLayer(hills)
+        } catch {
+            print("Failed to add hillshade: \(error)")
+        }
+    }
+}

Sources/MapTilerSDK/Commands/Style/AddLayer.swift

@@ -21,6 +21,8 @@ package struct AddLayer: MTCommand {
             return handleMTLineLayer(layer)
         } else if let layer = layer as? MTRasterLayer {
             return handleMTRasterLayer(layer)
+        } else if let layer = layer as? MTHillshadeLayer {
+            return handleMTHillshadeLayer(layer)
         } else if let layer = layer as? MTCircleLayer {
             return handleMTCircleLayer(layer)
         }
@@ -84,6 +86,14 @@ package struct AddLayer: MTCommand {
         return "\(MTBridge.mapObject).addLayer(\(unquoteExpressions(in: layerString)));"
     }
 
+    private func handleMTHillshadeLayer(_ layer: MTHillshadeLayer) -> JSString {
+        guard let layerString: JSString = layer.toJSON() else {
+            return emptyReturnValue
+        }
+
+        return "\(MTBridge.mapObject).addLayer(\(unquoteExpressions(in: layerString)));"
+    }
+
     private func handleMTCircleLayer(_ layer: MTCircleLayer) -> JSString {
         guard let layerString: JSString = layer.toJSON() else {
             return emptyReturnValue

Sources/MapTilerSDK/Commands/Style/AddLayers.swift

@@ -26,6 +26,8 @@ package struct AddLayers: MTCommand {
                 jsString.append(handleMTLineLayer(layer))
             } else if let layer = layer as? MTRasterLayer {
                 jsString.append(handleMTRasterLayer(layer))
+            } else if let layer = layer as? MTHillshadeLayer {
+                jsString.append(handleMTHillshadeLayer(layer))
             } else if let layer = layer as? MTCircleLayer {
                 jsString.append(handleMTCircleLayer(layer))
             }
@@ -86,6 +88,14 @@ package struct AddLayers: MTCommand {
         return "\(MTBridge.mapObject).addLayer(\(layerString));"
     }
 
+    private func handleMTHillshadeLayer(_ layer: MTHillshadeLayer) -> JSString {
+        guard let layerString: JSString = layer.toJSON() else {
+            return emptyReturnValue
+        }
+
+        return "\(MTBridge.mapObject).addLayer(\(layerString));"
+    }
+
     private func handleMTCircleLayer(_ layer: MTCircleLayer) -> JSString {
         guard let layerString: JSString = layer.toJSON() else {
             return emptyReturnValue

Sources/MapTilerSDK/Map/Style/Layer/Hillshade/MTHillshadeIlluminationAnchor.swift

@@ -0,0 +1,17 @@
+//
+// Copyright (c) 2026, MapTiler
+// All rights reserved.
+// SPDX-License-Identifier: BSD 3-Clause
+//
+//  MTHillshadeIlluminationAnchor.swift
+//  MapTilerSDK
+//
+
+/// Direction of light source when map is rotated.
+public enum MTHillshadeIlluminationAnchor: String {
+    /// The hillshade illumination is relative to the north direction.
+    case map
+
+    /// The hillshade illumination is relative to the top of the viewport.
+    case viewport
+}

Sources/MapTilerSDK/Map/Style/Layer/Hillshade/MTHillshadeLayer+DSL.swift

@@ -0,0 +1,98 @@
+//
+// Copyright (c) 2026, MapTiler
+// All rights reserved.
+// SPDX-License-Identifier: BSD 3-Clause
+//
+//  MTHillshadeLayer+DSL.swift
+//  MapTilerSDK
+//
+
+import UIKit
+
+// DSL
+extension MTHillshadeLayer {
+    /// Adds layer to map DSL style.
+    ///
+    /// Prefer `MTStyle/addLayer(_:)` on MTMapView instead.
+    public func addToMap(_ mapView: MTMapView) {
+        Task {
+            let layer = MTHillshadeLayer(
+                identifier: self.identifier,
+                sourceIdentifier: self.sourceIdentifier,
+                maxZoom: self.maxZoom,
+                minZoom: self.minZoom,
+                sourceLayer: self.sourceLayer,
+                accentColor: self.accentColor,
+                exaggeration: self.exaggeration,
+                highlightColor: self.highlightColor,
+                illuminationAnchor: self.illuminationAnchor,
+                illuminationDirection: self.illuminationDirection,
+                shadowColor: self.shadowColor,
+                visibility: self.visibility
+            )
+
+            try await mapView.style?.addLayer(layer)
+        }
+    }
+
+    // MARK: - Modifiers (not to be used outside DSL)
+    @discardableResult
+    public func maxZoom(_ value: Double) -> Self {
+        self.maxZoom = value
+        return self
+    }
+
+    @discardableResult
+    public func minZoom(_ value: Double) -> Self {
+        self.minZoom = value
+        return self
+    }
+
+    @discardableResult
+    public func sourceLayer(_ value: String) -> Self {
+        self.sourceLayer = value
+        return self
+    }
+
+    @discardableResult
+    public func accentColor(_ value: UIColor) -> Self {
+        self.accentColor = value
+        return self
+    }
+
+    @discardableResult
+    public func exaggeration(_ value: Double) -> Self {
+        self.exaggeration = value
+        return self
+    }
+
+    @discardableResult
+    public func highlightColor(_ value: UIColor) -> Self {
+        self.highlightColor = value
+        return self
+    }
+
+    @discardableResult
+    public func illuminationAnchor(_ value: MTHillshadeIlluminationAnchor) -> Self {
+        self.illuminationAnchor = value
+        return self
+    }
+
+    @discardableResult
+    public func illuminationDirection(_ value: Double) -> Self {
+        self.illuminationDirection = value
+        return self
+    }
+
+    @discardableResult
+    public func shadowColor(_ value: UIColor) -> Self {
+        self.shadowColor = value
+        return self
+    }
+
+    @discardableResult
+    public func visibility(_ value: MTLayerVisibility) -> Self {
+        self.visibility = value
+        return self
+    }
+}