### Complete Map Setup Example

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/OSMView.md

Demonstrates the initialization and configuration of an OSMView, including setting zoom levels and assigning various delegates. This is a foundational example for integrating the map into a view controller.

```swift
import OSMFlutterFramework

class MapViewController: UIViewController {
    var mapView: OSMView!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Configure zoom
        let zoomConfig = ZoomConfiguration(
            initZoom: 5,
            minZoom: 0,
            maxZoom: 19,
            step: 1
        )
        
        // Create map
        mapView = OSMView(
            rect: view.bounds,
            location: CLLocationCoordinate2D(latitude: 48.8566, longitude: 2.3522),
            zoomConfig: zoomConfig
        )
        
        // Set delegates
        mapView.onMapGestureDelegate = self
        mapView.onMapMove = self
        mapView.mapHandlerDelegate = self
        
        view.addSubview(mapView)
    }
}

extension MapViewController: OnMapGesture {
    func onSingleTap(location: CLLocationCoordinate2D) {
        print("Tapped at: \(location)")
    }
    
    func onLongTap(location: CLLocationCoordinate2D) {
        print("Long-pressed at: \(location)")
    }
}
```

--------------------------------

### Build Package and Example App

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/AGENTS.md

Commands to build the Swift package and the example iOS application using xcodebuild.

```bash
# Build package
swift build
```

```bash
# Build example app (from example dir)
cd example/OSMMapCoreFrameworkExample
xcodebuild -workspace OSMMapCoreFrameworkExample.xcworkspace -scheme OSMMapCoreFrameworkExample -destination 'platform=iOS Simulator,name=iPhone 15'
```

--------------------------------

### Basic Location Tracking Setup

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/LocationManager.md

Example of setting up basic location tracking in a MapViewController. This includes initializing the map, setting the delegate, and enabling tracking with default configurations.

```swift
import CoreLocation

class MapViewController: UIViewController, OSMUserLocationHandler {
    @IBOutlet weak var mapView: OSMView!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Setup zoom
        let zoomConfig = ZoomConfiguration(initZoom: 10, minZoom: 0, maxZoom: 19)
        
        // Create map
        mapView = OSMView(
            rect: view.bounds,
            location: nil,  // Will center on user
            zoomConfig: zoomConfig
        )
        
        // Set delegate
        mapView.userLocationDelegate = self
        
        // Enable tracking
        let trackConfig = TrackConfiguration(
            moveMap: true,
            useDirectionMarker: false,
            controlUserMarker: true
        )
        mapView.locationManager.toggleTracking(configuration: trackConfig)
        
        view.addSubview(mapView)
    }
    
    func locationChanged(userLocation: CLLocationCoordinate2D, heading: Double) {
        // Receive real-time location updates
        print("User at: \(userLocation.latitude), \(userLocation.longitude)")
        print("Heading: \(heading)°")
    }
    
    func handlePermission(state: LocationPermission) {
        switch state {
        case .Granted:
            print("Location access granted")
        case .NotGranted:
            print("Location access denied - need to request in Info.plist")
        }
    }
}
```

--------------------------------

### ShapeStyleConfiguration Example

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/ShapeManager.md

Example of creating a ShapeStyleConfiguration with custom fill color, border color, border width, and line cap.

```swift
let style = ShapeStyleConfiguration(
    filledColor: UIColor.blue.withAlphaComponent(0.3),
    borderColor: .blue,
    borderWidth: 2.0,
    lineCap: .ROUND
)
```

--------------------------------

### MarkerIconPoi Initialization Examples

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/PoisManager.md

Demonstrates how to create MarkerIconPoi instances using both the full configuration constructor and the minimal constructor. The first example shows a POI with custom styling, while the second uses minimal parameters and relies on a group icon.

```swift
// Using full configuration
let poi1 = MarkerIconPoi(
    configuration: MarkerConfiguration(
        icon: restaurantIcon,
        iconSize: (x: 30, y: 30),
        angle: 45.0,
        anchor: (x: 0.5, y: 0.5)
    ),
    location: CLLocationCoordinate2D(latitude: 48.8566, longitude: 2.3522)
)

// Using minimal constructor (location only, uses group icon)
let poi2 = MarkerIconPoi(
    location: CLLocationCoordinate2D(latitude: 48.86, longitude: 2.35),
    angle: nil,
    anchor: nil
)
```

--------------------------------

### Install OSMFlutterFramework using Podfile

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/README.md

Include the OSMFlutterFramework in your application's Podfile to manage its installation.

```ruby
pod "OSMFlutterFramework"
```

--------------------------------

### Format Custom Tile URLs in Swift

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/errors.md

Provides examples of CustomTiles configuration for tile servers. Demonstrates how URL tokens like {z}, {x}, and {y} are replaced and shows an example of a malformed URL that might fail.

```swift
// Missing tokens - will fail
let badTile = CustomTiles([
    "urls": [["url": "https://tile.example.com/tile.png"]],  // No {z}/{x}/{y}
    "tileExtension": "",
    "tileSize": 256,
    "maxZoomLevel": "19"
])

// Will be auto-corrected by CustomTiles constructor
// Added suffix: /tile.png{z}/{x}/{y}
```

--------------------------------

### Camera Control Examples

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/OSMView.md

Provides examples for controlling the map's camera, including moving to a specific location, fitting bounds, setting boundary constraints, and adjusting zoom levels. Use these methods to manipulate the map's viewport programmatically.

```swift
// Zoom to specific location
mapView.moveTo(
    location: CLLocationCoordinate2D(latitude: 51.5074, longitude: -0.1278),
    zoom: 12,
    animated: true
)

// Fit bounds
let bounds = BoundingBox(north: 50.0, west: 0.0, east: 10.0, south: 40.0)
mapView.moveToByBoundingBox(bounds: bounds, animated: true)

// Set bounds constraints
mapView.setBoundingBox(bounds: bounds)

// Control zoom
mapView.zoomIn(step: 2)
mapView.zoomOut(animated: false)
```

--------------------------------

### OSMUserLocationHandler Implementation Example

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/LocationManager.md

Example implementation of the OSMUserLocationHandler protocol within a MapViewController. This shows how to handle location and permission updates.

```swift
extension MapViewController: OSMUserLocationHandler {
    func locationChanged(userLocation: CLLocationCoordinate2D,
                        heading: Double) {
        print("Location: \(userLocation)")
        print("Heading: \(heading)°")
    }
    
    func handlePermission(state: LocationPermission) {
        switch state {
        case .Granted:
            print("Location permission granted")
        case .NotGranted:
            print("Location permission denied")
        }
    }
}

// Set delegate
mapView.userLocationDelegate = self
```

--------------------------------

### MarkerIconPoi Constructors

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/PoisManager.md

Demonstrates the two constructors available for MarkerIconPoi: one for full configuration and another for minimal setup.

```APIDOC
## MarkerIconPoi

POI marker combining location and configuration.

### Constructor (full configuration)

```swift
init(configuration: MarkerConfiguration, location: CLLocationCoordinate2D)
```

#### Parameters

- **configuration** (MarkerConfiguration) - Required - Full marker styling
- **location** (CLLocationCoordinate2D) - Required - POI location

### Constructor (minimal)

```swift
public init(location: CLLocationCoordinate2D, angle: Float?, anchor: MarkerAnchor?)
```

#### Parameters

- **location** (CLLocationCoordinate2D) - Required - POI location
- **angle** (Float?) - Optional - Rotation angle (optional)
- **anchor** (MarkerAnchor?) - Optional - Custom anchor point (optional)

### Example

```swift
// Using full configuration
let poi1 = MarkerIconPoi(
    configuration: MarkerConfiguration(
        icon: restaurantIcon,
        iconSize: (x: 30, y: 30),
        angle: 45.0,
        anchor: (x: 0.5, y: 0.5)
    ),
    location: CLLocationCoordinate2D(latitude: 48.8566, longitude: 2.3522)
)

// Using minimal constructor (location only, uses group icon)
let poi2 = MarkerIconPoi(
    location: CLLocationCoordinate2D(latitude: 48.86, longitude: 2.35),
    angle: nil,
    anchor: nil
)
```
```

--------------------------------

### Draw Basic Circle Example

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/ShapeManager.md

Demonstrates drawing a basic circle shape on the map using CircleOSM, CLLocationCoordinate2D, and ShapeStyleConfiguration.

```swift
let style = ShapeStyleConfiguration(
    filledColor: UIColor.red.withAlphaComponent(0.3),
    borderColor: .red,
    borderWidth: 2.0
)

let circle = CircleOSM(
    center: CLLocationCoordinate2D(latitude: 48.8566, longitude: 2.3522),
    distanceInMeter: 500,
    style: style
)

mapView.shapeManager.drawShape(key: "circle1", shape: circle)
```

--------------------------------

### Draw Basic Rectangle Example

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/ShapeManager.md

Demonstrates drawing a basic rectangle shape on the map using RectShapeOSM, CLLocationCoordinate2D, and ShapeStyleConfiguration.

```swift
let style = ShapeStyleConfiguration(
    filledColor: UIColor.green.withAlphaComponent(0.2),
    borderColor: .green,
    borderWidth: 1.5
)

let rect = RectShapeOSM(
    center: CLLocationCoordinate2D(latitude: 51.5074, longitude: -0.1278),
    distanceInMeter: 1000,
    style: style
)

mapView.shapeManager.drawShape(key: "rect1", shape: rect)
```

--------------------------------

### MapMarkerHandler Protocol Implementation

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/MarkerManager.md

Example implementation of the MapMarkerHandler protocol in a ViewController to print marker interaction locations. Remember to set the delegate.

```swift
extension MyViewController: MapMarkerHandler {
    func onMarkerSingleTap(location: CLLocationCoordinate2D) {
        print("Marker tapped at: \(location)")
    }
    
    func onMarkerLongPress(location: CLLocationCoordinate2D) {
        print("Marker long-pressed at: \(location)")
    }
}

// Set delegate
mapView.mapHandlerDelegate = self
```

--------------------------------

### RectShapeOSM Drawing Example

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/ShapeManager.md

Demonstrates how to create and draw RectShapeOSM instances on a mapView using both center-based and bounding box-based constructors. Requires a mapView and a ShapeStyleConfiguration.

```swift
// Center-based
let style = ShapeStyleConfiguration(
    filledColor: UIColor.green.withAlphaComponent(0.2),
    borderColor: .green,
    borderWidth: 1.5
)

let rect = RectShapeOSM(
    center: CLLocationCoordinate2D(latitude: 48.8566, longitude: 2.3522),
    distanceInMeter: 1000,
    style: style
)

mapView.shapeManager.drawShape(key: "zone1", shape: rect)

// Bounding box-based
let bounds = BoundingBox(north: 50.0, west: 0.0, east: 10.0, south: 40.0)
let boundRect = RectShapeOSM(boundingBpox: bounds, style: style)
mapView.shapeManager.drawShape(key: "bounds_rect", shape: boundRect)
```

--------------------------------

### Draw Transparent Shape Example

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/ShapeManager.md

Example of drawing a transparent shape (CircleOSM) by setting a low alpha value for the filled color in ShapeStyleConfiguration.

```swift
let style = ShapeStyleConfiguration(
    filledColor: UIColor.yellow.withAlphaComponent(0.1),  // Very transparent
    borderColor: .yellow,
    borderWidth: 1.0
)

let zone = CircleOSM(
    center: CLLocationCoordinate2D(latitude: 48.8566, longitude: 2.3522),
    distanceInMeter: 2000,
    style: style
)

mapView.shapeManager.drawShape(key: "light_zone", shape: zone)
```

--------------------------------

### Manage Multiple POI Categories

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/PoisManager.md

This example demonstrates a class for managing different categories of POIs (restaurants, hotels, attractions) on a map. It includes setting up unique icons for each category and methods to add markers belonging to these categories.

```swift
class POICategoryManager {
    let mapView: OSMView
    
    init(mapView: OSMView) {
        self.mapView = mapView
    }
    
    func setupCategories() {
        // Restaurants
        let restaurantIcon = UIImage(systemName: "fork.knife")!.withTintColor(.red)
        mapView.poisManager.setOrCreateIconPoi(
            id: "restaurants",
            icon: restaurantIcon,
            iconSize: (x: 32, y: 32)
        )
        
        // Hotels
        let hotelIcon = UIImage(systemName: "building.2")!.withTintColor(.blue)
        mapView.poisManager.setOrCreateIconPoi(
            id: "hotels",
            icon: hotelIcon,
            iconSize: (x: 32, y: 32)
        )
        
        // Attractions
        let attractionIcon = UIImage(systemName: "star.fill")!.withTintColor(.orange)
        mapView.poisManager.setOrCreateIconPoi(
            id: "attractions",
            icon: attractionIcon,
            iconSize: (x: 32, y: 32)
        )
    }
    
    func addRestaurants(_ locations: [CLLocationCoordinate2D]) {
        let pois = locations.map {
            MarkerIconPoi(location: $0, angle: nil, anchor: nil)
        }
        mapView.poisManager.setMarkersPoi(id: "restaurants", markers: pois)
    }
    
    func addHotels(_ locations: [CLLocationCoordinate2D]) {
        let pois = locations.map {
            MarkerIconPoi(location: $0, angle: nil, anchor: nil)
        }
        mapView.poisManager.setMarkersPoi(id: "hotels", markers: pois)
    }
    
    func addAttractions(_ locations: [CLLocationCoordinate2D]) {
        let pois = locations.map {
            MarkerIconPoi(location: $0, angle: nil, anchor: nil)
        }
        mapView.poisManager.setMarkersPoi(id: "attractions", markers: pois)
    }
}

// Usage
let poiManager = POICategoryManager(mapView: mapView)
poiManager.setupCategories()

poiManager.addRestaurants([
    CLLocationCoordinate2D(latitude: 48.8566, longitude: 2.3522),
    CLLocationCoordinate2D(latitude: 48.86, longitude: 2.35)
])

poiManager.addHotels([
    CLLocationCoordinate2D(latitude: 48.85, longitude: 2.35)
])
```

--------------------------------

### Interactive Road Selection Example

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/RoadManager.md

Implements interactive road selection by handling polyline taps. When a road is tapped, it's highlighted, and the previously selected road is deselected. Requires conforming to PoylineHandler and setting the delegate.

```swift
class MapViewController: UIViewController, PoylineHandler {
    var selectedRoadId: String?
    
    @IBOutlet weak var mapView: OSMView!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        mapView.roadTapHandlerDelegate = self
    }
    
    func onTap(roadId: String) {
        // Highlight selected road
        if let previousId = selectedRoadId {
            mapView.roadManager.removeRoad(id: previousId)
        }
        
        selectedRoadId = roadId
        
        // Redraw with highlight color
        let highlightConfig = RoadConfiguration(
            width: 6.0,
            color: .yellow,
            borderWidth: 1.0,
            borderColor: .orange
        )
        mapView.roadManager.removeRoad(id: roadId)
        // Re-add with highlight config (in real app, would store original coordinates)
    }
}
```

--------------------------------

### Draw Opaque Shape Example

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/ShapeManager.md

Example of drawing a fully opaque shape (CircleOSM) by setting the alpha value to 1.0 for the filled color in ShapeStyleConfiguration.

```swift
let style = ShapeStyleConfiguration(
    filledColor: UIColor.blue.withAlphaComponent(1.0),  // Fully opaque
    borderColor: .darkBlue,
    borderWidth: 2.0
)

let shape = CircleOSM(
    center: CLLocationCoordinate2D(latitude: 48.8566, longitude: 2.3522),
    distanceInMeter: 1000,
    style: style
)

mapView.shapeManager.drawShape(key: "opaque_zone", shape: shape)
```

--------------------------------

### Implement PoylineHandler Protocol

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/RoadManager.md

Example implementation of the PoylineHandler protocol to receive tap events on polylines. This involves conforming a view controller to the protocol and setting it as the delegate for the map view's road tap handler.

```swift
extension MyViewController: PoylineHandler {
    func onTap(roadId: String) {
        print("Road tapped: (roadId)")
    }
}

// Set delegate
mapView.roadTapHandlerDelegate = self
```

--------------------------------

### Enable Continuous Location Updates

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/LocationManager.md

Use this method to enable continuous location updates, which starts the tracking of the user's location. No parameters are needed.

```swift
mapView.locationManager.requestEnableLocation()
```

--------------------------------

### Configure Polyline Border Styling in Swift

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/errors.md

Shows examples of RoadConfiguration for drawing polylines with borders. A border is only rendered if its width is positive, the color is not nil, and it differs from the polyline's main color.

```swift
// Border NOT drawn - same color as line
let config1 = RoadConfiguration(
    width: 5.0,
    color: .blue,
    borderColor: .blue,  // Same as color - border ignored
    borderWidth: 1.0
)

// Border drawn - different color
let config2 = RoadConfiguration(
    width: 5.0,
    color: .blue,
    borderColor: .white,  // Different from color
    borderWidth: 1.0
)

// Border NOT drawn - borderWidth is 0
let config3 = RoadConfiguration(
    width: 5.0,
    color: .blue,
    borderColor: .white,
    borderWidth: 0  // Border ignored
)
```

--------------------------------

### Add Styled Polyline with Border

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/RoadManager.md

Adds a polyline with advanced styling, including width, color, border, opacity, line cap, and polyline type. This example demonstrates a solid blue line with a white border.

```swift
let coordinates = [
    CLLocationCoordinate2D(latitude: 48.85, longitude: 2.35),
    CLLocationCoordinate2D(latitude: 48.86, longitude: 2.36)
]

let config = RoadConfiguration(
    width: 4.0,
    color: .blue,
    borderWidth: 1.0,
    borderColor: .white,
    opacity: 0.9,
    lineCap: .ROUND,
    polylineType: .LINE
)

mapView.roadManager.addRoad(id: "styled_route", polylines: coordinates, configuration: config)
```

--------------------------------

### Initialize OSM Map View

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/overview.md

Demonstrates how to create and configure an OSMView instance with zoom settings and map configuration. Add the created map view to the current view hierarchy.

```swift
import OSMFlutterFramework

let zoomConfig = ZoomConfiguration(
    initZoom: 5,
    minZoom: 0,
    maxZoom: 19,
    step: 1
)

let mapView = OSMView(
    rect: CGRect(x: 0, y: 0, width: 300, height: 400),
    location: CLLocationCoordinate2D(latitude: 48.8566, longitude: 2.3522),
    zoomConfig: zoomConfig,
    mapTileConfiguration: OSMMapConfiguration(),
    tile: nil
)

self.view.addSubview(mapView)
```

--------------------------------

### Initialize OSMView with Parameters

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/configuration.md

The main map container is initialized with these constructor parameters. Use this to set the initial view frame, location, zoom constraints, and tile rendering options.

```swift
public init(rect: CGRect,
            location: CLLocationCoordinate2D?,
            zoomConfig: ZoomConfiguration,
            mapTileConfiguration: OSMMapConfiguration = OSMMapConfiguration(),
            tile: CustomTiles? = nil)
```

--------------------------------

### Initialize OSMView

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/OSMView.md

Create a new OSMView instance with specified frame, initial location, and zoom configuration. Custom map tile configurations and tile layers can also be provided.

```swift
public init(rect: CGRect,
            location: CLLocationCoordinate2D?,
            zoomConfig: ZoomConfiguration,
            mapTileConfiguration: OSMMapConfiguration = OSMMapConfiguration(),
            tile: CustomTiles? = nil)
```

```swift
import OSMFlutterFramework

let zoomConfig = ZoomConfiguration(initZoom: 5, minZoom: 0, maxZoom: 19, step: 1)
let mapView = OSMView(
    rect: CGRect(x: 0, y: 0, width: 400, height: 600),
    location: CLLocationCoordinate2D(latitude: 48.8566, longitude: 2.3522),
    zoomConfig: zoomConfig
)
view.addSubview(mapView)
```

--------------------------------

### Risky Circular Reference Example

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/errors.md

An example demonstrating a potential circular reference where the view controller holds a strong reference to the map view, and the map view's delegate (the view controller) also holds a strong reference back, preventing deallocation.

```swift
// RISKY - mapView → delegate → mapView (cycle)
class MyViewController: UIViewController, OnMapGesture {
    var mapView: OSMView!
    
    override func viewDidLoad() {
        super.viewDidLoad() 
        mapView = OSMView(...)
        mapView.onMapGestureDelegate = self  // self holds mapView strongly
    }
    
    func onSingleTap(location: CLLocationCoordinate2D) {
        // self accessed, creating cycle
    }
}
```

--------------------------------

### Get Current Map Bounding Box

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/llms.txt

Retrieve the current bounding box visible on the map.

```swift
public func getBoundingBox() -> BoundingBox
```

--------------------------------

### Initialize and Draw a Circle Shape

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/ShapeManager.md

Demonstrates the initialization of a CircleOSM object with specific styling and coordinates, then drawing it on the map.

```swift
let style = ShapeStyleConfiguration(
    filledColor: UIColor.red.withAlphaComponent(0.3),
    borderColor: .red,
    borderWidth: 2.0
)

let circle = CircleOSM(
    center: CLLocationCoordinate2D(latitude: 48.8566, longitude: 2.3522),
    distanceInMeter: 500,
    style: style
)

mapView.shapeManager.drawShape(key: "danger_zone", shape: circle)
```

--------------------------------

### Get Current Zoom Level

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/OSMView.md

Retrieve the current zoom level of the map, which ranges from 0 to 19.

```swift
public func zoom() -> Int

let currentZoom = mapView.zoom() // Returns 5
```

--------------------------------

### OSMView Constructor

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/OSMView.md

Initializes a new OSMView instance with specified frame, initial location, zoom configuration, map tile configuration, and custom tile layer.

```APIDOC
## OSMView Constructor

### Description
Initializes a new map view with specified frame, initial location, zoom configuration, map tile configuration, and custom tile layer.

### Method
`public init(rect: CGRect, location: CLLocationCoordinate2D?, zoomConfig: ZoomConfiguration, mapTileConfiguration: OSMMapConfiguration = OSMMapConfiguration(), tile: CustomTiles? = nil)`

### Parameters
#### Path Parameters
- **rect** (CGRect) - Yes - View frame (position and size)
- **location** (CLLocationCoordinate2D?) - No - Initial center coordinate (use initialisationMapWithInitLocation() if not provided)
- **zoomConfig** (ZoomConfiguration) - Yes - Zoom level configuration
- **mapTileConfiguration** (OSMMapConfiguration) - No - Tile rendering options
- **tile** (CustomTiles?) - No - Custom tile layer (nil uses OpenStreetMap)

### Return
OSMView instance

### Example
```swift
import OSMFlutterFramework

let zoomConfig = ZoomConfiguration(initZoom: 5, minZoom: 0, maxZoom: 19, step: 1)
let mapView = OSMView(
    rect: CGRect(x: 0, y: 0, width: 400, height: 600),
    location: CLLocationCoordinate2D(latitude: 48.8566, longitude: 2.3522),
    zoomConfig: zoomConfig
)
view.addSubview(mapView)
```
```

--------------------------------

### Create and Style POIs with Custom Icons

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/PoisManager.md

Demonstrates how to create custom icons for POIs and apply varied styling, including rotation for specific POIs, using MarkerConfiguration. This is useful for visually differentiating POI types or states.

```swift
let restaurantIcon = UIImage(systemName: "fork.knife")!.withTintColor(.red)

let restaurantConfig = MarkerConfiguration(
    icon: restaurantIcon,
    iconSize: (x: 32, y: 32),
    angle: nil,
    anchor: (x: 0.5, y: 0.5),  // Center anchor
    scaleType: .Scale
)

mapView.poisManager.setOrCreateIconPoi(
    id: "restaurants",
    icon: restaurantIcon,
    iconSize: (x: 32, y: 32)
)

// Create POIs with varied styling
var pois: [MarkerIconPoi] = []

for (index, location) in restaurantLocations.enumerated() {
    var config = restaurantConfig
    
    // Rotate popular restaurants (5-star)
    if isPopular(index) {
        config = config.copyWith(angle: Float(index * 30))
    }
    
    let poi = MarkerIconPoi(
        configuration: config,
        location: location
    )
    pois.append(poi)
}

mapView.poisManager.setMarkersPoi(id: "restaurants", markers: pois)
```

--------------------------------

### OSMView Initialization

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/llms.txt

Initializes the OSMView with specified parameters including frame, initial location, zoom configuration, map tile configuration, and custom tiles.

```APIDOC
## OSMView Initialization

### Description
Initializes the OSMView with specified parameters including frame, initial location, zoom configuration, map tile configuration, and custom tiles.

### Parameters
- **rect** (CGRect) - Required - The frame for the map view.
- **location** (CLLocationCoordinate2D?) - Optional - The initial geographic location to display.
- **zoomConfig** (ZoomConfiguration) - Required - Configuration for the map's zoom level.
- **mapTileConfiguration** (OSMMapConfiguration) - Optional - Configuration for map tiles, defaults to OSMMapConfiguration().
- **tile** (CustomTiles?) - Optional - Custom tile configuration.
```

--------------------------------

### Get All Marker Locations

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/MarkerManager.md

Retrieve an array containing the CLLocationCoordinate2D of all markers currently displayed on the map. Useful for tracking or debugging.

```swift
let markers = mapView.markerManager.getAllMarkers()
print("Total markers: \(markers.count)")
```

--------------------------------

### Get Map Center Coordinate

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/OSMView.md

Retrieves the current geographical coordinate of the map's center. This is useful for pinpointing the map's focus.

```swift
let center = mapView.center()
print("Center: \(center.latitude), \(center.longitude)")
```

--------------------------------

### Get Map Bounding Box

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/OSMView.md

Retrieves the current visible geographical boundaries of the map. This is useful for determining the extent of the displayed map area.

```swift
let bounds = mapView.getBoundingBox()
print("North: \(bounds.north), South: \(bounds.south)")
```

--------------------------------

### MarkerIconPoi Full Configuration Constructor

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/PoisManager.md

Initializes a MarkerIconPoi with a full configuration, including icon, size, angle, and anchor. Use this when specific styling is required for each POI.

```swift
init(configuration: MarkerConfiguration,
     location: CLLocationCoordinate2D)
```

--------------------------------

### Add Polyline with Transparency

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/RoadManager.md

Adds a polyline with adjustable transparency using the 'opacity' property in RoadConfiguration. This example creates a semi-transparent blue line with a white border.

```swift
let config = RoadConfiguration(
    width: 8.0,
    color: .blue,
    borderWidth: 2.0,
    borderColor: .white,
    opacity: 0.6,  // Semi-transparent
    lineCap: .ROUND
)

mapView.roadManager.addRoad(
    id: "transparent_route",
    polylines: coordinates,
    configuration: config
)
```

--------------------------------

### Add a Marker to the Map

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/overview.md

Shows how to create a Marker object with a system image icon and add it to the map using the MarkerManager. Ensure the marker configuration includes an icon and desired anchor point.

```swift
let marker = Marker(
    location: CLLocationCoordinate2D(latitude: 48.8566, longitude: 2.3522),
    markerConfiguration: MarkerConfiguration(
        icon: UIImage(systemName: "mappin")!,
        iconSize: (x: 30, y: 30),
        angle: nil,
        anchor: (x: 0.5, y: 1.0),
        scaleType: .Scale
    )
)
mapView.markerManager.addMarker(marker: marker)
```

--------------------------------

### OSMMapConfiguration

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/types.md

Configuration for tile rendering behavior. This includes settings for scaling, drawing previous layers, and adapting scale to screen density.

```APIDOC
## OSMMapConfiguration

### Description
Configuration for tile rendering behavior. This includes settings for scaling, drawing previous layers, and adapting scale to screen density.

### Fields
- **zoomLevelScaleFactor** (Double) - Yes - 0.65 - Scale factor for tile rendering
- **numDrawPreviousLayers** (Int) - Yes - 1 - Number of previous zoom level tiles to draw
- **adaptScaleToScreen** (Bool) - Yes - true - Whether to adapt scaling to device screen density
```

--------------------------------

### Control Location Tracking

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/LocationManager.md

Start and stop location tracking, and center the map on the user's current location. These actions are typically triggered by user interface elements.

```swift
class MapViewController: UIViewController {
    @IBOutlet weak var mapView: OSMView!
    
    @IBAction func startTrackingTapped(_ sender: UIButton) {
        let trackConfig = TrackConfiguration(
            moveMap: true,
            useDirectionMarker: true,
            controlUserMarker: true
        )
        mapView.locationManager.toggleTracking(configuration: trackConfig)
    }
    
    @IBAction func stopTrackingTapped(_ sender: UIButton) {
        mapView.locationManager.stopLocation()
    }
    
    @IBAction func centerMapTapped(_ sender: UIButton) {
        mapView.locationManager.moveToUserLocation(animated: true)
    }
}
```

--------------------------------

### Request Single Location

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/LocationManager.md

Call this method to request the user's current location once. It performs a one-shot request and does not require any specific setup beyond accessing the locationManager property.

```swift
mapView.locationManager.requestSingleLocation()
```

--------------------------------

### Basic POI Group Management

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/PoisManager.md

Shows how to create an icon group for POIs and then add multiple POI markers to that group using the poisManager.

```APIDOC
## Usage Examples: Basic POI Group

### Create and Add Markers to a POI Group

This example demonstrates setting up a POI icon group for restaurants and then adding individual restaurant markers to it.

```swift
// Create restaurant icon group
let restaurantIcon = UIImage(systemName: "fork.knife")!.withTintColor(.red)
mapView.poisManager.setOrCreateIconPoi(
    id: "restaurants",
    icon: restaurantIcon,
    iconSize: (x: 32, y: 32)
)

// Add markers to the group
let restaurants = [
    MarkerIconPoi(
        location: CLLocationCoordinate2D(latitude: 48.8566, longitude: 2.3522),
        angle: nil,
        anchor: nil
    ),
    MarkerIconPoi(
        location: CLLocationCoordinate2D(latitude: 48.86, longitude: 2.35),
        angle: nil,
        anchor: nil
    )
]

mapView.poisManager.setMarkersPoi(id: "restaurants", markers: restaurants)
```
```

--------------------------------

### Tile Configuration Method

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/llms.txt

Allows setting custom tile configurations for the map.

```APIDOC
## Tile Configuration

### Description
Allows setting custom tile configurations for the map.

### Method
- **setCustomTile(tile: CustomTiles)**: Sets a custom tile configuration for the map. The map initializes with either a raster or vector base layer depending on `tile?.isVector`. Raster tiles use `OSMTiledLayerConfig` with `{x}/{y}/{z}` URL templates. Vector tiles use `MCTiled2dMapVectorLayerInterface` with a `styleURL` and a built-in `SystemFontLoader`.
```

--------------------------------

### showAll

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/MarkerManager.md

Makes all previously hidden markers visible again on the map.

```APIDOC
## showAll()

### Description
Show all markers that were hidden.

### Method Signature
```swift
public func showAll()
```

### Request Example
```swift
mapView.markerManager.showAll()
```
```

--------------------------------

### Marker Struct and Configuration

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/llms.txt

Defines how to create and configure markers on the map, including their position, icon, size, angle, anchor point, and scaling behavior.

```swift
public struct Marker {
    public init(location: CLLocationCoordinate2D, markerConfiguration: MarkerConfiguration)
}

public typealias MarkerIconSize = (x: Int, y: Int)
public typealias MarkerAnchor = (x: Double, y: Double)

public enum MarkerScaleType {
    case Scale
    case rotate
    case invariant
    case fixed
}

public struct MarkerConfiguration {
    public init(
        icon: UIImage,
        iconSize: MarkerIconSize?,
        angle: Float?,
        anchor: MarkerAnchor?,
        scaleType: MarkerScaleType = .Scale
    )
    public func copyWith(
        icon: UIImage? = nil,
        iconSize: MarkerIconSize? = nil,
        angle: Float? = nil,
        anchor: MarkerAnchor? = nil,
        scaleType: MarkerScaleType? = nil
    ) -> MarkerConfiguration
}
```

--------------------------------

### Show All Map Layers

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/llms.txt

Make all map layers visible.

```swift
public func showAllLayers()
```

--------------------------------

### Correct Main Thread Dispatch for Marker Addition

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/errors.md

Demonstrates the correct way to add a marker to the map view by dispatching the operation to the main thread. This is crucial for thread safety in the OSMMapCore framework.

```swift
DispatchQueue.main.async {
    mapView.markerManager.addMarker(marker: marker)
}
```

--------------------------------

### SwiftUI Integration for OSMView

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/AGENTS.md

Demonstrates how to integrate the OSMView into a SwiftUI view hierarchy by creating a UIViewControllerRepresentable.

```swift
struct OSMMapView: UIViewControllerRepresentable {
    func makeUIViewController(context: Context) -> InnerOSMMapView {
        // ...
    }
}
class InnerOSMMapView: UIViewController {
    let map = OSMView(...)
}
```

--------------------------------

### RoadConfiguration Constructor

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/RoadManager.md

Initializes a RoadConfiguration object to define the appearance of a road. Key parameters include width, color, and opacity.

```swift
public struct RoadConfiguration {
    let width: Float
    let color: UIColor
    let borderColor: UIColor?
    let borderWidth: Float?
    let opacity: Float
    let lineCap: MCLineCapType
    let lineJoin: MCLineJoinType
    let polylineType: PolylineType
}
```

```swift
public init(width: Float,
            color: UIColor,
            borderWidth: Float? = nil,
            borderColor: UIColor? = nil,
            opacity: Float = 1.0,
            lineCap: LineCapType = LineCapType.ROUND,
            polylineType: PolylineType = PolylineType.LINE)
```

--------------------------------

### MarkerConfiguration

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/types.md

Complete configuration for marker appearance, including icon, size, rotation, anchor point, and scaling behavior.

```APIDOC
## MarkerConfiguration

### Description
Complete configuration for marker appearance.

### Fields
- **icon** (UIImage) - Yes - — - Icon image to display
- **iconSize** (MarkerIconSize?) - No - nil - Icon dimensions in pixels; uses image size if nil
- **angle** (Float?) - No - nil - Rotation angle in degrees
- **anchor** (MarkerAnchor?) - No - nil - Icon anchor point; defaults to top-left if nil
- **scaleType** (MarkerScaleType) - Yes - Scale - Scaling behavior with zoom

### Methods
- **copyWith()** - Create modified copy of configuration
```

--------------------------------

### showAll()

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/RoadManager.md

Makes all previously hidden roads visible on the map.

```APIDOC
## showAll()

### Description
Shows all roads that were previously hidden using the `hideAll()` method.

### Method
POST (Assumed, as it changes map state)

### Endpoint
`/map/roads/show`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```swift
mapView.roadManager.showAll()
```

### Response
#### Success Response (200)
Void

#### Response Example
None (Void return type)
```

--------------------------------

### OSMMapConfiguration Defaults

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/configuration.md

Sets the default configuration for tile rendering, including scale factor, number of previous layers to draw, and screen adaptation.

```swift
OSMMapConfiguration(
    zoomLevelScaleFactor: 0.65,
    numDrawPreviousLayers: 1,
    adaptScaleToScreen: true
)
```

--------------------------------

### ShapeStyleConfiguration Constructor

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/ShapeManager.md

Initializes a ShapeStyleConfiguration with specified colors, border width, and an optional line cap style. Defaults lineCap to ROUND.

```swift
public init(filledColor: UIColor,
            borderColor: UIColor,
            borderWidth: Double,
            lineCap: LineCapType = LineCapType.ROUND)
```

--------------------------------

### moveToByBoundingBox()

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/OSMView.md

Moves and zooms the camera to fit a specified bounding box, with an option to animate the transition.

```APIDOC
## moveToByBoundingBox()

### Description
Move and zoom camera to fit a bounding box.

### Method
`public func moveToByBoundingBox(bounds: BoundingBox, animated: Bool)`

### Parameters
#### Path Parameters
- **bounds** (BoundingBox) - Yes - Target bounds to fit
- **animated** (Bool) - Yes - Whether to animate movement

### Return
Void

### Example
```swift
let bounds = BoundingBox(north: 50.0, west: 0.0, east: 10.0, south: 40.0)
mapView.moveToByBoundingBox(bounds: bounds, animated: true)
```
```

--------------------------------

### OSMMapConfiguration Structure

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/types.md

Configures tile rendering behavior for the map. Passed during map initialization.

```swift
public struct OSMMapConfiguration {
    let zoomLevelScaleFactor: Double
    let numDrawPreviousLayers: Int
    let adaptScaleToScreen: Bool
}
```

--------------------------------

### MarkerConfiguration Constructor

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/MarkerManager.md

Initializes MarkerConfiguration with an icon and optional appearance properties. Defaults to Scale type.

```swift
public init(icon: UIImage,
            iconSize: MarkerIconSize?,
            angle: Float?,
            anchor: MarkerAnchor?,
            scaleType: MarkerScaleType = MarkerScaleType.Scale)
```

--------------------------------

### showAll

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/ShapeManager.md

Makes all previously hidden shapes visible on the map.

```APIDOC
## showAll()

### Description
Show all shapes that were hidden.

### Method
`public func showAll()`

### Request Example
```swift
mapView.shapeManager.showAll()
```
```

--------------------------------

### ShapeStyleConfiguration Constructor

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/ShapeManager.md

Configures the appearance of a shape, including its fill color, border color, and border width.

```APIDOC
## ShapeStyleConfiguration Constructor

### Description
Shape appearance configuration for fill and border.

### Constructor
```swift
public init(filledColor: UIColor, borderColor: UIColor, borderWidth: Double, lineCap: LineCapType = LineCapType.ROUND)
```

#### Parameters
- **filledColor** (UIColor) - Required - Interior fill color
- **borderColor** (UIColor) - Required - Border line color
- **borderWidth** (Double) - Required - Border width in pixels
- **lineCap** (LineCapType) - Optional - Default: ROUND - Line cap style (BUTT, ROUND, SQUARE)
```

--------------------------------

### Marker Constructor

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/MarkerManager.md

Initializes a Marker object with its geographic location and appearance settings.

```swift
public init(location: CLLocationCoordinate2D,
            markerConfiguration: MarkerConfiguration)
```

--------------------------------

### moveTo()

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/OSMView.md

Moves the camera to a specified location and zoom level, with an option to animate the movement.

```APIDOC
## moveTo()

### Description
Move camera to specified location and zoom level.

### Method
`public func moveTo(location: CLLocationCoordinate2D, zoom: Int?, animated: Bool)`

### Parameters
#### Path Parameters
- **location** (CLLocationCoordinate2D) - Yes - Target center coordinate
- **zoom** (Int?) - No - Target zoom level (0-19); nil keeps current
- **animated** (Bool) - Yes - Whether to animate movement

### Return
Void

### Example
```swift
mapView.moveTo(
    location: CLLocationCoordinate2D(latitude: 48.8566, longitude: 2.3522),
    zoom: 10,
    animated: true
)
```
```

--------------------------------

### Enable User Location Tracking

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/overview.md

Shows how to enable and configure user location tracking, including options to move the map with the user and use a direction marker. Set the userLocationDelegate to receive location updates.

```swift
let trackConfig = TrackConfiguration(
    moveMap: true,
    useDirectionMarker: true,
    disableMarkerRotation: false,
    controlUserMarker: true
)

mapView.locationManager.toggleTracking(configuration: trackConfig)

// Set delegate to receive updates
mapView.userLocationDelegate = self
```

--------------------------------

### initialisationMapWithInitLocation()

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/OSMView.md

Initializes the map with the initial location if it was provided as nil during the constructor call. This method should be called after the view has been initialized.

```APIDOC
## initialisationMapWithInitLocation()

### Description
Initialize map with the initial location if one was provided in constructor. Call this if the location was nil in init.

### Method
`public func initialisationMapWithInitLocation()`

### Parameters
(none)

### Return
Void

### Example
```swift
let mapView = OSMView(rect: ..., location: nil, zoomConfig: ...)
// ... later ...
mapView.initialisationMapWithInitLocation()
```
```

--------------------------------

### Camera & Navigation Methods

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/llms.txt

Provides methods for controlling the map's camera and navigation, including centering, bounding box manipulation, and zoom adjustments.

```APIDOC
## Camera & Navigation

### Description
Provides methods for controlling the map's camera and navigation, including centering, bounding box manipulation, and zoom adjustments.

### Methods
- **initialisationMapWithInitLocation()**: Initializes the map with the initial location.
- **moveTo(location: CLLocationCoordinate2D, zoom: Int?, animated: Bool)**: Moves the map camera to a specified location and zoom level, with an option for animation.
- **moveToByBoundingBox(bounds: BoundingBox, animated: Bool)**: Moves the map camera to fit within the specified bounding box, with an option for animation.
- **setBoundingBox(bounds: BoundingBox)**: Sets the bounding box for the map view.
- **center() -> CLLocationCoordinate2D**: Returns the current center coordinate of the map.
- **getBoundingBox() -> BoundingBox**: Returns the current bounding box of the map view.
- **zoom() -> Int**: Returns the current zoom level of the map.
- **setZoom(zoom: Int, animated: Bool = true)**: Sets the zoom level of the map, with an option for animation.
- **zoomIn(step: Int? = nil, animated: Bool = true)**: Zooms the map in by a specified step, with an option for animation.
- **zoomOut(step: Int? = nil, animated: Bool = true)**: Zooms the map out by a specified step, with an option for animation.
- **enableRotation(enable: Bool)**: Enables or disables map rotation.
- **setRotation(angle: Double, animated: Bool = true)**: Sets the rotation angle of the map, with an option for animation.
- **stopCamera()**: Stops any ongoing camera animations.
```

--------------------------------

### Adding New Features to OSMView

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/AGENTS.md

Demonstrates how to extend the OSMView class to add new public methods or features. These extensions allow for cleaner integration with the map view's functionality.

```swift
extension OSMView {
    public func myNewFeature() {
        // use mapView.camera or mapView directly
    }
}
```

--------------------------------

### RectShapeOSM Constructor (Bounding Box-based)

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/ShapeManager.md

Initializes a RectShapeOSM using a bounding box and style configuration. Note the typo in the parameter name 'boundingBpox'.

```swift
public init(boundingBpox: BoundingBox,
            style: ShapeStyleConfiguration)
```

--------------------------------

### UserLocationConfiguration Struct

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/llms.txt

Configures the icons used for the user's current location and direction marker.

```swift
public struct UserLocationConfiguration {
    public init(userIcon: MarkerConfiguration, directionIcon: MarkerConfiguration?)
    public func copyWith(
        userIcon: MarkerConfiguration? = nil,
        directionIcon: MarkerConfiguration? = nil
    ) -> UserLocationConfiguration
}
```

--------------------------------

### Add OSMMapCoreIOSFramework to Package.swift

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/llms.txt

Add this Swift Package Manager dependency to your Package.swift file to include the framework.

```swift
.package(url: "https://github.com/liodali/OSMMapCoreIOSFramework.git", from: "1.0.0")
```

--------------------------------

### Info.plist Location Usage Descriptions

Source: https://github.com/liodali/osmmapcoreiosframework/blob/main/_autodocs/api-reference/LocationManager.md

Add these keys to your app's Info.plist file to request location permissions from the user. Specify the reasons for using location data.

```xml
<key>NSLocationWhenInUseUsageDescription</key>
<string>We need your location to show it on the map</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>We need your location to track your movements</string>
```