Google Earth toolbox - ge_screenoverlay

View source code of the function ge_screenoverlay() in the MATLAB editor
Google Earth toolbox contents

ge_screenoverlay

Include external images in the GoogleEarth Viewer interface.

Syntax

kmlStr = ge_screenoverlay(fileName)

kmlStr = ge_screenoverlay(fileName,Parameter,Value)

Description

kmlStr = ge_screenoverlay(fileName)

With the above syntax, a screen overlay can be included in the KML string. Screen overlays are useful for including legends, logos, and for displaying non-spatial data. If no parameter/value pairs are specified, the image file fileName is displayed at its true size in the lower left corner of the GoogleEarth Viewer.

kmlStr = ge_screenoverlay(fileName,Parameter,Value)

In addition to the above syntax, a number of options can be set. Assigning values to the parameters can be accomplished by inclusion of an alternating sequence of parameters and their value. The table below provides an overview of the authorized options. The order in which the parameters are included does not matter. Please be aware that the options are case-sensitive. Examples are provided further down.

Parameter	Description
'drawOrder'	Determines which image should be stored on top, when multiple image overlap (at a given time step). Default is 0.
'posBottom'	See 'Remarks' section below. Default is 0.
'posBottomUnits'	See 'Remarks' section below. Default is 'fraction'.
'posLeft'	See 'Remarks' section below. Default is 0.
'posLeftUnits'	See 'Remarks' section below. Default is 'fraction'.
'rotation'	Rotation in degrees around the point specified by sizeLeft and sizeBottom. Default is 0.
'sizeBottom'	See 'Remarks' section below. Default is 0.
'sizeBottomUnits'	See 'Remarks' section below. Default is 'fraction'.
'sizeHeight'	See 'Remarks' section below. Default is 1.
'sizeHeightUnits'	See 'Remarks' section below. Default is 'fraction'.
'sizeLeft'	See 'Remarks' section below. Default is 1.
'sizeLeftUnits'	See 'Remarks' section below. Default is 'fraction'.
'sizeWidth'	See 'Remarks' section below. Default is 1.
'sizeWidthUnits'	See 'Remarks' section below. Default is 'fraction'.
'timeSpanStart'	Determines the start time of a period when the image is visible.
'timeSpanStop'	Determines the end time of a period when the image is visible.
'visibility'	Determines whether the image is initially visible.

Remarks

Positioning an image on the screen is accomplished through specifying

1. which pixel of the screen should be underneath...
2. ...which pixel of the image.

The screen pixel is defined by 'posLeft' (distance from the left side of the Earth Viewer panel) and 'posBottom' (distance from the bottom side of the Earth Viewer panel) parameters. These properties can be defined in units of pixels (...,'posLeftUnits','pixels',... or ...,'posBottomUnits','pixels',...) or as a fraction (...,'posLeftUnits','fraction',... or ...,'posBottomUnits','fraction',...).

Having thus defined item (1) above, we also need to define which pixel of the image should be positioned over the screen pixel we just defined. This is accomplished through the 'sizeLeft' (distance from the left side of the image) and 'sizeBottom' (distance from the bottom side of the image) parameters. These properties can be defined in units of pixels (...,'sizeLeftUnits','pixels',... or ...,'sizeBottomUnits','pixels',...) or as a fraction (...,'sizeLeftUnits','fraction',... or ...,'sizeBottomUnits','fraction',...).

As a final touch, we can set the size of the image using the parameters 'sizeWidth' and 'sizeHeight'), and their units in pixels (...,'sizeWidthUnits','pixels',... or ...,'sizeHeigthUnits','pixels',...) or as a fraction (...,'sizeWidthUnits','fraction',... or ...,'sizeHeigthUnits','fraction',...).

Examples

See the demo file demo_ge_screenoverlay for more details.

The above will generate a *.kml file that looks like the image below when opened in the Google Earth viewer.

---