Yer Paylaşımları

Karo yer paylaşımı (bazen karo katmanı olarak da adlandırılır), temel harita karolarının üzerinde gösterilen bir resim koleksiyonudur.

Kod Örnekleri

GitHub'daki ApiDemos deposunda, döşeme yerleşimi özelliğini gösteren bir örnek yer alır:

• TileOverlayDemoActivity - Java: Java'da yer paylaşımlı karo özellikleri
• TileCoordinateDemoActivity - Java: Java'da karo yer paylaşımları için kullanılan koordinat sistemi
• TileOverlayDemoActivity - Kotlin: Kotlin'de yer paylaşımlı karo özellikleri
• TileCoordinateDemoActivity - Kotlin: Kotlin'de karo yer paylaşımları için kullanılan koordinat sistemi

Giriş

A TileOverlay, temel harita karolarının üzerine eklenen bir dizi resmi tanımlar.

Desteklemek istediğiniz her yakınlaştırma seviyesi için parçalar sağlamanız gerekir. Birden fazla yakınlaştırma seviyesinde yeterli sayıda parçanız varsa Google'ın tüm harita için harita verilerini tamamlayabilirsiniz.

Karo yer paylaşımları, haritaya genellikle geniş coğrafi alanları kapsayan kapsamlı görüntüler eklemek istediğinizde kullanışlıdır. Buna karşılık, yer paylaşımları, tek bir görüntüyü haritada belirli bir alana sabitlemek istediğinizde kullanışlıdır.

Ayrıca, karo yer paylaşımında programatik olarak bir şeffaflık faktörü ayarlayarak veya şeffaf karo resimleri sağlayarak haritaya ek özellikler eklemek için şeffaf karo yer paylaşımlarını kullanabilirsiniz.

Parça koordinatları ve yakınlaştırma seviyeleri

Google Haritalar API, her yakınlaştırma düzeyindeki görüntüleri bir ızgara şeklinde düzenlenmiş bir dizi kare harita kutucuğuna böler. Harita yeni bir konuma veya yeni bir yakınlaştırma seviyesine taşındığında Maps API, hangi karoların gerekli olduğunu belirler ve bu bilgileri alınacak bir karo grubuna dönüştürür.

(0,0) koordinatlarına sahip karo her zaman haritanın kuzeybatı köşesindedir. x değerleri batıdan doğuya, y değerleri ise kuzeyden güneye doğru artar. Karolar, bu başlangıç noktasındaki x,y koordinatları kullanılarak dizine eklenir.

0 yakınlaştırma seviyesinde, tüm dünya tek bir karoda oluşturulur. Her yakınlaştırma seviyesi, büyütme oranını iki kat artırır. Bu nedenle, yakınlaştırma seviyesi 1'de harita, 2x2'lik bir karo ızgarası olarak oluşturulur. 2. yakınlaştırma seviyesinde 4x4'lük bir ızgara olur. 3. yakınlaştırma seviyesinde 8x8'lik bir ızgara olur ve bu şekilde devam eder.

Örneğin, 2. yakınlaştırma seviyesinde dünya 16 karoya bölünür. Her karo, x, y ve yakınlaştırmanın benzersiz bir kombinasyonuyla referans alınabilir:

Bir döşeme katmanı için resim oluştururken desteklemek istediğiniz her yakınlaştırma seviyesinde her döşeme için bir resim oluşturmanız gerekir. Google Haritalar, döşemeleri görüntülerken 256 dp'yi (cihazdan bağımsız pikseller) hedefler. Yüksek çözünürlüklü cihazlar için yüksek dpi'lı karolar (512x512 piksel) döndürmeniz önerilir. Farklı ekran boyutlarını ve yoğunluklarını destekleme hakkında bilgi edinmek için Android Geliştiricileri belgelerine bakın.

Not: Kamera tarafından desteklenen yakınlaştırma seviyeleri çeşitli faktörlere bağlıdır ve karolarınızın destekleyeceği yakınlaştırma seviyeleriyle ilgili değildir.

1. GoogleMap.getMaxZoomLevel(), mevcut kamera konumunda kullanılabilen maksimum yakınlaştırma seviyesini döndürür. Bu işlem, o anda kullanılan harita türünü dikkate alır. Örneğin, bir uydu veya arazi haritasının maksimum yakınlaştırma seviyesi, temel harita parçalarından daha düşük olabilir.
2. GoogleMap.getMinZoomLevel(), minimum yakınlaştırma seviyesini döndürür. Bu seviye, her konum için aynıdır (maksimum yakınlaştırma seviyesinin aksine) ancak cihazlar ve harita boyutları arasında farklılık gösterebilir.

Karo yer paylaşımı ekleme

Karo yer paylaşımı oluşturmanın en basit ve en yaygın yolu, ilgili karo resmine işaret eden bir URL sağlamaktır. UrlTileProvider, URL'ye dayalı resim karoları sağlayan TileProvider'nin kısmi bir uygulamasıdır. Bu sınıf, tüm resimlerin aynı boyutlara sahip olmasını gerektirir.

Karo koordinatlarını (x, y, yakınlaştırma) kabul eden ve karo için kullanılacak resmi işaret eden bir URL döndüren UrlTileProvider.getTileUrl() işlevini uygulamanız gerekir. Belirli x, y ve yakınlaştırma için karo yoksa yöntem null değerini döndürmelidir. URL, bir web kaynağına, Android öğesine veya yerel diskteki bir dosyaya işaret edebilir.

Karo resim stoğunuzu, desteklemeyi planladığınız tüm x,y koordinatları ve yakınlaştırma seviyeleri için tanımlanmış bir sunucuda ayarlayın. Ardından karo yer paylaşımını ekleyin:

1. Karo resimlerini sağlamak için bir UrlTileProvider tanımlayın.
2. Her karo resminin URL'sini oluşturmak için getTileUrl() yöntemini geçersiz kılın.
3. Aşağıdaki seçenekleri içeren bir TileOverlayOptions nesnesi sağlayın:
• fadeIn: Boole. Karoların yavaşça belirip belirmeyeceğini belirtir. Varsayılan değer: true. Karo yer paylaşımları arasında hızlıca geçiş yaparken belirginleşme efektini kapatmak faydalı olabilir. Şeffaflık ve görünüm arasında ilişki hakkında bilgi edinmek için aşağıdaki şeffaflık bölümüne bakın.
• tileProvider: Bu yer paylaşımı için kullanılacak TileProvider.
• transparency: Float. Karo resimleri için şeffaflık faktörü ayarlar. Değer, [0.0f, 1.0f] aralığında olmalıdır. 0.0f, tamamen opak (varsayılan) anlamına gelir ve 1.0f, tamamen şeffaf anlamına gelir. Kod örneği ve şeffaflık ile belirme arasındaki ilişki için aşağıdaki şeffaflık bölümüne bakın.
• visible: Boole. Karo yer paylaşımının görünürlüğünü belirtir. Görünmez bir karo yer paylaşımı (false değeri) harita üzerinde çizilmez ancak diğer tüm özelliklerini korur. Varsayılan değer true'dir.
• zIndex: Karo yer paylaşımının, zemin yer paylaşımları , daireler, çoklu çizgiler ve poligonlar dahil olmak üzere diğer yer paylaşımlarına göre hangi sırayla çizileceğini belirler. Daha yüksek z-index'e sahip yer paylaşımları, daha düşük z-index'e sahip olanların üzerine çizilir. Aynı z-endeksine sahip yer paylaşımlarının sırası rastgeledir. Varsayılan z-index değeri 0'dır. İşaretçilerin, diğer yer paylaşımlarının z-dizininden bağımsız olarak her zaman diğer yer paylaşımlarının üzerinde çizildiğini unutmayın.
4. Yer paylaşımını haritaya eklemek için GoogleMap.addTileOverlay() yöntemini çağırın.

val 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)
)
tileOverlay?.let {
    val isVisible = it.isVisible
    val fadeIn = it.fadeIn
    val transparency = it.transparency
    val zIndex = it.zIndex
}

      

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(java.util.Locale.US, "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));

      

UrlTileProvider kullanımına dair bir örnek görmek için Google Play Hizmetleri SDK'sıyla birlikte gelen örnek koddaki TileOverlayDemoActivity bölümüne bakın.

Karo yer paylaşımları için şeffaflık ayarlama

Kullanıcıların yer paylaşımlı karoların altındaki temel haritayı görebilmesi için haritaya şeffaf karolar yerleştirmek yararlı olabilir. Bunu, kendi şeffaf döşemelerinizi sağlayarak veya döşeme yer paylaşımı programında şeffaflık faktörü ayarlayarak yapabilirsiniz.

Aşağıdaki kod örneği, karo yer paylaşımının şeffaflığını 0.5f ile 0.0f arasında değiştirir:

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

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

      

TileOverlay tileOverlayTransparent = map.addTileOverlay(new TileOverlayOptions()
    .tileProvider(new UrlTileProvider(256, 256) {
        // ...
    })
    .transparency(0.5f));

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

      

Şeffaflık, döşeme resimleri için alfa kanalı çarpanı olarak uygulanır. Karo yer paylaşımının şeffaflığını ayarlamak için yukarıdaki örnekte gösterildiği gibi [0.0f, 1.0f] aralığında transparency içeren bir TileOverlayOptions nesnesi sağlayın. 0.0f değeri, döşeme yer paylaşımının tamamen opak olduğu, 1.0f değeri ise tamamen şeffaf olduğu anlamına gelir. Varsayılan değer 0.0f (opak) şeklindedir.

TileOverlay.getTransparency() işlevini çağırarak döşeme katmanının şeffaflığına erişebilir, TileOverlay.setTransparency() işlevini çağırarak da şeffaflığı değiştirebilirsiniz.

Şeffaflık, animasyon ve görünme

Şeffaflık değiştirildiğinde animasyon gösterilmez. Şeffaflık seçeneği, fadeIn seçeneğiyle birlikte çalışır.

Yavaşça belirme, karo yüklenirken şeffaflık animasyonu sağlar. Bir şeffaflık değeri ayarlarsanız karolar tamamen şeffaf durumdan tanımlanan şeffaflık değerine doğru belirginleşir. Şeffaflığı, belirginleştirme sırasında değiştirirseniz animasyon yeni hedef şeffaflığa doğru devam eder.

Karo yer paylaşımını kaldırma

TileOverlay.remove() yöntemini kullanarak bir döşeme yer paylaşımını kaldırabilirsiniz.

tileOverlay?.remove()

      

tileOverlay.remove();

      

Eski karoları temizleme

Karo yer paylaşımı tarafından sağlanan karolar "eski" hale gelirse yenilemeyi zorunlu kılmak için clearTileCache() yöntemini çağırabilirsiniz. Bu işlem, bu yer paylaşımındaki tüm karoların yeniden yüklenmesine neden olur. Örneğin, TileProvider tarafından sağlanan döşemeler değişirse önceki döşemelerin artık oluşturulmadığından emin olmak için daha sonra clearTileCache() işlevini çağırmanız gerekir.

tileOverlay?.clearTileCache()

      

tileOverlay.clearTileCache();