Getting Started with KMLigPlugIn

KMLigPlugIn processes image data for display in Google Earth. A sequence of jpeg images and camera metadata in RBNB channels is combined into a Google Earth KMZ archive containing a KML and image files. The images are displayed as "billboards", with a time slider to move through the images.

The PlugIn takes as input images and metadata from RBNB channels. A camera's position, orientation, field of view, and image display parameters are used to appropriately locate the images within Google Earth. This information is stored in a metadata channel in the same RBNB folder as the images. If the camera or its field of view change with time, the metadata can be updated along with the images. By convention, for an image channel named "folder/image.jpg", the metadata channel would be "folder/image.xml". An example metadata is shown in Figure 1. The <name> element specifies how the PhotoOverlay should be labeled in Google Earth. The <Camera> element specifies where the camera is positioned and how it is oriented. The <ViewVolume> element specifies how images are displayed relative to the camera. The <Point> element specifies where the icon for the PhotoOverlay is displayed in Google Earth. In practice, the camera's location can be determined via GPS, field observation, or approximated by manipulation within Google Earth to closely overlay the maps and added structures.

<?xml version="1.0" encoding="utf-8"?>
<Meta>
	<name>CollisPO</name>
	<Camera>
		<longitude>-72.28889252700002</longitude>
		<latitude>43.703</latitude>
		<altitude>7</altitude>
		<heading>-95.37000000000015</heading>
		<tilt>90</tilt>
		<roll>0</roll>
	</Camera>
	<ViewVolume>
		<leftFov>-30</leftFov>
		<rightFov>30</rightFov>
		<bottomFov>-22.5</bottomFov>
		<topFov>22.5</topFov>
		<near>20</near>
	</ViewVolume>
	<Point>
		<coordinates>-72.2888925270,43.70291,10.36999999</coordinates>
	</Point>
</Meta>

Figure 1. An example metadata for a camera, which specifies the camera's position, orientation, field of view, and image display parameters.

The PlugIn generates KML by using template files, which are included in the RBNB distribution and automaticallly loaded at runtime. KML2.2 added the PhotoOverlay element, which allows for images to be displayed within Google Earth in a greatly simplified manner compared to the DAE file approach supported in earlier versions. The KMLigPlugIn takes advantage of this new capability, providing the functionality of the KMLitPlugIn with far less complexity.

The output of the KMLigPlugIn is a KMZ archive, which contains single KML file and multiple images. In response to a request, the KMLigPlugIn requests images and metadata from the RBNB server. Values from the metadata are substituted into the template format of the kml file. This template format is defined in two files, kml.kml and photooverlay.kml. Substitutions are made to variables denoted by "##" encasement. The template files are shown in Figures 2 and 3. These template files may be edited, allowing flexibility in deployment. For example, the icon can readily be customized.

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

Figure 2. Template file used to generate kml content.

<PhotoOverlay>
	<name>##name##</name>
	<description>autogenerated by KMLigPlugIn</description>
	<TimeSpan>
		<begin>##begin##</begin>
		<end>##end##</end>
	</TimeSpan>
	<Camera>
		<longitude>##clongitude##</longitude>
		<latitude>##clatitude##</latitude>
		<altitude>##caltitude##</altitude>
		<tilt>##ctilt##</tilt>
		<heading>##cheading##</heading>
		<roll>##croll##</roll>
	</Camera>
	<Style>
		<IconStyle>
			<Icon>
				<href>http://maps.google.com/mapfiles/kml/shapes/camera.png</href>
			</Icon>
		</IconStyle>
	</Style>
	<Icon>
		<href>##href-jpg##</href>
	</Icon>
	<shape>rectangle</shape>
	<ViewVolume>
		<near>##vnear##</near>
		<leftFov>##vleftfov##</leftFov>
		<rightFov>##vrightfov##</rightFov>
		<bottomFov>##vbottomfov##</bottomFov>
		<topFov>##vtopfov##</topFov>
	</ViewVolume>
	<roll>0</roll>
	<Point>
		<coordinates>##coordinates##</coordinates>
	</Point>
</PhotoOverlay>

Figure 3. Template file used to generate PhotoOverlay elements within kml files.

The output of KMLigPlugIn can also be adjusted on a per-request basis. The maximum number of images and minimum interval between images can be specified by URL munges. The parameters are kmlit_count and kmlit_interval, respectively. For example, a URL specifying no more than 30 images over a 120 second request is: