KML Screen Overlays

The primary purpose of virtual globes is to display data and images on the globe. But there is often ancillary information that needs to be included as well. Things like the dataset title, or a legend defining the colors used in the imagery, don't belong on the globe but are still needed. Screen overlays are images that are displayed on the screen to put the other information in context.

Use of screen overlays is a bit tricky and there is a large section on them in the KML 2.1 Reference. This primer covers all the same material in the hope that a second perspective may help clarify some of the trickier points. Additionally we have created a kml file filled with examples that users can load into Google Earth and modify on their own to get a sense of how screen overlays work.

Introduction: A screen overlay is an image that will appear on the screen in the same location, staying the same size, no matter what happens with the earths zoom, rotation, tilt angle, etc. They are used for displaying the logo of the originating organization, a legend for the data, or some other relevant information.

There are two coordinate systems at work:
The coordinate system of the screen is called "screenXY"
The coordinate system of the image itself is called "overlayXY"

You use these two coordinate systems to pin one point in the image (overlay) to one point on the screen using (x, y) coordinates for each defined in some units.

For both screen and image the default origin (0,0) is the lower left corner. X is positive to the right, y is positive up. Both are the upper right quadrant of a Cartesian coordinate system.

The available units are:
fraction: x and y are some fraction of the total width and height.
pixels : x and y are the number of pixels from the origin (lower left).
insetPixels: x and y are the number of pixels from the UPPER RIGHT corner. x is positive to the left and y is positive down.

Fraction Units: The "fraction" unit is appealing since as long as you stay between (0, 1) your image is guaranteed to always be on the screen. Moving around is fairly intuitive and corner points are well defined.

(0,0) = lower left corner
(0,1) = upper left corner
(1,0) = lower right corner
(1,1) = upper right corner

For example: You can pin the center of the image to center of the screen with:

<overlayXY x="0.5" y="0.5" xunits="fraction" yunits="fraction"/>
<screenXY x="0.5" y="0.5" xunits="fraction" yunits="fraction"/>

If you want to pin the upper left corner of your logo (overlay) NEAR the upper left corner of the screen, but leave a slight gap for framing, use:

<overlayXY x="0" y="1" xunits="fraction" yunits="fraction"/>
<screenXY x="0.05" y="0.95" xunits="fraction" yunits="fraction"/>

The disadvantage of fraction units is they're relative. If you have only one image that may not be an issue - but if you have multiple images you are trying to lay out in some artistic or functional way, it can be a problem. There will always be some screen size that will cause your images to overlap, or be further apart than you intended.

One practical example: We made a movie of the sea ice extent and thought it would be nice to put the date of the image in the legend box. But because the date changed while the legend didn't we needed those to be separate images. There was no way to tie those together using fraction units because changing the screen size changes the relative positions of the images so we could never guarantee the date graphic would stay nicely framed by the legend graphic.

Pixels/insetPixels: When using fractions to define relative coordinates won't work you can use absolute coordinates. The "pixel" and "insetPixel" units can be mixed and matched to specify points any distance away from any corner. So you can move the origin around to where you want it.

(pixel, pixel) -> (0,0) is in the lower left, positive right & up
(pixel, insetPixel) -> (0,0) is in the upper left, positive right & down
(insetPixel, pixel) -> (0,0) is in the lower right, positive left & up
(insetPixel, insetPixel) -> (0,0) is in the upper right, positive left & down.

When using absolute coordinates there is always a danger of the user resizing the screen small enough that your overlay is outside the veiwable window. We recommend keeping your coordinates small by picking the origin closest to where you want the overlay. As a rule you should probably avoid the upper right corner of the screen since that's where Google has their navigation widget.

For the example cited above we wanted a logo and a legend in the upper left corner, and we wanted the date image of the currently displayed ground overlay to fit nicely with the other two. But the date gets updated every three seconds while the logo and legend are static. We want to keep the date graphic as small as possible to keep performance up, but still have it integrated into the grouping. So we went with:


<overlayXY x="0" y="1" xunits="fraction" yunits="fraction"/>
<screenXY x="5" y="5" xunits="pixels" yunits="insetPixels"/>
<size x="115" y="90" xunits="pixel" yunits="pixel"/>


<overlayXY x="0" y="1" xunits="fraction" yunits="fraction"/>
<screenXY x="125" y="5" xunits="pixels" yunits="insetPixels"/>
<size x="250" y="70" xunits="pixel" yunits="pixel"/>


<overlayXY x="0" y="1" xunits="fraction" yunits="fraction"/>
<screenXY x="125" y="75" xunits="pixels" yunits="insetPixels"/>
<size x="250" y="20" xunits="pixel" yunits="pixel"/>

For every graphic we are choosing the upper left corner of the graphic (overlayXY) to be the point we pin to the screen (screenXY). We pin the logo in the upper left corner of the screen, 5 pixels in and 5 pixels down. Then we pin the legend next to the logo, still 5 pixels down but 5+115+5=125 pixels in or 5 pixels to the right of the logo. Then because the legend is shorter than the logo, there is a nice little nook for the date to fit in. We pin the date graphic 75 pixels down (95-20) so the bottom will line up with the bottom of the logo.

The NSIDC_screen_overlays.kml file contains examples of overlay images placed in various locations around the screen. For the examples we used fractions to pick a point on the image, and pixels/insetPixels to pick a point on the screen, so we could pin the image a slight distance away from the edge of the screen. If you have other examples you'd like to see included let us know.