أداة خريطة التمثيل اللوني لأجهزة Android في "خرائط Google"

اختيار النظام الأساسي: Android iOS JavaScript

تُعد خرائط التمثيل اللوني مفيدة لتمثيل توزيع نقاط البيانات وكثافة عرضها على الخريطة.

مقدمة

تتضمّن حزمة تطوير البرامج (SDK) للخرائط الخاصة بـ Android Library (مكتبة الأدوات) الخاصة بخرائط Google أداة مساعدة لخريطة التمثيل اللوني يمكنك استخدامها لإضافة خريطة تمثيل لوني واحدة أو أكثر إلى خريطة Google في تطبيقك.

يناقش هذا الفيديو استخدام خرائط التمثيل اللوني كبديل للعلامات عندما تتطلّب بياناتك عددًا كبيرًا من نقاط البيانات على الخريطة.

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

في المثال أدناه، يمثّل اللون الأحمر مناطق ذات كثافة عالية في مراكز الشرطة في مدينة فيكتوريا بأستراليا.

خريطة تمثيل لوني على الخريطة

تلميح: يمكنك ضبط ألوان خريطة التمثيل اللوني باستخدام الطريقة setGradient(). يمكنك الاطّلاع على كيفية تخصيص الألوان والخصائص الأخرى لخريطة التمثيل اللوني.

إذا لم يسبق لك إعداد حزمة تطوير البرامج (SDK) لـ "خرائط Google" لأداة Android Utility حتى الآن، يمكنك اتّباع دليل الإعداد قبل قراءة بقية هذه الصفحة.

إضافة خريطة تمثيل لوني بسيطة

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

توفّر الأداة الفئة HeatmapTileProvider، التي تنفِّذ واجهة TileProvider لعرض صور المربّعات لخريطة التمثيل اللوني. تقبل HeatmapTileProvider مجموعة من كائنات LatLng (أو كائنات WeightedLatLng، على النحو الموضَّح أدناه). ويتم إنشاء صور المربعات لمستويات تكبير مختلفة بناءً على خيارات نصف القطر والتدرج والتعتيم التي يتم تقديمها. يمكنك تغيير القيم التلقائية لهذه الخيارات.

الاطّلاع على الخطوات بمزيد من التفصيل:

1. استخدِم HeatmapTileProvider.Builder() لتمرير مجموعة من عناصر LatLng إليه لإضافة HeatmapTileProvider جديد.
2. يمكنك إنشاء عنصر TileOverlayOptions جديد باستخدام الخيارات ذات الصلة، بما في ذلك HeatmapTileProvider.
3. اطلب GoogleMap.addTileOverlay() لإضافة العنصر إلى الخريطة.

Kotlin

private fun addHeatMap() {
    var latLngs: List<LatLng?>? = null

    // Get the data: latitude/longitude positions of police stations.
    try {
        latLngs = readItems(R.raw.police_stations)
    } catch (e: JSONException) {
        Toast.makeText(context, "Problem reading list of locations.", Toast.LENGTH_LONG)
            .show()
    }

    // Create a heat map tile provider, passing it the latlngs of the police stations.
    val provider = HeatmapTileProvider.Builder()
        .data(latLngs)
        .build()

    // Add a tile overlay to the map, using the heat map tile provider.
    val overlay = map.addTileOverlay(TileOverlayOptions().tileProvider(provider))
}

@Throws(JSONException::class)
private fun readItems(@RawRes resource: Int): List<LatLng?> {
    val result: MutableList<LatLng?> = ArrayList()
    val inputStream = context.resources.openRawResource(resource)
    val json = Scanner(inputStream).useDelimiter("\\A").next()
    val array = JSONArray(json)
    for (i in 0 until array.length()) {
        val `object` = array.getJSONObject(i)
        val lat = `object`.getDouble("lat")
        val lng = `object`.getDouble("lng")
        result.add(LatLng(lat, lng))
    }
    return result
}

      

Java

private void addHeatMap() {
    List<LatLng> latLngs = null;

    // Get the data: latitude/longitude positions of police stations.
    try {
        latLngs = readItems(R.raw.police_stations);
    } catch (JSONException e) {
        Toast.makeText(context, "Problem reading list of locations.", Toast.LENGTH_LONG).show();
    }

    // Create a heat map tile provider, passing it the latlngs of the police stations.
    HeatmapTileProvider provider = new HeatmapTileProvider.Builder()
        .data(latLngs)
        .build();

    // Add a tile overlay to the map, using the heat map tile provider.
    TileOverlay overlay = map.addTileOverlay(new TileOverlayOptions().tileProvider(provider));
}

private List<LatLng> readItems(@RawRes int resource) throws JSONException {
    List<LatLng> result = new ArrayList<>();
    InputStream inputStream = context.getResources().openRawResource(resource);
    String json = new Scanner(inputStream).useDelimiter("\\A").next();
    JSONArray array = new JSONArray(json);
    for (int i = 0; i < array.length(); i++) {
        JSONObject object = array.getJSONObject(i);
        double lat = object.getDouble("lat");
        double lng = object.getDouble("lng");
        result.add(new LatLng(lat, lng));
    }
    return result;
}

      

في هذا المثال، يتم تخزين البيانات في ملف JSON police_stations.json. إليك مقتطفًا من الملف:

[
{"lat" : -37.1886, "lng" : 145.708 } ,
{"lat" : -37.8361, "lng" : 144.845 } ,
{"lat" : -38.4034, "lng" : 144.192 } ,
{"lat" : -38.7597, "lng" : 143.67 } ,
{"lat" : -36.9672, "lng" : 141.083 }
]

استخدام نقاط خطوط الطول/العرض المُرجّحة

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

لتطبيق الترجيح على مواقع جغرافية معيّنة:

1. أنشِئ سمة WeightedLatLng جديدة لكل موقع جغرافي يتطلب ترجيحًا. مرِّر الترميزَين LatLng والرمز double الذي يمثّلان الكثافة المطلوبة. وتشير الكثافة إلى الأهمية النسبية أو القيمة النسبية لهذا الموقع الجغرافي. أما القيمة الأعلى، فستؤدي إلى لون أكثر كثافة في تدرج خريطة التمثيل اللوني. بشكل تلقائي، يكون اللون الأعلى كثافة هو الأحمر.

2. يمكنك طلب HeatmapTileProvider.Builder().weightedData()، بدلاً من HeatmapTileProvider.Builder().data()، لإنشاء خريطة التمثيل اللوني.

تخصيص خريطة التمثيل اللوني

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

تتوفّر الخيارات التالية:

1. نصف القطر: حجم تمويه غاوس المطبّق على خريطة التمثيل اللوني معبرًا عنه بالبكسل. والعدد التلقائي هو 20. يجب أن تتراوح القيمة بين 10 و50. استخدِم radius() في أداة الإنشاء لضبط القيمة عند إنشاء خريطة التمثيل اللوني، أو غيِّر القيمة لاحقًا باستخدام setRadius().
2. التدرج: مجموعة من الألوان التي تستخدمها خريطة التمثيل اللوني لإنشاء خريطة ألوانها، تتراوح من الأقل إلى الأعلى كثافة. يتم إنشاء تدرج باستخدام مصفوفتين: مصفوفة عدد صحيح تحتوي على الألوان، ومصفوفة عائمة تشير إلى نقطة البداية لكل لون، ويتم تحديدها كنسبة مئوية من الحد الأقصى للكثافة، ويتم التعبير عنها في شكل كسر من 0 إلى 1. تحتاج إلى تحديد لون واحد فقط للتدرج أحادي اللون، أو تحديد لونين على الأقل للتدرج متعدد الألوان. يتم إنشاء خريطة الألوان باستخدام الاستيفاء بين هذه الألوان. ويحتوي التدرج الافتراضي على لونين. استخدِم gradient() في أداة الإنشاء لضبط القيمة عند إنشاء خريطة التمثيل اللوني، أو غيِّر القيمة لاحقًا باستخدام setGradient().
3. التعتيم: هذا هو تعتيم طبقة خريطة التمثيل اللوني بأكملها، ويتراوح من 0 إلى 1. القيمة التلقائية هي 0.7. استخدِم opacity() في أداة الإنشاء لضبط القيمة عند إنشاء خريطة التمثيل اللوني، أو غيِّر القيمة لاحقًا باستخدام setOpacity().

على سبيل المثال، أنشِئ Gradient لضبط التدرج قبل إضافة خريطة التمثيل اللوني:

Kotlin

// Create the gradient.
val colors = intArrayOf(
    Color.rgb(102, 225, 0),  // green
    Color.rgb(255, 0, 0) // red
)
val startPoints = floatArrayOf(0.2f, 1f)
val gradient = Gradient(colors, startPoints)

// Create the tile provider.
val provider = HeatmapTileProvider.Builder()
    .data(latLngs)
    .gradient(gradient)
    .build()

// Add the tile overlay to the map.
val tileOverlay = map.addTileOverlay(
    TileOverlayOptions()
        .tileProvider(provider)
)

      

Java

// Create the gradient.
int[] colors = {
    Color.rgb(102, 225, 0), // green
    Color.rgb(255, 0, 0)    // red
};

float[] startPoints = {
    0.2f, 1f
};

Gradient gradient = new Gradient(colors, startPoints);

// Create the tile provider.
HeatmapTileProvider provider = new HeatmapTileProvider.Builder()
    .data(latLngs)
    .gradient(gradient)
    .build();

// Add the tile overlay to the map.
TileOverlay tileOverlay = map.addTileOverlay(new TileOverlayOptions().tileProvider(provider));

      

لتغيير مستوى تعتيم خريطة التمثيل اللوني الحالية، اتّبِع الخطوات التالية:

Kotlin

provider.setOpacity(0.7)
tileOverlay?.clearTileCache()

      

Java

provider.setOpacity(0.7);
tileOverlay.clearTileCache();

      

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

لتغيير مجموعة البيانات التي تم إنشاء خريطة تمثيل لوني عليها، استخدِم HeatmapTileProvider.setData() أو HeatmapTileProvider.setWeightedData() للنقاط WeightedLatLng. ملاحظة: إذا كنت تريد إضافة نقاط إلى خريطة التمثيل اللوني أو إزالة نقاط من خريطة التمثيل اللوني، عليك تعديل عملية جمع البيانات ثم استخدام setData() أو setWeightedData().

Kotlin

val data: List<WeightedLatLng> = ArrayList()
provider.setWeightedData(data)
tileOverlay?.clearTileCache()

      

Java

List<WeightedLatLng> data = new ArrayList<>();
provider.setWeightedData(data);
tileOverlay.clearTileCache();

      

إزالة خريطة تمثيل لوني

لإزالة خريطة التمثيل اللوني، عليك إزالة تراكب الصور:

Kotlin

tileOverlay?.remove()

      

Java

tileOverlay.remove();

      

الاطّلاع على التطبيق التجريبي

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