イントロダクション

MapConductor Android SDK ドキュメント

MapConductor は、Google Maps、Mapbox、HERE、ArcGIS、そして MapLibre を含む複数の地図SDKに対して、共通の API を提供する統一地図 SDK です。このドキュメントでは、Maven から配布される v1.1.7 向けの公開 API コンポーネントについて説明します。

概要

MapConductor SDK を使うと、単一の API で複数の地図SDKを扱えるようになります。各地図SDK固有の実装は SDK 側で吸収され、アプリケーションからは一貫したインターフェースで操作できます。

サポートされている地図SDK

Google Maps: GoogleMapViewState / GoogleMapView
Mapbox: MapboxViewState / MapboxMapView
HERE Maps: HereViewState / HereMapView
ArcGIS: ArcGISMapViewState / ArcGISMapView
MapLibre: MapLibreViewState / MapLibreMapView

コアクラス

SDK は、以下のような基本的な地理情報クラスを提供します。

GeoPointInterface: 緯度・経度・高度を表す地理座標
GeoRectBounds: 南西・北東の2点で表される矩形の地理範囲
MapCameraPositionInterface: カメラ位置（ターゲット、ズーム、方位、傾き、パディング）

主なコンポーネント

SDK は次のようなコアコンポーネントを提供します。

マップビューコンポーネント: 地図SDK別のマップビュー（GoogleMapView, MapboxMapView, HereMapView, ArcGISMapView, MapLibreMapView）
Marker: カスタマイズ可能なアイコンやインタラクションを持つポイントマーカー
Circle: スタイル指定可能な円形オーバーレイ
Polyline: 複数点を結ぶ線分
Polygon: 枠線と塗りつぶしを持つ多角形
GroundImage: 地理座標に配置する画像オーバーレイ（Google Maps のみ対応）

はじめに

MapConductor をプロジェクトで利用するには、次のステップに従います。

1. インストール

依存関係やバージョンの詳細は、チュートリアルを参照してください。

2. 各地図 SDK のセットアップ

重要: MapConductor は既存の地図 SDK の上に統一 API レイヤーを提供するライブラリです。そのため、MapConductor を利用する前に、各地図 SDK を個別にセットアップする必要があります。

各地図SDKは、それぞれ API キー、パーミッション、設定などの準備が必要です。

Google Maps のセットアップ – Google Maps SDK の API キーやパーミッションの設定
Mapbox のセットアップ – Mapbox のアクセストークンやスタイル設定
HERE Maps のセットアップ – HERE SDK の API キーやライセンス設定
ArcGIS のセットアップ – ArcGIS SDK の API キーやライセンス設定
MapLibre のセットアップ – タイルやスタイル情報の設定

利用する地図 SDK だけをセットアップすればかまいません。

3. 基本的な使い方

マップビューを作成し、マーカーと円を表示する例です。

@Composable
fun BasicMapExample(modifier: Modifier = Modifier) {
    val sanFrancisco = GeoPoint.fromLatLong(37.7749, -122.4194)
    val camera = MapCameraPosition(
        position = sanFrancisco,
        zoom = 13.0,
    )
    // 利用する地図 SDK に置き換えてください
// - Google Maps -> rememberGoogleMapViewState
// - Mapbox -> rememberMapboxViewState
// ... など
    val mapViewState = rememberGoogleMapViewState(
        cameraPosition = camera,
    )

    // MapView も利用する地図SDKに応じて切り替えます
// - Google Maps -> GoogleMapView
// - Mapbox -> MapboxMapView
// ... など
    GoogleMapView(
        modifier = modifier,
        state = mapViewState,
        onMapClick = { geoPoint ->
            println("Map clicked at: ${geoPoint.latitude}, ${geoPoint.longitude}")
        }
    ) {
        // マーカーを追加
        Marker(
            position = sanFrancisco,
            icon = ColorDefaultIcon(label = "SF"),
            extra = "San Francisco marker",
            onClick = { markerState ->
                println("Marker clicked: ${markerState.extra}")
            }
        )

        // 円を追加
        Circle(
            center = sanFrancisco,
            radiusMeters = 1000.0,
            strokeColor = Color.Blue,
            fillColor = Color.Blue.copy(alpha = 0.3f)
        )
    }
}

マーカーと円が描画された地図

4. マップ地図SDKの切り替え

マップ地図SDKを切り替えるには、MapViewStateInterface の実装を変更するだけです。

// Google Maps
val googleMapState = rememberGoogleMapViewState()

// Mapbox
val mapboxState = rememberMapboxMapViewState()

// HERE Maps
val hereState = rememberHereMapViewState()

// ArcGIS
val arcgisState = rememberArcGISMapViewState()

// MapLibre
val mapLibreState = rememberMapLibreMapViewState()

その他のコードは共通で、すべてのコンポーネントを地図SDK間で同じように扱えます。

v1.1.7 での主な変更点

v1.1.0 と比較した v1.1.7 の主な改善点は次のとおりです。

地図の表示範囲を移動させたときにInfoBubbleの表示位置が再計算されないバグを修正

v1.1.0 での主な変更点

v1.0.0 と比較した v1.1.0 の主な改善点は次のとおりです。

各地図SDKでカメラ移動イベント (onCameraMoveStart, onCameraMove, onCameraMoveEnd) を統一
MapViewStateInterface のカメラ位置と VisibleRegion 連携の改善
マーカーコントローラのインターフェースを整理し、地図SDK実装を明確化
例示アプリに高度なカメラ制御と VisibleRegion の利用例を追加