KML Reference в Delphi по-русски #1: Базовые классы для работы с метками

В последнее время занимаюсь разработкой небольшой программы для визуализации различной географической информации — отдельных точек на карте, областей, путей подъезда и так далее. Для этих целей разрабатывается модуль в Delphi основная задача которого — создание kml-файла, который можно импортировать в тот же Google Maps или Google Earth. Для разработки модуля используется документация Google — KML Reference. В этом цикле статей я буду постепенно рассказывать о том, как происходит разработка модуля, какие «подводные камни» могут встретиться при работе с KML и так далее.

В связи с тем, что тема работы с KML достаточно обширная, в этой статье не будет готовых примеров работы с KML — я лишь дам описание необходимых классов для работы с KML в Delphi. Однако, в дальнейшем, я буду ссылаться на эту статью, чтобы лишний раз не дублировать описание свойств элементов.

Общие сведения о KML

KML (Keyhole Markup Language) — язык разметки на основе XML для представления трёхмерных геопространственных данных в программе «Google Планета Земля».

Сейчас kml-файлы используются не только в Google Earth, но и, например, в таких Российских системах, как Публичная Кадастровая Карта (для импорта/экспорта информации) и других продуктах, использующих в своей работе географическую информацию.

По своей структуре, kml-файл — это обычный xml, сформированный по определенным правилам, которые прописаны в документа KML Referense. Поэтому, для тех, кто достаточно хорошо знаком с XML в Delphi не составит особого труда быстро научиться создавать kml-файлы. Я же, в свою очередь, не буду углубляться в основы работы с XML в Delphi, а буду на конкретных примерах показывать то, как создавать KML в Delphi и отображать всю информацию в Google Earth.

Иерархия элементов в KML представлена на рисунке ниже.

(с) Google KML Reference

Прямоугольниками выделены абстрактные элементы, которые непосредственно в kml-файл не включаются, однако они позволяют нам понять какие из элементов содержат одни и те же свойства. Например, Geometry — абстрактный элемент, свойства которого встречаются в таких элементах KML как Point (точка), Polygon (полигон) и так далее.

Базовые классы Delphi для работы с метками в KML

Поставить метку на карте — это одна из самых простых задач для пользователя. Однако для разработчика поставить метку — означает создание сразу нескольких классов, каждый из которых наследует какие-либо свойства от своих родителей.

Смотрим описание элемента «Placemark» в KML Reference:

Описание элемента Placemark

Как можно видеть в описании, практически все свойства Placemark наследуются от элемента Feature, а сам элемент Feature прямой наследник от Object.

Специфическим для Placemark является только последнее свойство элемента — Geometry, которое должно содержать, судя по описанию 0 или 1 геометрический элемент. Однако, несмотря на то, что KML Reference не конкретизирует, какой именно элемент может выступать в качестве Geometry (Point, LineString и т.д.), могу сказать, что единственный подходящий для нас элемент — точка (Point).

Таким образом, чтобы в дальнейшем, при добавлении в наш модуль дополнительных классов и методов работы с kml в delphi, нам не приходилось каждый раз переписывать классы и плодить лишние свойства, нам необходимо создать следующие классы:

1. Базовый Object (назовем его TKmlObject)
2. Feature — класс со свойствами общими для всех «фич»
3. Geometry — класс со свойствами общими для всех геометрических элементов
4. Point — класс описывающий одну точку
5. Placemark — класс описывающий одну метку.

Также, дополнительно создадим класс, который будет содержать координаты (широту, долготу и высоту над уровнем моря).

Базовый класс TKmlObject содержит всего два свойства:

TKmlObject = class
  private
    FId: string;
    FTargetId: string;
  public
    property Id: string read FId write FId;
    property TargetId: string read FTargetId write FTargetId;
  end;

Что касается вспомогательного класса для описания координат точки, то в Google Earth любая точка может описываться тремя координатами: широта, долгота и высота над уровнем моря. Поэтому наш вспомогательный класс для хранения координат будет выглядеть следующим образом:

TKmlCoordinate = class
  private
    FLatitude: single;
    FLongtitude: single;
    FAltitude: single;
  public
    property Latitude: single read FLatitude write FLatitude;
    property Longtitude: single read FLongtitude write FLongtitude;
    property Altitude: single read FAltitude write FAltitude;
  end;

Следующий класс — TKmlFeature. У этого класса свойств намного больше:

TKmlFeature = class(TKmlObject)
  private
    FName: string;
    FVisibility: boolean;
    FOpen: boolean;
    FAuthor: string;
    FLink: string;
    FAddress: string;
    FAddressDetails: string;
    FPhoneNumber: string;
    FSnippet: string;
    FDescription: string;
    FStyleUrl: string;
    FStyleSelector: string;
    FRegion: string;
    FExtendedData: string;
  public
    property Name: string read FName write FName;
    property Visibility: boolean read FVisibility write FVisibility;
    property Open: boolean read FOpen write FOpen;
    property Author: string read FAuthor write FAuthor;
    property Link: string read FLink write FLink;
    property Address: string read FAddress write FAddress;
    property AddressDetails: string read FAddressDetails write FAddressDetails;
    property PhoneNumber: string read FPhoneNumber write FPhoneNumber;
    property Snippet: string read FSnippet write FSnippet;
    property Description: string read FDescription write FDescription;
    property StyleUrl: string read FStyleUrl write FStyleUrl;
    property StyleSelector: string read FStyleSelector write FStyleSelector;
    property Region: string read FRegion write FRegion;
    property ExtendedData: string read FExtendedData write FExtendedData;
  end;

Свойство	Тип	Описание	Пример в Google Earth
Name	string	Пользовательский текст, используемый в качестве метки для объекта
Visibility	boolean	Указывает, отображается ли элемент в средстве трехмерного просмотра при его первоначальной загрузке. 1 — элемент отображается, 0 — элемент будет скрыт
Open	boolean	Указывает, будет ли документ или папка закрытыми или открытыми при первой загрузке на панель «Метки». 0 = свернуто (по умолчанию), 1 = развернуто. Этот элемент применяется только к Document, Folder и NetworkLink.
Author	string	Информация об авторе. Отображается в результатах поиска
Link	string	Определяет URL веб-сайта, содержащего этот файл KML или KMZ.
Address	string	Строковое значение, представляющее собой неструктурированный адрес, записанный в виде улицы, города, адреса штата и/или почтового индекса. Address может использоваться для для указания местоположения точки вместо использования координат широты и долготы. Однако, если указан элемент Point, то он имеет приоритет Address.
AddressDetails	string	Структурированный адрес, отформатированный как xAL
PhoneNumber	string	Строковое значение, представляющее номер телефона. Этот элемент используется только в Google Maps Mobile.
Snippet	string	Краткое описание элемента на карте. В Google Earth это описание отображается на панели «Метки» под названием функции. Если фрагмент не предоставлен, используются первые две строки из Description. Это свойство не поддерживает разметку HTML.
Description	string	Полное описание элемента. Поддерживается HTML и JavaScript
StyleUrl	string	Ссылка на элемент Style или StyleMap, которые используются для задания элементам различных визуальных свойств (цвет, толщина линии, иконка и т.д.)
StyleSelector	string	Определяет локальный стиль для элемента (об этом поговорим в следующих статьях)
Region	string	Используется для указания принадлежности элемента определенной области
ExtendedData	string	Позволяет добавлять пользовательские данные в файл KML. Эти данные могут быть (1) данными, которые ссылаются на внешнюю XML-схему, (2) нетипизированными парами данных / значений или (3) типизированными данными. Данная функция KML может содержать комбинацию этих типов пользовательских данных.

Класс TKmlGeometry, описывающий какой-либо геометрический объект на карте, по сути является тем же TKmlObject:

TKmlGeometry = class(TKmlObject);

А вот наследник TKmlGeometry — TKmlPoint уже содержит свои собственные свойства:

TAltitudeModeEnum = (amClampToGround, amRelativeToGround, amAbsolute);
TKmlPoint = class(TKmlGeometry)
  private
    FExtrude: boolean;
    FAltitudeMode:TAltitudeModeEnum;
    FCoordinates: TKmlCoordinate;
  public
    constructor Create;
    destructor Destroy;override;
    property Extrude: boolean read FExtrude write FExtrude;
    property AltitudeMode:TAltitudeModeEnum read FAltitudeMode write FAltitudeMode;
    property Coordinates: TKmlCoordinate read FCoordinates;
  end;

Для типа данных TAltitudeModeEnum определены следующие значения:

• amClampToGround — точка будет лежать на земной поверхности
• amRelativeToGround — устанавливает высоту элемента относительно фактического уровня земли определенного места. Например, если высота места местоположения находится точно на уровне моря, а высота для точки установлена ​​на 9 метров, то для этого режима высота метки составит 9 метров. Однако если такая же координата установлена ​​для местоположения, где высота над уровнем моря составляет 10 метров, то высота метки составит 19 метров;
• amAbsolute — Устанавливает высоту метки относительно уровня моря, независимо от фактической высоты местности под элементом. Например, если вы установите высоту метки в 10 метров в режиме абсолютной высоты, значок метки точки будет отображаться на уровне земли, если местность находится на 10 метров над уровнем моря. Если местность находится на высоте 3 метра над уровнем моря, метка будет отображаться над земной поверхностью на 7 метров.

И, наконец, наш целевой класс — TKmlPlacemark будет выглядеть следующим образом:

TKmlPlacemark = class(TKmlFeature)
  private
    FPoint: TKmlPoint;
  public
    constructor Create;
    destructor Destroy;override;
    property Point: TKmlPoint read FPoint;
  end;

Таким образом, мы создали необходимые классы Delphi с помощью которых мы можем описать всего лишь одну метку на карте Google Earth. Как я сказал в начале статьи, эта статья не будет содержать примеров использования KML в Delphi, однако, в следующей статье мы рассмотрим работающий пример Delphi, с помощью которого можно поставить на карту несколько меток, дать им описание (в том числе с использованием HTML) и так далее.

Следующая статья: «KML Reference в Delphi по-русски #2: Ставим метку на карте»

Книжная полка

	Автор: Дмитрий Осипов Название: Delphi. Программирование для Windows, OS X, iOS и Android Описание Подробно рассматривается библиотека FM, позволяющая создавать полнофункциональное программное обеспечение для операционных систем Windows и OS X, а также для смартфонов и планшетных компьютеров, работающих под управлением Android и iOS
	Автор: Андрей Шкрыль Название: Разработка клиент-серверных приложений в Delphi Описание: Рассмотрены практические вопросы по разработке клиент-серверных приложений в среде Delphi 7 и Delphi 2005 с использованием СУБД MS SQL Server 2000, InterBase и Firebird. Приведена информация о теории построения реляционных баз данных и языке SQL. Освещены вопросы эксплуатации и администрирования СУБД.
	Автор: Антон Григорьев Название: О чем не пишут в книгах по Delphi Описание: Рассмотрены малоосвещенные вопросы программирования в Delphi. Описаны методы интеграции VCL и API. Показаны внутренние механизмы VCL и приведены примеры вмешательства в эти механизмы. Рассмотрено использование сокетов в Delphi: различные режимы их работы, особенности для протоколов TCP и UDP и др.