تراكبات البلاط

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

عيّنات تعليمات برمجية

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

• TileOverlayDemoActivity - Java: ميزات تراكب الصور في Java
• TileCoordinateDemoActivity - Java: نظام الإحداثيات المستخدَم لتراكبات الصور في Java
• TileOverlayDemoActivity - Kotlin: ميزات تراكب الصور في Kotlin
• TileCoordinateDemoActivity - Kotlin: نظام الإحداثيات المستخدَم لتراكبات الصور في Kotlin

مقدمة

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

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

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

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

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

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

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

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

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

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

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

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

إضافة تراكب صور

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

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

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

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

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 أثناء العمل، يُرجى الرجوع إلى TileOverlayDemoActivity في رمز نموذجي المضمّنة في حزمة تطوير البرامج (SDK) لخدمات Google Play.

ضبط الشفافية لتراكبات الصور

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

تعرض عينة التعليمات البرمجية التالية الشفافية لتراكب الصور بين 0.5f و0.0f:

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

      

يتم تنفيذ الشفافية كمضاعف لقناة ألفا لصور المربّعات. لضبط شفافية تراكب الصور، قدِّم كائن 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();