Model Class
A Model drawable represents an ARObject as a 3D Model.
A Model file consist of a link to a WT3 file that is created using the Wikitude 3D Encoder,
as well as certain control properties and triggers that fire on certain events. You can find out more about 3D in the Wikitude SDK documentation.
3D content is rendered on top of 2D objects. This limitation exists because of some SDK internal restrictions and might change in an upcoming release.
On creation, setup parameters can be passed to customize the properties of
the Model.
//create a new Model and pass some setup parameters var model = new AR.Model("models/my3dModel.wt3", { // scales it to half of the original size scale: { x: 0.5, y: 0.5, z: 0.5 }, // rotates it 90 degrees around the z-axis and 180 degrees around the x-axis rotate: { x: 180.0, y: 0.0, z: 90.0 }, // moves the 0bject 5 SDUs along the x- and the y-axis translate: { x: 5, y: 5, z: 0 }, onClick : function() { //something happens } });
Constructor
Model
-
uri
-
options
Parameters:
-
uri
StringAn URI pointing to the wt3 file including all model information/a>
-
options
Object optionalSetup-Parameters to customize additional object properties.
Accepted options-properties are-
enabled
(defaults totrue
) Boolean optional -
mirrored
(defaults totrue
) Boolean 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 -
rotate.x
(defaults to0
) Number optional -
rotate.y
(defaults to0
) Number optional -
rotate.z
(defaults to0
) Number optional -
rotate.global.x
(defaults to0
) Number optional -
rotate.global.y
(defaults to0
) Number optional -
rotate.global.z
(defaults to0
) Number optional -
translate.x
(defaults to0
) Number optional -
translate.y
(defaults to0
) Number optional -
translate.z
(defaults to0
) Number optional -
translate.global.x
(defaults to0
) Number optional -
translate.global.y
(defaults to0
) Number optional -
translate.global.z
(defaults to0
) Number optional -
scale.x
(defaults to1
) Number optional -
scale.y
(defaults to1
) Number optional -
scale.z
(defaults to1
) Number optional -
onLoaded
Function optional -
onInitialized
Function optional -
onError
Function optional
-
Item Index
Methods
Properties
- destroyed
- enabled
- mirrored
- rotate
- rotate.global.x
- rotate.global.y
- rotate.global.z
- rotate.heading deprecated
- rotate.roll deprecated
- rotate.tilt deprecated
- rotate.x
- rotate.y
- rotate.z
- rotatesToCamera
- scale
- scale.x
- scale.y
- scale.z
- translate
- translate.global.x
- translate.global.y
- translate.global.z
- translate.x
- translate.y
- translate.z
- uri
Methods
destroy
()
Destroys the object.
Properties
enabled
Boolean
Flag to enable/disable the Drawable. If the Drawable is disabled, it will never appear on the screen and triggers on this Drawable will never be fired. In case it is enabled, it can be rendered on the screen and fire triggers.
Default: true
mirrored
Boolean
Flag to enable/disable mirroring for this Drawable. When using the front camera, a mirrored drawable will be rotated 180 degree around its y axis.
Default: true for generic drawables, false for labels and HTMLDrawables
rotate
Object
Defines the rotation of the Drawable around its center. This property can be used to set the x, y and z components simultaneously in a single call to the native side of the Wikitude SDK for maximum performance. The Object may contain x, y and z or any subset thereof.
rotate.global.x
Number
Defines a rotation of the Drawable around the x-axis of the target image, specified in degrees. Values will be applied modulo 360. A value of 361 degrees has the same effect as setting the value to 1 degree. All global transformations will be applied after the local transformations.
Default: 0
rotate.global.y
Number
Defines a rotation of the Drawable around the y-axis of the target image, specified in degrees. Values will be applied modulo 360. A value of 361 degrees has the same effect as setting the value to 1 degree. All global transformations will be applied after the local transformations.
Default: 0
rotate.global.z
Number
Defines a rotation of the Drawable around the z-axis of the target image, specified in degrees. Values will be applied modulo 360. A value of 361 degrees has the same effect as setting the value to 1 degree. All global transformations will be applied after the local transformations.
Default: 0
rotate.x
Number
Defines a rotation of the Drawable around the x-axis of the Drawable, specified in degrees. Values will be applied modulo 360. A value of 361 degrees has the same effect as setting the value to 1 degree.
Default: 0
rotate.y
Number
Defines a rotation of the Drawable around the y-axis of the Drawable, specified in degrees. Values will be applied modulo 360. A value of 361 degrees has the same effect as setting the value to 1 degree.
Default: 0
rotate.z
Number
Defines a rotation of the Drawable around the z-axis of the Drawable, specified in degrees. Values will be applied modulo 360. A value of 361 degrees has the same effect as setting the value to 1 degree.
Default: 0
rotatesToCamera
Boolean
Defines if the drawable is oriented to face the camera. This is only possible for Drawables attached to a GeoObject.
Default: true for generic drawables, false for Models
scale
Object
Defines the scale of the Drawable. This property can be used to set the x, y and z components simultaneously in a single call to the native side of the Wikitude SDK for maximum performance.The Object may contain x, y and z or any subset thereof.
translate
Object
Defines the translation of the Drawable. This property can be used to set the x, y and z components simultaneously in a single call to the native side of the Wikitude SDK for maximum performance. The Object may contain x, y and z or any subset thereof.
translate.global.x
Number
The horizontal offset to the calculated position of the Drawable, in SDUs. A positive x causes the Drawable to move right, a negative x causes it to move left. All global transformations will be applied after the local transformations.
Default: 0
translate.global.y
Number
The vertical offset to the calculated position of the Drawable, in SDUs. A positive y causes the Drawable to move up, a negative y causes it to move down. All global transformations will be applied after the local transformations.
Default: 0
translate.global.z
Number
The depth-offset to the calculated position of the Drawable, in SDUs. A positive z causes the Drawable to move towards the user, a negative z causes it to move away. All global transformations will be applied after the local transformations.
Default: 0
translate.x
Number
The horizontal offset to the calculated position of the Drawable, in SDUs. A positive x causes the Drawable to move right, a negative x causes it to move left.
Default: 0
translate.y
Number
The vertical offset to the calculated position of the Drawable, in SDUs. A positive y causes the Drawable to move up, a negative y causes it to move down.
Default: 0
translate.z
Number
The depth-offset to the calculated position of the Drawable, in SDUs. A positive z causes the Drawable to move towards the user, a negative z causes it to move away.
Default: 0
uri
String
The uri pointing to the model file. This property is read-only and cannot be modified after creation.
Events
onClick
When the Model is clicked, the system will trigger Model.onClick(ARObject,String).
The return value (true or false) determines whether the event is consumed by this callback function (see also Drawable::onClick).
Event Payload:
-
arObject
ARObjectthe ARObject the clicked Drawable is attached to.
-
modelPart
Stringthe name of the model part which was clicked. A model usually consists of hierarchy of model parts: nodes and mesh parts. Each node contains one or mesh parts. If a node holds only one mesh, modelPart is equal to node's name. If a node contains more than one mesh parts, modelPart is a string composed of XYZ[i], where XYZ is the node's name and i is the index of the model part enclosed in brackets. A list of model parts which can be clicked can be obtained from the Wikitude 3D Encoder.
onDragBegan
Executed when the user starts dragging on a Drawable with a single finger. 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
-
xIntersection
Numberthe world space X-coordinate of the intersection position of the initiating touch ray and the instant tracking plane [-infinity, infinity]; undefined if no InstantTrackable is available
-
xIntersection
Numberthe world space X-coordinate of the intersection position of the initiating touch ray and the instant tracking plane [-infinity, infinity]; undefined if no InstantTrackable is available
onDragChanged
Executed when the user drags on a Drawable with a single finger. 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]
-
yNormalized
Numberthe distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]
-
xIntersection
Numberthe world space X-coordinate of the intersection position of the updated touch ray and the instant tracking plane [-infinity, infinity]; undefined if no InstantTrackable is available
-
xIntersection
Numberthe world space X-coordinate of the intersection position of the updated touch ray and the instant tracking plane [-infinity, infinity]; undefined if no InstantTrackable is available
onDragEnded
Executed when the user stops dragging on a Drawable with a single finger. 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
-
xIntersection
Numberthe world space X-coordinate of the intersection position of the final touch ray and the instant tracking plane [-infinity, infinity]; undefined if no InstantTrackable is available
-
xIntersection
Numberthe world space X-coordinate of the intersection position of the final touch ray and the instant tracking plane [-infinity, infinity]; undefined if no InstantTrackable is available
onError
The trigger will fire when the Model file cannot be loaded.
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 onLoaded. To get more detailed information why the model failed to load, the error trigger can have an error message parameter.
onInitialized
The trigger will fire when the Model file is successfully loaded and is about to be rendered.
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 onInitialized.
onLoaded
The trigger will fire when the Model file is successfully loaded.
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 onLoaded.
onPanBegan
Executed when the user starts dragging on a Drawable with two fingers. 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 a Drawable with two fingers. 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 a Drawable with two fingers. 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 a Drawable with two fingers. 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 a Drawable with two fingers. 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 a Drawable with two fingers. 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 a Drawable with two fingers. 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 a Drawable with two fingers. 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 a Drawable with two fingers. 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