Arquivos KMZ

O que é um arquivo KMZ?

Um arquivo KMZ é composto por um arquivo KML principal e zero ou mais arquivos de suporte empacotados usando um utilitário Zip em uma unidade, chamada arquivo. O arquivo KMZ pode ser armazenado e enviado por e-mail como uma única entidade. Um NetworkLink pode buscar um arquivo KMZ de um servidor da Web. Quando o arquivo KMZ não está compactado, o arquivo .kml principal e seus arquivos de suporte são separados em seus formatos e estrutura de diretórios originais, com seus nomes de arquivo e extensões originais. Além de ser um formato de arquivo, o formato Zip também é compactado; portanto ele só pode incluir um único arquivo KML grande. Dependendo do conteúdo do arquivo KML, esse processo normalmente resulta em compactação 10:01. Seu arquivo KML de 10 Kbytes pode ser atendido por um arquivo KMZ de 1 Kbyte.

O Google Earth e o Google Maps podem ler arquivos KML e KMZ diretamente e podem salvar arquivos como KMZ. Por padrão, o arquivo KML principal é nomeado doc.kml.

Observação: para maior clareza, esta página se refere ao arquivo KML principal em um arquivo KMZ como doc.kml. Esse arquivo KML principal pode ter qualquer nome, desde que termine em .kml e que haja apenas um arquivo .kml.

Você deve criar um arquivo KMZ se seu arquivo doc.kml for maior que 10 Kbytes ou se os arquivos doc.kml fizerem referência a outros arquivos (imagens, arquivos de som, modelos, texturas).

Estrutura de diretórios recomendada

Esta seção fornece algumas recomendações simples para os criadores de arquivos KML/KMZ. O exemplo usado nesta seção é do website de Jimmy Buffett, que usa o formato KML para mostrar passeios planejados e destaques relacionados no Google Earth.

Faça o download do arquivo KMZ que contém esse passeio. Usado com permissão.

Observação: O Google Earth 6.0 aplica estritamente o seguinte conjunto de diretrizes ao resolver referências relativas em um arquivo KMZ (consulte especialmente o item 4 na lista a seguir). As versões anteriores do Google Earth eram menos rigorosas com relação à forma como resolviam essas referências relativas. Como resultado, algumas referências relativas que funcionavam no Google Earth 5.2 e em versões anteriores talvez precisem ser editadas agora para funcionar com as versões 6.0 e posteriores.

Siga estas diretrizes ao criar arquivos KMZ:

  1. Crie uma pasta que abrigará o conteúdo de seu arquivo KMZ. Forneça um nome descritivo (por exemplo, buffetthawaiitour).
  2. Coloque o arquivo KML padrão (doc.kml ou qualquer nome que você queira dar a ele) no nível superior dessa pasta. Inclua somente um arquivo .kml. Quando o Google Earth abre um arquivo KMZ, ele examina o arquivo, procurando pelo primeiro arquivo .kml nessa lista. Ele ignora todos os arquivos .kml subsequentes, se houver algum, no arquivo. Se o arquivo contiver vários arquivos .kml, não será possível ter certeza de qual será encontrado primeiro; portanto, é preciso incluir apenas um.
  3. Inclua uma ou mais subpastas na pasta principal para coletar imagens, modelos, texturas, arquivos de som ou outros recursos referenciados no arquivo doc.kml. A complexidade dessa estrutura de diretórios depende do número de arquivos de suporte e de suas preferências para organização. 
  4. Use referências relativas. Consulte Referências a arquivos externos para obter mais detalhes. Todos os caminhos relativos começam na pasta básica descrita acima no item 1. Por exemplo, se um arquivo KMZ vacationJournal.kmz estiver na área de trabalho e seu arquivo doc.kml fizer referência a um arquivo myFavoritePlace.jpg, que também está na área de trabalho, o <href> no arquivo doc.kml será ../myFavoritePlace.jpg.
  5. Não use a extensão .kmz para qualquer uma das subpastas em um arquivo KMZ. A extensão .kmz é reservada ao nome do próprio arquivo.

Por exemplo, aqui está a estrutura do arquivo KMZ para o passeio de Jimmy Buffett:

Como há apenas cinco arquivos de suporte, todos são coletados em uma subpasta files da pasta principal. Se você carregar o arquivo no Google Earth e copiar e colá-lo em um navegador de texto, verá que todos os elementos <href> usam referências relativas a esses arquivos de suporte (que representam ícones, uma superposição de tela e o arquivo de som para o passeio).

Este é o código KML para uma das referências de ícone:

<IconStyle>
  <scale>1.1</scale>
  <Icon>
    <href>files/icon_surfing.png</href>
  </Icon>
</IconStyle>

Este é o código KML da referência para o arquivo de som:

<gx:SoundCue>
  <href>files/Margaritaville.mp3</href>
</gx:SoundCue>

Referências a arquivos externos

O arquivo doc.kml normalmente contém diversos links para outros arquivos (imagens, ícones, modelos, texturas e arquivos de som). As referências a esses arquivos estão contidas no atributo href (ou às vezes no elemento <href>), que pode ser encontrado nos seguintes elementos KML:

Esses links externos podem ser referências absolutas ou relativas, conforme descrito na seção a seguir. Podem se referir a arquivos do mesmo arquivo KMZ ou a arquivos contidos em outros arquivos KMZ ou armazenados em outros lugares da Web. Com exceção do elemento <sourceHref> em <Model>, as referências relativas são sempre resolvidas em relação ao arquivo doc.kml, como explicado na seção Como resolver referências relativas.

Referências absolutas versus relativas

As referências absolutas contêm o URL completo para o arquivo vinculado. Elas são úteis para arquivos postados em um servidor central e não são ambíguas. No entanto, se você usar referências absolutas a arquivos locais, os links serão quebrados quando os arquivos forem movidos para um novo sistema. As referências relativas evitam esse problema.

Veja um exemplo de referência absoluta a um arquivo armazenado em um servidor central:

<Icon>
  <href>http://maps.google.com/mapfiles/kml/pushpin/ylw-pushpin.png</href>
</Icon>

Como resolver referências relativas

Em geral, as referências relativas são resolvidas em relação ao arquivo doc.kml. Qualquer URL relativo é resolvido com base no diretório que contém esse arquivo, que é considerado a raiz do arquivo KMZ. No exemplo do passeio havaiano, o URL básico é parecido com o seguinte (dependendo de onde você fizer o download do arquivo KMZ): 

buffetthawaiitour.kmz

Para se referir a um arquivo localizado em um arquivo KMZ diferente (por exemplo, para images/jimmyphoto.jpg contido em margaritavillealbum.kmz, use a notação ".." para subir um nível na estrutura de diretório, que o tiraria do arquivo KMZ atual (buffetthawaiitour.kmz):

<href>../margaritavillealbum.kmz/images/jimmyphoto.jpg"</href>

Observação: as regras para resolver referências relativas em um arquivo KMZ baseiam-se no padrão RFC 3986 Seção 5 para resolução de URLs da Web. O URL básico é determinado pelo local do arquivo doc.kml,, e todos os URLs relativos são resolvidos em relação a esse URL básico.

A exceção: <sourceHref> em <Model>

O elemento <Model> contém um elemento <Link> que especifica o carregamento de um arquivo COLLADA no Google Earth. Os arquivos COLLADA especificam objetos 3D e têm uma extensão .dae. O elemento <Model> também contém um elemento <Alias>, que contém um mapeamento entre o <targetHref> (o arquivo de textura a ser buscado pelo Google Earth) e o <sourceHref> (o caminho especificado para o arquivo de textura no arquivo COLLADA .dae). Se o elemento <sourceHref> contiver um caminho relativo, o Google Earth interpretará esse caminho como relativo ao arquivo .dae que faz referência a ele (não relativo ao arquivo doc.kml como em todos os outros casos). Por exemplo:

<Model>
.
.
.
  <Link>
    <href>MackyBldg.kmz/files/CU Macky.dae</href>
  </Link>
  <ResourceMap>
    <Alias>
      <sourceHref>../files/StairsnoCulling.jpg</sourceHref>
      <targetHref>../files/StairsnoCulling.jpg</targetHref>
    </Alias>
    <Alias>
      <sourceHref>../files/sideturretnoCulling.jpg</sourceHref>
      <targetHref>../files/sideturretnoCulling.jpg</targetHref>
	</Alias>
.
.
.
</Model>

Como criar o arquivo KMZ

Use o Windows Explorer ou o Mac Finder para criar um arquivo Zip. Selecione o conteúdo da pasta que contém o arquivo doc.kml e os recursos relacionados e escolha uma opção, como "WinZip > Adicionar a arquivo Zip...." A biblioteca Java JAR também tem uma biblioteca Zip para criação e extração programática de um arquivo Zip, e o Linux tem versões de linha de comando de zip e unzip.

Observação: ao criar o arquivo Zip, selecione o conteúdo da pasta que contém o arquivo doc.kml, não a própria pasta.

Depois de criar o arquivo, altere a extensão .zip para .kmz. Para extrair os arquivos do arquivo, altere a extensão de arquivo .kmz de volta para .zip e use o utilitário Zip para descompactar o arquivo.

Google Earth e arquivos KMZ

Uso do elemento <iframe>

Nos balões <description> de KML, a maioria dos elementos HTML é tratada no Google Earth da mesma forma que em navegadores da Web padrão. Um <iframe> em um balão de descrição, no entanto, é tratado como HTML puro, o que significa que elementos especiais de KML não são reconhecidos. Por exemplo, um <iframe> não pode exibir elementos KMZ, e links de âncora local, como <a href="#my feature;flyto">, não são reconhecidos. O elemento <src> em um elemento <iframe> não pode apontar para um arquivo local em disco, nem para um arquivo em um arquivo KMZ; ele deve apontar para um URL na Internet que possa ser visitado por um navegador.