Справочное руководство по KML 2.1

Это руководство познакомит вас с новыми функциями KML 2.1. Можете начать с краткого обзора, загрузив примеры по ссылкам ниже в Google Планету Земля. Чтобы подробнее изучить новые элементы KML и лучше понять их возможности, внимательно читайте текст и рассматривайте картинки. Надеемся, что вскоре вы начнете применять эти функции на практике. Подробные сведения можно найти в Справке по KML 2.1 и Схеме KML 2.1.

Основные нововведения в KML 2.1

• Регионы позволяют настроить разные уровни детализации для отображения данных в Google Планете Земля. В сочетании с сетевыми ссылками регионы обеспечивают потоковую передачу больших объемов информации, причем чем ближе компонент находится к пользователю, тем больше деталей загружается и отображается (подробные сведения приведены в разделе Фрагментированные изображения). С помощью регионов можно также эмулировать слои Google Планеты Земля.
• Текстурированные трехмерные модели можно создавать в собственном координатном пространстве и сохранять как файлы COLLADA™, которые затем импортируются в Google Планету Земля и размещаются на местности.
• Постепенные обновления данных, загружаемых по сетевым ссылкам, позволяют изменять, добавлять и удалять содержание KML, которое уже загружено в Google Планету Земля.
• Время и дата устаревания данных, указываемые в формате dateTime, помогают периодически очищать кэш и обеспечивают актуальность содержания.
• Переключатели в папках служат для того, чтобы пользователь мог выбрать только один элемент в папке. Для этого воспользуйтесь новым элементом <ListStyle> и задайте параметр radioFolder.

Интересные примеры

• Примеры простых регионов
• Импорт исторических изображений: ортофотоплан Маунтин-Вью 1991 года (крупное изображение разделено на фрагменты, которые загружаются по сетевым ссылкам)
• Университетская достопримечательность (текстурированная трехмерная модель COLLADA, созданная в SketchUp)
• Динамические обновления сетевых ссылок
• Принудительное обновление данных в заданный день или время (используются новые возможности определения срока действия данных)
• Папки с переключателями

Технические спецификации

Ниже перечислены новые элементы, которые появились в KML 2.1.

<Change> <Create> <Delete> <expires> <LatLonAltBox> <listItemType> <ListStyle> <Location> <maxLodPixels>

<minLodPixels> <Orientation> <Lod> <Model> <Region> <Scale> <targetHref> <Update>

Использование регионов

С помощью регионов можно загружать в Google Планету Земля большие объемы информации без ущерба производительности. Данные отображаются, только если попадают в поле обзора пользователя и занимают достаточно места на экране. Регионы позволяют создать несколько вариантов одних и тех же данных с разным разрешением, чтобы загружать более подробные только тогда, когда пользователь будет способен различить детали.

Примечание. Некоторые классы в KML являются производными от т. н. родительского класса. Они наследуют все его элементы, а также имеют свои собственные, уникальные элементы. Этот принцип характерен для объектно-ориентированных систем в целом. Для удобства в этом разделе мы будем говорить о родительском классе, чтобы не перечислять все производные. Приведем несколько примеров.

• Термин компонент описывает любой элемент KML, являющийся производным от <Feature>: Document, Folder, GroundOverlay, NetworkLink, Placemark или ScreenOverlay.
• Термин геометрия описывает любой геометрический элемент KML: Point, Polygon, LinearRing, LineString, Model или MultiGeometry.
• Термин наложение описывает любой элемент, производный от Overlay: GroundOverlay или Screen Overlay.

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

Ключевые понятия

Регион (компонент Region) можно включить в любой компонент KML. Регионы влияют на отображение меток и наложений, а также позволяют задать качество обработки и уровень детализации соответствующего геометрического объекта или наложенного изображения. Регионы наследуются согласно иерархии KML и влияют на отображение компонентов, расположенных ниже в иерархии.

Ниже перечислены ключевые понятия, относящие к регионам, которые рассматриваются в этом разделе.

• Куб выделения
• Уровень детализации
• Высота
• Степень прозрачности
• Вложенные регионы
• Сетевые ссылки на основе регионов

Куб выделения

Регион содержит элемент <LatLonAltBox>, который определяет куб выделения данных. Кубом выделения называется трехмерная область, содержащая некий набор объектов или точек. Подобно <LatLonBox> в GroundOverlay, <LatLonAltBox> имеет северную, южную, восточную и западную границы. Если регион содержит трехмерные данные либо двухмерные данные на заданной высоте, то для <LatLonAltBox> также необходимо указать минимальную и максимальную высоту (<minAltitude> и <maxAltitude>).

Включенные в куб выделения объекты отрисовываются, когда регион становится виден пользователю либо когда размер проекции <LatLonAltBox> на экран отвечает пиксельному диапазону данного региона (подробные сведения приведены в разделе Уровень детализации). Если оба условия соблюдены, регион называется активным.

Уровень детализации

Другое важное понятие, связанное с регионами, – это уровень детализации. Поскольку количество пикселей на экране компьютера ограничено, имеет смысл организовать данные так, чтобы они загружались, только если достаточно места для их правильного отображения достаточно. Если регион занимает относительно малую часть экрана (например, потому что пользователь находится далеко или потому что двухмерное изображение просматривается под углом), высокий уровень детализации не требуется. Данные с более низким разрешением загружаются быстрее, а пользователь при этом не заметит разницы.

Элементы <minLodPixels> и <maxLodPixels> компонента Region служат для определения области экрана в квадратных пикселях. Чтобы данные были отображены на экране, занимаемая ими область должна быть больше значения <minLodPixels>, но меньше <maxLodPixels>. Как только регион выходит за эти границы, он перестает быть видимым и становится неактивным.

Если необходимо, чтобы регион оставался активным при любых размерах, укажите для <maxLodPixels> значение -1.

Пример 1: определение региона для наложения на земную поверхность

Начнем с простого примера, в котором регион создается для двухмерного наложения на земную поверхность. Для этих целей используется исторический ортофотоплан части города Маунтин-Вью в Калифорнии, сделанный в 1991 году. Наложение становится видно по мере увеличения масштаба. Ниже показано, как оно выглядит при первом приближении (для наглядности в файл добавлен компонент LineString – белая линия, очерчивающая границы наложения).

В этом примере значение <minLodPixels> равно 128, т. е. наложение отображается, если оно занимает хотя бы 128 квадратных пикселей. (Для <maxLodPixels> выбрано значение -1, чтобы наложение, просматриваемое под данным углом, оставалось видимым при любом масштабе). Используемое изображение представляет собой прямоугольник площадью 256 квадратных пикселей.

Вот как выглядит наложение, когда пользователь приближается к нему:

А так оно выглядит, когда занимает область экрана, площадь которой почти равна значению <minLodPixels> (если уменьшить площадь ещё немного, наложение исчезнет):

В данном случае в элемент <LatLonAltBox> не обязательно включать атрибуты <minAltitude> и <maxAltitude>, так как изображение двухмерное и расположено на земной поверхности. Куб выделения определяется элементом <LatLonAltBox> региона и равен размеру <LatLonBox> наложения, как показано в KML-коде ниже.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.1">
 <Document>
 <name>Flat Region</name>
 <Region>
 <LatLonAltBox>
 <north>37.430419921875</north>
 <south>37.41943359375</south>
 <east>-122.080078125</east>
 <west>-122.091064453125</west>
 </LatLonAltBox>
 <Lod>
 <minLodPixels>128</minLodPixels>
 </Lod>
 </Region>
 <GroundOverlay>
 <name>Mountain View DOQQ</name>
 <Icon>
 <href>files/image.JPEG</href>
 </Icon>
 <LatLonBox>
 <north>37.430419921875</north>
 <south>37.41943359375</south>
 <east>-122.080078125</east>
 <west>-122.091064453125</west>
 </LatLonBox>
 </GroundOverlay> <Document> </kml>

Обратите внимание на то, что в KML-файле компонент Region находится на том же иерархическом уровне, что и накладываемое изображение (геометрический объект), отображением которого он управляет.

После того как вы изучите KML-код, загрузите изображение в Google Планету Земля по ссылке ниже. Рассмотрите его с разных ракурсов, следя за тем, в какой момент регион появляется и исчезает в зависимости от занимаемой им части экрана: если сильно наклонить или отдалить изображение, оно будет скрыто, так как его площадь станет меньше значения <minLodPixels>.

Файл для загрузки в Google Планету Земля (historicOverlay.kmz)

Высота

Пример 2: определение региона для трехмерной модели

В этом примере показано, как создать регион для трехмерного объекта, размещенного на земной поверхности. В элементе <LatLonAltBox> этого региона для <maxAltitude> задано значение 300 метров, равное высоте здания. Само здание – это штаб-квартира ООН в Нью-Йорке.

Обратите внимание на то, что границы <LatLonAltBox> региона могут не совпадать с границами модели, определенными широтой и долготой. Координаты модели рассчитываются относительно ее собственного начала координат, которое может отличаться от ее фактического расположения на Земле.

<?xml version='1.0' encoding='UTF-8'?>
<kml xmlns="http://earth.google.com/kml/2.1">
 <Document>
 <name>3D Region on ground</name>
 <Placemark>
 <name>United Nations Headquarters</name>
 <visibility>0</visibility>
 <Region>
 <Lod>
 <minLodPixels>128</minLodPixels>
 </Lod>
 <LatLonAltBox>
 <north>40.750683130314</north>
 <south>40.748162385230</south>
 <east>-73.966608428427</east>
 <west>-73.969476624071</west>
 <minAltitude>0</minAltitude>
 <maxAltitude>300</maxAltitude>
 <altitudeMode>absolute</altitudeMode>
 </LatLonAltBox>
 </Region>
 <Model>
 <altitudeMode>absolute</altitudeMode>
 <Location>
 <longitude>-73.967763927199</longitude>
 <latitude>40.749458312255</latitude>
 <altitude>0.406173708576</altitude>
 </Location>
 <Link>
 <href>models/un.dae</href>
 </Link>
 </Model>
 </Placemark>
 </Document>
</kml>

Загрузите файл в Google Планету Земля по ссылке ниже. Рассмотрите модель с разных ракурсов и обратите внимание на то, при каких обстоятельствах она исчезает с экрана.

Файл для загрузки в Google Планету Земля (unitedNations.kmz)

Пример 3: определение региона для двухмерного наложения, расположенного над земной поверхностью

В этом примере рассматривается двухмерное наложение, расположенное на некоторой высоте над земной поверхностью. Эта техника подходит, в частности, для отображения атмосферных фронтов или маршрутов самолетов. Мы рассмотрим небольшое облако, находящееся на высоте 100 000 метров над уровнем моря.

Для атрибутов <minAltitude> и <maxAltitude> элемента <LatLonAltBox> задано одинаковое значение – 100 000 метров, так как облако двухмерное (его толщина равна нулю). Значение <altitudeMode> – absolute, т. е. высота отсчитывается от уровня моря.

Обратите внимание на то, что значение <altitude> накладываемого изображения (компонента GroundOverlay) также равно 100 000 и совпадает с высотой куба выделения региона (компонента Region). Значение <altitudeMode> одинаково для обоих компонентов.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.1">
 <Document>
 <name>Flat Region at altitude</name>
 <GroundOverlay>
 <name>Cloud overlay</name>
 <Region>
 <LatLonAltBox>
 <north>33.75</north>
 <south>22.5</south>
 <east>-45</east>
 <west>-56.25</west>
 <minAltitude>100000</minAltitude>
 <maxAltitude>100000</maxAltitude>
 <altitudeMode>absolute</altitudeMode>
 </LatLonAltBox>
 <Lod>
 <minLodPixels>128</minLodPixels>
 </Lod>
 </Region>
 <Icon>
 <href>files/image.PNG</href>
 </Icon>
 <altitude>100000</altitude>
 <altitudeMode>absolute</altitudeMode>
 <LatLonBox>
 <north>33.75</north>
 <south>22.5</south>
 <east>-45</east>
 <west>-56.25</west>
 </LatLonBox>
 </GroundOverlay>
 </Document>
</kml>

Файл для загрузки в Google Планету Земля cloudRegion.kmz)

Степень прозрачности

Для региона можно задать степень прозрачности, чтобы он появлялся и исчезал постепенно. В Google Планете Земля предусмотрены атрибуты maxFadeExtent и minFadeExtent, определяющие степень прозрачности, когда регион достигает соответственно максимального и минимального видимого размера. Задавать диапазоны прозрачности не обязательно, однако они позволяют избежать эффекта внезапно появляющихся и исчезающих линий и многоугольников разного разрешения. Обработка прозрачности требует значительных вычислительных ресурсов, поэтому эту технику не рекомендуется применять к изображениям.

Примечание. Диапазон прозрачности применим ко всем объектам, кроме значков меток – они отображаются, когда значение диапазона превышает 0,5.

 

Ниже показано, как степень прозрачности влияет на отображение ломаной линии (компонента LineString).

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.1">
<Document>
 <name>Region in Placemark LineString</name>
 <description>
 The LineString corners mark the extent
 of the Region LatLonAltBox.
 The LineString minFadeExtent (at greatest range)
 is 1/4 of the maxFadeExtent (at closest range)..
 </description>
 <Placemark>
 <name>Region LineString</name>
 <LineString>
 <coordinates>
 22,50,0
 28,50,0
 28,45,0
 22,45,0
 22,50,0
 </coordinates>
 </LineString>
 <Region> 
 <LatLonAltBox> 
 <north>50</north> 
 <south>45</south> 
 <east>28</east> 
 <west>22</west> 
 </LatLonAltBox> 
 <Lod>
 <minLodPixels>128</minLodPixels> 
 <maxLodPixels>1024</maxLodPixels> 
 <minFadeExtent>128</minFadeExtent>
 <maxFadeExtent>512</maxFadeExtent>
 </Lod>
 </Region> 
 </Placemark>
</Document>
</kml>

Файл для загрузки в Google Планету Земля (fadeLineString.kml)

Вложенные регионы

Для каждого из вложенных регионов можно установить собственное разрешение. Как правило, чем меньше регион, тем оно выше. Этот принцип схематически представлен ниже: каждый регион имеет свой уровень детализации, выраженный размером области экрана (в пикселях), которую он должен занимать, чтобы быть активным. По мере увеличения масштаба становятся активны регионы с более высоким уровнем детализации, поскольку они занимают на экране больше места. При этом они замещают загруженные ранее регионы с более низким разрешением.

Когда становится активен очередной регион в последовательности, происходит следующее:

• ему передаются данные, связанные с каждым регионом (как в описанном ниже примере фрагментированного изображения);
• данные загруженного ранее региона замещаются новыми (как показано на схеме выше).

Значение <LatLonAltBox> дочернего компонента Region не должно превышать значение <LatLonAltBox> родительского компонента Region. Регионы наследуются согласно иерархии Folder и NetworkLink. Локально определенные регионы имеют приоритет перед регионами, расположенными выше в иерархии. Этот принцип можно наблюдать в приведенном ниже примере кода, где метка ukraineRegion наследует регион от его родительского компонента Document. Папка romaniaFolder задает собственный регион, который используется меткой romaniaRegion. Дополнительные примеры использования регионов с сетевыми ссылками приведены ниже в разделе Интеллектуальная загрузка данных по сетевым ссылкам на основе регионов.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.1">
<Document>
 <name>Nested Regions</name> <Region> <LatLonAltBox> <north>56.25</north> <south>45</south> <east>33.75</east> <west>22.5</west> </LatLonAltBox> <Lod> <minLodPixels>128</minLodPixels> <maxLodPixels>1024</maxLodPixels> </Lod> </Region> <Placemark> <name>ukraineRegion</name> <LineString> <tessellate>1</tessellate> <coordinates> 22.5,45,0 33.75,45,0 33.75,56.25,0 22.5,56.25,0 22.5,45,0 </coordinates> </LineString> </Placemark> <Folder> <name>romaniaFolder</name> <Region> <LatLonAltBox> <north>50.625</north> <south>45</south> <east>28.125</east> <west>22.5</west> </LatLonAltBox> <Lod> <minLodPixels>128</minLodPixels> <maxLodPixels>1024</maxLodPixels> </Lod> </Region> <Placemark> <name>romaniaRegion</name> <LineString> <tessellate>1</tessellate> <coordinates> 22.5,45,0 28.125,45,0 28.125,50.625,0 22.5,50.625,0 22.5,45,0 </coordinates> </LineString> </Placemark> </Folder> </Document> </kml>

Интеллектуальная загрузка данных по сетевым ссылкам на основе регионов

Загрузка файлов по сетевым ссылкам на основе регионов, проиллюстрированная в предыдущем примере, представляет собой оптимальный способ отображения больших объемов данных в Google Планете Земля. При совместном использовании регионов и сетевых ссылок можно создать иерархию указателей, каждый из которых ссылается на определенный субрегион. Как показано в KML-коде ниже, если задать для элемента <viewRefreshMode> параметр onRegion, содержание региона загружается, только когда он активен. При наличии вложенных регионов с разными уровнями детализации дополнительные данные загружаются, только если того требует изменившаяся точка обзора. Этот принцип подробно описан ниже в разделе Фрагментированные накладываемые изображения.

Часть 1: родительский файл

Чтобы запустить этот пример, сохраните первую часть стандартным образом. Вторую часть сохраните под названием romaniaRegion.kml, чтобы регион загружался по сетевой ссылке, когда он станет активен.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.1">
<Document>
 <name>Nested Regions</name> <Region> <LatLonAltBox> <north>56.25</north> <south>45</south> <east>33.75</east> <west>22.5</west> </LatLonAltBox> <Lod> <minLodPixels>128</minLodPixels> <maxLodPixels>1024</maxLodPixels> </Lod> </Region> <Placemark> <name>ukraineRegion</name> <LineString> <tessellate>1</tessellate> <coordinates> 22.5,45,0 33.75,45,0 33.75,56.25,0 22.5,56.25,0 22.5,45,0 </coordinates> </LineString> </Placemark> <NetworkLink> <name>romania NetworkLink</name> <Region> <LatLonAltBox> <north>50.625</north> <south>45</south> <east>28.125</east> <west>22.5</west> </LatLonAltBox> <Lod> <minLodPixels>128</minLodPixels> <maxLodPixels>1024</maxLodPixels> </Lod> </Region> <Link> <href>romaniaRegion.kml</href> <viewRefreshMode>onRegion</viewRefreshMode> </Link> </NetworkLink> </Document> </kml>

Часть 2: файл с сетевыми ссылками на основе регионов

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.1">
<Document>
 <name>romania Document</name>
 <Region>
 <LatLonAltBox> <north>50.625</north> <south>45</south> <east>28.125</east> <west>22.5</west> </LatLonAltBox>
 <Lod> <minLodPixels>128</minLodPixels> <maxLodPixels>1024</maxLodPixels> </Lod>
 </Region> <Placemark> <name>romaniaRegion</name> <LineString> <tessellate>1</tessellate> <coordinates> 22.5,45,0
 28.125,45,0 28.125,50.625,0 22.5,50.625,0 22.5,45,0 </coordinates> </LineString> </Placemark>
</Document>
</kml>

Фрагментированные накладываемые изображения

В: Можно ли опубликовать в общем доступе изображение размером 47 МБ?
О: Можно, но по частям.

В: Что случится, если все начнут так делать?
О: Если использовать сетевые ссылки на основе регионов и обеспечить разные уровни детализации изображения, то все будет в порядке.

Этот раздел посвящен созданию фрагментированного изображения, которое представляет собой иерархию регионов и сетевых ссылок для эффективной загрузки больших объемов графических данных. Изображение загружается по частям в виде фрагментов с соответствующим уровнем детализации: какой смысл показывать картинку размером 7008х6720 пикселей на экране с разрешением 1024х768? Более того, если пользователь находится на высоте нескольких километров над землей, данные придется сжать до размера нескольких пикселей, что отрицательно отразится на производительности. Фрагментированные изображения (такие как ортофотоплан Маунтин-Вью 1991 года) позволяют эффективно использовать сетевые ссылки, чтобы определять, находится ли данный регион в пределах видимости и отвечает ли размер его проекции текущей точке обзора. Если регион активен (т. е. выполняются оба условия), по сетевой ссылке загружаются связанные с ним данные; в противном случае этого не происходит. Если представить исходное изображение в виде иерархии фрагментов с разным уровнем детализации, будут загружаться фрагменты, отвечающие текущей точке обзора.

Чтобы увидеть иерархию в действии, загрузите файл с ортофотопланом в Google Планету Земля и попробуйте приближать и отдалять его.

 

Пример использования сетевых ссылок на основе регионов для загрузки больших объемов данных. Размер исходного изображения – 7008х6720 пикселей. Когда изображение просматривается под углом, как показано на рисунке, загружается лишь пять небольших фрагментов (их границы обозначены белыми линиями). В примере используется исторический ортофотоплан города Маунтин-Вью в Калифорнии за 1991 год.

Подготовка фрагментированных изображений к публикации

В нашем примере исходный ортофотоплан Маунтин-Вью разделен на сотни меньших наложений (компонентов GroundOverlay). Эти наложения – фрагменты – организованы на пяти уровнях иерархии. Для простоты в примере используется всего 21 изображение и три уровня иерархии, но принцип идентичен. Обратите внимание на то, что это лишь один из подходов к созданию иерархии сетевых ссылок на основе регионов; существуют и другие.

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

1. Подготовьте изображения, разделив их на меньшие фрагменты (рекомендуемый размер – 256х256 пикселей).
2. Создайте KML-файлы, в которых определены регионы, ссылки, сетевые ссылки и, в данном случае, наложения на земную поверхность.

Подготовка изображений

Создайте фрагменты стандартного размера с разным разрешением (фрагменты загружаются в Google Планету Земля по мере того, как становятся активны связанные с ними регионы). В нашем примере используется размер 256х256 пикселей, который достаточно удобен для обработки.

1. Начните с исходного изображения с максимальным разрешением. Разделите его на n фрагментов, а результат затем разделите ещё на n фрагментов.
   Повторяйте эти действия, пока не получите фрагменты заданного размера (в нашем случае это 256х256 пикселей).
   
   Предположим, размер исходного изображения – 1024х1024 пикселей.
   Ниже показана иерархия, которая получится после его фрагментирования.

 

 

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

 

На схеме показано, как именно точка обзора и уровень детализации вложенных регионов определяют, какие фрагменты загружать. Здесь показаны три уровня детализации. Когда пользователь просматривает местность с большого расстояния, отображается самый маленький вариант. Он занимает целый куб LatLonAltBox, но так как размер его проекции составляет всего 256 квадратных пикселей, пользователь не заметит отсутствия мелких деталей. По мере приближения точки обзора регион делится на четыре фрагмента, каждый из которых имеет тот же размер, что и самый маленький вариант изображения.

При дальнейшем приближении становятся видны фрагменты с максимальным разрешением. Их отображение зависит от того, на каком расстоянии находится пользователь: удаленные области по-прежнему содержат загруженные ранее фрагменты с более низким разрешением. В примере ортофотоплана Маунтин-Вью включите кубы выделения и изучите метки A и B. Вы увидите, что одновременно используются фрагменты, относящиеся к разным уровням иерархии (они обведены белыми линиями).

Обратите внимание на то, что значения <minLodPixels> и <maxLodPixels> для всех регионов на всех уровнях иерархии одинаковы. То, какие именно фрагменты и с какого уровня иерархии следует загружать, определяется элементом <LatLonAltBox>.

Подготовка KML-файлов

Подготовьте для каждого изображения KML-файл, связывающий наложенное изображение с регионом и сетевой ссылкой. Каждый такой файл должен содержать следующие компоненты:

• компонент Region (с элементами <LatLonAltBox>, <minLodPixels> и <maxLodPixels>), на основе которого определяется, активен ли тот или иной регион в данный момент времени;
• набор сетевых ссылок (компонентов NetworkLink), указывающих на дочерние файлы, т. е. фрагменты на следующем уровне иерархии;
• накладываемое изображение для данного региона.

В примере показан KML-файл верхнего уровня для ортофотоплана Маунтин-Вью. Значение <maxLodPixels> равно -1, т. е. регион остается активным даже при максимальном приближении. Если не задать такое значение, иерархия может не быть загружена вовсе.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.1">
 <NetworkLink>
 <name>SuperOverlay: MV DOQQ</name>
 <Region>
 <LatLonAltBox>
 <north>37.44140625</north>
 <south>37.265625</south>
 <east>-121.9921875</east>
 <west>-122.16796875</west>
 </LatLonAltBox>
 <Lod>
 <minLodPixels>128</minLodPixels>
 <maxLodPixels>-1</maxLodPixels>
 </Lod>
 </Region>
 <Link>
 <href>http://mw1.google.com/mw-earth-vectordb/kml-samples/mv-070501/1.kml</href>
 <viewRefreshMode>onRegion</viewRefreshMode>
 </Link>
 </NetworkLink>
</kml>

В примере кода ниже представлен регион ортофотоплана (179.kml). Этот файл содержит пять тегов href, четыре из которых указывают на KML-файлы на следующем уровне иерархии изображений, а ещё один – на файл накладываемого изображения.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.1">
 <Document>
 <Region>
 <Lod>
 <minLodPixels>128</minLodPixels><maxLodPixels>-1</maxLodPixels>
 </Lod>
 <LatLonAltBox>
 <north>37.430419921875</north><south>37.41943359375</south>
 <east>-122.091064453125</east><west>-122.10205078125</west>
 </LatLonAltBox>
 </Region>
 <NetworkLink>
 <name>001120</name>
 <Region>
 <Lod>
 <minLodPixels>128</minLodPixels><maxLodPixels>-1</maxLodPixels>
 </Lod>
 <LatLonAltBox>
 <north>37.430419921875</north><south>37.4249267578125</south>
 <east>-122.0965576171875</east><west>-122.10205078125</west>
 </LatLonAltBox>
 </Region>
 <Link>
 <href>180.kml</href>
 <viewRefreshMode>onRegion</viewRefreshMode>
 </Link>
 </NetworkLink>
 <NetworkLink>
 <name>001121</name>
 <Region>
 <Lod>
 <minLodPixels>128</minLodPixels><maxLodPixels>-1</maxLodPixels>
 </Lod>
 <LatLonAltBox>
 <north>37.430419921875</north><south>37.4249267578125</south>
 <east>-122.091064453125</east><west>-122.0965576171875</west>
 </LatLonAltBox>
 </Region>
 <Link>
 <href>185.kml</href>
 <viewRefreshMode>onRegion</viewRefreshMode>
 </Link>
 </NetworkLink>
 <NetworkLink>
 <name>001122</name>
 <Region>
 <Lod>
 <minLodPixels>128</minLodPixels><maxLodPixels>-1</maxLodPixels>
 </Lod>
 <LatLonAltBox>
 <north>37.4249267578125</north><south>37.41943359375</south>
 <east>-122.0965576171875</east><west>-122.10205078125</west>
 </LatLonAltBox>
 </Region>
 <Link>
 <href>190.kml</href>
 <viewRefreshMode>onRegion</viewRefreshMode>
 </Link>
 </NetworkLink>
 <NetworkLink>
 <name>001123</name>
 <Region>
 <Lod>
 <minLodPixels>128</minLodPixels><maxLodPixels>-1</maxLodPixels>
 </Lod>
 <LatLonAltBox>
 <north>37.4249267578125</north><south>37.41943359375</south>
 <east>-122.091064453125</east><west>-122.0965576171875</west>
 </LatLonAltBox>
 </Region>
 <Link>
 <href>195.kml</href>
 <viewRefreshMode>onRegion</viewRefreshMode>
 </Link>
 </NetworkLink>
 <GroundOverlay>
 <drawOrder>5</drawOrder>
 <Icon>
 <href>179.JPEG</href>
 </Icon>
 <LatLonBox>
 <north>37.430419921875</north><south>37.41943359375</south>
 <east>-122.091064453125</east><west>-122.10205078125</west>
 </LatLonBox>
 </GroundOverlay>
 </Document>
</kml>

Отображение трехмерных объектов

С помощью KML-файлов можно импортировать трехмерные модели зданий, мостов, монументов, статуй и других объектов в формате COLLADA. Модели создаются в собственном пространстве координат в таких приложениях, как SketchUp, 3D Studio Max, Softimage XSI или Maya. При последующем импорте трехмерной модели в Google Планету Земля она загружается, поворачивается и масштабируется так, чтобы соответствовать системе координат изображения Земли. Уже загруженные модели можно двигать и масштабировать с помощью элемента <Update>, который доступен в версии KML 2.1.

Образец модели

Модель в Google Планете Земля подчиняется тем же правилам, что и любой другой геометрический объект, такой как точка, линейное кольцо или многоугольник. Ниже показан пример простого KML-файла, с помощью которого импортируется модель с текстурами.

Элемент <Link> может содержать как абсолютную или относительную ссылку на файл, так и внешний URL.

Чтобы просмотреть модель, загрузите файл MackyBldg.kmz. Это архив, содержащий все необходимые текстуры и наложения, а также файл doc.kml с самой моделью.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.1">
<Placemark>
 <name>SketchUp Model of Macky Auditorium</name>
 <description>University of Colorado, Boulder; model created by Noël Nemcik.</description> <LookAt>
 <longitude>-105.2727379358738</longitude>
 <latitude>40.01000594412381</latitude>
 <altitude>0</altitude>
 <range>127.2393107680517</range>
 <tilt>65.74454495876547</tilt>
 <heading>-27.70337734057933</heading> </LookAt> <Model id="model_4">
 <altitudeMode>relativeToGround</altitudeMode>
 <Location>
 <longitude>-105.272774533734</longitude>
 <latitude>40.009993372683</latitude>
 <altitude>0</altitude>
 </Location>
 <Orientation>
 <heading>0</heading>
 <tilt>0</tilt>
 <roll>0</roll>
 </Orientation>
 <Scale>
 <x>1</x>
 <y>1</y>
 <z>1</z>
 </Scale>
 <Link>
 <href>files/CU Macky.dae</href>
 </Link>
 </Model>
</Placemark>
</kml>

Расположение модели задано с помощью широты, долготы и высоты в элементе <Location>. Для полноты в пример включены элементы <Orientation> и <Scale>, отвечающие соответственно за ориентацию и масштаб; для них оставлены значения по умолчанию.

Элемент <Orientation> определяет вращение модели вокруг осей x (наклон), y (поворот) и z (направление). Ось y указывает на север и параллельна линиям долготы, а ось х направлена на восток и параллельна линиям широты. Значения поворота положительны и задаются в градусах, как показано на схеме ниже.

Создание KMZ-архива

KMZ-архив – это набор локальных файлов, относящихся к единой KML-презентации, в том числе картинок, текстур и моделей. В KML-файле содержатся ссылки на них. KMZ-архив представляет собой автономный файл, который не обязательно размещать на сетевом сервере. Его можно сохранять или отправлять по электронной почте как единый объект. KML- и KMZ-файлы можно открывать непосредственно в Google Планете Земля.

Файл doc.kml и локальные файлы, ссылки на которые он содержит, сжимаются в ZIP-архив. Для этих целей существует множество приложений, включая WinZip (в ОС Windows), Stuffit (в ОС Mac) и zip (в ОС Linux или Mac). ZIP-архив также можно создать непосредственно в файловом менеджере Windows Explorer или Mac Finder.

После того как ZIP-архив будет сформирован, измените его расширение на KMZ.

Ниже перечислены файлы, которые входят в KMZ-архив модели здания из нашего примера.

• doc.kml – упомянутый выше KML-файл, который отвечает за импорт и размещение модели COLLADA (в формате DAE) в Google Планете Земля. Этот файл должен находиться на корневом уровне KMZ-архива.
• textures.txt – файл, содержащий информацию для замены путей к текстурам в файле модели (в нашем случае это CU Macky.dae) на пути из KMZ-архива. Этот файл должен находиться на корневом уровне KMZ-архива. Всем текстурам, ссылки на которые есть в CU Macky.dae, в файле textures.txt соответствует строка следующего вида:

<путь_к_файлу_kmz> <путь_к_файлу_COLLADA> [<идентификатор_модели_в_KML>]

<путь_к_файлу_kmz> – это относительная ссылка, указывающая на текстуру внутри KMZ-архива. Путь определяется относительно расположения файла CU Macky.dae, который хранится в каталоге files/ в KMZ-архиве. Так как текстуры также находятся в каталоге files/, каждый <путь_к_файлу_kmz> должен начинаться с ../files/ .

<путь_к_файлу_COLLADA> – это название файла текстуры, записанное в той же форме, что и в файле CU Macky.dae.

[идентификатор_модели_в_KML] – это идентификатор модели, использующей данную текстуру. Одна и та же текстура может применяться к разным моделям. Этот параметр является необязательным.

Ниже показан фрагмент файла textures.txt.

<../files/CU-Macky---Center-StairsnoCulling.jpg> <CU-Macky---Center-StairsnoCulling.jpg> <model_4>
<../files/CU-Macky-4sideturretnoCulling.jpg> <CU-Macky-4sideturretnoCulling.jpg> <model_4>
<../files/CU-Macky-Back-NorthnoCulling.jpg> <CU-Macky-Back-NorthnoCulling.jpg> <model_4>

• files/ – каталог с файлами COLLADA, в которых определены геометрические параметры, текстуры и материалы модели. В нашем примере этот каталог содержит файл COLLADA (CU Macky.dae) и JPEG-изображения, определяющие текстуры здания (CU-Macky-BrickwallnoCulling.jpg, CU-Macky--Center-StairsnoCulling.jpg, CU_Macky-EastdetaildoornoCulling.jpg и другие).

Мы рассмотрели один из множества способов организации файлов в KMZ-архиве. Фактически структура архива может быть любой и зависит от личных предпочтений разработчика. Например, картинки обычно помещаются в каталог images/. Относительные ссылки (такие как ссылки на файлы в элементе <href> компонентов NetworkLink, Link, Overlay/Icon или Model) обрабатываются на основе расположения файла doc.kml. Если у вас есть каталог images, то ссылки на картинки в теге <href> будут выглядеть следующим образом: images/myBrickTexture.jpg, images/myMountainOverlay.png и т. д.

Обновление данных, загружаемых по сетевым ссылкам

Чтобы данные, загружаемые с помощью сетевой ссылки, можно было постепенно обновлять, используется <Update> – дочерний элемент элемента <NetworkLinkControl>. Он может содержать любое количество элементов <Change>, <Create> и <Delete>, которые обрабатываются по порядку.

Последовательность событий схематически представлена ниже.

1. Компонент NetworkLink загружает "исходный" KML-файл в Google Планету Земля. Элементу, который потребуется обновлять, необходимо присвоить идентификатор (id) уже на этапе определения. В одном файле не должно быть двух одинаковых идентификаторов.
2. Другой компонент NetworkLink загружает второй KML-файл, содержащий обновления уже загруженных объектов KML (элементы <Change>, <Create> и <Delete> в любой комбинации). В этом файле содержатся две ссылки на исходные данные KML.
3. Чтобы элемент <Update> мог обновить нужный объект, используется тег targetHref, содержащий ссылку на исходный файл, в котором определен этот объект. Чтобы определить объекты, подлежащие изменению, или контейнеры новых объектов, используются элементы <Change>, <Create> и <Delete> с тегом targetId, содержащим ссылки на id этих объектов.

Пример изменения

В этом примере рассматривается набор компонентов NetworkLink и KML-файлов. Чтобы запустить его, выполните указанные ниже действия.

1. Загрузите файл Point-load.kml в Google Планету Земля. Он содержит компонент NetworkLink, который загружает исходный файл с двумя точками (Point.kml).
2. Загрузите файл Update-load.kml в Google Планету Земля. Он содержит второй компонент NetworkLink, который загружает файл с данными обновления (с новым названием точки point123).

В первом файле содержится компонент NetworkLink, который загружает файл данных с двумя точками. Меткам, содержащим эти точки, присвоены идентификаторы. В третьем файле содержится ещё один компонент NetworkLink, добавляющий файл Update. Элемент <Change> изменяет название метки point123.

Ниже представлены четыре файла из этого примера. Первый из них – Point-load.kml с компонентом NetworkLink, который загружает исходный файл (Point.kml).

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.1">
<NetworkLink>
 <name>Loads Point.kml</name>
 <Link>
 <href>http://developers.google.com/kml/documentation/Point.kml</href>
 </Link>
</NetworkLink>
</kml>

Второй файл – Point.kml с исходными данными (двумя точками). Обновляться будет точка с идентификатором point123.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.1">
<Document>
 <Placemark id="pm123">
 <name>point123</name>
 <Point> <coordinates>-95.44,40.42,0</coordinates> </Point>
 </Placemark> <Placemark id="pm456"> <name>point456</name>
 <Point> <coordinates>-95.43,40.42,0</coordinates>
 </Point>
 </Placemark>
</Document>
</kml>

Следующий файл – Update-load.kml – содержит второй компонент NetworkLink, который загружает файл с данными обновления.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.1">
<NetworkLink>
 <name>Update</name>
 <Link>
 <href>http://developers.google.com/kml/documentation/NetworkLinkControl-Update.kml</href></Link> </NetworkLink>
</kml>

Последний файл – NetworkLinkControl-Update.kml – содержит данные обновления.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.1">
<NetworkLinkControl>
 <Update>
 <targetHref>http://developers.google.com/kml/documentation/Point.kml</targetHref>
 <Change>
 <Placemark targetId="pm123"> <name>Name changed by Update Change</name>
 <!-- координаты не меняются -->
 </Placemark>
 </Change> </Update>
</NetworkLinkControl>
</kml>

Устаревание данных

По умолчанию данные загружаются по ссылкам в Google Планету Земля только один раз. Чтобы предотвратить устаревание данных, загруженных с помощью тега <href> (внутри элемента Link или Icon), используется атрибут refreshMode элемента onExpire. По умолчанию время устаревания указывается в соответствующих HTTP-заголовках, но его также можно определить с помощью элемента expires компонента NetworkLinkControl. Время записывается в XML-формате dateTime (см. документ Схема XML, ч. 2. Типы данных, вторая редакция). Если время устаревания задано как в HTTP-заголовках, так и в KML-коде, приоритет имеет последний.

Пример 1: определение времени устаревания с помощью HTTP-сервера

Этот пример носит иллюстративный характер. В нем рассматривается компонент GroundOverlay со значком, для которого задан атрибут refreshMode элемента onExpire. Так как в KML-файле время устаревания не определено, используется соответствующая информация с HTTP-сервера.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.1">
<Document>
 <name>refreshMode onExpire</name>
 <Snippet maxLines="10">
 Image automatically reloads according to http
 server expiration.
 </Snippet>
 <GroundOverlay>
 <Icon>
 <href>http://www.someserver.com/image.jpeg</href>
 <refreshMode>onExpire</refreshMode>
 </Icon>
 <LatLonBox>
 <!-- На основе сеанса редактирования в Планете Земля -->
 <!-- Крыша здания в Presidio -->
 <north>37.80385180177469</north>
 <east>-122.4558710620651</east>
 <south>37.80337403503347</south>
 <west>-122.4564295653771</west>
 </LatLonBox>
 </GroundOverlay>
</Document>
</kml>

Пример 2: определение времени устаревания в KML

В примере ниже метка размещается в произвольно выбранном месте. Используется ссылка с атрибутом refreshMode элемента onExpire. В данном случае дата и время устаревания данных определяются элементом KML <expires> (с помощью скрипта Python). Заданное таким образом время устаревания имеет приоритет перед информацией, которая передается в HTTP-заголовках.

Ниже показан KML-код для компонента NetworkLink с элементом <Link>, содержащим <href> и <refreshMode>.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.1">
<Document>
 <NetworkLink>
 <Link>
 <href>http://dev.someserver.com/cgi-bin/expires.py</href>
 <refreshMode>onExpire</refreshMode>
 </Link>
 </NetworkLink>
</Document>
</kml>

Скрипт Python определяет время устаревания как [сейчас + 11 секунд] и обновляет координаты метки.

#!/usr/bin/python

import random
import time 
lat = random.random() * 180. - 90.
lon = random.random() * 360. - 180. 
now = time.time()
future = time.gmtime(now + 11)
y = future[0]
mo = future[1]
d = future[2]
h = future[3]
mi = future[4]
s = future[5]
iso8601 = '%04d-%02d-%02dT%02d:%02d:%02dZ' % (y,mo,d,h,mi,s) 
print 'Content-type: application/vnd.google-earth.kml+xml'
print 
print '<?xml version=\"1.0\" encoding=\"UTF-8\"?>'
print '<kml xmlns=\"http://earth.google.com/kml/2.1\">' 
# дочерний элемент <kml>
print '<NetworkLinkControl>'
print '<expires>%s</expires>' % iso8601
print '</NetworkLinkControl>' 
print '<Placemark>'
print '<name>placemark expires %s</name>' % iso8601
print '<Point>'
print '<coordinates>%f,%f,0</coordinates>' % (lon,lat)
print '</Point>'
print '</Placemark>' 
print '</kml>'

Папки с переключателями

Теперь можно создавать папки с элементами, из которых пользователь может выбрать только один. Переключатель задается с помощью элемента <ListStyle>, в котором для атрибута listItemType указывается значение radioFolder. Ниже показан пример использования этого элемента.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.1">
<Document>
 <name>ListStyle radiofolder</name>
 <Folder>
 <name>radioFolder Folder</name>
 <Style>
 <ListStyle>
 <listItemType>radioFolder</listItemType> 
 </ListStyle>  
 </Style>
 <Placemark>
 <name>north</name>
 <Point>
 <coordinates>-114,41.79,0</coordinates>
 </Point>
 </Placemark>
 <Placemark>
 <name>south</name>
 <Point>
 <coordinates>-114,41.78,0</coordinates>
 </Point>
 </Placemark>
 </Folder> 
</Document> 
</kml>

Так папка с переключателями для дочерних элементов выглядит в панели "Метки":