Passeios em KML

Sumário

• Introdução
• A estrutura de um passeio
• Linhas do tempo do passeio
• FlyTo e flyToMode
• Como pausar e aguardar
• Atualizações
• Como adicionar um som
• Como ativar e desativar balões de descrição
• Como incorporar imagens históricas
• Problemas conhecidos

Introdução

Novidade no Google Earth 5.0, o passeio permite voos controlados por dados geoespaciais, incluindo:

• durações de voo específicas entre locais
• voo passando por locais, sem parar
• reprodução de arquivos de som em horários predefinidos durante o passeio
• atualizações temporárias de elementos KML dentro dos limites do passeio

Para obter mais informações sobre passeios do ponto de vista de um cliente do Google Earth, consulte o Guia do usuário do Google Earth.

Namespace de extensão do Google

Os elementos KML que definem os passeios estão contidos em um conjunto de extensões para o padrão OGC KML, usando o prefixo gx. Para usá-los, é necessário incluir o URI do namespace correto no elemento <kml> de abertura em seu arquivo KML:

<kml xmlns="http://www.opengis.net/kml/2.2"
 xmlns:gx="http://www.google.com/kml/ext/2.2">

Os elementos relacionados ao passeio no conjunto de extensão gx incluem:

<gx:Tour>	<gx:playMode>
<gx:Playlist>	<gx:Wait>
<gx:Flyto>	<gx:AnimatedUpdate>
<gx:flyToMode>	<gx:SoundCue>
<gx:TourControl>	<gx:duration>

O passeio é suportado no Google Earth 5.0, mas pode não ser suportado em outros navegadores geográficos. Se seu navegador não suportar extensões específicas, os dados nessas extensões serão ignorados silenciosamente, e o restante do arquivo KML será carregado sem erros.

Terminologia

primitivo do passeio: um de um conjunto de elementos que definem uma ação em um passeio. Um exemplo de primitivo de passeio é FlyTo, definido pelo elemento <gx:FlyTo> e seus filhos.

lista de reprodução: o recipiente de uma lista de primitivos de passeio que definem um passeio. A lista de reprodução pode ser visualizada junto com uma linha do tempo (consulte Linhas do tempo do passeio para obter mais informações).

A estrutura de um passeio

Os passeios são construídos colocando-se elementos específicos, em ordem, em um arquivo KML. O arquivo KML pode conter qualquer outro elemento KML legal junto com o passeio.

O exemplo a seguir mostra um passeio completo e uma pasta contendo diversos marcadores. O passeio começa na Ilha Sul da Nova Zelândia, antes de voar para o Norte via Monte Taranaki, e demonstra flyToModes smooth e bounce, além do método <gx:balloonVisibility> de abertura de um balão de descrição. Os elementos de passeio são descritos com mais detalhes abaixo.

 complete_tour_example.kml

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2"
 xmlns:gx="http://www.google.com/kml/ext/2.2">

<Document>
  <name>A tour and some features</name>
  <open>1</open>

  <gx:Tour>
    <name>Play me!</name>
    <gx:Playlist>

      <gx:FlyTo>
        <gx:duration>5.0</gx:duration>
        <!-- bounce is the default flyToMode -->
        <Camera>
          <longitude>170.157</longitude>
          <latitude>-43.671</latitude>
          <altitude>9700</altitude>
          <heading>-6.333</heading>
          <tilt>33.5</tilt>
        </Camera>
      </gx:FlyTo>

      <gx:Wait>
        <gx:duration>1.0</gx:duration>
      </gx:Wait>

      <gx:FlyTo>
        <gx:duration>6.0</gx:duration>
        <Camera>
          <longitude>174.063</longitude>
          <latitude>-39.663</latitude>
          <altitude>18275</altitude>
          <heading>-4.921</heading>
          <tilt>65</tilt>
          <altitudeMode>absolute</altitudeMode>
        </Camera>
      </gx:FlyTo>

      <gx:FlyTo>
        <gx:duration>3.0</gx:duration>
        <gx:flyToMode>smooth</gx:flyToMode>
        <LookAt>
          <longitude>174.007</longitude>
          <latitude>-39.279</latitude>
          <altitude>0</altitude>
          <heading>112.817</heading>
          <tilt>68.065</tilt>
          <range>6811.884</range>
          <altitudeMode>relativeToGround</altitudeMode>
        </LookAt>
      </gx:FlyTo>

      <gx:FlyTo>
        <gx:duration>3.0</gx:duration>
        <gx:flyToMode>smooth</gx:flyToMode>
        <LookAt>
          <longitude>174.064</longitude>
          <latitude>-39.321</latitude>
          <altitude>0</altitude>
          <heading>-48.463</heading>
          <tilt>67.946</tilt>
          <range>4202.579</range>
          <altitudeMode>relativeToGround</altitudeMode>
        </LookAt>
       </gx:FlyTo>

      <gx:FlyTo>
        <gx:duration>5.0</gx:duration>
        <LookAt>
          <longitude>175.365</longitude>
          <latitude>-36.523</latitude>
          <altitude>0</altitude>
          <heading>-95</heading>
          <tilt>65</tilt>
          <range>2500</range>
          <altitudeMode>relativeToGround</altitudeMode>
        </LookAt>
      </gx:FlyTo>

      <gx:AnimatedUpdate>
        <gx:duration>0.0</gx:duration>
        <Update>
          <targetHref/>
          <Change>
            <Placemark targetId="pin2">
              <gx:balloonVisibility>1</gx:balloonVisibility>
            </Placemark>
          </Change>
        </Update>
      </gx:AnimatedUpdate>

      <gx:Wait>
        <gx:duration>6.0</gx:duration>
      </gx:Wait>

    </gx:Playlist>
  </gx:Tour>

  <Folder>
    <name>Points and polygons</name>

    <Style id="pushpin">
      <IconStyle>
        <Icon>
          <href>http://maps.google.com/mapfiles/kml/pushpin/ylw-pushpin.png</href>
        </Icon>
      </IconStyle>
    </Style>

    <Placemark id="mountainpin1">
      <name>New Zealand's Southern Alps</name>
      <styleUrl>#pushpin</styleUrl>
      <Point>
        <coordinates>170.144,-43.605,0</coordinates>
      </Point>
    </Placemark>

    <Placemark id="pin2">
      <name>The End</name>
      <description>
        Learn more at http://developers.google.com/kml/documentation
      </description>
      <styleUrl>pushpin</styleUrl>
      <Point>
        <coordinates>175.370,-36.526,0</coordinates>
      </Point>
    </Placemark>

    <Placemark id="polygon1">
      <name>Polygon</name>
      <Polygon>
        <tessellate>1</tessellate>
        <outerBoundaryIs>
          <LinearRing>
            <coordinates>
              175.365,-36.522,0
              175.366,-36.530,0
              175.369,-36.529,0
              175.366,-36.521,0
              175.365,-36.522,0
            </coordinates>
          </LinearRing>
        </outerBoundaryIs>
      </Polygon>
    </Placemark>

  </Folder>
</Document>
</kml>

Linhas do tempo do passeio

Os passeios são compostos por uma série de primitivos de passeio - FlyTos, Waits, TourControls, AnimatedUpdates e SoundCues. Alguns desses primitivos são reproduzidos um após o outro, aguardando que um primitivo seja concluído antes de começar o próximo. Outros são executados em paralelo a outros primitivos, de modo que várias ações possam ocorrer simultaneamente.

Primitivos que ocorrem em série

• <gx:FlyTo>
• <gx:Wait>
• <gx:TourControl>

Esses primitivos ocorrem uma após o outro e precisam ser totalmente concluídos antes de a lista de reprodução mudar para qualquer outro elemento, de qualquer tipo. Isso significa que somente um primitivo do tipo em série (FlyTo, Wait ou TourControl) pode ocorrer por vez, e nenhum SoundCue ou AnimatedUpdate adicional pode ser iniciado enquanto um primitivo do tipo em série estiver ocorrendo.

Primitivos que ocorrem em paralelo

• <gx:AnimatedUpdate>
• <gx:SoundCue>

Esses primitivos são enfileirados quando aparecem na lista de reprodução. Depois de serem iniciados, a lista de reprodução passa imediatamente para o próximo primitivo, sem aguardar a conclusão do SoundCue ou AnimatedUpdate. Isso significa que:

• qualquer quantidade de SoundCues e/ou AnimatedUpdates pode ocorrer ao mesmo tempo, enfileirando-os um após o outro na lista de reprodução
• SoundCues e/ou AnimatedUpdates podem ocorrer enquanto primitivos do tipo em série estiverem sendo reproduzidos (embora não possam ser iniciados durante a reprodução de primitivos do tipo em série)

O diagrama abaixo ilustra esse comportamento. Clique na imagem para obter uma visualização mais detalhada, incluindo o conteúdo KML que está definindo cada primitivo na lista de reprodução.

 

O diagrama mostra que cada FlyTo leva uma quantidade específica de tempo (especificada em seu elemento <gx:duration>) para ser concluído. Somente após esse período o próximo primitivo começa.

O SoundCue, por outro lado, ocorre em paralelo. O próximo primitivo na linha do tempo principal ocorre imediatamente, ao mesmo tempo em que o arquivo de som começa a ser reproduzido. O arquivo de som continua até que o fim do arquivo seja alcançado ou até o fim do passeio, o que ocorrer primeiro. Se o passeio terminar antes do arquivo de som, o arquivo de som deixará de ser reproduzido. Qualquer quantidade de arquivos de som pode ser reproduzida por vez, pois cada um é carregado em sua própria linha do tempo.

As atualizações animadas se comportam da mesma maneira. Se o ícone de um marcador for configurado para aumentar de tamanho durante um período de cinco segundos, ele o fará enquanto os próximos primitivos na linha do tempo principal ocorrerem.

FlyTo e flyToMode

Os passeios vão de um local a outro, e cada um deles é especificado usando um elemento <gx:FlyTo>. Ele contém um AbstractView (<Camera> ou <LookAt>) que define o local de visualização, o ângulo e a altitude no Google Earth.

Além disso, um flyToMode pode ser especificado, instruindo ao navegador como se aproximar do ponto. Antes da introdução do <gx:Tour>, os "passeios" eram reproduzidos no navegador pulando de um marcador para outro. A velocidade do voo (que era definida pelo navegador) era reduzida à medida que o navegador se aproximava do marcador, terminando com a velocidade zero antes de continuar para o próximo marcador. Esse comportamento ainda pode ser especificado em passeios usando a propriedade do elemento <gx:flyToMode>bounce</gx:flyToMode>.

O flyToMode smooth permite um voo suave e controlado pelo espaço. A velocidade entre os pontos é controlada pela inclusão de um elemento <gx:duration>, que define o tempo usado pelo navegador para viajar do ponto atual para a próxima visualização definida. Um voo ininterrupto é composto por uma série de FlyTos com flyToModes smooth. O navegador da Terra interpola a velocidade e um caminho curvo entre os pontos, de modo que cada marcador seja atingido exatamente no horário especificado no KML. Ao contrário do flyToMode bounce, a velocidade nunca chega a zero até que o voo seja interrompido por qualquer um dos seguintes eventos:

• o fim do passeio,
• um ponto com um flyToMode bounce ou
• uma espera.

Pausa, atualizações animadas e dicas de som não interrompem o voo.

FlyTo inicial

O primeiro <gx:FlyTo> contido em uma lista de reprodução parte da posição atual do visualizador no Google Earth. A duração é observada, de modo que a velocidade do primeiro ponto varia muito, dependendo de onde o visualizador estiver localizado na Terra quando o passeio começar. Recomenda-se que esse FlyTo inicial tenha uma duração de cinco segundos ou mais e seja do modo bounce, para proporcionar a melhor experiência de visualização.

Se <gx:flyToMode> for definido como smooth para o primeiro flyTo e for seguido por FlyTos smooth adicionais, a posição inicial do visualizador será considerada um ponto na curva smooth e afetará a curva do caminho entre o primeiro ponto e os pontos seguintes. Isso significa que a série inicial de FlyTos smooth será diferente para cada visualizador, dependendo de o que eles estavam visualizando no cliente do Google Earth quando o passeio começou. Se um flyTo smooth para o ponto inicial ainda for desejado, um <gx:Wait> poderá ser inserido no código do passeio após o primeiro flyTo. Isso separará a posição inicial do restante do passeio.

Exemplos

Os exemplos a seguir mostram a diferença entre flyToModes bounce e smooth. Cada passeio visita os mesmos marcadores, mas usam flyToModes diferentes. Para reproduzir os passeios no Google Earth, clique nos links acima de cada snippet de código e depois clique duas vezes no nome do passeio em seu painel Locais do Google Earth.

 bounce_example.kml

<gx:FlyTo>
  <gx:duration>4.0</gx:duration>
  <!-- bounce is the default flyToMode -->
  <LookAt>
    <longitude>-121.303179</longitude>
    <latitude>45.993041</latitude>
    <altitude>0</altitude>
    <heading>-27.923387</heading>
    <tilt>71.600075</tilt>
    <range>22570.546801</range>
    <altitudeMode>relativeToGround</altitudeMode>
  </LookAt>
</gx:FlyTo>

<!-- ...snip... -->

 smooth_example.kml

<gx:FlyTo>
  <gx:duration>4.0</gx:duration>
  <gx:flyToMode>smooth</gx:flyToMode>
  <LookAt>
    <longitude>-121.303179</longitude>
    <latitude>45.993041</latitude>
    <altitude>0</altitude>
    <heading>-27.923387</heading>
    <tilt>71.600075</tilt>
    <range>22570.546801</range>
    <altitudeMode>relativeToGround</altitudeMode>
  </LookAt>
</gx:FlyTo>

<!-- ...snip... -->

Como pausar e aguardar

Uma espera interrompe o movimento pelo espaço em um passeio, mas permite que os arquivos de som e atualizações animadas continuem. A duração de uma espera é especificada no KML.

Uma pausa para o passeio em seu local atual, como se o usuário tivesse clicado no botão Pausa, e afeta todos os primitivos. O passeio recomeça somente quando o usuário seleciona o botão Reproduzir no controle de passeio do Google Earth.

Esperas

Esse elemento afeta apenas a câmera. Ele especifica a duração durante a qual a câmera permanece parada. Quaisquer arquivos de som e/ou atualizações animadas em reprodução no momento não são afetados e continuam durante a espera. As esperas podem ser usadas para que os arquivos de som ou atualizações sejam concluídos, antes de o próximo flyTo ser iniciado ou antes de o passeio terminar.

<gx:Wait>
    <gx:duration>10.0</gx:duration>   <!-- wait time in seconds -->
</gx:Wait>

A duração da espera é especificada em segundos, usando o elemento <gx:duration>. Após esse tempo, o passeio continua com a próxima ação especificada na lista de reprodução. Uma espera interrompe o caminho de um voo suave, de modo que o movimento da câmera diminua até a velocidade zero em qualquer ponto imediatamente anterior à espera, independentemente de seu flyToMode.

Pausas

Pausas controladas pelo usuário são especificadas usando <gx:TourControl> e seu elemento filho, <gx:playMode>. O último tem um valor único permitido de pause. A chamada dessa ação é semelhante à ação do usuário ao clicar no botão de pausa do Google Earth: o passeio pausa nesse ponto e permanece assim até que se clique no botão Reproduzir. Durante a pausa, o usuário pode se movimentar à vontade no ambiente da Terra. Quando clicar em Reproduzir, o usuário retornará ao ponto do passeio em que a pausa foi definida.

As pausas não interrompem caminhos de voo suaves; a velocidade entre os pontos de ambos os lados de uma pausa é calculada pelo navegador como se a pausa não existisse.

<gx:TourControl>
    <gx:playMode>pause</gx:playMode>
</gx:TourControl>

Exemplos

Veja um exemplo de espera abaixo. Um arquivo de som é enfileirado, contendo dez segundos de um discurso de introdução. Uma espera de 10 segundos é inserida imediatamente após o som, impedindo a ocorrência do FlyTo seguinte até a conclusão do discurso.

 wait_example.kml

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2"
 xmlns:gx="http://www.google.com/kml/ext/2.2">   

<gx:Tour>
  <gx:Playlist>

    <gx:SoundCue>
      <href>
        http://dev.keyhole.com/codesite/cntowerfacts.mp3
      </href>   <!-- this file is ten seconds long -->
    </gx:SoundCue>

    <gx:Wait>
      <gx:duration>10</gx:duration>
    </gx:Wait>

    <gx:FlyTo>
      <gx:duration>5</gx:duration>
      <gx:flyToMode>bounce</gx:flyToMode>
      <LookAt>
        <longitude>-79.387</longitude>
 <latitude>43.643</latitude>
 <altitude>0</altitude> <heading>-172.3</heading> <tilt>10</tilt> <range>1200</range> <altitudeMode>relativeToGround</altitudeMode>
 </LookAt> </gx:FlyTo> </gx:Playlist> </gx:Tour> </kml>

O exemplo a seguir demonstra o uso de uma pausa. O visualizador é levado a um local específico na Terra, e o passeio é pausado. O usuário pode se movimentar pelo ambiente da Terra por quanto tempo quiser. Quando estiver pronto para retomar o passeio, ele deve selecionar Reproduzir nos controles do passeio. O Google Earth volta para o último local do passeio e continua a reprodução.

 pause_example.kml

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2"
 xmlns:gx="http://www.google.com/kml/ext/2.2">  

<gx:Tour>
  <gx:Playlist>

    <gx:FlyTo>
 <gx:duration>5</gx:duration>
 <gx:flyToMode>bounce</gx:flyToMode>
 <LookAt>
 <longitude>-79.387</longitude>
 <latitude>43.643</latitude>
 <altitude>0</altitude>
 <heading>-172.3</heading>
 <tilt>10</tilt>
 <range>1200</range>
 <altitudeMode>relativeToGround</altitudeMode>
 </LookAt>
 </gx:FlyTo> <gx:TourControl> <gx:playMode>pause</gx:playMode> </gx:TourControl> <gx:SoundCue> <href> http://dev.keyhole.com/codesite/cntowerfacts.mp3 </href> <!-- this file is ten seconds long --> </gx:SoundCue> <gx:Wait> <gx:duration>10.0</gx:duration> </gx:Wait> </gx:Playlist> </gx:Tour> </kml>

Atualizações

Os elementos KML no ambiente da Terra podem ser modificados, alterados ou criados durante um passeio, incluindo o tamanho, estilo e local dos marcadores, adição de superposições de solo, geometria e muito mais. Para obter mais informações sobre como atualizar o KML, leia a seção Atualizações do Guia do Desenvolvedor.

As atualizações para o KML podem ocorrer durante um passeio e são ativadas pelo uso do elemento <gx:AnimatedUpdate>. O comportamento de atualização em um passeio é diferente do comportamento de atualização em um NetworkLink da seguinte maneira:

• as atualizações no KML são revertidas quando o passeio é encerrado e
• não são incluídas quando o estado atual é salvo.

Além disso, quaisquer alterações que causem interpolação (ou seja, que contenham estados intermediários, como mudanças no tamanho) são animadas durante o período especificado. As alterações que não têm etapas intermediárias (como balões de descrição abrindo ou fechando) são atualizadas apenas no final do período especificado. Se nenhuma duração for especificada, a atualização ocorrerá imediatamente (o valor padrão para <gx:duration> é 0.0).

Além das diferenças listadas acima, a atualização em um elemento <gx:AnimatedUpdate> se comporta da mesma forma que a atualização em <NetworkLinkControl>. Ela pode ser usada para alterar o tamanho, o local e a aparência do marcador, adicionar superposições de solo ou modelos e, usando o elemento <gx:balloonVisibility>, ativar ou desativar balões de informações.

<gx:AnimatedUpdate> e a linha do tempo do passeio

Atualizações animadas são executadas em paralelo à linha do tempo, ou seja, o passeio continua diretamente no próximo primitivo de passeio da lista de reprodução, enquanto a atualização animada está ocorrendo. O <gx:duration> controla quanto tempo demora a atualização, mas não atrasa o próximo primitivo do passeio.

Para permitir a conclusão de uma atualização animada antes da próxima ação ocorrer, insira um <gx:Wait> com uma duração igual à duração da atualização entre a atualização de animação e o próximo primitivo do passeio.

Além disso, uma atualização animada será truncada se sua duração ultrapassar a duração do último elemento <gx:FlyTo> ou <gx:Wait>. É possível alterar os valores do <gx:duration> apropriado ou inserir um elemento <gx:Wait> adicional ao final da lista de reprodução para dar tempo para a atualização animada terminar.

Para obter mais informações sobre a linha do tempo, leia Linhas do tempo do passeio acima.

Exemplo

O seguinte snippet de código mostra uma alteração no tamanho de um ícone de marcador específico, de uma escala de 1.0 para uma escala de 10.0. A alteração ocorre em 6,5 segundos, durante os quais o ícone expande gradualmente seu tamanho inicial para seu tamanho final.

Observe a inclusão de um primitivo <gx:Wait> ao final do passeio. As atualizações animadas não mantêm por si só um passeio aberto - somente primitivos de passeio do tipo em série definem a extensão de um passeio. Por esse motivo, uma espera de 2,4 segundos foi inserida. Combinada com o FlyTo de 4,1 segundos, a espera proporciona tempo para a atualização terminar antes do fim do passeio.

 animatedupdate_example.kml

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2"
 xmlns:gx="http://www.google.com/kml/ext/2.2"> <Document> <name>gx:AnimatedUpdate example</name> <open>1</open> <Style id="style"> <IconStyle id="iconstyle"> <scale>1.0</scale> </IconStyle> </Style> <Placemark id="mountainpin1"> <name>New Zealand's Southern Alps</name> <styleUrl>#style</styleUrl> <Point> <coordinates>170.144,-43.605,0</coordinates> </Point> </Placemark> <gx:Tour> <name>Play me!</name> <gx:Playlist> <!-- The order and duration of TourPrimitives is important; in this example, the AnimatedUpdate needs 6.5 seconds to complete. The FlyTo provides 4.1, and the Wait 2.4, giving the update time to complete before the Tour ends. AnimatedUpdates don't hold Tours open, but FlyTos and Waits do. For more information, refer to: http://developers.google.com/kml/documentation/touring.html#tourtimelines --> <gx:AnimatedUpdate> <gx:duration>6.5</gx:duration> <Update> <targetHref></targetHref> <Change> <IconStyle targetId="iconstyle"> <scale>10.0</scale> </IconStyle> </Change> </Update> </gx:AnimatedUpdate> <gx:FlyTo> <gx:duration>4.1</gx:duration> <Camera> <longitude>170.157</longitude> <latitude>-43.671</latitude> <altitude>9700</altitude> <heading>-6.333</heading> <tilt>33.5</tilt> <roll>0</roll> </Camera> </gx:FlyTo> <!-- wait for the AnimatedUpdate to complete --> <gx:Wait> <gx:duration>2.4</gx:duration> </gx:Wait> </gx:Playlist> </gx:Tour> </Document> </kml>

Como adicionar som

Arquivos de som podem ser incluídos em passeios e reproduzidos em qualquer ponto usando o elemento <gx:SoundCue>. Um elemento <href> filho especifica o arquivo de som. Os formatos suportados dependem dos codecs instalados em seu sistema e incluem, mas não estão limitados a:

• mp3
• aac

Nenhuma duração é especificada.

Os arquivos de som são reproduzidos em paralelo à linha do tempo principal, ou seja, a lista de reprodução passa para o próximo primitivo do passeio enquanto o arquivo de som está sendo reproduzido. Leia Linhas do tempo do passeio para obter mais informações. Assim como acontece com as atualizações animadas, os arquivos de som não mantêm um passeio aberto. Somente primitivos de passeio do tipo em série definem a duração de um passeio. Se o passeio terminar antes do arquivo de som, o arquivo de som deixará de ser reproduzido.

Como reproduzir diversos arquivos de som

É possível reproduzir muitos arquivos de som por vez. O Google Earth combinará os arquivos. Isso é útil em casos em casos em que o arquivo de música de fundo é carregado no início do passeio, e inserções de voz são fornecidas em pontos específicos do passeio.

Como permitir que um arquivo de som seja concluído antes da reprodução do próximo primitivo

Se desejar que o passeio aguarde enquanto um arquivo de som é reproduzido, inclua um elemento <gx:Wait> imediatamente após o primitivo <gx:SoundCue>. <gx:Wait> especifica, em segundos, uma quantidade de tempo que o passeio deve aguardar antes de continuar no próximo primitivo.

A reprodução de um arquivo de som não pode continuar após o final de um passeio. É possível usar uma espera para ampliar a vida de um passeio enquanto o arquivo de som está sendo reproduzido.

Exemplo

O exemplo de passeio abaixo tem 15 segundos, definidos pelas durações combinadas de <gx:FlyTo> e <gx:Wait>. O primeiro clipe de som dura 15 segundos e é reproduzido durante todo o passeio. O segundo arquivo é enfileirado para iniciar aos 5 segundos, é combinado com o primeiro arquivo e reproduzido durante 10 segundos. O <gx:Wait> é necessário para ampliar a duração do passeio de modo que os clipes de som tenham tempo suficiente para terminar.

 soundcue_example.kml

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2"
 xmlns:gx="http://www.google.com/kml/ext/2.2">

<gx:Tour>
  <gx:Playlist>
 
    <gx:SoundCue>
      <href>
        http://dev.keyhole.com/codesite/AJsBlues.mp3
      </href>    <!-- 15 second audio clip -->
    </gx:SoundCue>
 
    <gx:FlyTo>
      <gx:duration>5</gx:duration>
      <gx:flyToMode>bounce</gx:flyToMode>
      <LookAt>
        <longitude>-79.387</longitude>
 <latitude>43.643</latitude>
 <altitude>0</altitude>
 <range>1200</range>
 <tilt>10</tilt>
 <heading>-172.3</heading>
 <altitudeMode>relativeToGround</altitudeMode>
 </LookAt> </gx:FlyTo> <gx:SoundCue> <href> http://dev.keyhole.com/codesite/cntowerfacts.mp3 </href> <!-- 10 second audio clip --> </gx:SoundCue> <gx:Wait> <gx:duration>10</gx:duration> <!-- continues the tour for 10 seconds --> </gx:Wait> <!-- while audio clip plays --> </gx:Playlist> </gx:Tour> </kml>

Como ativar e desativar balões de descrição

Um balão de descrição de um marcador pode ser aberto ou fechado durante um passeio, usando <gx:balloonVisibility> em uma atualização animada. As alterações na visibilidade do balão serão feitas no final de qualquer período de tempo especificado; eles serão animados no tempo especificado. A omissão do valor de um <gx:duration> atribuirá o valor padrão de 0.0 (o balão abrirá ou fechará imediatamente).

Exemplo

 balloonvisibility_tourexample.kml

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2"
 xmlns:gx="http://www.google.com/kml/ext/2.2">
  
  <Document>
    <name>balloonVisibility Example</name>
    <open>1</open>

    <gx:Tour>
      <name>Play me</name>
      <gx:Playlist>
 
        <gx:FlyTo>
          <gx:duration>5.0</gx:duration>
          <!-- bounce is the default flyToMode -->
          <LookAt>
            <longitude>-119.748584</longitude>
            <latitude>33.736266</latitude>
            <altitude>0</altitude>
            <heading>-9.295926</heading>
            <tilt>84.0957450</tilt>
            <range>4469.850414</range>
            <gx:altitudeMode>relativeToSeaFloor</gx:altitudeMode>
          </LookAt>
        </gx:FlyTo>

        <gx:AnimatedUpdate>
          <!-- the default duration is 0.0 -->
          <Update>
            <targetHref/>
            <Change>
              <Placemark targetId="underwater1">
                <gx:balloonVisibility>1</gx:balloonVisibility>
              </Placemark>
            </Change>
          </Update>
        </gx:AnimatedUpdate>

        <gx:Wait>
          <gx:duration>4.0</gx:duration>
        </gx:Wait>

        <gx:AnimatedUpdate>
          <Update>
            <targetHref/>
            <Change>
              <Placemark targetId="underwater1">
                <gx:balloonVisibility>0</gx:balloonVisibility>
              </Placemark>
            </Change>
          </Update>
        </gx:AnimatedUpdate>

        <gx:FlyTo>
          <gx:duration>3</gx:duration>
          <gx:flyToMode>smooth</gx:flyToMode>
          <LookAt>
            <longitude>-119.782630</longitude>
            <latitude>33.862855</latitude>
            <altitude>0</altitude>
            <heading>-19.314858</heading>
            <tilt>84.117317</tilt>
            <range>6792.665540</range>
            <gx:altitudeMode>relativeToSeaFloor</gx:altitudeMode>
          </LookAt>
        </gx:FlyTo>

        <gx:AnimatedUpdate>
          <Update>
            <targetHref/>
            <Change>
              <Placemark targetId="underwater2">
                <gx:balloonVisibility>1</gx:balloonVisibility>
              </Placemark>
            </Change>
          </Update>
        </gx:AnimatedUpdate>

        <gx:Wait>
          <gx:duration>4.0</gx:duration>
        </gx:Wait>

        <gx:AnimatedUpdate>
          <Update>
            <targetHref/>
            <Change>
              <Placemark targetId="underwater2">
                <gx:balloonVisibility>0</gx:balloonVisibility>
              </Placemark>
            </Change>
          </Update>
        </gx:AnimatedUpdate>

        <gx:FlyTo>
          <gx:duration>3</gx:duration>
          <gx:flyToMode>smooth</gx:flyToMode>
          <LookAt>
            <longitude>-119.849578</longitude>
            <latitude>33.968515</latitude>
            <altitude>0</altitude>
            <heading>-173.948935</heading>
            <tilt>23.063392</tilt>
            <range>3733.666023</range>
            <altitudeMode>relativeToGround</altitudeMode>
          </LookAt>
        </gx:FlyTo>

        <gx:AnimatedUpdate>
          <Update>
            <targetHref/>
            <Change>
              <Placemark targetId="onland">
                <gx:balloonVisibility>1</gx:balloonVisibility>
              </Placemark>
            </Change>
          </Update>
        </gx:AnimatedUpdate>

        <gx:Wait>
          <gx:duration>4.0</gx:duration>
        </gx:Wait>

      </gx:Playlist>
    </gx:Tour>

    <Placemark id="underwater1">
      <name>Underwater off the California Coast</name>
      <description>
        The tour begins near the Santa Cruz Canyon, 
        off the coast of California, USA.
      </description>
      <Point>
        <gx:altitudeMode>clampToSeaFloor</gx:altitudeMode>
        <coordinates>-119.749531,33.715059,0</coordinates>
      </Point>
    </Placemark>

    <Placemark id="underwater2">
      <name>Still swimming...</name>
      <description>We're about to leave the ocean, and visit the coast...</description>
      <Point>
        <gx:altitudeMode>clampToSeaFloor</gx:altitudeMode>
        <coordinates>-119.779550,33.829268,0</coordinates>
      </Point>
    </Placemark>

    <Placemark id="onland">
      <name>The end</name>
      <description>
        <![CDATA[The end of our simple tour. 
        Use <gx:balloonVisibility>1</gx:balloonVisibility> 
        to show description balloons.]]>
      </description>
      <Point>
        <coordinates>-119.849578,33.968515,0</coordinates>
      </Point>
    </Placemark>

  </Document>
</kml>

Como incorporar imagens históricas

Se o usuário tiver ativado imagens históricas em seu cliente, seu passeio poderá especificar a data a partir da qual as imagens serão obtidas. Para especificar a data da imagem para exibição, inclua um elemento <gx:TimeStamp> no AbstractView. <gx:TimeStamp> também afeta KML baseado em tempo e luz do sol.

A data especificada pela última vez será usada para todas as imagens posteriores.

Exemplo

 historicalimagery_example.kml

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2"
 xmlns:gx="http://www.google.com/kml/ext/2.2">

<gx:Tour>
  <name>Small town over time</name>
  <gx:Playlist>
    <gx:FlyTo>
      <gx:duration>5.0</gx:duration>
      <Camera>
        <gx:TimeStamp>
          <when>1990-08-04</when>
        </gx:TimeStamp>
        <longitude>-121.991</longitude>
        <latitude>47.857</latitude>
        <altitude>7000</altitude>
        <altitudeMode>absolute</altitudeMode>
      </Camera>
    </gx:FlyTo>

    <gx:FlyTo>
      <gx:duration>3.0</gx:duration>
      <gx:flyToMode>smooth</gx:flyToMode>
      <Camera>
        <gx:TimeStamp>
          <when>2009</when>
        </gx:TimeStamp>
        <longitude>-121.991</longitude>
        <latitude>47.857</latitude>
        <altitude>7000</altitude>
        <altitudeMode>absolute</altitudeMode>
      </Camera>
    </gx:FlyTo>

  </gx:Playlist>
</gx:Tour>
</kml>

Problemas conhecidos

Atualmente, o cliente do Google Earth não atende totalmente ao KML de passeio. Veja abaixo alguns problemas conhecidos; eles poderão ser corrigidos nas próximas versões.

• Os elementos <gx:AnimatedUpdate> e <gx:TourControl> quebrarão a curva criada por uma série de FlyTos smooth. Os pontos de FlyTo em ambos os lados desses elementos serão unidos com um caminho linear.
• Os arquivos de som carregados com <gx:SoundCue> continuam a ser reproduzidos durante uma pausa iniciada por <gx:TourControl>. Quando o passeio é retomado, o Google Earth volta ao ponto no arquivo de som no qual a pausa foi disparada.
• Ao usar modos de altitude diferentes de absoluto, o caminho entre FlyTos pode pular para cima ou para baixo à medida que a câmera se aproxima de um ponto. Isso é causado pelo carregamento de dados atualizados de terreno no cliente. À medida que a câmera se aproxima de um ponto, as informações sobre esse ponto se tornam mais e mais detalhadas. Como resultado, a elevação do solo abaixo do ponto pode ser atualizada, exigindo uma correção no caminho até esse ponto.
  
  O mecanismo de gravação no Google Earth especifica modos de altitude absolutos para todos os FlyTos por esse motivo. Você também deverá converter altitudes em valores absolutos se essas correções de caminho estiverem interferindo em seu passeio.