برنامج KML التعليمي

KML هو تنسيق ملف يستخدم لعرض البيانات الجغرافية في متصفح Earth مثل Google Earth. يستخدم KML بنية مستندة إلى علامات بالإضافة إلى عناصر وسمات متداخلة كما يعتمد على مقياس XML. تتأثر جميع العلامات بحالة الأحرف ويجب أن تظهر تمامًا كما هي مدرجة في مرجع KML. يشير المرجع إلى العلامات الاختيارية. يجب أن تظهر العلامات بالترتيب الموضح في المرجع داخل العنصر المحدد.

إذا كنت تستخدم ملف KML لأول مرة، فاستكشف هذا المستند ونماذج الملفات المصاحبة له (SamplesInEarth) لبدء التعرف على البنية الأساسية لملف KML والعلامات الأكثر استخدامًا. يصف القسم الأول الميزات التي يمكن إنشاؤها باستخدام واجهة مستخدم Google Earth. وتشمل هذه الميزات العلامات الموضعية والأوصاف وتراكبات الأرض والمسارات والمضلعات. يصف القسم الثاني الميزات التي تتطلب تأليف KML باستخدام محرر النصوص. عند حفظ ملف نصي بامتداد .kml أو .kmz، فستعرف متصفحات Earth كيفية عرضه.

نصيحة: لمشاهدة "رمز" KML لميزة في Google Earth، يمكنك النقر بزر الماوس الأيمن على الميزة في العارض ثلاثي الأبعاد لبرنامج Google Earth وتحديد "نسخ". ثم الصق محتويات الحافظة في أي محرر نصوص. تم تحويل الميزة المرئية المعروضة في برنامج Google Earth إلى ما يكافئها بنص KML. احرص على تجربة هذه الميزة.

تتوفر جميع الأمثلة الموضحة هنا في ملف نماذج KML. ابدأ بتنزيل هذا الملف لعرض الأمثلة في Google Earth.

لمزيد من المعلومات

يوفّر مرجع KML 2.2 تفاصيل حول تنسيق ملف KML. إذا كنت معتادًا على استخدام XML، فستهتم أيضًا بمخطط KML 2.2.

للحصول على مناقشة حول كيفية استخدام بعض الميزات الرئيسية في ملف KML، راجع دليل المطور.

جدول المحتويات

مستندات KML الأساسية

إن أبسط أنواع مستندات KML هي تلك التي يمكن تأليفها مباشرة في Google Earth، أي أنك لن تحتاج إلى تعديل أو إنشاء أي KML في محرر نصوص. يمكن كتابة العلامات الموضعية وتراكبات الأرض والمسارات والمضلعات مباشرة في Google Earth.

العلامات الموضعية

العلامة الموضعية هي إحدى أكثر الميزات استخدامًا في Google Earth. فهي تحدد موضعًا على سطح الأرض، باستخدام دبوس أصفر اللون كرمز. تشتمل أبسط علامة موضعية على عنصر <Point> فقط يحدد موقع العلامة الموضعية. يمكنك تحديد اسم ورمز مخصص للعلامة الموضعية، ويمكنك أيضًا إضافة عناصر هندسية أخرى إليها.

افتح ملف عيّنات KML في Google Earth ووسّع المجلد الفرعي للعلامات الموضعية. يتضمن هذا المجلد ثلاثة أنواع مختلفة من العلامات الموضعية: البسيطة والعائمة والمنبثقة. ويظهر رمز KML للعلامة الموضعية البسيطة على النحو التالي:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Placemark>
    <name>Simple placemark</name>
    <description>Attached to the ground. Intelligently places itself 
       at the height of the underlying terrain.</description>
    <Point>
      <coordinates>-122.0822035425683,37.42228990140251,0</coordinates>
    </Point>
  </Placemark>
</kml>

ويتم تقسيم بنية هذا الملف على النحو التالي:

  • عنوان XML. هذا هو السطر 1 في كل ملف KML. لا يمكن أن تظهر مسافات أو أحرف أخرى قبل هذا السطر.
  • تعريف مساحة الاسم في KML. هذا هو السطر 2 في كل ملف KML 2.2.
  • كائن علامة موضعية يحتوي على العناصر التالية:
    • اسم يُستخدم كتسمية للعلامة الموضعية
    • وصف يظهر في "البالون" المرفق بالعلامة الموضعية
    • نقطة تحدد موضع العلامة الموضعية على سطح الأرض (خط الطول وخط العرض والارتفاع الاختياري)

إذا كنت تتساءل عن مكان العلامة الموضعية، فهذا يعني أنه يقع مباشرة فوق المبنى 41 في Google، حيث تم تطوير Google Earth.

ما يعتبره المستخدمون عادة "كعلامة موضعية" في برنامج Google Earth هو في الواقع عنصر <علامة موضعية> يتضمن عنصر <Point> ثانويًا في KML. العلامة الموضعية للنقطة هي الطريقة الوحيدة لرسم رمز وتسمية في العارض ثلاثي الأبعاد لبرنامج Google Earth. بشكل افتراضي، يكون الرمز هو الدبوس الأصفر المألوف. في KML، يمكن أن تحتوي <العلامة الموضعية> على عنصر هندسي واحد أو أكثر، مثل LineString أو مضلّع أو نموذج. ولكن لا يمكن أن يحتوي الرمز <العلامة الموضعية> الذي يتضمن نقطة إلا على رمز وتصنيف. يتم استخدام النقطة لوضع الرمز، ولكن لا يوجد تمثيل رسومي للنقطة نفسها.

رمز HTML الوصفي في العلامات الموضعية

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

الترميز التلقائي في Google Earth (الإصدار 4.0 والإصدارات الأحدث)

يتضمن Google Earth 4.0 ميزة الترميز التلقائي التي تحوّل تلقائيًا النص مثل www.google.com إلى روابط تشعبية نشطة يمكن للمستخدم النقر عليها. يتم تحويل كل من النص داخل العلامة <description> وعلامة <Snippet> والعنصر <text> في <BalloonStyle> إلى روابط تشعّبية HTTP تلقائيًا. ولا تحتاج إلى إضافة علامات <a href= ...> بنفسك.

استخدام عنصر CDATA

إذا كنت ترغب في كتابة شفرة HTML قياسية داخل علامة <description> (الوصف)، يمكنك وضعها داخل علامة CDATA. وإذا لم يكن الأمر كذلك، ينبغي كتابة الأقواس المعقوفة كمراجع للكيانات لمنع Google Earth من تحليل شفرة HTML بشكل غير صحيح (على سبيل المثال، تتم كتابة الرمز > على النحو &gt; وتتم كتابة الرمز < على هيئة &lt;). هذه ميزة قياسية من XML، وليست فريدة بالنسبة لبرنامج Google Earth.

ضع في الاعتبار الفرق بين ترميز HTML مع علامات CDATA وبدون CDATA. أولاً، في ما يلي العلامة <description> مع علامات CDATA:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>
    <Placemark>
      <name>CDATA example</name>
      <description>
        <![CDATA[
          <h1>CDATA Tags are useful!</h1>
          <p><font color="red">Text is <i>more readable</i> and 
          <b>easier to write</b> when you can avoid using entity 
          references.</font></p>
        ]]>
      </description>
      <Point>
        <coordinates>102.595626,14.996729</coordinates>
      </Point>
    </Placemark>
  </Document>
</kml>

في ما يلي العلامة <description> التي لا تحتوي على علامات CDATA، لذلك يجب أن تستخدم الأحرف الخاصة مراجع الكيانات:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>
    <Placemark>
      <name>Entity references example</name>
      <description>
	        &lt;h1&gt;Entity references are hard to type!&lt;/h1&gt;
	        &lt;p&gt;&lt;font color="green"&gt;Text is 
          &lt;i&gt;more readable&lt;/i&gt; 
          and &lt;b&gt;easier to write&lt;/b&gt; 
          when you can avoid using entity references.&lt;/font&gt;&lt;/p&gt;
      </description>
      <Point>
        <coordinates>102.594411,14.998518</coordinates>
      </Point>
    </Placemark>
  </Document>
</kml>

التراكبات الأرضية

تمكنك التراكبات الأرضية من "تركيب" صورة في التضاريس على الأرض. يحتوي العنصر <Icon> على الرابط المؤدي إلى ملف .jpg الذي يحتوي على صورة التراكب. في ما يلي مثال للطبقة الأرضية في ملف نماذج KML الذي يُظهر انفجار جبل إتنا في عام 2001: 

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Folder>
    <name>Ground Overlays</name>
    <description>Examples of ground overlays</description>
    <GroundOverlay>
      <name>Large-scale overlay on terrain</name>
      <description>Overlay shows Mount Etna erupting 
          on July 13th, 2001.</description>
      <Icon>
        <href>https://developers.google.com/kml/documentation/images/etna.jpg</href>
      </Icon>
      <LatLonBox>
        <north>37.91904192681665</north>
        <south>37.46543388598137</south>
        <east>15.35832653742206</east>
        <west>14.60128369746704</west>
        <rotation>-0.1556640799496235</rotation>
      </LatLonBox>
    </GroundOverlay>
  </Folder>
</kml>

لاحظ أن الملف يبدأ بالسطرين نفسهيْن في المثال الأول: رأس XML وبيان مساحة اسم KML.

يستخدم هذا المثال مجلدًا (بعنوان "تراكبات الأرض") كآلية لتجميع محتوياته وتصنيفها. لاحظ كيف يظهر المجلد في لوحة الأماكن عند تحميل ملف نماذج KML في Google Earth.

يتم التحكم في موضع التراكب الأرضي بواسطة العلامة <LatLonBox>. يتم إعطاء قيم الحدود القصوى لخط العرض الشمالي والجنوب وخطي العرض الشرقي والغربي. بالإضافة إلى ذلك، يتم تقديم قيم التدوير للصور التي لا يتزامن محورها y مع الشبكة المتّجهة شمالاً. يستخدم هذا المثال صورة JPEG للتراكب. كما يدعم Google Earth تنسيقات BMP وGIF وTIFF وTGA وPNG.

المسارات

يمكن إنشاء العديد من الأنواع المختلفة من المسارات في برنامج Google Earth، كما أنه من السهل الابتكار باستخدام بياناتك. في KML، يتم إنشاء مسار من خلال عنصر <LineString>. ألقِ نظرة على مثال "المتقاضي المطلق" في مجلد المسارات لتشاهد كيف تم إنشاء الشكل بواسطة الشفرة التالية:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>
    <name>Paths</name>
    <description>Examples of paths. Note that the tessellate tag is by default
      set to 0. If you want to create tessellated lines, they must be authored
      (or edited) directly in KML.</description>
    <Style id="yellowLineGreenPoly">
      <LineStyle>
        <color>7f00ffff</color>
        <width>4</width>
      </LineStyle>
      <PolyStyle>
        <color>7f00ff00</color>
      </PolyStyle>
    </Style>
    <Placemark>
      <name>Absolute Extruded</name>
      <description>Transparent green wall with yellow outlines</description>
      <styleUrl>#yellowLineGreenPoly</styleUrl>
      <LineString>
        <extrude>1</extrude>
        <tessellate>1</tessellate>
        <altitudeMode>absolute</altitudeMode>
        <coordinates> -112.2550785337791,36.07954952145647,2357
          -112.2549277039738,36.08117083492122,2357
          -112.2552505069063,36.08260761307279,2357
          -112.2564540158376,36.08395660588506,2357
          -112.2580238976449,36.08511401044813,2357
          -112.2595218489022,36.08584355239394,2357
          -112.2608216347552,36.08612634548589,2357
          -112.262073428656,36.08626019085147,2357
          -112.2633204928495,36.08621519860091,2357
          -112.2644963846444,36.08627897945274,2357
          -112.2656969554589,36.08649599090644,2357 
        </coordinates>
      </LineString>
    </Placemark>
  </Document>
</kml>

لاحظ كيف يمثل خطًا واحدًا بالفعل مرسومًا على ارتفاع فوق الأرض. أما العلامة ttsellate> فتقسّم السطر إلى أجزاء أصغر حجمًا، بينما تعمل العلامة <extrude> على تمديد الخط إلى أسفل.

المضلعات

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

يتم إنشاء مثال البنتاغون من خلال رسم هياكل داخلية وخارجية بسيطة ثم إخراجها إلى الأرض. إليك الشفرة :

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Placemark>
    <name>The Pentagon</name>
    <Polygon>
      <extrude>1</extrude>
      <altitudeMode>relativeToGround</altitudeMode>
      <outerBoundaryIs>
        <LinearRing>
          <coordinates>
            -77.05788457660967,38.87253259892824,100 
            -77.05465973756702,38.87291016281703,100 
            -77.05315536854791,38.87053267794386,100 
            -77.05552622493516,38.868757801256,100 
            -77.05844056290393,38.86996206506943,100 
            -77.05788457660967,38.87253259892824,100
          </coordinates>
        </LinearRing>
      </outerBoundaryIs>
      <innerBoundaryIs>
        <LinearRing>
          <coordinates>
            -77.05668055019126,38.87154239798456,100 
            -77.05542625960818,38.87167890344077,100 
            -77.05485125901024,38.87076535397792,100 
            -77.05577677433152,38.87008686581446,100 
            -77.05691162017543,38.87054446963351,100 
            -77.05668055019126,38.87154239798456,100
          </coordinates>
        </LinearRing>
      </innerBoundaryIs>
    </Polygon>
  </Placemark>
</kml>

مستندا KML متقدمان

يصف هذا القسم بعض عناصر KML التي يجب تأليفها باستخدام محرر النصوص، مثل الأنماط المشتركة للهندسة والرموز المميزة للعلامات الموضعية وتراكبات الشاشة. تُعد كتابة ملفات KML "يدويًا" أكثر تقدمًا إلى حد ما من استخدام واجهة Google Earth لإنشاء الميزات وتعديلها، ولكن مع إجراء القليل من الممارسة، فإن معظم المستخدمين يشعرون بالارتياح في تعديل ملفات KML لإضافة هذه التأثيرات.

أنماط الهندسة

بعد إنشاء الميزات داخل Google Earth وفحص شفرة KML التي ينشئها Google Earth، ستلاحظ أن الأنماط هي جزء مهم من كيفية عرض بياناتك. يريد المستخدمون المتمرسون معرفة كيفية تحديد أنماطهم الخاصة.

إذا حددت نمطًا في بداية مستند KML وحددت معرّفًا له أيضًا، فيمكنك استخدام هذا النمط في الأشكال الهندسية والعلامات الموضعية والتراكبات التي يتم تحديدها في أي مكان آخر في المستند. ونظرًا لأنه يمكن لأكثر من عنصر واحد استخدام نفس النمط، فإنه تتم الإشارة إلى الأنماط المحددة بهذه الطريقة والمُستخدمة بهذه الطريقة باسم الأنماط المشتركة. يمكنك تحديد نمط معيّن مرة واحدة، ويمكنك بعد ذلك الرجوع إليه عدة مرات باستخدام العنصر <styleUrl>. إذا كان تعريف النمط داخل الملف نفسه، فاسبق معرّف النمط بعلامة #. إذا كان تعريف النمط في ملف خارجي، فعليك تضمين عنوان URL الكامل في العنصر <styleUrl>.

يحتوي ملف نماذج KML على عدد من الأنماط المشتركة، ويتم تحديد كل نمط بمعرّف في بداية الملف. لاحظ أنه من الأسهل أن تكون أرقام التعريف عبارة عن سلاسل وصفية بحيث يمكنك معرفة تأثيرها بسهولة. في ما يلي مثال لنمط ("transBluePoly") يحدد لونًا أزرق شفافًا لأوجه المضلّع وعرضًا للسطر 1.5 (واللون الافتراضي للأبيض) لحواف المضلع. يتم استخدام هذا النمط من خلال المبنى 41 في مثال Google Campus (في مجلد المضلعات):

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>
    <Style id="transBluePoly">
      <LineStyle>
        <width>1.5</width>
      </LineStyle>
      <PolyStyle>
        <color>7dff0000</color>
      </PolyStyle>
    </Style>
    <Placemark>
      <name>Building 41</name>
      <styleUrl>#transBluePoly</styleUrl>
      <Polygon>
        <extrude>1</extrude>
        <altitudeMode>relativeToGround</altitudeMode>
        <outerBoundaryIs>
          <LinearRing>
            <coordinates> -122.0857412771483,37.42227033155257,17
              -122.0858169768481,37.42231408832346,17
              -122.085852582875,37.42230337469744,17
              -122.0858799945639,37.42225686138789,17
              -122.0858860101409,37.4222311076138,17
              -122.0858069157288,37.42220250173855,17
              -122.0858379542653,37.42214027058678,17
              -122.0856732640519,37.42208690214408,17
              -122.0856022926407,37.42214885429042,17
              -122.0855902778436,37.422128290487,17
              -122.0855841672237,37.42208171967246,17
              -122.0854852065741,37.42210455874995,17
              -122.0855067264352,37.42214267949824,17
              -122.0854430712915,37.42212783846172,17
              -122.0850990714904,37.42251282407603,17
              -122.0856769818632,37.42281815323651,17
              -122.0860162273783,37.42244918858722,17
              -122.0857260327004,37.42229239604253,17
              -122.0857412771483,37.42227033155257,17 
            </coordinates>
          </LinearRing>
        </outerBoundaryIs>
      </Polygon>
    </Placemark>
  </Document>
</kml>

لاحظ أن العنصر <styleUrl> هو عنصر فرعي للعلامة <placemarks> (وليس ضمن الشكل الهندسي الذي يؤثر فيه).

أنماط الرموز المميزة

يوضح لك "الرمز المميز" في مجلد الأنماط والترميز كيفية إنشاء تأثير تمرير الماوس فوق ملف KML. يحدد المستند نمطين، أحدهما لـ "العلامة الموضعية العادية" والآخر "لتمييز العلامة الموضعية" (يظهر عند تمرير المؤشر فوق الرمز). يحتوي عنصر >StyleMap> على زوج من المفاتيح/القيمة لتعيين كل نمط رمز إلى حالة الرمز. هناك حالتان للرموز: عادية وتمييز.

في ما يلي الخطوات الأساسية الموضّحة هنا:

  1. حدد <النمط> للرمز العادي للعلامة الموضعية، وعيّن رقم تعريف لها (هنا، "العلامة الموضعية العادية"). يتضمن النمط <Icon> مع <href> للصورة الفعلية المراد استخدامها، كما هو موضح أدناه.
  2. حدد <النمط> لرمز تمييز العلامة الموضعية وعيّن معرّفًا لها (هنا، "تمييز العلامة الموضعية").
  3. يمكنك إنشاء عنصر style.> تعيين رقم تعريف له ("exampleStyleMap"). ستشير العلامة الموضعية إلى هذا المعرّف.
  4. في العنصر styleStyle>، حدِّد " #normalplacemarks" للحالة الطبيعية.
  5. في العنصر >StyleMap>، حدد "#highlightplacemarks" للحالة highlight.
  6. في العلامة الموضعية، أضف عنصر <styleUrl> يشير إلى "#exampleStyleMap". 
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>
    <name>Highlighted Icon</name>
    <description>Place your mouse over the icon to see it display the new icon</description>
    <Style id="highlightPlacemark">
      <IconStyle>
        <Icon>
          <href>http://maps.google.com/mapfiles/kml/paddle/red-stars.png</href>
        </Icon>
      </IconStyle>
    </Style>
    <Style id="normalPlacemark">
      <IconStyle>
        <Icon>
          <href>http://maps.google.com/mapfiles/kml/paddle/wht-blank.png</href>
        </Icon>
      </IconStyle>
    </Style>
    <StyleMap id="exampleStyleMap">
      <Pair>
        <key>normal</key>
        <styleUrl>#normalPlacemark</styleUrl>
      </Pair>
      <Pair>
        <key>highlight</key>
        <styleUrl>#highlightPlacemark</styleUrl>
      </Pair>
    </StyleMap>
    <Placemark>
      <name>Roll over this icon</name>
      <styleUrl>#exampleStyleMap</styleUrl>
      <Point>
        <coordinates>-122.0856545755255,37.42243077405461,0</coordinates>
      </Point>
    </Placemark>
  </Document>
</kml>

تراكبات الشاشة

لا يمكن كتابة تراكبات الشاشة مباشرة داخل برنامج Google Earth ولذا تكون أصعب في الإنشاء من تراكبات الأرض. ويتم تضمين مجموعة شاملة من النماذج في مجلد "تراكبات الشاشة" في ملف نماذج KML.

وكمثال على ذلك، مكّن المجلد "الموضع المطلق: في الجزء العلوي الأيمن" في ملف نماذج KML وسترى تراكب شاشة أعلى يمين نافذة العرض. تم إنشاء هذا باستخدام شفرة KML التالية:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <ScreenOverlay>
    <name>Absolute Positioning: Top left</name>
    <Icon>
      <href>http://developers.google.com/kml/documentation/images/top_left.jpg</href>
    </Icon>
    <overlayXY x="0" y="1" xunits="fraction" yunits="fraction"/>
    <screenXY x="0" y="1" xunits="fraction" yunits="fraction"/>
    <rotationXY x="0" y="0" xunits="fraction" yunits="fraction"/>
    <size x="0" y="0" xunits="fraction" yunits="fraction"/>
  </ScreenOverlay>
</kml>

يتم التحكم في الموضع من خلال تعيين نقطة في الصورة المحددة بواسطة <overlayXY> إلى نقطة على الشاشة يتم تحديدها بواسطة العلامة <screenXY>. في هذه الحالة، تم تقريب الركن العلوي الأيمن من الصورة (0,1) مع النقطة نفسها على الشاشة.

اطّلع على الأمثلة الأخرى في المجلد لمعرفة كيفية الحصول على مواضع ثابتة أخرى، ولإنشاء صور بحجم ديناميكي مع حجم الشاشة. (تجدر الإشارة إلى أنه يمكن أيضًا تحديد xunits وyunits كوحدات بكسل للتحكّم في الدقة). للحصول على مزيد من التفاصيل، يمكنك الاطلاع على مرجع KML 2.2.

يحتوي رابط الشبكة على عنصر <Link> يتضمن <href> (مرجع نص تشعبي) الذي يحمِّل ملفًا. يمكن أن يكون <href> أحد مواصفات الملفات المحلية أو عنوان URL مطلقًا. على الرغم من الاسم، لا يحمِّل <NetworkLink> الملفات من الشبكة بالضرورة.

تحدد <href> في أحد الروابط موقع أي مما يلي:

  • ملف صورة تستخدمه الرموز في أنماط الرموز والتراكبات الأرضية وتراكبات الشاشة
  • ملف نموذج مستخدم في عنصر <Model>
  • ملف KML أو KMZ تم تحميله من خلال رابط شبكة

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

حتى الآن، تتطلب جميع أمثلةنا تسليم رمز KML إلى Google Earth من الجهاز المحلي. تتيح لك روابط الشبكة إمكانية عرض المحتوى من موقع جغرافي ناءٍ، وهي تُستخدَم عادةً لتوزيع البيانات على أعداد كبيرة من المستخدمين. وبهذه الطريقة، إذا كانت البيانات بحاجة إلى تعديل، يجب تغييرها في موقع المصدر فقط، ويستلم جميع المستخدمين البيانات المعدّلة تلقائيًا.

برمجة CGI لـ KML

بالإضافة إلى الإشارة إلى الملفات التي تحتوي على بيانات ثابتة، يمكن أن يشير <href> لرابط الشبكة إلى البيانات التي يتم إنشاؤها بطريقة ديناميكية—على سبيل المثال، بواسطة نص برمجي لـ CGI موجود على خادم شبكة. من خلال معرفة لغة برمجة نصية مثل PHP أو Python أو Perl، يمكنك إنشاء نص برمجي يوصل بثًا (أو ملفًا) من بيانات KML إلى كل رابط شبكة.

هناك أمران ضروريان لتسليم ملف KML عبر CGI للشبكة:

عند إجراء استدعاء من العميل (Google Earth) إلى الخادم، يجب على الخادم (1) عرض رمز استجابة HTTP 200 و (2) ضبط نوع محتوى الاستجابة على text/plain أو application/vnd.google-earth.kml+xml.

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

نصيحة: هناك طريقة بسيطة للتعامل مع الأخطاء وهي تحليل خطأ الخادم كنص لاسم مجلد. على سبيل المثال، يمكنك جعل الخادم يعرض <Folder><name>database inaccessible</name></Folder> كسلسلة. يكون ذلك أكثر فائدة (وأكثر سهولة في الاستخدام) من السماح بقطع الاتصال.

تستخدم الأمثلة التالية لغة Python، لكنها تكون صالحة في أي لغة برمجة نصية أخرى.

إنشاء علامة موضعية عشوائية

يُنشئ النص البرمجي Python التالي قيمًا عددية عشوائية لـ latitude وlongitude ثم يدرج تلك القيم في العنصر <coordinates> من <Point>. وكلما يتم تحديث رابط الشبكة، يتم تشغيل النص البرمجي Python مرة أخرى وإنشاء KML باستخدام قيم جديدة لخطوط الطول ودوائر العرض. 

#!/usr/bin/python

import random

latitude = random.randrange(-90, 90)
longitude = random.randrange(-180, 180)
kml = (
   '<?xml version="1.0" encoding="UTF-8"?>\n'
   '<kml xmlns="http://www.opengis.net/kml/2.2">\n'
   '<Placemark>\n'
   '<name>Random Placemark</name>\n'
   '<Point>\n'
   '<coordinates>%d,%d</coordinates>\n'
   '</Point>\n'
   '</Placemark>\n'
   '</kml>'
   ) %(longitude, latitude)
print 'Content-Type: application/vnd.google-earth.kml+xml\n'
print kml

في ما يلي مثال لملف KML يحتوي على رابط شبكة يحمِّل نص Python البرمجي هذا:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Folder>
    <name>Network Links</name>
    <visibility>0</visibility>
    <open>0</open>
    <description>Network link example 1</description>
    <NetworkLink>
      <name>Random Placemark</name>
      <visibility>0</visibility>
      <open>0</open>
      <description>A simple server-side script that generates a new random
        placemark on each call</description>
      <refreshVisibility>0</refreshVisibility>
      <flyToView>0</flyToView>
      <Link>
        <href>http://yourserver.com/cgi-bin/randomPlacemark.py</href>
      </Link>
    </NetworkLink>
  </Folder>
</kml>

استعلامات البحث المستندة إلى العرض

رابط الشبكة القياسي هو رابط أحادي الاتجاه؛ حيث تتدفق البيانات فقط من الخادم إلى Google Earth. يتيح التحديث المستند إلى العرض الاتصال ثنائي الاتجاه. عندما يكون التحديث المستند إلى العرض نشطًا، يعرض Google Earth إحداثيات العرض على الخادم في وقت محدد. وقد يكون هذا كل n ثانية أو دقيقة أو ساعة، أو بمجرد انقضاء مدة معينة من الوقت منذ توقف العرض. راجع <viewRefreshMode> في مرجع KML 2.2.

يتم عرض الإحداثيات إلى الخادم باستخدام HTTP GET لإلحاق الإحداثيات كما يلي (هذه هي معلومات مربع الإحاطة الافتراضي):

GET /path/to/server/script/query?BBOX=[longitude_west, latitude_south, longitude_east, latitude_north] HTTP/1.1

إذا تم إرسال الطلب بينما كان المستخدم ينظر لأسفل في الإسكندرية، فقد تظهر الإحداثيات على النحو التالي:

GET /path/to/server/script/query?BBOX=-122.497790,37.730385,-122.380087,37.812331 HTTP/1.1

يمكن استخدام هذه الميزة في بعض التطبيقات المبتكرة للغاية، ولكن للبدء، نقدم مثالاً بسيطًا أدناه.

تتبع نقطة تحت العرض مباشرة

يحلل نص Python البرمجي من جانب الخادم الرسالة المعروضة المُرسلة بواسطة Google Earth ويرد بعلامة موضعية في وسط الشاشة. في كل مرة يتم فيها تحديث رابط الشبكة، يتم إنشاء علامة موضعية جديدة. 

#!/usr/bin/python

import cgi

url = cgi.FieldStorage()
bbox = url['BBOX'].value
bbox = bbox.split(',')
west = float(bbox[0])
south = float(bbox[1])
east = float(bbox[2])
north = float(bbox[3])

center_lng = ((east - west) / 2) + west
center_lat = ((north - south) / 2) + south

kml = ( 
   '<?xml version="1.0" encoding="UTF-8"?>\n'
   '<kml xmlns="http://www.opengis.net/kml/2.2">\n'
   '<Placemark>\n'
   '<name>View-centered placemark</name>\n'
   '<Point>\n'
   '<coordinates>%.6f,%.6f</coordinates>\n'
   '</Point>\n'
   '</Placemark>\n'
   '</kml>'
   ) %(center_lng, center_lat)

print 'Content-Type: application/vnd.google-earth.kml+xml\n'
print kml

وإليك ملف KML لرابط الشبكة الذي يحمِّل النص البرمجي Python:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Folder>
    <name>Network Links</name>
    <visibility>0</visibility>
    <open>0</open>
    <description>Network link example 2</description>
    <NetworkLink>
      <name>View Centered Placemark</name>
      <visibility>0</visibility>
      <open>0</open>
      <description>The view-based refresh allows the remote server to calculate
         the center of your screen and return a placemark.</description>
      <refreshVisibility>0</refreshVisibility>
      <flyToView>0</flyToView>
      <Link>
        <href>http://yourserver.com/cgi-bin/viewCenteredPlacemark.py</href>
        <refreshInterval>2</refreshInterval>
        <viewRefreshMode>onStop</viewRefreshMode>
        <viewRefreshTime>1</viewRefreshTime>
      </Link>
    </NetworkLink>
  </Folder>
</kml>

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

3 أنواع KML MIME

عند الاستجابة لطلب من برنامج Google Earth (أو أي متصفح Earth)، يجب أن يتبع خادم KML مجموعة معينة من القواعد حتى يتمكن برنامج Google Earth من تفسير ردوده بشكل صحيح.

عند النجاح، يجب أن يعرض الخادم رمز استجابة HTTP 200 وتعيين نوع محتوى الاستجابة على نوع MIME مناسب، كما هو موضح هنا.

يقرأ برنامج Google Earth ملفات KML وKMZ. نوع MIME لملفات KML هو

  • application/vnd.google-earth.kml+xml

نوع MIME لملفات KMZ هو

  • application/vnd.google-earth.kmz

بالنسبة إلى Apache، أضف هذه الأسطر إلى ملف httpd.conf:

  • AddType application/vnd.google-earth.kml+xml .kml
  • AddType application/vnd.google-earth.kmz .kmz

اطلع على وثائق Microsoft للحصول على تفاصيل حول إعداد أنواع MIME على خادم IIS التابع لشركة Microsoft.

يجب أن يحتوي نص الاستجابة على بيانات KML صالحة، بما في ذلك إعلان XML (<?xml version="1.0" encoding="UTF-8"?>). إذا كان الخادم يعرض ملف KML غير صالح، فسيوقف رابط الشبكة رسالة إلغاء تنشيطه أو يعطلها أو يُخرجها.

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

هل أنت مستعد للمزيد؟ راجع دليل المطور، الذي يصف ميزات KML الرئيسية. ويمكنك أيضًا تصفُّح مرجع KML للحصول على معلومات عن عناصر معيّنة.