Airplane ModelLayer Hidden Behind Annotations in Mapbox MapView

[Hammad335]

Environment

• Xcode version: 16.1
• iOS version: 18.1
• Devices affected:
• Maps SDK Version: 11.8.0

Observed behavior and steps to reproduce

We are using Mapbox in Swift Xcode project and have implemented a ModelLayer to display real-time 3D airplane models on the map. These models are rendered using live position data fetched from an API. Additionally, markers are displayed on the map using MapViewAnnotation.

The problem occurs when the airplane model intersects with an annotation (marker). Since the annotation layer is rendered above the map by default, it occludes the airplane model when viewed from a top-down perspective. The airplane remains hidden behind the annotation until it moves past the marker’s position.

This behavior happens because the airplane layer is part of the map itself, whereas MapViewAnnotation renders annotations above the map layer, causing a layering conflict.

Code to Add MapViewAnnotation:

ForEvery(mapVM.items) { item in
                    MapViewAnnotation(coordinate: CLLocationCoordinate2D(latitude: item.lat, longitude: item.lng)) {
                        AsyncImage(url: URL(string: item.thumbnailImageURL)) { res in res.image?
                            .resizable()
                            .clipShape(Circle())
                            .frame(width: 45, height: 45)
                            .padding(3)
                            .background(Circle().fill(.white))
                            if (res.error) != nil {
                                Image(item.type)
                                    .resizable()
                                    .clipShape(Circle())
                                    .frame(width: 45, height: 45)
                                    .padding(3)
                                    .background(Circle().fill(.white))
                            }
                        }
                    }
                }

Video:

Screen.Recording.2025-01-17.at.4.22.22.PM.mp4

Steps to Reproduce:

1. Add a custom 3D airplane ModelLayer to the Mapbox map.
2. Display annotations using MapViewAnnotation at positions that overlap the airplane model's path.
3. Observe the rendering issue when the airplane passes beneath an annotation while viewed from a top-down perspective.

Expected behavior

The airplane model should be rendered above the annotations, or there should be a way to control the z-index/layering order between annotations and map layers.

Workaround Tried

To tackle the above problem, we attempted to display markers using PointAnnotation instead of MapViewAnnotation. However, this approach introduced new challenges:

Customization Limitation: PointAnnotation does not allow us to customize the size of the marker image (fetched dynamically from an API). As a result, the markers appear disproportionately large and visually unappealing.

URL Image Support Issue:
PointAnnotation does not provide a way to display images directly from a URL (async network images), as it only accepts asset images. Even when we convert network images to local images, all annotations display the same image for unknown reasons, which makes it impossible to correctly represent distinct markers.

Code to Add PointAnnotation:

Map(viewport: $viewport) {
                /// loop and show annotation on our feature
                ForEvery(mapVM.items) { item in
                    
                    PointAnnotation(coordinate: CLLocationCoordinate2D(latitude: item.lat, longitude: item.lng))
                        .image(.init(image: UIImage(data: item.thumbnailImageData) ?? UIImage(), name: "POI-Image"))
                }
            }

Images: Below image shows how marker images rendered using PointAnnotation are excessively large and it highlights the issue where the same image is displayed for all markers.

Note:
I would greatly appreciate any guidance on how to achieve the desired results or clarification if I might be implementing something incorrectly. Thank you!

[pjleonard37]

Hi @Hammad335

Thanks for sharing this use case with all of this detail! This repository is for reporting bugs or feature requests for the iOS Maps SDK itself. For how-to questions like these please contact our Support team using the contact form linked at the bottom of this page or ask in the Mapbox Developers Discord for assistance from the developer community. Best of luck with your project!