diff --git a/Sources/MapConductorCore/map/CameraPaddingEmulation.swift b/Sources/MapConductorCore/map/CameraPaddingEmulation.swift new file mode 100644 index 0000000..86e27df --- /dev/null +++ b/Sources/MapConductorCore/map/CameraPaddingEmulation.swift @@ -0,0 +1,181 @@ +import CoreGraphics +import Foundation + +/// ネイティブにパディングを持たない地図 SDK 向けの、`MapCameraPosition.paddings` の再現。 +/// +/// パディングの意味は「画面の端をその分だけ空け、残りの領域の中央にカメラのターゲットを置く」。 +/// ネイティブに無い SDK では、ターゲットが空けた残りの中央に来るよう、**カメラの中心をずらして** +/// 渡す(``cameraCenter(for:fov:viewportSize:)``)。読み戻しでは逆にずらしてターゲットへ戻す +/// (``target(forCameraCenter:camera:paddings:fov:viewportSize:)``)。 +/// +/// ずらす量は、画面の中心からターゲットまでの画面上のずれ +/// `dx = (left − right) / 2`、`dy = (top − bottom) / 2`(pt)を、地表の距離へ換算したもの。 +/// +/// - 遠近あり(`fov > 0`): 焦点距離 `f = (H / 2) / tan(fov / 2)`、カメラから画面中心の地点までの +/// 距離 `D = f · mpp`(mpp は画面中心での 1pt あたりのメートル)。ターゲットへの視線が +/// 光軸から下へ `α = atan(dy / f)` 傾くので、手前への距離は `D·sin t − D·cos t·tan(t − α)`。 +/// 横は、ターゲットの光軸方向の奥行き `z` を使って `dx · z / f`。 +/// - 遠近なし(`fov == 0`。ビューを傾けて擬似的に tilt を表す SDK): 手前へ `dy · mpp / cos t`、横へ +/// `dx · mpp`。 +/// - 視野角が分からない(`fov == nil`)か tilt が 0: tilt 0 と同じ `dy · mpp`、`dx · mpp`。 +/// +/// 視野角はプロバイダが持つ値を渡す。**コアは既定の視野角を持たない。** +@_spi(MapConductorDriver) +public enum CameraPaddingEmulation { + /// ターゲットをパディングの残りの中央に見せるために、カメラの中心として渡す地点。 + /// + /// パディングが無い(または全て 0)ならターゲットをそのまま返す。 + public static func cameraCenter( + for camera: MapCameraPositionProtocol, + fov: Double?, + viewportSize: CGSize + ) -> GeoPoint { + let target = GeoPoint.from(position: camera.position) + guard let offset = groundOffset(camera: camera, paddings: camera.paddings, fov: fov, viewportSize: viewportSize) else { + return target + } + let heading = CameraBearing.toNativeHeading(camera.bearing) + // ターゲットが画面中心より下(手前)・右に見えるよう、中心は奥・左へ置く。 + let forward = Spherical.computeOffset(origin: target, distance: offset.backward, heading: heading) + let center = Spherical.computeOffset(origin: forward, distance: offset.lateral, heading: heading - 90.0) + return GeoPoint(latitude: center.latitude, longitude: center.longitude, altitude: target.altitude ?? 0) + } + + /// ``cameraCenter(for:fov:viewportSize:)`` の逆。読み戻したカメラの中心からターゲットを求める。 + /// + /// `camera` からは zoom / tilt / bearing だけを使う。 + public static func target( + forCameraCenter center: GeoPointProtocol, + camera: MapCameraPositionProtocol, + paddings: MapPaddingsProtocol?, + fov: Double?, + viewportSize: CGSize + ) -> GeoPoint { + let origin = GeoPoint.from(position: center) + guard let offset = groundOffset(camera: camera, paddings: paddings, fov: fov, viewportSize: viewportSize) else { + return origin + } + let heading = CameraBearing.toNativeHeading(camera.bearing) + let back = Spherical.computeOffset(origin: origin, distance: offset.backward, heading: heading + 180.0) + let target = Spherical.computeOffset(origin: back, distance: offset.lateral, heading: heading + 90.0) + return GeoPoint(latitude: target.latitude, longitude: target.longitude, altitude: origin.altitude ?? 0) + } + + /// 地図 SDK へ渡すカメラ。`position` をずらした中心に、`paddings` を 0 にしたもの。 + /// + /// 移動の入り口で一度だけ通す。アニメーションの補間は、この「中心」の空間で行う。 + public static func applied( + to camera: MapCameraPosition, + fov: Double?, + viewportSize: CGSize + ) -> MapCameraPosition { + guard groundOffset(camera: camera, paddings: camera.paddings, fov: fov, viewportSize: viewportSize) != nil else { + return camera + } + return camera.copy( + position: cameraCenter(for: camera, fov: fov, viewportSize: viewportSize), + paddings: MapPaddings.Zeros + ) + } + + /// 地図 SDK から読み戻したカメラ(`position` は画面中心)を、ターゲットと `paddings`・`fov` を + /// 持つカメラへ戻す。``applied(to:fov:viewportSize:)`` の逆。 + /// + /// `unproject`(画面座標 → 地理座標)を渡すと、パディングの残りの中央にある地点を地図に直接 + /// 聞いてターゲットにする。地図 SDK の縮尺や傾きの扱いが計算とずれていても正確になる。 + public static func restored( + _ camera: MapCameraPosition, + paddings: MapPaddingsProtocol?, + fov: Double?, + viewportSize: CGSize, + unproject: ((CGPoint) -> GeoPoint?)? = nil + ) -> MapCameraPosition { + let target = paddedCenterPoint(paddings: paddings, viewportSize: viewportSize) + .flatMap { point in unproject?(point) } + ?? self.target( + forCameraCenter: camera.position, + camera: camera, + paddings: paddings, + fov: fov, + viewportSize: viewportSize + ) + return MapCameraPosition( + position: GeoPoint( + latitude: target.latitude, + longitude: target.longitude, + altitude: camera.position.altitude ?? 0 + ), + zoom: camera.zoom, + bearing: camera.bearing, + tilt: camera.tilt, + paddings: paddings ?? MapPaddings.Zeros, + visibleRegion: camera.visibleRegion, + fov: fov + ) + } + + /// パディングを除いた領域の中央(画面座標)。パディングが無ければ nil。 + public static func paddedCenterPoint(paddings: MapPaddingsProtocol?, viewportSize: CGSize) -> CGPoint? { + guard let paddings, viewportSize.width > 0, viewportSize.height > 0 else { return nil } + let dx = (paddings.left - paddings.right) / 2.0 + let dy = (paddings.top - paddings.bottom) / 2.0 + if dx == 0, dy == 0 { return nil } + return CGPoint(x: viewportSize.width / 2.0 + dx, y: viewportSize.height / 2.0 + dy) + } + + /// 動かした後の地図で、ターゲットがパディングの残りの中央からずれていれば、ずれを打ち消す + /// カメラの中心を返す(ずれが 0.5pt 未満なら nil)。 + /// + /// 計算で置いた中心は、地図 SDK の縮尺・傾きの上限・視野角が計算と違うとずれる。地図の + /// 投影(`project` / `unproject`)で実際の位置を測って詰める。数回繰り返すと収束する。 + public static func correctedCenter( + target: GeoPointProtocol, + paddings: MapPaddingsProtocol?, + viewportSize: CGSize, + project: (GeoPointProtocol) -> CGPoint?, + unproject: (CGPoint) -> GeoPoint? + ) -> GeoPoint? { + guard let desired = paddedCenterPoint(paddings: paddings, viewportSize: viewportSize), + let actual = project(target) else { return nil } + let deltaX = actual.x - desired.x + let deltaY = actual.y - desired.y + guard abs(deltaX) >= 0.5 || abs(deltaY) >= 0.5 else { return nil } + return unproject(CGPoint(x: viewportSize.width / 2.0 + deltaX, y: viewportSize.height / 2.0 + deltaY)) + } + + /// 画面中心からターゲットまでの地表の距離(メートル)。手前が正の `backward`、右が正の `lateral`。 + static func groundOffset( + camera: MapCameraPositionProtocol, + paddings: MapPaddingsProtocol?, + fov: Double?, + viewportSize: CGSize + ) -> (backward: Double, lateral: Double)? { + guard let paddings else { return nil } + let dx = (paddings.left - paddings.right) / 2.0 + let dy = (paddings.top - paddings.bottom) / 2.0 + if dx == 0, dy == 0 { return nil } + + let latitude = min(max(camera.position.latitude, -85.0), 85.0) + let mpp = WebMercatorZoomAltitudeConverter.webMercatorInitialMpp256 + * cos(latitude * .pi / 180.0) / pow(2.0, camera.zoom) + let tilt = min(max(camera.tilt, 0.0), 89.0) * .pi / 180.0 + let height = Double(viewportSize.height) + + guard tilt > 0, let fov else { + return (dy * mpp, dx * mpp) + } + if fov <= 0 { + return (dy * mpp / cos(tilt), dx * mpp) + } + guard height > 0 else { return (dy * mpp, dx * mpp) } + + let focal = (height / 2.0) / tan(fov * .pi / 360.0) + let distance = focal * mpp + let alpha = atan(dy / focal) + // 視線が地平線より上を向くと地表に当たらない。手前すれすれで止める。 + let fromVertical = min(tilt - alpha, 89.0 * .pi / 180.0) + let backward = distance * sin(tilt) - distance * cos(tilt) * tan(fromVertical) + let depth = distance * cos(tilt) / cos(fromVertical) * cos(alpha) + return (backward, dx * depth / focal) + } +} diff --git a/Sources/MapConductorCore/map/MapCameraPositionBase.swift b/Sources/MapConductorCore/map/MapCameraPositionBase.swift index 23ee4c4..c185278 100644 --- a/Sources/MapConductorCore/map/MapCameraPositionBase.swift +++ b/Sources/MapConductorCore/map/MapCameraPositionBase.swift @@ -50,6 +50,16 @@ public protocol MapCameraPositionProtocol { var tilt: Double { get } var paddings: MapPaddingsProtocol? { get } var visibleRegion: VisibleRegion? { get } + /// 描画しているカメラの**縦**の視野角(度)。 + /// + /// 地図 SDK ごとに違うので、カメラを読み戻すときにプロバイダが入れる。 + /// `0` は「tilt を遠近なしで描いている」(ビューを傾けて擬似的に表現している)、 + /// `nil` は「分からない/傾けられない」。カメラを動かすときには使わない。 + var fov: Double? { get } +} + +public extension MapCameraPositionProtocol { + var fov: Double? { nil } } public final class MapCameraPosition: MapCameraPositionProtocol { @@ -62,6 +72,11 @@ public final class MapCameraPosition: MapCameraPositionProtocol { public let tilt: Double public let paddings: MapPaddingsProtocol? public let visibleRegion: VisibleRegion? + /// 描画しているカメラの縦の視野角(度)。``MapCameraPositionProtocol/fov`` を参照。 + /// + /// ``visibleRegion`` と同じく読み戻し専用の値で、カメラを動かすときは無視される。 + /// ``equals(other:)`` の比較にも入れない。 + public let fov: Double? private let positionValue: GeoPoint /// `zoom` / `bearing` / `tilt` が明示されたか。 @@ -79,7 +94,8 @@ public final class MapCameraPosition: MapCameraPositionProtocol { bearing: Double? = nil, tilt: Double? = nil, paddings: MapPaddingsProtocol? = MapPaddings.Zeros, - visibleRegion: VisibleRegion? = nil + visibleRegion: VisibleRegion? = nil, + fov: Double? = nil ) { self.positionValue = GeoPoint.from(position: position) self.zoom = zoom ?? 0.0 @@ -90,6 +106,7 @@ public final class MapCameraPosition: MapCameraPositionProtocol { self.isTiltSpecified = tilt != nil self.paddings = paddings self.visibleRegion = visibleRegion + self.fov = fov } /// 未指定の `zoom` / `bearing` / `tilt` を `current` の値で埋めたカメラを返す。 @@ -105,7 +122,8 @@ public final class MapCameraPosition: MapCameraPositionProtocol { bearing: isBearingSpecified ? bearing : current.bearing, tilt: isTiltSpecified ? tilt : current.tilt, paddings: paddings, - visibleRegion: visibleRegion + visibleRegion: visibleRegion, + fov: fov ) } @@ -122,7 +140,8 @@ public final class MapCameraPosition: MapCameraPositionProtocol { bearing: Double? = nil, tilt: Double? = nil, paddings: MapPaddingsProtocol? = nil, - visibleRegion: VisibleRegion? = nil + visibleRegion: VisibleRegion? = nil, + fov: Double? = nil ) -> MapCameraPosition { // 渡されなかったプロパティは、未指定だったならコピー後も未指定のまま。 MapCameraPosition( @@ -131,7 +150,8 @@ public final class MapCameraPosition: MapCameraPositionProtocol { bearing: bearing ?? (isBearingSpecified ? self.bearing : nil), tilt: tilt ?? (isTiltSpecified ? self.tilt : nil), paddings: paddings ?? self.paddings, - visibleRegion: visibleRegion ?? self.visibleRegion + visibleRegion: visibleRegion ?? self.visibleRegion, + fov: fov ?? self.fov ) } diff --git a/Tests/MapConductorCoreTests/CameraPaddingEmulationTests.swift b/Tests/MapConductorCoreTests/CameraPaddingEmulationTests.swift new file mode 100644 index 0000000..05b2d26 --- /dev/null +++ b/Tests/MapConductorCoreTests/CameraPaddingEmulationTests.swift @@ -0,0 +1,147 @@ +import CoreGraphics +import XCTest + +@_spi(MapConductorDriver) @testable import MapConductorCore + +/// パディングの再現で、ターゲットが空けた残りの中央に見えることを、ピンホールカメラで投影し直して確かめる。 +final class CameraPaddingEmulationTests: XCTestCase { + private let tokyo = GeoPoint(latitude: 35.6812, longitude: 139.7671) + private let viewport = CGSize(width: 1194, height: 834) + + private func camera( + tilt: Double, + bearing: Double = 0, + paddings: MapPaddings + ) -> MapCameraPosition { + MapCameraPosition(position: tokyo, zoom: 15, bearing: bearing, tilt: tilt, paddings: paddings) + } + + private func mpp(_ camera: MapCameraPosition) -> Double { + WebMercatorZoomAltitudeConverter.webMercatorInitialMpp256 + * cos(camera.position.latitude * .pi / 180) / pow(2, camera.zoom) + } + + /// カメラの中心 `center` から見た `point` の画面上のずれ(中心からの pt、右と下が正)。 + private func project( + _ point: GeoPoint, + center: GeoPoint, + camera: MapCameraPosition, + fov: Double + ) -> CGPoint { + let heading = CameraBearing.toNativeHeading(camera.bearing) + let distance = Spherical.computeDistanceBetween(from: center, to: point) + let angle = (Spherical.computeHeading(from: center, to: point) - heading) * .pi / 180 + let forward = distance * cos(angle) + let right = distance * sin(angle) + let tilt = camera.tilt * .pi / 180 + let focal = (viewport.height / 2) / tan(fov * .pi / 360) + let range = focal * mpp(camera) + let depth = (forward + range * sin(tilt)) * sin(tilt) + range * cos(tilt) * cos(tilt) + return CGPoint(x: focal * right / depth, y: -focal * forward * cos(tilt) / depth) + } + + func testNoPaddingsKeepsTarget() { + let cam = camera(tilt: 60, paddings: MapPaddings.Zeros) + let center = CameraPaddingEmulation.cameraCenter(for: cam, fov: 36.87, viewportSize: viewport) + XCTAssertEqual(center.latitude, tokyo.latitude, accuracy: 1e-12) + XCTAssertEqual(center.longitude, tokyo.longitude, accuracy: 1e-12) + } + + func testTiltZeroMovesCenterByHalfThePadding() { + let cam = camera(tilt: 0, paddings: MapPaddings(top: 300)) + let center = CameraPaddingEmulation.cameraCenter(for: cam, fov: 36.87, viewportSize: viewport) + XCTAssertEqual(Spherical.computeDistanceBetween(from: tokyo, to: center), 150 * mpp(cam), accuracy: 0.05) + XCTAssertGreaterThan(center.latitude, tokyo.latitude) + } + + func testPerspectiveTargetLandsAtPaddedCenter() { + for (tilt, bearing) in [(30.0, 0.0), (60.0, 0.0), (60.0, 135.0), (45.0, -70.0)] { + let paddings = MapPaddings(top: 300, left: 40, bottom: 0, right: 0) + let cam = camera(tilt: tilt, bearing: bearing, paddings: paddings) + let center = CameraPaddingEmulation.cameraCenter(for: cam, fov: 36.87, viewportSize: viewport) + let offset = project(tokyo, center: center, camera: cam, fov: 36.87) + XCTAssertEqual(offset.x, 20, accuracy: 0.5, "tilt \(tilt) bearing \(bearing)") + XCTAssertEqual(offset.y, 150, accuracy: 0.5, "tilt \(tilt) bearing \(bearing)") + } + } + + func testOrthographicStretchesByCosTilt() { + let cam = camera(tilt: 60, paddings: MapPaddings(top: 300)) + let center = CameraPaddingEmulation.cameraCenter(for: cam, fov: 0, viewportSize: viewport) + XCTAssertEqual(Spherical.computeDistanceBetween(from: tokyo, to: center), 150 * mpp(cam) / cos(.pi / 3), accuracy: 0.05) + } + + func testUnknownFovFallsBackToTiltZero() { + let cam = camera(tilt: 60, paddings: MapPaddings(top: 300)) + let center = CameraPaddingEmulation.cameraCenter(for: cam, fov: nil, viewportSize: viewport) + XCTAssertEqual(Spherical.computeDistanceBetween(from: tokyo, to: center), 150 * mpp(cam), accuracy: 0.05) + } + + func testRoundTrip() { + for fov in [nil, 0.0, 30.0, 36.87] as [Double?] { + let paddings = MapPaddings(top: 250, left: 10, bottom: 30, right: 90) + let cam = camera(tilt: 55, bearing: 200, paddings: paddings) + let center = CameraPaddingEmulation.cameraCenter(for: cam, fov: fov, viewportSize: viewport) + let back = CameraPaddingEmulation.target( + forCameraCenter: center, + camera: cam, + paddings: paddings, + fov: fov, + viewportSize: viewport + ) + XCTAssertEqual(back.latitude, tokyo.latitude, accuracy: 1e-7) + XCTAssertEqual(back.longitude, tokyo.longitude, accuracy: 1e-7) + } + } + + func testFovIsCarriedByCopyButNotCompared() { + let cam = MapCameraPosition(position: tokyo, zoom: 10, fov: 36.87) + XCTAssertEqual(cam.copy(zoom: 11).fov, 36.87) + XCTAssertTrue(cam.equals(other: MapCameraPosition(position: tokyo, zoom: 10))) + XCTAssertNil(MapCameraPosition(position: tokyo).fov) + } + + func testAppliedAndRestoredRoundTrip() { + let paddings = MapPaddings(top: 300) + let cam = camera(tilt: 60, bearing: 45, paddings: paddings) + let sent = CameraPaddingEmulation.applied(to: cam, fov: 36.87, viewportSize: viewport) + XCTAssertEqual(sent.paddings?.top, 0) + let back = CameraPaddingEmulation.restored(sent, paddings: paddings, fov: 36.87, viewportSize: viewport) + // 読み戻しは中心の緯度で縮尺を取るので、往復は 1 m 程度の誤差を許す。 + XCTAssertLessThan(Spherical.computeDistanceBetween(from: GeoPoint.from(position: back.position), to: tokyo), 1.0) + XCTAssertEqual(back.paddings?.top, 300) + XCTAssertEqual(back.fov, 36.87) + } + + /// 地図の縮尺が計算より 7% 大きくても、投影で測って詰めればターゲットがパディングの残りの中央に来る。 + func testCorrectedCenterConvergesWithAMisScaledMap() { + let paddings = MapPaddings(top: 300) + let cam = camera(tilt: 0, paddings: paddings) + let pointsPerMeter = 1.07 / mpp(cam) + var center = CameraPaddingEmulation.cameraCenter(for: cam, fov: 0, viewportSize: viewport) + func project(_ point: GeoPointProtocol) -> CGPoint? { + let distance = Spherical.computeDistanceBetween(from: center, to: GeoPoint.from(position: point)) + let angle = Spherical.computeHeading(from: center, to: GeoPoint.from(position: point)) * .pi / 180 + return CGPoint( + x: viewport.width / 2 + distance * sin(angle) * pointsPerMeter, + y: viewport.height / 2 - distance * cos(angle) * pointsPerMeter + ) + } + func unproject(_ point: CGPoint) -> GeoPoint? { + let dx = (Double(point.x) - viewport.width / 2) / pointsPerMeter + let dy = (viewport.height / 2 - Double(point.y)) / pointsPerMeter + let north = Spherical.computeOffset(origin: center, distance: dy, heading: 0) + return Spherical.computeOffset(origin: north, distance: dx, heading: 90) + } + for _ in 0..<3 { + guard let next = CameraPaddingEmulation.correctedCenter( + target: tokyo, paddings: paddings, viewportSize: viewport, + project: project, unproject: unproject + ) else { break } + center = next + } + let landed = project(tokyo)! + XCTAssertEqual(landed.y, viewport.height / 2 + 150, accuracy: 0.5) + XCTAssertEqual(landed.x, viewport.width / 2, accuracy: 0.5) + } +} diff --git a/api/MapConductorCore.api.swift b/api/MapConductorCore.api.swift index b584c55..1f1feec 100644 --- a/api/MapConductorCore.api.swift +++ b/api/MapConductorCore.api.swift @@ -1213,6 +1213,12 @@ public protocol MapCameraPositionProtocol { var tilt: Swift::Double { get } var paddings: (any MapConductorCore::MapPaddingsProtocol)? { get } var visibleRegion: MapConductorCore::VisibleRegion? { get } + var fov: Swift::Double? { get } +} +extension MapConductorCore::MapCameraPositionProtocol { + public var fov: Swift::Double? { + get + } } final public class MapCameraPosition : MapConductorCore::MapCameraPositionProtocol { final public var position: any MapConductorCore::GeoPointProtocol { @@ -1223,13 +1229,14 @@ final public class MapCameraPosition : MapConductorCore::MapCameraPositionProtoc final public let tilt: Swift::Double final public let paddings: (any MapConductorCore::MapPaddingsProtocol)? final public let visibleRegion: MapConductorCore::VisibleRegion? + final public let fov: Swift::Double? final public let isZoomSpecified: Swift::Bool final public let isBearingSpecified: Swift::Bool final public let isTiltSpecified: Swift::Bool - public init(position: any MapConductorCore::GeoPointProtocol, zoom: Swift::Double? = nil, bearing: Swift::Double? = nil, tilt: Swift::Double? = nil, paddings: (any MapConductorCore::MapPaddingsProtocol)? = MapPaddings.Zeros, visibleRegion: MapConductorCore::VisibleRegion? = nil) + public init(position: any MapConductorCore::GeoPointProtocol, zoom: Swift::Double? = nil, bearing: Swift::Double? = nil, tilt: Swift::Double? = nil, paddings: (any MapConductorCore::MapPaddingsProtocol)? = MapPaddings.Zeros, visibleRegion: MapConductorCore::VisibleRegion? = nil, fov: Swift::Double? = nil) final public func resolved(onto current: any MapConductorCore::MapCameraPositionProtocol) -> MapConductorCore::MapCameraPosition final public func equals(other: any MapConductorCore::MapCameraPositionProtocol) -> Swift::Bool - final public func copy(position: (any MapConductorCore::GeoPointProtocol)? = nil, zoom: Swift::Double? = nil, bearing: Swift::Double? = nil, tilt: Swift::Double? = nil, paddings: (any MapConductorCore::MapPaddingsProtocol)? = nil, visibleRegion: MapConductorCore::VisibleRegion? = nil) -> MapConductorCore::MapCameraPosition + final public func copy(position: (any MapConductorCore::GeoPointProtocol)? = nil, zoom: Swift::Double? = nil, bearing: Swift::Double? = nil, tilt: Swift::Double? = nil, paddings: (any MapConductorCore::MapPaddingsProtocol)? = nil, visibleRegion: MapConductorCore::VisibleRegion? = nil, fov: Swift::Double? = nil) -> MapConductorCore::MapCameraPosition final public func hashCode() -> Swift::Int public static let Default: MapConductorCore::MapCameraPosition @objc deinit