Feedback on KML 2.2

[ManoM]

On May 31st this year, at Developer Day, Google previewed early Beta
documentation for KML 2.2, the latest update to our geographic data
presentation language. That preview introduced a number of important
features to KML, including:

* PhotoOverlay
* Camera
* Atom attribution elements
* Limiting session length in NetworkLinks
* Linking between features

When Google Earth 4.2 was released on August 22nd, KML 2.2 Beta was
officially released, with some additions to what was previewed in May.
Here's what's new:

* 1) ExtendedData, which allows sophisticated balloon templating,
and gives you the ability to embed your own custom typed data in KML
files. For more information, see the Adding Custom Data page.
* 2) Linking between features. There was a syntax change for this
feature. For more information, see the KML 2.2 Reference.
* 3) Sky Data. For more information, see the Sky Data in KML page.

Very soon now, KML 2.2 will be exiting beta. Please give us your
feedback and questions on the new features of KML 2.2 as soon as
possible. We look forward to seeing what you create!

[Jonathan van Tuijl]

Some thoughts:
- viewFormat doesn't support all camera projections possible now, such
as roll or a sheared perspective when looking at a rectangular photo.
The latter can be left out for now if GE sends a view encompassing its
current projection one way or another. It could also rotate rather
than shear. Also, if camera(Tilt|Heading) existed it wouldn't equal
lookat(Tilt|Heading) (at high altitudes the difference can get huge).
Same for lookatTerrain(Tilt|Heading|Range). I think GE has the
foundation to calculate these easily, and that any program doing this
kind of work needs it. Would probably look less bloated than it is
inconsistent now.
- Some things can only be found in the tutorials or examples, e.g. how
an ImagePyramid works exactly. It should be in the spec.
- Do we really need to provide every unused tile? At 640x480 only 6
out of 16 256x256 tiles are used at level 2. Compression is effective
though, but it's still clutter.
- Is it reasonable for edge tiles to be allowed to be smaller? Like
256x256 256x256 128x256 for the top row and 256x224 256x224 128x224
for the bottom row. It isn't rocket science to add padding in the
viewer, or to replicate the last rows and columns to help
interpolation at the very edge.
- If I had to choose for another <shape>, it'd be a cube. Better
resolution uniformity for an all-around image and only needs planes
(can be taken straight from graphics hardware which might be used to
automatically render an all-around panorama). A disadvantage is that
it has six faces that don't map very well to one 2D image. Hopefully
the reason I only see them in QTVR panoramas isn't another software
patent.
- The way the Earth and sky are combined is flawed; the coordinate
systems don't generally match up and can't be automatically converted
because it's not known which is used where.

Jonathan

[JasonBirch]

OK, I have to say that I like this new structure for Schema A LOT. It
fits my requirements for KML to remain as a potentially self-contained
language, while making it a lot easier to parse/support in other
apps. Either you've been paying attention to community input, or you
guys really are all genuises :)

I'm not sure why the structure needs to be so verbose though. Instead
of this:

<Schema name="string" id="ID">
<SimpleField type=string" name="string">
<displayName>...</displayName> <!-- string -->
</SimpleField>
</Schema>

Couldn't you do this?

<Schema name="string" id="ID">
<SimpleField type=string" name="string">displayName</SimpleField>
</Schema>

I guess you get into design issues once you get into the actual Data
and SchemaData elements though, because you want to be able to use
CDATA in the displayName, and I'm not sure if you can do that in an
attribute value. So people would get confused by the two locations
for displayName.

I'd also really like to see SimpleArrayField supported. It was in
2.1, but never adequately documented. I have some strong use cases
for this (various length constructs for holding building permits and
multi-year assessment data on a property report). However, you would
have to add some kind of looping construct to the balloon templating
language to properly support it. You'd have to pre-process before
sending to QT, but I'm guessing that you're already doing that for the
attribute substitution?

Also, I really need some way of applying formating (sprintf-style,
with date enhancements except -- oh darn -- SimpleField doesn't
support date) to a typed field. If I could define the formatMask in
the initial Schema section, that would be awesome. Huh, I think I may
have presented a need for another sub-element of SimpleField :)

<Schema name="PropertyData" id="ID">
<SimpleField type="int" name="gislink">
<displayName>GIS Link</displayName>
</SimpleField>
<SimpleField type="string" name="address">
<displayName>Address</displayName>
</SimpleField>
<SimpleArrayField name="assessments">
<SimpleField type="int" name="year">
<displayName>Year</displayName>
</SimpleField>
<SimpleField type="real" name="string">
<displayName>TotalValue</displayName>
<formatMask>$%01.2f</formatMask>
</SimpleField>
</SimpleArrayField>
</Schema>

The formatting could just be done in the template I guess... maybe
more flexible?

It would be nice if there were optional "length" and "precision"
attributes on SimpleField. This would make importing data a lot
easier. And did I mention that I'd really like a date data type? ;)

Oh, I have some questions about <Camera>

Did its description change, or have I misread it from the start? Its
docs say that it can be placed within any element which extends
<Feature>. Does this mean that I can place a Camera within a Folder
(which inherits from Feature by way of Container)? It also has an ID
field. Does this mean that I can link to a Camera using a (network
link or <a> element within a description or... some other means)? And
if multiple Cameras are placed within a Folder, will I be able to
"Play" the Folder as a tour from within Google Earth?

Jason

[JasonBirch]

Well, I just answered part of my question. I can add two cameras to a
folder, but they don't show up in the list, nor can they be used for a
tour. Too bad :( That would have been really awesome for some if the
video recording I do at work with Pro.

It also looks like I'm not allowed to do this:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.2">
<Document>
<Camera id="camera1">
<longitude>-124</longitude>
<latitude>49.8</latitude>
<altitude>1000</altitude>
<heading>30</heading>
<tilt>90</tilt>
</Camera>
<Camera id="camera2">
<longitude>-125</longitude>
<latitude>48.8</latitude>
<altitude>2000</altitude>
<heading>210</heading>
<tilt>90</tilt>
</Camera>
<Placemark>
<name>Test</name>
<description><![CDATA[
<a href="#camera1;flyto">Camera 1</a>
<a href="#camera2;flyto">Camera 2</a>
]]></description>
<Point>
<coordinates>
-123.22942809433,48.57834409549591,0
</coordinates>
</Point>
</Placemark>
</Document>
</kml>

More sadness :)

[JasonBirch]

OK, you rock :)

I still want all the cool stuff that I asked for, but the existing
schema stuff and the ability to link between features is really cool.
I've just written a post about my experience playing with this here:

http://www.jasonbirch.com/nodes/2007/09/08/129/kml-schema-rides-again/

I did run into a few problems over the course of my experiments:

- <name>$[newt/name]</name> sorta worked. The name showed up in
Places, but not on the placemark annotation

- <styleUrl>#$[newt/style_id]</styleUrl> flat out did not work, which
was disappointing, as it would be very nice to be able to switch
styles based on an attribute. It would make thematic mapping a lot
easier.

- Did I already say I wanted an attribute formatter and date
support? :)

- When I saved the KML in Google Earth it removed my CDATA tags and
just turned everything into html entities. Ick.

I wonder if using BalloonStyle is doing myself a disservice though.
Unless the search engine spiders are going to be reading the extended
data information, I be better off for findability by just cluttering
up my KML with a bunch of fully specified description tags. I think
I'll take the high road, and hope that the spiders are doing the right
thing...

Jason

[Jonathan van Tuijl]

JasonBirch wrote:
> Oh, I have some questions about <Camera>
>
> Did its description change, or have I misread it from the start? Its
> docs say that it can be placed within any element which extends
> <Feature>. Does this mean that I can place a Camera within a Folder
> (which inherits from Feature by way of Container)? It also has an ID
> field. Does this mean that I can link to a Camera using a (network
> link or <a> element within a description or... some other means)? And
> if multiple Cameras are placed within a Folder, will I be able to
> "Play" the Folder as a tour from within Google Earth?

You might as well try to fly to a ListStyle, where the purpose of the
id field, just as it is for Camera or indeed any Object, is to allow
<Update>ing. You can simply only fly to Features.

This should work if it doesn't include typos:

<Folder>
<Style>
<ListStyle>
<listItemType>checkHideChildren</listItemType>
</ListStyle>
</Style>
<description><![CDATA[<ul>
<li><a href="#camera1;flyto">Camera 1</a></li>
<li><a href="#camera2;flyto">Camera 2</a></li>
</ul>]]></description>
<Placemark id="camera1">
<Camera>

<longitude>-124</longitude>
<latitude>49.8</latitude>
<altitude>1000</altitude>
<heading>30</heading>
<tilt>90</tilt>
</Camera>

</Placemark>
<Placemark id="camera2">
<Camera>

<longitude>-125</longitude>
<latitude>48.8</latitude>
<altitude>2000</altitude>
<heading>210</heading>
<tilt>90</tilt>
</Camera>

</Placemark>
</Folder>

Whether a tour works with that, I don't know.

Jonathan

[JasonBirch]

On Sep 8, 2:37 pm, Jonathan van Tuijl wrote:
> You might as well try to fly to a ListStyle, where the purpose of the
> id field, just as it is for Camera or indeed any Object, is to allow
> <Update>ing. You can simply only fly to Features.

Understood, but I was hoping to convince Google to change the Camera
to be more like a Feature (see the KML feature request page).

It's annoying that I have to place an arbitrary invisible point just
to be able to tell GE to fly to a certain place and look in a
particular direction. It clutters up the web with irrelevant
Features. You used to be able to run a tour across Folders with
LookAt values, which was moderately workable, but that feature went
away with 4.x.

IMO, the view points (Camera, LookAt) need to be divorced from the
Features, as they're more of an instruction to Google Earth (and other
viewers) than an attribute of a specific Feature. They
could still be used as attributes of Features for simplicity, but it
shouldn't be required.

Jason

[JasonBirch]

I wrote:
> It's annoying that I have to place an arbitrary invisible point

It's annoying that I didn't actually pay enough attention to your
example :) If I'm creating the points through GE, I have to create
the points, but I can strip them out after. I'd never even considered
creating a placemark without geometry.

I guess it's a reasonable (this still not entirely satisfactory in my
mind) solution to have Placemarks without name, description, or
geometry as the holders for Cameras. This certainly reduces the
"clutter" effect anyway.

Hiding the folder's contents with the ListStyle did not allow the tour
mode to work. However, defining a null icon and hiding the balloon
worked well:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.2">
<Document>

<open>1</open>
<name>Google Earth Tour</name>
<Style id="cameraStyle">
<BalloonStyle>
<displayMode>hide</displayMode>
</BalloonStyle>
<IconStyle>
<Icon />
</IconStyle>
</Style>
<Folder>
<name>Press Play</name>
<open>0</open>
<Snippet maxLines="2">
<![CDATA[
<a href="#camera1;flyto">Camera 1</a><br />
<a href="#camera2;flyto">Camera 2</a><br />
]]>
</Snippet>
<Placemark id="camera1">
<styleUrl>#cameraStyle</styleUrl>

<Camera>
<longitude>-124</longitude>
<latitude>49.8</latitude>

<altitude>4000</altitude>
<heading>30</heading>
<tilt>35</tilt>

</Camera>
</Placemark>
<Placemark id="camera2">

<styleUrl>#cameraStyle</styleUrl>

<Camera>
<longitude>-125</longitude>
<latitude>48.8</latitude>
<altitude>2000</altitude>
<heading>210</heading>

<tilt>70</tilt>
</Camera>
</Placemark>
</Folder>
</Document>
</kml>

Here's a larger prototype on my site (I cheated and used LookAt,
because that's what GE gives me when I Snapshot View):

http://www.jasonbirch.com/files/VITour.kml

Jason

[Chris 'Xenon' Hanson]

On Sep 7, 3:57 pm, ManoM wrote:
> On May 31st this year, at Developer Day, Google previewed early Beta
> documentation for KML 2.2, the latest update to our geographic data
> presentation language. That preview introduced a number of important
> features to KML, including:

> * Camera

> Very soon now, KML 2.2 will be exiting beta. Please give us your
> feedback and questions on the new features of KML 2.2 as soon as
> possible. We look forward to seeing what you create!

I think I posted this elsewhere during the beta, but I'd REALLY like
to know why the field of view (in ViewVolume) is only in the
PhotoOverlay and not in the Camera itself? It sure would be helpful to
be able to specify it in a Camera, since GE obviously can control it.
And, I'd really like to see an animated camera path without having to
use a network link to reload it continuously.

[Jonathan van Tuijl]

Chris 'Xenon' Hanson wrote:
> I think I posted this elsewhere during the beta, but I'd REALLY like
> to know why the field of view (in ViewVolume) is only in the
> PhotoOverlay and not in the Camera itself? It sure would be helpful to
> be able to specify it in a Camera, since GE obviously can control it.

Probably because it's only essential for photos. The UI would get
quite messy if everything that could ever be an option was made an
option, and limiting it to KML wouldn't do much good. Every option has
to be carefully considered (if it wasn't for that we could specify a
custom 4x4 matrix, or at least certain types of shear if the culling
code can't handle arbitrary projections). With standard controls it's
likely to confuse the typical end user because it looks similar to
what he probably already calls zooming, but can be very different. I
would personally like zoom in my navigation controls though,
especially now that I have a SpaceNavigator with which I don't move
relative to the ground in front; just thinking whether it's good for
GE.

Note on KML 2.2: wouldn't rectangle be a better default shape for
PhotoOverlays? I believe cylindrical panoramas are less common.

Jonathan

[Valery35]

Nice!

My testing and ideas for new features see also
http://gisplanet.blogspot.com/2007/09/ge-42-photo-overlay-examples.html
http://gisplanet.blogspot.com/2007/09/ge-42-embed-flash-in-balloon.html
http://gisplanet.blogspot.com/2007/08/ge-42-photo-overlay-embed-video-and.html

[Chris 'Xenon' Hanson]

On Sep 8, 11:24 pm, Jonathan van Tuijl wrote:
> Chris 'Xenon' Hanson wrote:
> > I think I posted this elsewhere during the beta, but I'd REALLY like
> > to know why the field of view (in ViewVolume) is only in the
> > PhotoOverlay and not in the Camera itself? It sure would be helpful to
> > be able to specify it in a Camera, since GE obviously can control it.
> Probably because it's only essential for photos. The UI would get
> quite messy if everything that could ever be an option was made an
> option, and limiting it to KML wouldn't do much good.

> Jonathan

Remember, just because GE doesn't implement something doesn't mean KML
shouldn't. KML is supposed to be an industry standard, and by that
definition, it ought to be feature complete.

Regardless of that, I still think it wouldn't be killing GE to offer
FOV/Zoom control. Yes, you can already move forward and backwards in
the scene, but there are many viewpoints in the real world that can't
be represented that way, as the PhotoOverlay has demonstrated.

[Jonathan van Tuijl]

Chris 'Xenon' Hanson wrote:
> Remember, just because GE doesn't implement something doesn't mean KML
> shouldn't. KML is supposed to be an industry standard, and by that
> definition, it ought to be feature complete.

Yep. It's currently tied much to GE, but it's moving away from that.

> Regardless of that, I still think it wouldn't be killing GE to offer
> FOV/Zoom control. Yes, you can already move forward and backwards in
> the scene, but there are many viewpoints in the real world that can't
> be represented that way, as the PhotoOverlay has demonstrated.

Yeah. In fact I played with the PhotoOverlay placement UI with my
SpaceNavigator. Because the SN lets you spin in place you can use it
to telescope around. The high degree of anisotropy and GE's limited
use of anisotropic filtering makes images blurry though. It's also
hard to keep it under control; it rotates just as fast, but when
you're zoomed in 20x it's 20x as fast relative to the viewport! To add
to that, I use the highest sensitivity it allows. I still manage
though, and it's quite fun. Position yourself a few kilometers above
the ground, zoom in all the way, and start looking for known places,
trace trajectories, etc.

The real argument against it is that when you're just looking around,
which is what GE is used for most of the time, you can do with a
reasonable fixed FOV, and less controls is better for most users.
Again, I'd personally like FOV control, especially now that I've
played with it. :-)

Just a little note on zoom implementation: it's best to implement it
so that when you're supposed to be zooming at a constant speed, the
motion vectors in the viewport stay the same. It can be done by
emulating exponential focal length, not FOV *ANGLE*, which deviates
much at the wide end.

Jonathan

[jaggu]

Hi Manom,
I couldn;t find information on how to link between features in kml
2.2.. could u plz show me some pointers on how to do it?

Regards,
jagadeesh

[Jonathan van Tuijl]

jaggu wrote:
> I couldn;t find information on how to link between features in kml
> 2.2.. could u plz show me some pointers on how to do it?

See the red addition to http://code.google.com/apis/kml/documentation/kml_tags_beta1.html#description
. If your browser doesn't automatically stay at description, click
<description> in the bar on your left. A complete example would be:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.2">
<Document>

<name>Linking example</name>
<description><![CDATA[<a href="#feature1;balloon">Open Feature 1's
balloon</a>]]></description>
<Placemark id="feature1">
<name>Feature 1</name>
<description><![CDATA[<a href="#feature2;flyto">Fly to Feature 2</
a>]]></description>
<Point>
<coordinates>0,0</coordinates>
</Point>
</Placemark>
<Placemark id="feature2">
<name>Feature 2</name>
<description><![CDATA[<a href="#feature1;balloonFlyto">Fly to
Feature 1 and open its balloon</a>]]></description>
<Point>
<coordinates>0.03,0</coordinates>
</Point>
</Placemark>
</Document>
</kml>

If you want to continue discussing this, please create another thread
(click "Getting Started" on your right and then "+ Post your
question"). It's off-topic here.

Jonathan

[Chris 'Xenon' Hanson]

On Sep 9, 10:21 am, Jonathan van Tuijl wrote:
> The real argument against it is that when you're just looking around,
> which is what GE is used for most of the time, you can do with a
> reasonable fixed FOV, and less controls is better for most users.
> Again, I'd personally like FOV control, especially now that I've
> played with it. :-)

> Jonathan

Yeah. I think that zoom factors other than the nominal "naked eye" are
essential to the typical user experience. But who am I...?

[johnb]

I think there's a problem with the addition of the atom:link.
NetworkLink now contains both an "atom:link" and a "kml:link." When
using JAXB to generate classes from the schema, these both map to a
field named "link." This naming collision causes the kml:link to be
replaced by the atom:link. This makes it unusable using JAXB. I
suggest renaming the kml:link type. This breaks backwards-
compatibility, but no more than renaming ImageLink to BasicLink.

Thanks,
John

On Sep 7, 5:57 pm, ManoM wrote:
> On May 31st this year, at Developer Day, Google previewed early Beta

> documentation forKML2.2, the latest update to our geographic data

> presentation language. That preview introduced a number of important

> features toKML, including:

>
> * PhotoOverlay
> * Camera
> * Atom attribution elements
> * Limiting session length in NetworkLinks
> * Linking between features
>

> When Google Earth 4.2 was released on August 22nd,KML2.2Beta was

> officially released, with some additions to what was previewed in May.
> Here's what's new:
>
> * 1) ExtendedData, which allows sophisticated balloon templating,
> and gives you the ability to embed your own custom typed data inKML
> files. For more information, see the Adding Custom Data page.
> * 2) Linking between features. There was a syntax change for this
> feature. For more information, see theKML2.2Reference.
> * 3) Sky Data. For more information, see the Sky Data inKMLpage.
>

> Very soon now,KML2.2will be exiting beta. Please give us your
> feedback and questions on the new features ofKML2.2as soon as

[ManoM]

Hi John,

But kml:Link is upper case, and atom:link is lower. It shouldn't cause
that problem. I'm not hugely familiar with JAXB, but I know Java is
case sensitive. Are you ignoring case? That would be a dangerous thing
to do with KML.

ManoM

[JasonBirch]

On Sep 8, 2:30 am, I wrote:
> - <styleUrl>#$[newt/style_id]</styleUrl> flat out did not work, which
> was disappointing, as it would be very nice to be able to switch
> styles based on an attribute. It would make thematic mapping a lot
> easier.

The more I play with this new Schema stuff, the more I want to use it
in _ALL_ KML fields. For instance, I want to take my pano metadata
(fov, etc) and store it in attributes, and then reference these
attributes in the PhotoOverlay. Separation of data and
presentation...

Jason

[johnb]

Hi ManoM,

Thanks for the fast reply. I know both KML and Java are case
sensitive, but JAXB uses Sun's naming convention of fields always
starting with a lower-case letter. So both fields are named "link."
FeatureType is generated just fine with a protected field "link", but
NetworkLinkType subclasses it and can't have another protected field
of the same name. Instead it has all of its fields replaced with a
single list called "rest" that has the url, refreshVisibility, link,
and flyToView all lumped together. There's no way to access the
individual fields directly.

This is admittedly as much of a JAXB problem as a KML problem, but
since the 2.2 spec is still in draft it would be nice to make it
compatible with as many existing tools as possible.

Thanks,
John

[ManoM]

Hi John,

Doesn't JAXB have any provision for namespace support? That would be
very basic for an XML library.

ManoM

[Izhido]

Something to consider: under <BalloonStyle><text>, a listing of
possible feature $[tags] is mentioned. However, at first sight, and
unless you read every word carefully, the document seems to imply
these tags are the ***only*** tags allowed there. It would be cool if
the document either: 1) Mentioned all of the tags the <text> tag
allow, or 2) Be more specific about the fact that **all** <Feature>
(and descendant) tags are allowed there.

- Izhido

[BobPeters]

Please let there be a way to access a Placemark's current lat/long in
the <description> or some like place.
That way I can create a link that submits its current location to a
server so I can correct its position in an external database.

Thanks,

Bob

[aaime]

On 7 Set, 23:57, ManoM wrote:
> On May 31st this year, at Developer Day, Google previewed early Beta
> documentation for KML 2.2, the latest update to our geographic data
> presentation language. That preview introduced a number of important
> features to KML, including:
>
> * PhotoOverlay
> * Camera
> * Atom attribution elements
> * Limiting session length in NetworkLinks
> * Linking between features
>
> When Google Earth 4.2 was released on August 22nd, KML 2.2 Beta was
> officially released, with some additions to what was previewed in May.
> Here's what's new:
>
> * 1) ExtendedData, which allows sophisticated balloon templating,
> and gives you the ability to embed your own custom typed data in KML
> files. For more information, see the Adding Custom Data page.

I have some feedback on the typed data part of KML 2.2.
It surely looks nice from the perspective of a GIS developer, yet
raises questions:
* int, short... what's the range? Are you assuming 32bit ints, 64bit
ints? If 32bits,
no support for the long type?
* there is no way to encode a date?

All in all, since KML is an XML flavour, wouldn't it make more sense
to
specify the type using the well known XSD primitive data types,
defined here:
http://www.w3.org/TR/xmlschema-2/#built-in-primitive-datatypes
(and assuming the default value for all facets, to avoid making the
specification
too complex).

The nice thing is that they are well known and precisely defined both
in the semantics and in how they are expected to be encoded.

Cheers
Andrea Aime

[ManoM]

Hi Andrea,

These types are in fact defined in terms of XSD primitive data types,
we simply haven't done a good job explaining that in the current
documentation.

Mano

[BenG]

Hi, This link here
http://code.google.com/apis/kml/documentation/kml_tags_beta1.html#kml
says: "A basic <kml> element contains 0 or more Features and 0 or 1
NetworkLinkControl"
however the kml22beta.xsd indicates there can really only be 0 or 1
Features inside of a <kml> element.
Is this a mistake in the kml 22 reference?

On Sep 7, 5:57 pm, ManoM wrote:

[ManoM]

Hi BenG,

In this case, the schema is correct, the documentation is incorrect.
Thanks for bringing this to our attention.

ManoM

On Oct 31, 7:44 am, BenG wrote:
> Hi, This link herehttp://code.google.com/apis/kml/documentation/kml_tags_beta1.html#kml