تراكبات الصور

تراكب المربعات، الذي يسمى أحيانًا طبقة المربع، هو مجموعة من الصور التي يتم عرضها أعلى مربعات الخرائط الأساسية.

تعليمات برمجية نموذجية

يتضمن مستودع ApiDemos على GitHub نموذجًا يعرض ميزة تراكب المربّعات:

• المربعات التي تظهر على سطح الفيديو - نشاط جافا: ميزات تراكب المربعات في جافا
• tileCoordinateDemoActivity - جافا: نظام الإحداثيات المستخدم لتراكبات المربعات في جافا
• مربّع مركّب على سطح الفيديو - Kotlin: ميزات تراكب المربعات في لغة Kotlin
• tileCoordinateDemoActivity - Kotlin: نظام الإحداثيات المُستخدَم لتراكبات المربعات في Kotlin

المقدمة

تحدّد TileOverlay مجموعة من الصور التي تتم إضافتها أعلى مربعات الخرائط الأساسية.

يلزمك تقديم المربعات لكل مستوى تكبير/تصغير تريد دعمه. إذا كان لديك ما يكفي من المربّعات على مستويات تكبير/تصغير متعددة، يمكنك تكملة بيانات خريطة Google للخريطة بأكملها.

تكون تراكبات المربعات مفيدة عندما تريد إضافة صور شاملة إلى الخريطة، وعادة ما تغطي مناطق جغرافية كبيرة. في المقابل، تكون تراكبات الأرضية مفيدة عندما ترغب في إصلاح صورة واحدة في منطقة واحدة على الخريطة.

يمكنك أيضًا استخدام تراكبات شفافة للنوافذ لإضافة ميزات إضافية إلى الخريطة، من خلال تعيين عامل شفافية على تراكب المربعات برمجيًا أو من خلال تقديم صور شفافة للمربع.

إحداثيات المربعات ومستويات التكبير/التصغير

تقسّم واجهة برمجة تطبيقات "خرائط Google" الصور في كل مستوى من مستويات التكبير أو التصغير إلى مجموعة من مربعات الخرائط المربّعة التي يتم تنظيمها على شكل شبكة. عندما تنتقل الخريطة إلى موقع جديد، أو إلى مستوى تكبير/تصغير جديد، تحدّد API للخرائط المربعات التي تحتاج إليها وتترجم هذه المعلومات إلى مجموعة من المربّعات المطلوب استردادها.

يكون المربع الذي يحتوي على الإحداثيات (0,0) دائمًا في الركن الشمالي الغربي من الخريطة، مع زيادة قيم x من الغرب إلى الشرق وزيادة y القيم من الشمال إلى الجنوب. تتم فهرسة المربعات باستخدام إحداثيات x، y من ذلك الأصل.

في مستوى التكبير/التصغير 0، يتم عرض العالم بأسره في مربع واحد. يؤدي كل مستوى من مستويات التكبير أو التصغير إلى زيادة مستوى التكبير بمقدار عاملين. لذا، عند مستوى التكبير 1، سيتم عرض الخريطة كشبكة من المربّعات 2×2. في مستوى التكبير/التصغير 2، تكون عبارة عن شبكة 4×4. في مستوى التكبير/التصغير 3، تكون الشبكة 8x8، وهكذا.

على سبيل المثال، في مستوى التكبير/التصغير 2، يتم تقسيم الأرض إلى 16 مربعًا. يمكن الإشارة إلى كل مربّع من خلال مزيج فريد من عناصر x وy وzoom:

عند إنشاء صور لطبقة تجانب، ستحتاج إلى إنشاء صورة لكل جزء في كل مستوى تكبير ترغب في دعمه. تستهدف "خرائط Google" 256 وحدة بكسل مستقلة الكثافة (وحدة بكسل مستقلة عن الجهاز) عند عرض المربّعات. بالنسبة إلى الأجهزة ذات الدقة العالية، يُنصح بإرجاع مربّعات dpi العالية (512x512 بكسل). يمكنك الرجوع إلى مستندات مطوّري برامج Android للحصول على معلومات حول دعم أحجام الشاشة وكثافتها المختلفة.

ملاحظة: تعتمد مستويات التكبير أو التصغير التي تدعمها الكاميرا على عدة عوامل، وليست مرتبطة بمستويات التكبير/التصغير التي تدعمها مربعاتك.

1. تعرض GoogleMap.getMaxZoomLevel() الحد الأقصى لمستوى التكبير/التصغير المتوفر في موضع الكاميرا الحالي. ويأخذ ذلك في الاعتبار نوع الخريطة المستخدَمة حاليًا. على سبيل المثال، قد يكون الحد الأقصى لمستوى التكبير/التصغير في قمر صناعي أو خريطة تضاريس أقل من مربعات الخرائط الأساسية.
2. تعرض GoogleMap.getMinZoomLevel() الحد الأدنى لمستوى التكبير/التصغير، وهو نفس مستوى التكبير أو التصغير لكل موقع جغرافي (على عكس الحد الأقصى لمستوى التكبير أو التصغير) ولكن قد يختلف باختلاف الأجهزة وأحجام الخرائط.

إضافة تركيب مركّب

إنّ الطريقة الأبسط والأكثر شيوعًا لإنشاء مربّع مركّب هي توفير عنوان URL يؤدي إلى صورة مربّع ذات صلة. UrlTileProvider هو تنفيذ جزئي للسمة TileProvider يوفّر أجزاء الصورة بناءً على عنوان URL. تتطلب هذه الفئة أن تكون جميع الصور بنفس الأبعاد.

يجب تنفيذ السمة UrlTileProvider.getTileUrl() التي تقبل إحداثيات المربع (x، y، تكبير/تصغير)، وتعرض عنوان URL يشير إلى الصورة لاستخدامها في المربع. يجب أن تعرض الطريقة قيمة خالية في حال عدم توفّر مربّع للقيم x وy وzoom المحدّدة. ويمكن أن يشير عنوان URL إلى مورد ويب أو مادة عرض متوافقة مع Android أو ملف على القرص المحلي.

يمكنك إعداد مخزونك من صور المربعات على خادم محدد لجميع إحداثيات س، ص ومستويات التكبير/التصغير التي تنوي دعمها. بعد ذلك، أضِف التراكب:

1. حدِّد UrlTileProvider لتوفير صور المربعات.
2. يمكنك إلغاء getTileUrl() لإنشاء عنوان URL لكل صورة من مربّعات.
3. قدِّم الكائن TileOverlayOptions مع الخيارات ذات الصلة:
• fadeIn: منطقي. لتحديد ما إذا كان يجب تلاشي المربعات أم لا. القيمة التلقائية هي true. قد يكون من المفيد إيقاف خيار التلاشي التدريجي عند التبديل بين تراكبات المربعات بسرعة. للحصول على معلومات عن العلاقة بين الشفافية والتلاشي التدريجي، يُرجى الاطّلاع على القسم حول الشفافية أدناه.
• tileProvider: تمثّل هذه الخاصية السمة TileProvider للاستخدام مع هذه التركيبة.
• transparency: قيمة عائمة. تعيين عامل شفافية لصور المربّعات. يجب أن تكون القيمة في النطاق [0.0f, 1.0f] حيث تعني 0.0f معتمة تمامًا (الإعداد التلقائي) وتشير القيمة 1.0f إلى الشفافية الكاملة. راجِع قسم الشفافية أدناه للاطّلاع على نموذج للرمز والعلاقة بين الشفافية والتلاشي.
• visible: منطقي. يحدد مستوى رؤية تراكب المربعات. لا يتم رسم تراكب المربعات غير المرئية (القيمة false) على الخريطة، ولكنه يحتفظ بكل خصائصه الأخرى. القيمة التلقائية هي true.
• zIndex: لتحديد ترتيب رسم تراكب المربعات بالنسبة إلى التراكبات الأخرى، بما في ذلك تراكبات الأرضية والدوائر والخطوط المتعددة والمضلعات. ويتم رسم التراكبات ذات مؤشر z الأعلى فوق تلك التي تحتوي على مؤشرات z أقل. ويتم ترتيب التراكبات باستخدام مؤشر z نفسه بشكل عشوائي. فهرس z الافتراضي هو 0. وتجدر الإشارة إلى أنه يتم دائمًا رسم العلامات فوق التراكبات الأخرى، بغض النظر عن فهرس z للتراكبات الأخرى.
4. اتّصل GoogleMap.addTileOverlay() لإضافة التراكب إلى الخريطة.

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));

      

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)
)

      

للاطّلاع على مثال لـ UrlTileProvider أثناء الاستخدام، يمكنك الرجوع إلى TileOverlayDemoActivity في نموذج الرمز المضمّن مع حزمة SDK لخدمات Google Play.

تعيين شفافية لتراكبات

من المفيد تراكب المربعات الشفافة على الخريطة حتى يتمكن المستخدمون من رؤية الخريطة الأساسية أسفل المربّعات المتراكبة. ويمكنك إجراء ذلك من خلال تقديم فئاتك الشفافة أو من خلال تعيين عامل شفافية على تراكب المربعات برمجيًا.

يعمل نموذج الرمز التالي على تبديل شفافية تراكب المربعات بين 0.5f و0.0f:

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());
    }
}

      

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
    }
}

      

ويتم تنفيذ الشفافية كمُضاعِف قناة ألفا لصور الفئات. لضبط شفافية تراكب المربعات، يمكنك توفير عنصر TileOverlayOptions مع transparency في النطاق [0.0f, 1.0f] كما هو موضّح في النموذج أعلاه. تعني القيمة 0.0f أن تراكب المربعات معتم بالكامل بينما يعني 1.0f أنه شفاف بالكامل. القيمة التلقائية هي 0.0f (معتم).

يمكنك الوصول إلى شفافية تراكب المربعات من خلال استدعاء TileOverlay.getTransparency()، ويمكنك تغييرها من خلال استدعاء TileOverlay.setTransparency().

الشفافية والصور المتحركة والتلاشي للداخل

ولا يتم تطبيق أي رسوم متحركة عند تغيير الشفافية. يعمل خيار الشفافية مع خيار fadeIn.

يوفر خيار التلاشي للحركة رسومًا متحركة للشفافية عند تحميل المربع. إذا ضبطت قيمة الشفافية، يتلاشى المربّع من شفاف بالكامل إلى قيمة الشفافية المحددة. إذا غيّرت الشفافية أثناء تلاشي الألوان، تستمر الصورة المتحركة نحو شفافية الهدف الجديدة.

إزالة تراكب المربعات

يمكنك إزالة تراكب الصورة باستخدام طريقة TileOverlay.remove().

tileOverlay.remove();

      

tileOverlay?.remove()

      

محو مربعات قديمة

إذا أصبحت المربعات التي يوفرها تراكب المربعات "قديمة"، يمكنك استدعاء clearTileCache() لفرض التحديث. سيؤدي ذلك إلى إعادة تحميل كل المربعات المتراكبة على هذا التراكب. على سبيل المثال، إذا كانت الأقسام المُقدَّمة من التغيير TileProvider، عليك استدعاء clearTileCache() بعد ذلك لضمان عدم عرض الأقسام السابقة.

tileOverlay.clearTileCache();

      

tileOverlay?.clearTileCache()