Mapbox Android：如何渲染本地设备中ZIP格式的Shapefile为矢量图层？

问题描述 #

刚接触Android移动开发，正在开发一款离线GIS应用，目前遇到的核心问题是：无法将设备本地存储的ZIP格式Shapefile渲染为矢量图层。

已尝试方案 #

• 曾通过Mapbox Studio将Shapefile导入自定义地图样式，使用样式URL在应用中可正常渲染，但该方式依赖在线资源，不符合离线需求。
• 考虑到运行时生成Mapbox矢量瓦片难度较高，尝试将Shapefile转换为GeoJSON后作为Symbol Layer添加到地图中，但尚未成功。

当前代码（MainActivity.kt） #

import android.annotation.SuppressLint
import android.os.Bundle
import android.widget.Toast
import androidx.activity.ComponentActivity
import com.example.kmtsaplingmap.utils.LocationPermissionHelper
import com.mapbox.android.gestures.MoveGestureDetector
import com.mapbox.maps.CameraOptions
import com.mapbox.maps.ImageHolder
import com.mapbox.maps.MapView
import com.mapbox.maps.Style
import com.mapbox.maps.extension.style.expressions.dsl.generated.interpolate
import com.mapbox.maps.extension.style.sources.generated.vectorSource
import com.mapbox.maps.extension.style.style
import com.mapbox.maps.plugin.LocationPuck2D
import com.mapbox.maps.plugin.PuckBearing
import com.mapbox.maps.plugin.gestures.OnMoveListener
import com.mapbox.maps.plugin.gestures.gestures
import com.mapbox.maps.plugin.locationcomponent.OnIndicatorBearingChangedListener
import com.mapbox.maps.plugin.locationcomponent.OnIndicatorPositionChangedListener
import com.mapbox.maps.plugin.locationcomponent.location
import java.lang.ref.WeakReference

class MainActivity : ComponentActivity() {
    private lateinit var mapView: MapView
    private lateinit var locationPermissionHelper: LocationPermissionHelper
    private val onIndicatorBearingChangedListener = OnIndicatorBearingChangedListener {
        mapView.mapboxMap.setCamera(CameraOptions.Builder().bearing(it).build())
    }
    private val onIndicatorPositionChangedListener = OnIndicatorPositionChangedListener {
        mapView.mapboxMap.setCamera(CameraOptions.Builder().center(it).build())
        mapView.gestures.focalPoint = mapView.mapboxMap.pixelForCoordinate(it)
    }
    private val onMoveListener = object : OnMoveListener {
        override fun onMoveBegin(detector: MoveGestureDetector) {
            onCameraTrackingDismissed()
        }
        override fun onMove(detector: MoveGestureDetector): Boolean {
            return false
        }
        override fun onMoveEnd(detector: MoveGestureDetector) {}
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // 以编程方式创建地图并设置初始相机
        mapView = MapView(this)

        // 将地图视图添加到Activity中（也可作为子视图添加到其他视图）
        setContentView(mapView)

        // 处理访问用户位置的权限
        locationPermissionHelper = LocationPermissionHelper(WeakReference(this))
        locationPermissionHelper.checkPermissions {
            onMapReady()
        }
    }

    private fun onMapReady() {
        mapView.mapboxMap.setCamera(
            CameraOptions.Builder()
                .zoom(14.0)
                .build()
        )

        mapView.mapboxMap.loadStyle(
            // 使用包含Shapefile数据集的Mapbox Studio样式URL时可渲染矢量图层
            style(style = Style.OUTDOORS) {
                // TODO: 渲染本地保存的Shapefile
                +vectorSource("local shapefile") {
                    url("asset://test.zip")
                }
            }
        ) { style ->
            initLocationComponent()
            setupGesturesListener()
        }
    }

    private fun setupGesturesListener() {
        mapView.gestures.addOnMoveListener(onMoveListener)
    }

    @SuppressLint("IncorrectNumberOfArgumentsInExpression")
    private fun initLocationComponent() {
        val locationComponentPlugin = mapView.location
        locationComponentPlugin.updateSettings {
            puckBearing = PuckBearing.HEADING
            puckBearingEnabled = true
            enabled = true
            locationPuck = LocationPuck2D(
                bearingImage = ImageHolder.from(R.drawable.mapbox_user_puck_icon),
                shadowImage = ImageHolder.from(R.drawable.mapbox_user_icon_shadow),
                scaleExpression = interpolate {
                    linear()
                    zoom()
                    stop {
                        literal(0.0)
                        literal(0.6)
                    }
                    stop {
                        literal(20.0)
                        literal(1.0)
                    }
                }.toJson()
            )
        }
        locationComponentPlugin.addOnIndicatorPositionChangedListener(onIndicatorPositionChangedListener)
        locationComponentPlugin.addOnIndicatorBearingChangedListener(onIndicatorBearingChangedListener)
    }

    private fun onCameraTrackingDismissed() {
        Toast.makeText(this, "onCameraTrackingDismissed", Toast.LENGTH_SHORT).show()
        mapView.location
            .removeOnIndicatorPositionChangedListener(onIndicatorPositionChangedListener)
        mapView.location
            .removeOnIndicatorBearingChangedListener(onIndicatorBearingChangedListener)
        mapView.gestures.removeOnMoveListener(onMoveListener)
    }

    override fun onDestroy() {
        super.onDestroy()
        mapView.location
            .removeOnIndicatorBearingChangedListener(onIndicatorBearingChangedListener)
        mapView.location
            .removeOnIndicatorPositionChangedListener(onIndicatorPositionChangedListener)
        mapView.gestures.removeOnMoveListener(onMoveListener)
    }
}

解决方案 #

1. 处理Shapefile到GeoJSON的转换 #

离线场景下分两种情况处理：

预处理转换（推荐）

用QGIS、GDAL等工具将ZIP中的Shapefile转换为GeoJSON，确保坐标系为WGS84（EPSG:4326），然后将GeoJSON文件放到assets目录下。

运行时转换（动态读取）

如果需要在App内动态解析ZIP中的Shapefile，添加以下依赖到Module的build.gradle：

implementation 'org.locationtech.jts:jts-core:1.18.2'
implementation 'com.github.jillesvangurp:geojson-jackson:1.1.0'
implementation 'org.geotools:gt-shapefile:28.2'
// 注意：GeoTools库较大，Android环境下需配置ProGuard规则裁剪无用代码

然后添加解析逻辑：

private fun parseShapefileFromAssets(): String? {
    return try {
        assets.open("test.zip").use { zipInput ->
            ZipInputStream(zipInput).use { zis ->
                var entry: ZipEntry? = zis.nextEntry
                var shpStream: InputStream? = null
                var dbfStream: InputStream? = null
                // 同时读取.shp和.dbf文件（Shapefile核心依赖文件）
                while (entry != null) {
                    when {
                        entry.name.endsWith(".shp") -> shpStream = zis.readBytes().inputStream()
                        entry.name.endsWith(".dbf") -> dbfStream = zis.readBytes().inputStream()
                    }
                    zis.closeEntry()
                    entry = zis.nextEntry
                }
                if (shpStream != null && dbfStream != null) {
                    val reader = ShapefileReader(shpStream, dbfStream, Charset.forName("UTF-8"))
                    val features = reader.features.map { feature ->
                        Feature.fromGeometry(
                            Geometry.fromJts(feature.defaultGeometry),
                            feature.attributes.mapKeys { it.key.toString() }
                        )
                    }
                    FeatureCollection.fromFeatures(features).toJson()
                } else null
            }
        }
    } catch (e: Exception) {
        e.printStackTrace()
        null
    }
}

2. 在Mapbox中加载GeoJSON并渲染 #

修改onMapReady方法中的样式加载逻辑，添加GeoJSON源和对应的图层：

private fun onMapReady() {
    mapView.mapboxMap.setCamera(
        CameraOptions.Builder()
            .zoom(14.0)
            .build()
    )

    mapView.mapboxMap.loadStyle(style(Style.OUTDOORS)) { loadedStyle ->
        val geoJsonData = parseShapefileFromAssets() ?: run {
            Toast.makeText(this, "解析Shapefile失败", Toast.LENGTH_SHORT).show()
            return@loadStyle
        }
        // 添加GeoJSON源
        loadedStyle.addSource(
            geoJsonSource("local-shapefile-source") {
                data(geoJsonData)
            }
        )
        // 添加面图层（根据Shapefile类型替换为LineLayer/SymbolLayer）
        loadedStyle.addLayer(
            fillLayer("local-fill-layer", "local-shapefile-source") {
                fillColor("#2ECC71")
                fillOpacity(0.6)
                fillOutlineColor("#27AE60")
            }
        )
        initLocationComponent()
        setupGesturesListener()
    }
}

3. 大文件优化方案 #

如果Shapefile数据量较大，GeoJSON会导致性能问题，建议提前将Shapefile转换为Mapbox矢量瓦片（.mbtiles），然后用以下方式加载：

loadedStyle.addSource(
    vectorSource("local-mbtiles-source") {
        url("asset://test.mbtiles")
    }
)
loadedStyle.addLayer(
    fillLayer("mbtiles-fill-layer", "local-mbtiles-source") {
        sourceLayer("your-layer-name") // mbtiles中对应的图层名
        fillColor("#3498DB")
        fillOpacity(0.5)
    }
)

4. 权限注意事项 #

如果读取的是外部存储的ZIP文件，需申请对应权限：

• Android 12及以下：READ_EXTERNAL_STORAGE
• Android 13及以上：READ_MEDIA_IMAGES/READ_MEDIA_FILES（根据文件位置选择）

内容的提问来源于stack exchange，提问作者Gery