Overlay Ubin

Overlay ubin, kadang-kadang disebut lapisan ubin, adalah kumpulan gambar yang ditampilkan di atas ubin peta dasar.

Contoh Kode

Repositori ApiDemos pada GitHub mencakup contoh yang menunjukkan fitur overlay ubin:

Pengantar

TileOverlay menentukan sekumpulan gambar yang ditambahkan di atas ubin peta dasar.

Anda harus menyediakan ubin untuk setiap tingkat zoom yang ingin didukung. Jika memiliki ubin yang cukup pada beberapa tingkat zoom, Anda dapat menambahkan data peta Google untuk keseluruhan peta.

Overlay ubin berguna jika Anda ingin menambahkan citra yang besar ke peta, yang biasanya mencakup area geografis yang luas. Sebaliknya, overlay bumi berguna jika Anda ingin menetapkan satu gambar pada satu area di peta.

Anda juga dapat menggunakan overlay ubin transparan untuk menambahkan fitur tambahan ke peta, dengan menetapkan faktor transparansi pada overlay ubin secara terprogram atau dengan memberikan gambar ubin transparan.

Koordinat ubin dan tingkat zoom

Google Maps API membagi citra pada setiap tingkat zoom menjadi satu kumpulan ubin peta bujur sangkar yang disusun dalam grid. Jika peta berpindah ke lokasi baru, atau ke tingkat zoom baru, Maps API akan menentukan ubin mana yang diperlukan dan menerjemahkan informasi tersebut menjadi satu kumpulan ubin yang akan diambil.

Ubin dengan koordinat (0,0) selalu berada di sudut barat laut peta, dengan nilai x meningkat dari barat ke timur dan nilai y meningkat dari utara ke selatan. Ubin diindeks menggunakan koordinat x,y dari titik asal tersebut.

Pada tingkat zoom 0, seluruh dunia dirender ke dalam satu ubin. Setiap tingkat zoom meningkatkan pembesaran dengan faktor dua. Jadi, pada tingkat zoom 1 peta akan dirender berupa grid ubin 2x2. Pada tingkat zoom 2, berupa grid 4x4. Pada tingkat zoom 3, berupa grid 8x8, dan seterusnya.

Misalnya, pada tingkat zoom 2, bumi dibagi menjadi 16 ubin. Setiap ubin dapat dirujuk melalui kombinasi x, y, dan zoom yang unik:

Saat membuat gambar untuk lapisan ubin, Anda perlu membuat gambar untuk setiap ubin pada setiap tingkat zoom yang ingin didukung. Google Maps menargetkan 256 dp (piksel yang tidak tergantung perangkat) saat menampilkan ubin. Untuk perangkat dengan resolusi tinggi, Anda direkomendasikan untuk mengembalikan ubin dengan dpi tinggi (512x512 px). Baca dokumentasi Developer Android untuk informasi tentang cara mendukung beragam kepadatan dan ukuran layar.

Catatan: Tingkat zoom yang didukung oleh kamera bergantung pada berbagai faktor, dan tidak terkait dengan tingkat zoom yang akan didukung ubin Anda.

  1. GoogleMap.getMaxZoomLevel() menampilkan tingkat zoom maksimum yang tersedia pada posisi kamera saat ini. Ini memperhitungkan jenis peta yang digunakan saat ini. Misalnya, peta satelit atau medan mungkin memiliki tingkat zoom maksimum yang lebih rendah dari ubin peta dasar.
  2. GoogleMap.getMinZoomLevel() menampilkan tingkat zoom minimum, yang sama untuk setiap lokasi (tidak seperti tingkat zoom maksimum), tetapi dapat bervariasi antara perangkat dan ukuran peta.

Menambahkan overlay ubin

Cara paling mudah dan umum untuk membuat overlay ubin adalah menyediakan URL yang menunjuk ke gambar ubin yang relevan. UrlTileProvider adalah penerapan sebagian dari TileProvider yang menyediakan ubin gambar berdasarkan URL. Class ini mengharuskan semua gambar memiliki dimensi yang sama.

Anda perlu menerapkan UrlTileProvider.getTileUrl() yang menerima koordinat ubin (x, y, zoom), dan mengembalikan URL yang mengarah ke gambar yang akan digunakan untuk ubin. Metode ini akan mengembalikan null jika tidak ada ubin untuk x, y, dan zoom yang diberikan. Sebuah URL bisa mengarah ke resource web, aset Android, atau file pada disk lokal.

Siapkan stok gambar ubin Anda pada server, definisikan semua koordinat x,y dan tingkat zoom yang ingin Anda dukung. Kemudian tambahkan overlay ubin:

  1. Tentukan UrlTileProvider untuk menyediakan gambar ubin.
  2. Ganti getTileUrl() untuk membuat URL setiap gambar ubin.
  3. Berikan objek TileOverlayOptions dengan opsi yang relevan:
    • fadeIn: Boolean. Menetapkan apakah ubin akan muncul perlahan. Nilai defaultnya adalah true. Mungkin Anda sebaiknya menonaktifkan fade-in saat beralih antar-overlay ubin dengan cepat. Untuk informasi tentang hubungan antara transparansi dan fade-in, lihat bagian tentang transparansi di bawah.
    • tileProvider: TileProvider akan digunakan untuk overlay ini.
    • transparency: Float. Menetapkan faktor transparansi untuk gambar ubin. Nilai harus berada dalam rentang [0.0f, 1.0f], dengan 0.0f berarti sepenuhnya buram (default) dan 1.0f berarti sepenuhnya transparan. Lihat bagian transparansi di bawah untuk melihat contoh kode dan hubungan antara transparansi dan fade-in.
    • visible: Boolean. Menetapkan visibilitas overlay ubin. Overlay ubin yang tidak terlihat (nilai false) tidak digambar pada peta, tetapi mempertahankan semua properti lainnya. Nilai default-nya adalah true.
    • zIndex: Menentukan urutan penggambaran overlay ubin dalam kaitannya dengan overlay lainnya, termasuk overlay bumi , lingkaran, polyline dan poligon. Overlay yang memiliki indeks z lebih tinggi akan digambar di atas overlay yang memiliki indeks z lebih rendah. Urutan overlay dengan indeks z yang sama tidak didukung. Indeks z default-nya adalah 0. Perhatikan bahwa penanda selalu digambar di atas overlay lain, terlepas dari indeks z overlay lainnya.
  4. Panggil GoogleMap.addTileOverlay() untuk menambahkan overlay ke peta.

Java

private GoogleMap map;

TileProvider tileProvider = new UrlTileProvider(256, 256) {

    @Override
    public URL getTileUrl(int x, int y, int zoom) {

        /* Define the URL pattern for the tile images */
        String s = String.format("http://my.image.server/images/%d/%d/%d.png", zoom, x, y);

        if (!checkTileExists(x, y, zoom)) {
            return null;
        }

        try {
            return new URL(s);
        } catch (MalformedURLException e) {
            throw new AssertionError(e);
        }
    }

    /*
     * Check that the tile server supports the requested x, y and zoom.
     * Complete this stub according to the tile range you support.
     * If you support a limited range of tiles at different zoom levels, then you
     * need to define the supported x, y range at each zoom level.
     */
    private boolean checkTileExists(int x, int y, int zoom) {
        int minZoom = 12;
        int maxZoom = 16;

        return (zoom >= minZoom && zoom <= maxZoom);
    }
};

TileOverlay tileOverlay = map.addTileOverlay(new TileOverlayOptions()
    .tileProvider(tileProvider));
      

Kotlin

private lateinit var map: GoogleMap

var tileProvider: TileProvider = object : UrlTileProvider(256, 256) {
    override fun getTileUrl(x: Int, y: Int, zoom: Int): URL? {

        /* Define the URL pattern for the tile images */
        val url = "http://my.image.server/images/$zoom/$x/$y.png"
        return if (!checkTileExists(x, y, zoom)) {
            null
        } else try {
            URL(url)
        } catch (e: MalformedURLException) {
            throw AssertionError(e)
        }
    }

    /*
     * Check that the tile server supports the requested x, y and zoom.
     * Complete this stub according to the tile range you support.
     * If you support a limited range of tiles at different zoom levels, then you
     * need to define the supported x, y range at each zoom level.
     */
    private fun checkTileExists(x: Int, y: Int, zoom: Int): Boolean {
        val minZoom = 12
        val maxZoom = 16
        return zoom in minZoom..maxZoom
    }
}

val tileOverlay = map.addTileOverlay(
    TileOverlayOptions()
        .tileProvider(tileProvider)
)
      

Untuk melihat contoh penerapan UrlTileProvider, lihat TileOverlayDemoActivity dalam kode contoh yang dipaketkan bersama SDK layanan Google Play.

Menetapkan transparansi untuk overlay ubin

Menempatkan ubin transparan pada peta bisa bermanfaat karena peta dasar di bawah peta yang ditempatkan dapat dilihat oleh pengguna. Anda dapat melakukannya dengan menyediakan ubin transparan Anda sendiri, atau dengan menetapkan faktor transparansi pada overlay ubin secara terprogram.

Contoh kode berikut mengatur transparansi overlay ubin antara 0.5f dan 0.0f:

Java

private TileOverlay tileOverlayTransparent;

@Override
public void onMapReady(GoogleMap map) {
    tileOverlayTransparent = map.addTileOverlay(new TileOverlayOptions()
        .tileProvider(new UrlTileProvider(256, 256) {
            // ...
        })
        .transparency(0.5f));
}

// Switch between 0.0f and 0.5f transparency.
public void toggleTileOverlayTransparency() {
    if (tileOverlayTransparent != null) {
        tileOverlayTransparent.setTransparency(0.5f - tileOverlayTransparent.getTransparency());
    }
}
      

Kotlin

private var tileOverlayTransparent: TileOverlay? = null

override fun onMapReady(map: GoogleMap) {
    tileOverlayTransparent = map.addTileOverlay(
        TileOverlayOptions()
            .tileProvider(object : UrlTileProvider(256, 256) {
                // ...
            })
            .transparency(0.5f)
    )
}

// Switch between 0.0f and 0.5f transparency.
fun toggleTileOverlayTransparency() {
    tileOverlayTransparent?.let {
        it.transparency = 0.5f - it.transparency
    }
}
      

Transparansi diterapkan sebagai alpha channel multiplier untuk gambar ubin. Untuk menetapkan transparansi overlay ubin, berikan objek TileOverlayOptions dengan transparency dalam rentang [0.0f, 1.0f] seperti yang ditunjukkan di atas. Nilai 0.0f berarti overlay ubin sepenuhnya buram dan 1.0f berarti sepenuhnya transparan. Nilai default-nya adalah 0.0f (buram).

Anda dapat mengakses transparansi overlay ubin dengan memanggil TileOverlay.getTransparency(), dan dapat mengubahnya dengan memanggil TileOverlay.setTransparency().

Transparansi, animasi, dan fade-in

Tidak ada animasi jika transparansi berubah. Opsi transparansi beroperasi bersama opsi fade-In.

Fade-in menyediakan animasi transparansi saat memuat ubin. Jika Anda menetapkan nilai transparansi, ubin akan melakukan transisi fade-in dari sepenuhnya transparan ke nilai transparansi yang didefinisikan. Jika Anda mengubah transparansi selama fade-in, animasi akan terus berjalan menuju transparansi target yang baru.

Menghapus overlay ubin

Anda dapat menghapus overlay ubin dengan metode TileOverlay.remove().

Java

tileOverlay.remove();
      

Kotlin

tileOverlay.remove()
      

Menghilangkan ubin basi

Jika ubin yang disediakan oleh overlay ubin menjadi 'basi', Anda dapat memanggil clearTileCache() untuk memaksakan pembaruan. Ini akan menyebabkan semua ubin pada overlay ini dimuat ulang. Misalnya, jika ubin disediakan lewat perubahan TileProvider, Anda harus memanggil clearTileCache() setelahnya untuk memastikan ubin sebelumnya tidak lagi dirender.

Java

tileOverlay.clearTileCache();
      

Kotlin

tileOverlay.clearTileCache()