قراءة وكتابة البيانات المكانية

مقالة
06/22/2023

يسرد الجدول التالي تنسيقات الملفات المكانية المعتمدة لعمليات القراءة والكتابة باستخدام الوحدة النمطية Spatial IO.

تنسيق البيانات	قراءة	الكتابة
GeoJSON	✓	✓
GeoRSS	✓	✓
GML	✓	✓
GPX	✓	✓
KML	✓	✓
KMZ	✓	✓
CSV المكاني	✓	✓
نص معروف	✓	✓

توضح تلك الأقسام التالية جميع الأدوات المختلفة لقراءة وكتابة البيانات المكانية باستخدام وحدة الإدخال/الإخراج المكانية.

قراءة البيانات المكانية

atlas.io.read الدالة هي الدالة الرئيسية المستخدمة لقراءة تنسيقات البيانات المكانية الشائعة مثل ملفات KML وGPX و GeoRSS و GeoJSON و CSV ذات البيانات المكانية. يمكن لهذه الدالة أيضا قراءة الإصدارات المضغوطة من هذه التنسيقات، كملف zip أو ملف KMZ. تنسيق ملف KMZ هو إصدار مضغوط من KML يمكن أن يتضمن أيضًا أصولًا مثل الصور. بدلًا من ذلك، يمكن أن تأخذ وظيفة القراءة عنوان URL الذي يشير إلى ملف بأي من هذه التنسيقات. يجب استضافة عناوين URL على نقطة نهاية CORS ممكنة، أو يجب توفير خدمة وكيل في خيارات القراءة. يتم استخدام خدمة الوكيل لتحميل الموارد على المجالات التي لم يتم تمكين CORS فيها. ترجع دالة القراءة وعدًا بإضافة أيقونات الصور إلى الخريطة، وتعالج البيانات بشكل غير متزامن لتقليل التأثير على مؤشر ترابط واجهة المستخدم.

عند قراءة ملف مضغوط، إما كضغطة مضغوطة أو KMZ، بمجرد فك ضغطه، فإنه يبحث عن أول ملف صالح. على سبيل المثال، doc.kml، أو ملف بامتداد صالح آخر، مثل: .kml أو .xml أو geojson أو .json أو .csv أو .tsv أو .txt. بعد ذلك، يتم تحميل الصور المشار إليها في ملفات KML و GeoRSS في الخلفية لضمان إمكانية الوصول إليها. يمكن لبيانات الصور التي يتعذر الوصول إليها تحميل صورة احتياطية بديلة أو إزالتها من الأنماط. يتم تحويل الصور المستخرجة من ملفات KMZ إلى معرفات URI للبيانات.

النتيجة من دالة القراءة هي كائن SpatialDataSet. يوسع هذا الكائن فئة GeoJSON FeatureCollection. يمكن تمريره بسهولة إلى DataSource كما هو لعرض معالمه على الخريطة. SpatialDataSet لا يحتوي فقط على معلومات الميزات، ولكن يمكن أن يتضمن أيضا تراكبات KML الأرضية ومقاييس المعالجة والتفاصيل الأخرى كما هو موضح في الجدول التالي.

اسم الخاصية	كتابة	‏‏الوصف
`bbox`	`BoundingBox`	مربع إحاطة لكافة البيانات في مجموعة البيانات.
`features`	`Feature[]`	معالم GeoJSON داخل مجموعة البيانات.
`groundOverlays`	`(atlas.layer.ImageLayer \| atlas.layers.OgcMapLayer)[]`	صفيف KML GroundOverlays.
`icons`	Record<string, string>	مجموعة عناوين URL للأيقونات. المفتاح = اسم الأيقونة، القيمة = عنوان URL.
الخصائص	أي	معلومات الخصائص المقدمة على مستوى المستند لمجموعة بيانات مكانية.
`stats`	`SpatialDataSetStats`	إحصائيات حول المحتوى ووقت المعالجة لمجموعة بيانات مكانية.
`type`	`'FeatureCollection'`	قيمة نوع GeoJSON للقراءة فقط.

أمثلة على قراءة البيانات المكانية

يوضح نموذج تحميل البيانات المكانية كيفية قراءة مجموعة بيانات مكانية، ويعرضها على الخريطة باستخدام SimpleDataLayer الفئة . تستخدم التعليمة البرمجية ملف GPX المشار إليه بواسطة عنوان URL. للحصول على التعليمات البرمجية المصدر لهذه العينة، راجع تحميل التعليمات البرمجية لمصدر البيانات المكانية.

يوضح العرض التوضيحي التالي للتعليمات البرمجية كيفية قراءة KML أو KMZ على الخريطة وتحميله عليها. يمكن أن تحتوي KML على تراكبات أرضية، والتي تكون في شكل ImageLayer أو OgcMapLayer. يجب إضافة هذه التراكبات على الخريطة بشكل منفصل عن المعالم. بالإضافة إلى ذلك، إذا كانت مجموعة البيانات تحتوي على أيقونات مخصصة، فينبغي تحميل هذه الأيقونات إلى موارد الخرائط قبل تحميل المعالم.

يوضح نموذج تحميل KML على الخريطة كيفية تحميل ملفات KML أو KMZ على الخريطة. للحصول على التعليمات البرمجية المصدر لهذه العينة، راجع تحميل KML على التعليمات البرمجية المصدر للخريطة.

يمكنك اختياريا توفير خدمة وكيل للوصول إلى الأصول عبر المجالات التي لم يتم تمكين CORS لها. تحاول دالة القراءة الوصول إلى الملفات على مجال آخر باستخدام CORS أولا. في المرة الأولى التي يفشل فيها في الوصول إلى أي مورد على مجال آخر باستخدام CORS، فإنه يطلب المزيد من الملفات فقط إذا تم توفير خدمة وكيل. تقوم دالة القراءة بإلحاق عنوان URL للملف بنهاية عنوان URL للوكيل المقدم. توضح هذه القصاصة البرمجية كيفية تمرير خدمة وكيل إلى دالة القراءة:

//Read a file from a URL or pass in a raw data as a string.
atlas.io.read('https://nonCorsDomain.example.com/mySuperCoolData.xml', {
    //Provide a proxy service
    proxyService: window.location.origin + '/YourCorsEnabledProxyService.ashx?url='
}).then(async r => {
    if (r) {
        // Some code goes here . . .
    }
});

توضح القصاصة البرمجية التالية كيفية قراءة ملف محدد وعرضه على الخريطة. في هذه الحالة، تستخدم التعليمات البرمجية ملف CSV يحتوي على أعمدة بيانات مكانية. يجب إضافة مرجع إلى الوحدة النمطية خرائط Azure Spatial IO.

<!-- Add reference to the Azure Maps Spatial IO module. -->
<script src="https://atlas.microsoft.com/sdk/javascript/spatial/0/atlas-spatial.min.js"></script>

<script>
    var datasource, delimitedFileUrl = "Chicago_Police_Stations.csv";
    // Download CSV file (delimitedFileUrl) from:
    // https://github.com/Azure-Samples/AzureMapsCodeSamples/blob/main/Static/data/SpatialCSV/Chicago_Police_Stations.csv

    function GetMap() {

        //Instantiate a map object
        var map = new atlas.Map("myMap", {
            center: [-87.628899, 41.874693],
            zoom: 9,
            view: "Auto",
            // Replace <Your Azure Maps Subscription Key> with your Azure Maps subscription key. https://aka.ms/am-primaryKey
            authOptions: {
                authType: 'subscriptionKey',
                subscriptionKey: '{Your-Azure-Maps-Subscription-key}'
            }
        });
    
    //Wait until the map resources are ready.
      map.events.add('ready', function () {
        
        //Create a data source and add it to the map.
        datasource = new atlas.source.DataSource();
        map.sources.add(datasource);
        
        //Add a simple data layer for rendering the data.
        layer = new atlas.layer.SimpleDataLayer(datasource);
        map.layers.add(layer);
        
        //Read a CSV file from a URL or pass in a raw string.
        atlas.io.read(delimitedFileUrl).then(r => {
            if (r) {
                
                //Add the feature data to the data source.
                datasource.add(r);
                
                //If bounding box information is known for data, set the map view to it.
                if (r.bbox) {
                    map.setCamera({
                        bounds: r.bbox,
                        padding: 50
                    });
                }
            }
          });
        });
      }
</script>

كتابة البيانات المكانية

هناك دالتان رئيسيتان للكتابة في وحدة الإدخال/الإخراج المكانية. تنشئ دالة atlas.io.write سلسلة، بينما تقوم دالة atlas.io.writeCompressed بإنشاء ملف zip. سيحتوي الملف zip المضغوط على ملف نصي يحتوي على البيانات المكانية فيه. ترجع كلتا الدالتين وعدًا بإضافة البيانات إلى الملف. ويمكن لكلتيهما كتابة أي من البيانات التالية: SpatialDataSetأو DataSourceأو ImageLayerأو OgcMapLayerأو مجموعة المعالم أو المعالم أو الهندسة أو صفيف من أي مجموعة من أنواع البيانات هذه. عند الكتابة باستخدام أي من الدالتين، يمكنك تحديد تنسيق الملف المطلوب. إذا لم يتم تحديد تنسيق الملف، فستكتب البيانات ك KML.

نموذج خيارات كتابة البيانات المكانية هو أداة توضح معظم خيارات الكتابة التي يمكن استخدامها مع الدالةatlas.io.write. للحصول على التعليمات البرمجية المصدر لهذه العينة، راجع التعليمات البرمجية المصدر لخيارات كتابة البيانات المكانية.

مثال على كتابة البيانات المكانية

يتيح لك سحب الملفات المكانية وإفلاتها على عينة الخريطة سحب ملف KML أو KMZ أو GeoRSS أو GPX أو GML أو GeoJSON أو CSV وإسقاطه على الخريطة. للحصول على التعليمات البرمجية المصدر لهذه العينة، راجع سحب الملفات المكانية وإفلاتها في التعليمات البرمجية لمصدر الخريطة.

يمكنك اختياريا توفير خدمة وكيل للوصول إلى الأصول عبر المجالات التي لم يتم تمكين CORS لها. توضح هذه القصاصة البرمجية من التعليمات البرمجية أنه يمكنك دمج خدمة وكيل:

atlas.io.read(data, {
    //Provide a proxy service
    proxyService: window.location.origin + '/YourCorsEnabledProxyService.ashx?url='
}).then(
    //Success
    function(r) {
        //some code goes here ...
    }
);

قراءة نص معروف (WKT) وكتابته

نص معروف (WKT) هو معيار Open Geospatial Consortium (OGC) لتمثيل الهندسة المكانية كنص. تدعم العديد من الأنظمة الجغرافية المكانية WKT، مثل Azure SQL وAzure PostgreSQL باستخدام المكون الإضافي PostGIS. مثل معظم معايير OGC، يتم تنسيق الإحداثيات على أنها "خطوط الطول والعرض" لتتماشى مع اصطلاح "x y". على سبيل المثال، يمكن كتابة نقطة عند خط الطول -110 وخط العرض 45 كـ POINT(-110 45)باستخدام تنسيق WKT.

يمكن قراءة النص المعروف باستخدام الدالة atlas.io.ogc.WKT.read، وكتابته باستخدام الدالة atlas.io.ogc.WKT.write.

أمثلة على قراءة نص معروف (WKT) وكتابته

يوضح نموذج Read Well Known Text كيفية قراءة السلسلة POINT(-122.34009 47.60995) النصية المعروفة وعرضها على الخريطة باستخدام طبقة فقاعة. للحصول على التعليمات البرمجية المصدر لهذه العينة، راجع قراءة التعليمات البرمجية لمصدر النص المعروف جيدا.

يوضح نموذج النص المعروف جيدا للقراءة والكتابة كيفية قراءة وكتابة سلاسل النص المعروف جيدا (WKT) ك GeoJSON. للحصول على التعليمات البرمجية المصدر لهذه العينة، راجع قراءة وكتابة التعليمات البرمجية لمصدر النص المعروف جيدا.

قراءة GML وكتابته

GML هو مواصفات ملف XML مكانية غالبا ما تستخدم كملحق لمواصفات XML الأخرى. يمكن كتابة بيانات GeoJSON كـ XML باستخدام علامات GML باستخدام الدالة atlas.io.core.GmlWriter.write. يمكن قراءة XML الذي يحتوي على GML باستخدام الدالة atlas.io.core.GmlReader.read. تحتوي دالة القراءة على خيارين:

خيار isAxisOrderLonLat- يمكن أن يختلف ترتيب محور الإحداثيات "خط العرض، خط الطول" أو "خط الطول، خط العرض" بين مجموعات البيانات، ولا يتم تعريفه جيدًا دائمًا. بشكل افتراضي، يقرأ قارئ GML بيانات الإحداثيات على أنها "خط عرض، خط الطول"، ولكن تعيين هذا الخيار لقراءته true ك "خط الطول، خط العرض".
خيار propertyTypes - هذا الخيار هو جدول بحث عن قيمة المفتاح حيث يكون المفتاح هو اسم خاصية في مجموعة البيانات. القيمة هي نوع العنصر الذي سيتم تحويل القيمة إليه عند التحليل. قيم النوع المدعومة هي: stringو number وboolean وdate. إذا لم تكن الخاصية في جدول البحث أو لم يتم تعريف النوع، يتم تحليل الخاصية كسلسلة.

atlas.io.read يتم تعيين الدالة افتراضيا إلى الدالة atlas.io.core.GmlReader.read عندما تكتشف أن بيانات الإدخال هي XML، ولكن البيانات ليست واحدة من تنسيقات XML المكانية المعتمدة الأخرى.

GmlReader إحداثيات التحليلات التي تحتوي على أحد سريDs التالية:

EPSG:4326 (المفضل)
EPSG:4269، EPSG:4283، EPSG:4258، EPSG:4308، EPSG:4230، EPSG:4272، EPSG:4271، EPSG:4267، EPSG:4608، EPSG:4674 ربما بهامش خطأ صغير.
EPSG:3857، EPSG:102100، EPSG:3785، EPSG:900913، EPSG:102113، EPSG:41001، EPSG:54004

الخطوات التالية

راجع المقالات التالية للحصول على المزيد من نماذج التعليمات البرمجية لإضافتها إلى الخرائط الخاصة بك:

إضافة طبقة خريطة OGC

مشاركة عبر