[Work 39] 경로 지도의 참여자 마커 클러스터링과 초기 카메라 맞춤을 구현했습니다.

WhereAreYou/WhereAreYou/Presentation/Map/AppointmentRoute/AppointmentRouteMapView.swift

@@ -10,11 +10,32 @@ import NMapsMap
 
 final class AppointmentRouteMapView: NMFNaverMapView {
 
+    /// 지도에 표시된 참여자 마커 — 클러스터링 시 식별자로 개별 제어
+    private struct ParticipantMarker {
+        let id: String
+        let coordinate: Coordinate
+        let marker: NMFMarker
+        /// 클러스터 마커에 표시할 정보
+        let member: ClusterMarkerView.Member
+    }
+
+    /// 마커가 겹칠 때의 우선순위 — 클러스터 > 개별 참여자 > 목적지
+    private enum MarkerZIndex {
+        static let place = 0
+        static let participant = 1
+        static let cluster = 2
+    }
+
+    /// 겹침 판정에 쓰는 참여자 마커 크기
+    private static let participantMarkerSize = MapMarker.size(for: .participant(profileImage: nil, tintColor: .clear))
+
+    private lazy var clusterController = ClusterMarkerController(mapView: mapView, zIndex: MarkerZIndex.cluster)
     private var placeMarker: NMFMarker?
-    private var participantMarkers: [NMFMarker] = []
+    private var participantMarkers: [ParticipantMarker] = []
     private var participantPolylines: [NMFPolylineOverlay] = []
     private var placeMarkerLoadTask: Task<Void, Never>?
     private var markerLoadTask: Task<Void, Never>?
+    private var placeCoordinate: Coordinate?
     private var hasMovedToInitialPosition = false
 
     override init(frame: CGRect) {
@@ -27,30 +48,26 @@ final class AppointmentRouteMapView: NMFNaverMapView {
         setUp()
     }
 
-    // MARK: - Public
+    // MARK: - Lifecycle
 
-    func moveCamera(to coordinate: Coordinate, zoomLevel: Double = 15) {
-        let cameraPosition = NMFCameraPosition(
-            NMGLatLng(lat: coordinate.latitude, lng: coordinate.longitude),
-            zoom: zoomLevel
-        )
-        mapView.moveCamera(NMFCameraUpdate(position: cameraPosition))
+    override func didMoveToWindow() {
+        super.didMoveToWindow()
+        clusterController.setActive(window != nil)
     }
 
+    // MARK: - Public
+
     func setPlaceMarker(coordinate: Coordinate, name: String) {
         placeMarkerLoadTask?.cancel()
         placeMarker?.mapView = nil
 
         placeMarkerLoadTask = Task { [weak self] in
             let pinImage = await AppAssetImageLoader.shared.load(.pin)
             guard !Task.isCancelled else { return }
-            await self?.addPlaceMarker(coordinate: coordinate, name: name, pinImage: pinImage)
+            self?.addPlaceMarker(coordinate: coordinate, name: name, pinImage: pinImage)
         }
 
-        if !hasMovedToInitialPosition {
-            hasMovedToInitialPosition = true
-            moveCamera(to: coordinate)
-        }
+        placeCoordinate = coordinate
     }
 
     func setParticipants(_ participants: [AppointmentRouteParticipant]) {
@@ -67,9 +84,12 @@ final class AppointmentRouteMapView: NMFNaverMapView {
             guard !Task.isCancelled, !images.isEmpty else { return }
 
             for (index, participant) in participants.enumerated() {
-                await self?.addMarker(for: participant, color: colors[index], profileImage: images[index])
+                self?.addMarker(for: participant, color: colors[index], profileImage: images[index])
             }
+            self?.updateClusters()
         }
+
+        moveToInitialPositionIfNeeded(participants: participants)
     }
 
 }
@@ -84,6 +104,45 @@ private extension AppointmentRouteMapView {
         showLocationButton = true
         showScaleBar = false
         showZoomControls = true
+        mapView.addCameraDelegate(delegate: self)
+    }
+
+    // MARK: - Clustering
+
+    func updateClusters() {
+        let items = participantMarkers.map { participantMarker in
+            let coordinate = participantMarker.coordinate
+            return ParticipantClusterer.Item(
+                id: participantMarker.id,
+                coordinate: coordinate,
+                screenPoint: mapView.projection.point(
+                    from: NMGLatLng(lat: coordinate.latitude, lng: coordinate.longitude)
+                )
+            )
+        }
+        let clusters = ParticipantClusterer(markerSize: Self.participantMarkerSize).cluster(items)
+        applyClusters(clusters)
+    }
+
+    /// 묶인 참여자는 개별 마커를 숨기고 클러스터 마커로 대체
+    func applyClusters(_ clusters: [ParticipantClusterer.Cluster]) {
+        let groupedClusters = clusters.filter { $0.memberIDs.count > 1 }
+        let groupedIDs = Set(groupedClusters.flatMap(\.memberIDs))
+
+        participantMarkers.forEach { $0.marker.hidden = groupedIDs.contains($0.id) }
+        clusterController.update(clusters: groupedClusters) { id in
+            participantMarkers.first { $0.id == id }?.member
+        }
+    }
+
+    // MARK: - Camera
+
+    func moveToInitialPositionIfNeeded(participants: [AppointmentRouteParticipant]) {
+        guard !hasMovedToInitialPosition, let placeCoordinate else { return }
+        hasMovedToInitialPosition = true
+
+        let participantPath = participants.flatMap(\.path)
+        fitCamera(to: [placeCoordinate] + participantPath, maxZoom: MapZoom.overview)
     }
 
     // MARK: - Overlay Building
@@ -130,6 +189,7 @@ private extension AppointmentRouteMapView {
         marker.width = MapMarker.size(for: kind).width
         marker.height = MapMarker.size(for: kind).height
         marker.anchor = MapMarker.anchor(for: kind)
+        marker.zIndex = MarkerZIndex.place
         marker.mapView = mapView
 
         placeMarker = marker
@@ -147,16 +207,39 @@ private extension AppointmentRouteMapView {
         marker.width = MapMarker.size(for: kind).width
         marker.height = MapMarker.size(for: kind).height
         marker.anchor = MapMarker.anchor(for: kind)
+        marker.zIndex = MarkerZIndex.participant
         marker.mapView = mapView
 
-        participantMarkers.append(marker)
+        participantMarkers.append(
+            ParticipantMarker(
+                id: participant.id,
+                coordinate: position,
+                marker: marker,
+                member: ClusterMarkerView.Member(
+                    nickname: participant.nickname,
+                    profileImage: profileImage,
+                    tintColor: color
+                )
+            )
+        )
     }
 
     func clearParticipantOverlays() {
-        participantMarkers.forEach { $0.mapView = nil }
+        participantMarkers.forEach { $0.marker.mapView = nil }
         participantMarkers.removeAll()
+        clusterController.removeAll()
         participantPolylines.forEach { $0.mapView = nil }
         participantPolylines.removeAll()
     }
 
 }
+
+// MARK: - NMFMapViewCameraDelegate
+
+extension AppointmentRouteMapView: NMFMapViewCameraDelegate {
+
+    func mapViewCameraIdle(_ mapView: NMFMapView) {
+        updateClusters()
+    }
+
+}

WhereAreYou/WhereAreYou/Presentation/Map/AppointmentRoute/ClusterMarkerController.swift

@@ -0,0 +1,183 @@
+//
+//  ClusterMarkerController.swift
+//  WhereAreYou
+//
+//  Created by 김성훈 on 10/6/26.
+//
+
+import UIKit
+import NMapsMap
+
+/// 클러스터 마커의 표시, 멤버 순환, 슬라이드 전환 관리
+final class ClusterMarkerController: NSObject {
+
+    /// 지도에 표시된 클러스터 마커 — 멤버 구성이 같으면 재사용
+    private struct ClusterMarker {
+        let memberIDs: [String]
+        let marker: NMFMarker
+        /// 멤버별 정지 이미지 — 전환 프레임의 재료
+        let images: [UIImage]
+        let icons: [NMFOverlayImage]
+        var currentIndex = 0
+    }
+
+    /// 클러스터 대표 멤버가 바뀌는 주기
+    private static let rotationInterval: Duration = .seconds(2)
+    /// 대표 멤버가 바뀌는 슬라이드 전환 시간
+    private static let transitionDuration: CFTimeInterval = 0.35
+
+    private weak var mapView: NMFMapView?
+    private let zIndex: Int
+    private var clusterMarkers: [ClusterMarker] = []
+    private var isActive = false
+    private var rotationTask: Task<Void, Never>?
+    private var transitionLink: CADisplayLink?
+    private var transitionStart: CFTimeInterval = 0
+
+    init(mapView: NMFMapView, zIndex: Int) {
+        self.mapView = mapView
+        self.zIndex = zIndex
+        super.init()
+    }
+
+    // MARK: - Public
+
+    /// 클러스터 목록에 맞춰 마커를 갱신 — 멤버 구성이 같은 클러스터는 기존 마커 재사용
+    func update(clusters: [ParticipantClusterer.Cluster], member: (String) -> ClusterMarkerView.Member?) {
+        var staleMarkers = clusterMarkers
+        clusterMarkers = clusters.map { cluster in
+            if let index = staleMarkers.firstIndex(where: { $0.memberIDs == cluster.memberIDs }) {
+                return staleMarkers.remove(at: index)
+            }
+            return makeClusterMarker(for: cluster, members: cluster.memberIDs.compactMap(member))
+        }
+        staleMarkers.forEach { $0.marker.mapView = nil }
+        updateRotation()
+    }
+
+    /// 화면 표시 여부 — 표시 중일 때만 순환 동작
+    func setActive(_ isActive: Bool) {
+        self.isActive = isActive
+        updateRotation()
+    }
+
+    func removeAll() {
+        clusterMarkers.forEach { $0.marker.mapView = nil }
+        clusterMarkers.removeAll()
+        updateRotation()
+    }
+
+}
+
+// MARK: - Private
+
+private extension ClusterMarkerController {
+
+    private func makeClusterMarker(for cluster: ParticipantClusterer.Cluster, members: [ClusterMarkerView.Member]) -> ClusterMarker {
+        let images = members.indices.map { index in
+            ClusterMarkerView.renderImage(members: members, memberIndex: index)
+        }
+        let icons = images.map { NMFOverlayImage(image: $0) }
+
+        let coordinate = cluster.coordinate
+        let marker = NMFMarker(position: NMGLatLng(lat: coordinate.latitude, lng: coordinate.longitude))
+        if let firstIcon = icons.first {
+            marker.iconImage = firstIcon
+        }
+        marker.width = ClusterMarkerView.size.width
+        marker.height = ClusterMarkerView.size.height
+        marker.anchor = ClusterMarkerView.anchor
+        marker.zIndex = zIndex
+        marker.mapView = mapView
+
+        return ClusterMarker(memberIDs: cluster.memberIDs, marker: marker, images: images, icons: icons)
+    }
+
+    // MARK: - Rotation
+
+    /// 클러스터가 있고 화면에 떠 있을 때만 순환을 돌리고, 아니면 정지
+    func updateRotation() {
+        guard !clusterMarkers.isEmpty, isActive else {
+            cancelTransition()
+            rotationTask?.cancel()
+            rotationTask = nil
+            return
+        }
+        guard rotationTask == nil else { return }
+
+        rotationTask = Task { [weak self] in
+            while !Task.isCancelled {
+                try? await Task.sleep(for: Self.rotationInterval)
+                guard !Task.isCancelled, let self else { return }
+                self.rotateMembers()
+            }
+        }
+    }
+
+    /// 동작 줄이기가 켜져 있으면 바로 교체하고, 아니면 슬라이드 전환
+    func rotateMembers() {
+        if UIAccessibility.isReduceMotionEnabled {
+            showNextMembers()
+        } else {
+            startTransition()
+        }
+    }
+
+    // MARK: - Transition
+
+    func startTransition() {
+        guard transitionLink == nil else { return }
+
+        let link = CADisplayLink(target: self, selector: #selector(updateTransition))
+        link.preferredFrameRateRange = CAFrameRateRange(minimum: 20, maximum: 30, preferred: 30)
+        link.add(to: .main, forMode: .common)
+        transitionLink = link
+        transitionStart = CACurrentMediaTime()
+    }
+
+    @objc func updateTransition() {
+        let elapsed = (CACurrentMediaTime() - transitionStart) / Self.transitionDuration
+        guard elapsed < 1 else {
+            finishTransition()
+            return
+        }
+
+        // 가속 후 감속
+        let progress = elapsed * elapsed * (3 - 2 * elapsed)
+        for clusterMarker in clusterMarkers where clusterMarker.images.count > 1 {
+            let nextIndex = (clusterMarker.currentIndex + 1) % clusterMarker.images.count
+            let frame = ClusterMarkerView.renderTransitionFrame(
+                from: clusterMarker.images[clusterMarker.currentIndex],
+                to: clusterMarker.images[nextIndex],
+                progress: progress
+            )
+            clusterMarker.marker.iconImage = NMFOverlayImage(image: frame)
+        }
+    }
+
+    /// 전환을 끝내고 다음 멤버로 확정
+    func finishTransition() {
+        transitionLink?.invalidate()
+        transitionLink = nil
+        showNextMembers()
+    }
+
+    /// 전환을 중단하고 현재 멤버의 정지 아이콘으로 복원
+    func cancelTransition() {
+        guard let link = transitionLink else { return }
+        link.invalidate()
+        transitionLink = nil
+        for clusterMarker in clusterMarkers where clusterMarker.icons.indices.contains(clusterMarker.currentIndex) {
+            clusterMarker.marker.iconImage = clusterMarker.icons[clusterMarker.currentIndex]
+        }
+    }
+
+    func showNextMembers() {
+        for index in clusterMarkers.indices where clusterMarkers[index].icons.count > 1 {
+            let nextIndex = (clusterMarkers[index].currentIndex + 1) % clusterMarkers[index].icons.count
+            clusterMarkers[index].currentIndex = nextIndex
+            clusterMarkers[index].marker.iconImage = clusterMarkers[index].icons[nextIndex]
+        }
+    }
+
+}