GeoObject Class
A GeoObject represents a virtual object bound to specific
locations in the earth's 3-dimensional space. Any GeoObject is
linked to at least one Location.
A GeoObject
- must have at least one location and can never exist without at least one location.
- can have Drawables associated with it. These Drawables will represent the GeoObject in the camera view.
- can have triggers associated with it. Triggers fire on certain events and execute functions to react on these actions.
On creation, a reference to Locations must be passed to define where the
GeoObject is located in the real world.
A GeoObject can either be
enabled or disabled (see ARObject.enabled). Enabled means that the GeoObject
will be considered in the calculations to project its drawables onto the
camera screen, and its triggers will fire on the appropriate events. In case
the GeoObject is disabled, it will not be considered in the calculations, and
it will not fire any triggers.
On creation, setup parameters can be passed to customize the properties of
the GeoObject.
// a GeoObject which is disabled per default var geoObject1 = new AR.GeoObject(geoLocation1, { enabled : false }); // now, we enable geoObject1 so it will is considered for projection. geoObject1.enabled = true;
// a GeoObject which reacts when the GeoObject becomes visible and invisible. // whenever it becomes visible, the altitude is increased by 1 meter // whenever it becomes invisible, the altitude decreases by 1 meter. var geoObject2 = new AR.GeoObject(geoLocation1); geoObject2.onEnterFieldOfVision = function() { geoObject2.locations[0].altitude++; }; geoObject2.onExitFieldOfVision = function() { geoObject2.locations[0].altitude--; };
// a GeoObject which has two locations set var geoObject3 = new AR.GeoObject( [ geoLocation1, geoLocation2 ], null);
// a GeoObject with triggers and drawables set on creation date var geoObject4 = new AR.GeoObject(locations, { //the function executed when the GeoObject enters the field of vision onEnterFieldOfVision : function(){ ... }, //the function executed when the GeoObject exits the field of vision onExitFieldOfVision : function(){ ... }, drawables : { cam : [drawable1, drawable2] //the drawables representing the GeoObject in the camera view } });
//The Drawables can also be specified as a single object: new AR.GeoObject(locations, { ... drawables : { cam : drawable1} } );
For the render size of attached Drawables, see the chapter on SDUs.
Constructor
GeoObject
-
location
-
options
Parameters:
-
location
Location | Location[]Reference(s) to where this GeoObject is located.
-
options
Object optionalSetup-Parameters to customize additional object properties.
Accepted options-properties are-
enabled
(defaults totrue
) Boolean optional -
renderingOrder
(defaults to0
) Number optional -
onEnterFieldOfVision
Function optional -
onExitFieldOfVision
Function optional -
onClick
Function optional -
onDragBegan
Function optional -
onDragChanged
Function optional -
onDragEnded
Function optional -
onPanBegan
Function optional -
onPanChanged
Function optional -
onPanEnded
Function optional -
onRotationBegan
Function optional -
onRotationChanged
Function optional -
onRotationEnded
Function optional -
onScaleBegan
Function optional -
onScaleChanged
Function optional -
onScaleEnded
Function optional -
drawables.cam
Drawable[] optional -
drawables.radar
Drawable2D[] optional -
drawables.indicator
Drawable2D[] optional
-
Item Index
Methods
Properties
Methods
destroy
()
Destroys the object.
drawables.addCamDrawable
-
drawable
-
position
Adds Drawables to the ARObject in the camera.
Parameters:
-
drawable
Drawable | Drawable[]The drawable(s) that should be added to the camera. Can either be a single Drawable, or an Array of Drawables.
-
position
Number optionalThe position where the Drawable should be added in the array. If not specified, the Drawable will be added at the end of the array. Must be a whole number.
drawables.addIndicatorDrawable
-
drawable
-
position
Adds Drawable2Ds as off-screen-indicators to the GeoObject.
Parameters:
-
drawable
Drawable2D | Drawable2D[]The drawable(s) that should be added. Can either be a single Drawable2D, or an Array of Drawable2Ds.
-
position
Number optionalThe position where the Drawable2D should be added in the array. If not specified, the Drawable2D will be added at the end of the array. Must be a whole number.
drawables.addRadarDrawable
-
drawable
-
position
Adds Drawable2Ds to the GeoObject in the radar.
Parameters:
-
drawable
Drawable2D | Drawable2D[]The drawable(s) that should be added to the radar. Can either be a single Drawable2D, or an Array of Drawable2Ds.
-
position
Int optionalThe position where the Drawable2D should be added in the array. If not specified, the Drawable2D will be added at the end of the array. Must be a whole number.
drawables.removeCamDrawable
-
drawable|position
Removes Drawables from the ARObject in the cam.
Parameters:
-
drawable|position
Drawable | [Drawable] | NumberWhen a single Drawable or an Array of Drawables is given, these Drawables will be removed from the array. When an integer is given, the Drawable at the specified position will be removed.
drawables.removeIndicatorDrawable
-
drawable|position
Removes Drawable2Ds as indicators from the GeoObject.
Parameters:
-
drawable|position
Drawable2D | Drawable2D[] | IntWhen a single Drawable2D or an Array of Drawable2Ds is given, these Drawable2Ds will be removed from the array. When an integer is given, the Drawable2D at the specified position will be removed.
drawables.removeRadarDrawable
-
drawable|position
Removes Drawable2Ds from the GeoObject in the radar.
Parameters:
-
drawable|position
Drawable2D | Drawable2D[] | IntWhen a single Drawable2D or an Array of Drawable2Ds is given, these Drawable2Ds will be removed from the array. When an integer is given, the Drawable2D at the specified position will be removed.
isVisible
()
Boolean
Returns the current visibility state of the ARObject. An ARObject is defined visible when at least one of the ARObject's locations (geolocations or visual tracker) is projected onto a screen coordinate which is currently visible on the screen.
Returns:
Whether the ARObject is currently visible on the screen (true) or invisble (false).
Properties
drawables.cam
Drawable[]
The Drawables which will be used to represent the ARObject
in the camera view.
Drawables in the array will
be printed starting with the Drawable at position 0, causing
Drawables at later indices to overlap the previously drawn
Drawables.
The array content should not be manipulated via the [] operator, as it cannot be guaranteed that the changes will be propagated through to the native application. The property should only be manipulated with arobject.drawables.addCamDrawable() and arobject.drawables.removeCamDrawable(), or directly set with arobject.drawables.cam = new Array(...);.
drawables.indicator
Drawable2D[]
The Drawable2Ds which will be used to indicate the direction
where the GeoObject is located, in case the GeoObject is currently
not visible on the screen.
Drawables in the array will
be printed starting with the Drawable at position 0, causing
Drawables at later indices to overlap the previously drawn
Drawables.
The indicator Drawables will be rendered on the edge of the screen
and will move around the screen edges as the user is moving the
phone. For indicator Drawables, 1 SDU is defined to be the width of
the screen in landscape orientation. Thus, if an ImageDrawable with
width 0.5 SDUs is created, it will take up half the width of the screen.
As the indicator Drawables move around the edges of the screen, their x and
y orientation changes. Thus, the following behavior is defined for
any manipulation (translation, rotation, scaling etc.) on the Drawable2D:
The manipulations are applied when the Drawable2D is located on the top
edge of the screen, horizontally centered. A positive translate.y, for example, make
the Drawable move further away from the top screen edge. As the Drawable moves
around the edges of the screen and is finally located on the left edge of the screen,
translate.y will still cause the drawable to be drawn further away from the left
edge of the screen. The translate.x setting behaves accordingly with left/right
shifting of the Drawable.
The array content should not be manipulated via the [] operator, as it cannot be guaranteed that the changes will be propagated through to the native application. The property should only be manipulated with geoobject.drawables.addIndicatorDrawable() and geoobject.drawables.removeIndicatorDrawable(), or directly set with geoobject.drawables.indicator = new Array(...);.
Clicks on the indicator Drawable2Ds (Drawable.onClick) will not be handled. Assigning a function to the click trigger of Drawable2Ds used as indicators is allowed, however, they will not be triggered.
drawables.radar
Drawable2D[]
The Drawable2Ds which will be used to represent the ARObject
in the radar. The drawables will only show if AR.radar is
enabled and initialized with valid values.
Drawables in the array will
be printed starting with the Drawable at position 0, causing
Drawables at later indices to overlap the previously drawn
Drawables.
In the radar, 1 SDU is defined to be the radius of the radar. Thus,
if a Circle with radius 1 SDU is created, the circle will
take up the entire space of the radar.
The array content should not be manipulated via the [] operator, as it cannot be guaranteed that the changes will be propagated through to the native application. The property should only be manipulated with geoobject.drawables.addRadarDrawable() and geoobject.drawables.removeRadarDrawable(), or directly set with geoobject.drawables.radar = new Array(...);.
Clicks on the Drawable2Ds (Drawable.onClick) in the radar will not be handled. Assigning a function to the click trigger of Drawable2Ds in the radar is allowed, however, they will not be triggered. Refer to AR.radar.onClick() for event handling on radar clicks.
locations
Location[]
The array of Locations of the GeoObject. When a single Location is set as location, it will implicitly be transformed into an Array of Locations with only one entry. Thus, the following four statements have the same effect:
geoObject = new AR.GeoObject(location); geoObject.locations = location; geoObject.locations = new Array(location); geoObject.locations = [ location ];
renderingOrder
Number
Drawables of different ARObjects might overlap. In this case, renderingOrder defines the rendering order of the Drawables of the ARObject.
ARObjects with higher renderingOrder values cause their Drawables to be drawn on top of the Drawables of ARObjects with lower renderingOrder values.
In case two ARObjects have set the same renderingOrder, the Drawables are rendered based on the distance, causing objects closer to the user to
overlap objects further away.
For example, If you want to bring Drawables of a certain ARObject to the very front, set the renderingOrder value of the corresponding ARObject
to a very high value.
For the printing order of Drawables within the same ARObject, refer to Drawable2D.zOrder.
Must be a whole number.
Default: 0
Events
onClick
Will be executed when any of the ARObject's Drawables have been clicked,
and none of the clicked Drawables's onClick() triggers (might also be referenced by another ARObject)
have been set to quit the click chain. ARObject.onClick() will be executed after any Drawable.onClick() triggers have
been executed.
In case multiple ARObjects are hit by the click, the order of the execution is defined by the distance
of the ARObject to the user, with the closest ARObject's click trigger executed first.
The return value of the function determines if, after the onClick()-function was executed for this ARObject, the queue shall continue to execute onClick() for the next ARObject in the queue. In case the last ARObject in the queue still requests to continue the click-queue, context.onScreenClick() will be executed.
The return value of the function decides what to do next. If false, the click-queue should not stop with this ARObject. Thus, the next ARObject's onClick() function will be executed. This is the default value in case no return value is set or the function is not defined for this ARObject. If true, the queue-execution will stop at the current ARObject, underlying ARObjects will not receive onClick() calls.
onDragBegan
Executed when the user starts dragging on at least one Drawable with a single finger and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.
Event Payload:
-
xNormalized
Numberthe distance on the X-axis between the initiating touch position and the updated touch position [-1, 1]; always 0 in onDragBegan as no change to the drag gesture has occurred yet
-
yNormalized
Numberthe distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]; always 0 in onDragBegan as no change to the drag gesture has occurred yet
onDragChanged
Executed when the user drags on at least one Drawable with a single finger and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.
onDragEnded
Executed when the user stops dragging on at least one Drawable with a single finger and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.
Event Payload:
-
xNormalized
Numberthe distance on the X-axis between the initiating touch position and the updated touch position [-1, 1]; always identical to the most recent distance received in onDragChanged
-
yNormalized
Numberthe distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]; always identical to the most recent distance received in onDragChanged
onEnterFieldOfVision
The trigger will fire when the GeoObject's visibility has
changed from invisible to visible.
The trigger is null by default, and will thus result in no action executed when the trigger fires. A developer can add custom functionality by assigning a custom function to onEnterFieldOfVision.
onExitFieldOfVision
Will be executed when the GeoObject's visibility has changed
from visible to invisible.
The trigger is null by default, and will thus result in no action executed when the trigger fires. A developer can add custom functionality by assigning a custom function to onExitFieldOfVision.
onPanBegan
Executed when the user starts dragging on at least one Drawable with two fingers and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.
Event Payload:
-
xNormalized
Numberthe distance on the X-axis between the initiating touch positions and the updated touch positions [-1, 1]; always 0 in onPanBegan as no change to the pan gesture has occurred yet; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture
-
yNormalized
Numberthe distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]; always 0 in onPanBegan as no change to the pan gesture has occurred yet; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture
onPanChanged
Executed when the user drags on at least one Drawable with two fingers and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.
Event Payload:
-
xNormalized
Numberthe distance on the X-axis between the initiating touch positions and the updated touch positions [-1, 1]; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture
-
yNormalized
Numberthe distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture
onPanEnded
Executed when the user stops dragging on at least one Drawable with two fingers and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.
Event Payload:
-
xNormalized
Numberthe distance on the X-axis between the initiating touch positions and the updated touch positions [-1, 1]; always identical to the most recent distance received in onPanChanged; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture
-
yNormalized
Numberthe distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]; always identical to the most recent distance received in onPanChanged; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture
onRotationBegan
Executed when the user starts rotating on at least one Drawable with two fingers and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.
Event Payload:
-
angle
Numberthe CCW angle in degree between the line defined by the initiating touch positions and the line defined by the updated touch positions [0, 360); always 0 in onRotationBegan as no change to the rotation gesture has occurred yet
onRotationChanged
Executed when the user rotates on at least one Drawable with two fingers and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.
Event Payload:
-
angle
Numberthe CCW angle in degree between the line defined by the initiating touch positions and the line defined by the updated touch positions [0, 360)
onRotationEnded
Executed when the user stops rotating on at least one Drawable with two fingers and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.
Event Payload:
-
angle
Numberthe CCW angle in degree between the line defined by the initiating touch positions and the line defined by the updated touch positions [0, 360); always identical to the most recent angle received in onRotationChanged
onScaleBegan
Executed when the user starts scaling on at least one Drawable with two fingers and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.
Event Payload:
-
scale
Numberthe scale value defined the ratio of the distance between the updated touches over the distance between the initiating touches [0, inf]; always 1 in onScaleBegan as no change to the scale gesture has occurred yet
onScaleChanged
Executed when the user scales on at least one Drawable with two fingers and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.
Event Payload:
-
scale
Numberthe scale value defined the ratio of the distance between the updated touches over the distance between the initiating touches [0, inf]
onScaleEnded
Executed when the user stops scaling on at least one Drawable with two fingers and none of these Drawables quits the event propagation by returning true. This callback behaves identically to the onClick callback in terms of event propagation.
Event Payload:
-
scale
Numberthe scale value defined the ratio of the distance between the updated touches over the distance between the initiating touches [0, inf]; always identical to the most recent scale received in onScaleChanged