KARML Reference

KARML Extensions

The KARML extension to KML seeks to make as few modifications as necessary to author and display AR experiences. The most important limitation of KML is the lack of control the user has over the display and placement of labels, icons and the HTML content in balloons.

In order to allow greater control over each rendering element, the KARML extension adds an abstract class above KMLModel called KMLRender from which a KMLBalloon, KMLLabel, KMLSound and KMLTracker node are derived. These classes inherit the same location, orientation and scaling elements that the current KMLModel element has. This allows the user to optionally specify the exact positioning of the label, icon and balloon content individually. Because these elements are usually billboarded towards the user, we added an orientationMode to allow the user to accomplish anything from relative size billboarded content to fixed orientated and scaled content within the world. In addition to orienting content fixed to the world, we added a relative option to both the locationElement and the orientationElement so that objects can be located and oriented relative to the user (#user) or another element in the scene.

The following is an example of a basic KML feature at a designated set of coordinates. In GoogleEarth and in the Argon browser, a default icon and the feature name label is visible by default. Clicking on the icon brings up a description balloon using the default balloon styling (Note: the default style is white text against black semi-transparent background):

<Placemark>
        <name>MyPlacemark</name>
        <description>Example placemark</description>
        <Point id="coolPoint16">
                <coordinates>-84.388,33.773,0</coordinates>
        </Point>
</Placemark>

In order to give the user greater control over how the balloon content is rendered, the KARML extension adds undecorated to the displayMode element within BalloonStyle. The following example demonstrates how a placemark can use an undecorated style to indicate that HTML within the description element should only rely on the style defined therein (Note: applying no style produces white text against transparent background):

<Style id="mystyle">
        <BalloonStyle>
                <displayMode>undecorated</displayMode>
        </BalloonStyle>
</Style>
<Placemark>
        <name>MyPlacemark</name>
        <description><![CDATA[
                <style type="text/css">
                div.myclass
                {
                        background-color:                        rgba(0, 0, 255, 0.5);
                        border-width:                        1px;
                        border-color:                        rgba(0, 255, 0, 1.0);
                        color:                                rgba(255, 0, 0, 1);
                }
                </style>
                <div class="myclass">A self decorated placemark</div>
        ]]>
        </description>
        <Point>
                <coordinates>-84.388,33.773,0</coordinates>
        </Point>
        <styleUrl>#mystyle</styleUrl>
</Placemark>

As with standard KML, JavaScript can be placed within the CDATA block. While the KARML extension cannot enforce such behavior, the KHARMA architecture calls for a single global JavaScript namespace. Because, HTML content can be created on the fly, each CDATA block has a separate init function named after the feature rendering it:

<Placemark id="myplacemark">
        <name>MyPlacemark</name>
        <description><![CDATA[
                <script language="text/javascript">
                function setupContent () {
                        var div = document.getElementById("mydiv");
                        div.innerHTML("Dynamically generated balloon content");
                }

                //init function is the id of the feature followed by "_init"
                function myplacemark_init() { setupContent(); }
                </script>
                <div id="mydiv">empty</div>
        ]]>
        </description>
        <Point>
                <coordinates>-84.388,33.773,0</coordinates>
        </Point>
</Placemark>

The KARML Balloon element overrides any Point element and allows the HTML content defined within the description balloon to be given a location and orientation within the world. This element is modeled after the existing Model element and adds locationMode, orientationMode and scaleMode elements. The relative locationMode lets the user place content relative to the node specified in the targetHRef attribute using units other than the default. The following is an example of a KML Placemark whose HTML description balloon element is placed 2.0 meters north of the user (Note: The default orientation mode for a Balloon element is world fixed):

<Placemark>
        <name>MyPlacemark</name>
        <description>My example placemark relative to user</description>
        <Balloon>
                <locationMode targetHRef=”#user”>relative</locationMode> <!-- fixed (default), relative -->
                <location>
                        <latitude units="meters">2.0</latitude>
                        <longitude>0.0</longitude>
                        <altitude>0.0</altitude>
                </location>
                <orientationMode>billboard</orientationMode> <!-- fixed (default), relative, billboard -->
                <scaleMode>relative</scaleMode> <!-- fixed (default), relative -->
        </Balloon>
</Placemark>

Standard KML does not give the user much control over the placement of feature labels. The KARML label element allows the position, orientation and scaling of the label and icon to be specified independently of the description content. The scaleMode allows either fixed perspective scaling or the relative psuedo-depth scaling used in GoogleEarth (Note: The default scale mode for a Label element is world fixed):

<Placemark>
        <name>MyPlacemark</name>
        <description>My example placemark with oriented label</description>
        <Label>
                <locationMode>relative</locationMode>
                <location>
                        <latitude units="meters">6.0</latitude> <!-- default targetHref is #user -->
                        <longitude>0.0</longitude>
                        <altitude>0.0</altitude>
                </location>
                <orientation>
                        <heading>0.0</heading>
                        <tilt>0.0</tilt>
                        <roll>20.0</roll>
                </orientation>
               <scaleMode>relative</scaleMode> <!-- fixed (default), relative -->
        </Label>
</Placemark>

Another important consideration for the KARML markup is the detection and rendering of GEOSpots. GoogleEarth uses the LookAt and Camera elements to move the viewpoint to a specific geographic location and orientation. Since the user is in direct control of the viewpoint, these elements have been appropriated for defining GEOSpots. As a result, any KML feature with a Camera or LookAt element is indicated in the browser map view as a GEOSpot. Because geospots need a descriptive photo of the exact location to stand, KARML adds an optional icon element to the Camera and LookAt elements.

The following example is of a GEOSpot that has no synthetic backdrop:

<Placemark>
        <name>geospot1</name>
        <description>an example geospot with no panorama</description>
        <Camera>
                <longitude>-84.38832402520215</longitude>
                <latitude>33.77700206899468</latitude>
                <altitude>0</altitude>
                <tilt>0</tilt>
                <heading>0.004599010551754887</heading>
                <altitudeMode>relativeToGround</altitudeMode>
                <Icon>
                        <href>http://research.cc.gatech.edu/test.jpg</href>
                </Icon>
        </Camera>
        <Point>
                <coordinates>-84.389,33.776,0</coordinates>
        </Point>
</Placemark>

A GEOSpot that has a synthetic backdrop is created using the existing KMLPhotoOverlay element. Although the KML standard already accommodates a spherical overlay, we added a cube to the shape element because the majority of user generated panoramic images use a cubic format. The KARML extension allows for the macro $[side] to be resolved to front,back,left,right,top,bottom, $[s] to be resolved to f,b,l,r,u,d or $[n] to be resolved to 0,1,2,3,4,5.

<PhotoOverlay>
        <Name>geospot2</Name>
        <description>example geospot with a single panorama</description>
        <Camera>
                <longitude>-84.38832402520215</longitude>
                <latitude>33.77700206899468</latitude>
                <altitude>0</altitude>
                <Icon>
                        <href>http://geospots.cc.gatech.edu/geospot.jpg</href>
                </Icon>
        </Camera>
        <Icon>
                <href>http://geospots.cc.gatech.edu /image_$[side].jpg</href>
        </Icon>
        <shape>cube</shape>
        <Point>
                <coordinates>-84.389,33.7766,0</coordinates>
        </Point>
</PhotoOverlay>

The default KML Camera and LookAt elements can also include a TimeSpan or TimeStamp element. This allows a single GEOSpot to have multiple panoramas, each appropriate for use at a different time of the day or year. In the following example, the Folder element is used to group multiple PhotoOverlay elements each with a different TimeSpan:

<Folder>
        <Name>MyGeospot</Name>
        <description>example geospot with multiple panorama</description>
        <Camera>
                <longitude>-84.38832402520215</longitude>
                <latitude>33.77700206899468</latitude>
                <altitude>0</altitude>
                <tilt>0</tilt>
                <heading>0.0045990</heading>
                <altitudeMode>relativeToGround</altitudeMode>
                <TimeSpan>
                        <begin>1997-07-16T10:30:15+03:00</begin>
                        <end>1997-07-16T13:30:15+03:00</end>
                </TimeSpan>       
                <Icon>
                        <href>http://geospots.cc.gatech.edu/geospot.jpg</href>
                </Icon>
        </Camera>
        <PhotoOverlay>
                <Name>time1</Name>
                <Camera>
                        <TimeSpan>
                                <begin>1997-07-16T10:30:15+03:00</begin>
                                <end>1997-07-16T11:30:15+03:00</end>
                        </TimeSpan>       
                </Camera>
                <Icon>
                <href>http://geospots.cc.gatech.edu/image1_$[side].jpg</href>
                </Icon>
                <shape>cube</shape>
                <Point>
                        <coordinates>-84.389,33.7766,0</coordinates>
                </Point>
        </PhotoOverlay>
        <PhotoOverlay>
                <Name>time2</Name>
                <Camera>
                        <TimeSpan>
                                <begin>1997-07-16T11:30:15+03:00</begin>
                                <end>1997-07-16T12:30:15+03:00</end>
                        </TimeSpan>       
                </Camera>
                <Icon>
                <href>http://geospots.cc.gatech.edu/image2_$[side].jpg</href>
                </Icon>
                <shape>cube</shape>
                <Point>
                        <coordinates>-84.389,33.7766,0</coordinates>
                </Point>
        </PhotoOverlay>
        <PhotoOverlay>
                <Name>time3</Name>
                <Camera>
                        <TimeSpan>
                                <begin>1997-07-16T12:30:15+03:00</begin>
                                <end>1997-07-16T13:30:15+03:00</end>
                        </TimeSpan>       
                </Camera>
                <Icon>
                <href>http://geospots.cc.gatech.edu/image3_$[side].jpg</href>
                </Icon>
                <shape>cube</shape>
                <Point>
                        <coordinates>-84.389,33.7766,0</coordinates>
                </Point>
        </PhotoOverlay>
</Folder>

The existing gx: extension only allows SoundCue elements as part of a tour. The KARML extension creates a sound element modeled after the OpenAL sound object. The following example demonstrates a simple directed sound attached to a placemark (Note: only a single sound element can be added to each Placemark):

<Placemark>
        <name>MySound</name>
        <description>Example sound node</description>
        <Region> <!-- regions will eventually fire enter events -->
                <LatLonAltBox>
                        <north>50.625</north>
                        <south>45</south>
                        <east>28.125</east>
                        <west>22.5</west>
                        <minAltitude>10</minAltitude>
                        <maxAltitude>50</maxAltitude>
                </LatLonAltBox>
        </Region>
        <Sound>
                <location>
                        <latitude>47.77</latitude>
                        <longitude>25.3</longitude>
                        <altitude>30.0</altitude>
                </location>
                <orientation>
                        <heading>33.3</heading>
                        <tilt>6</tilt>
                        <roll>10</roll>
                </orientation>
                <gain>1</gain>
                <looping>1</looping>
                <sourceState>playing</sourceState> <!-- playing, stopped, resuming -->
                <link>
                        <href>http://research.cc.gatech.edu/test.mp3</href>
                </link>
        </Sound>
</Placemark>

We are also introducing tracked features into KML with the KMLTracker element. This element remains very generic because it can utilize any number of different plugins for marker, marker-less or external device tracking. An upcoming version of the Argon browser will have three built-in fiducial marker devices: #simpleid, #framesimpleid and #bch. Assigning a markerId of -1 indicates the device should track any visible marker. The following example demonstrates assigning a Placemark to the location of #simpleid marker number 31:

<Placemark>
        <name>Tracker Fiducial Marker Example</name>
        <Tracker>
                <device>#simpleid</device>
                <options>
                        <markerId>31</markerId>
                        <width>0.07</width> <!-- width of marker in meters -->
                        <height>0.07</height> <!-- (optional) -->
                </options>
                <locationMode>relative</locationMode> <!-- default (ignore), relative (update location) -->
                <orientationMode>billboard</orientationMode> <!-- default (ignore), billboard, relative (update orientation) -->
        </Tracker>
</Placemark>