Wikitude SDK API Reference

API Docs for: 5.2.0
Show:

Model Class

Extends Drawable
Module: AR

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.

Example:
//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: {
    roll: 90.0,
    tilt: 180.0,
    heading: 0.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 String

    An URI pointing to the wt3 file including all model information/a>

  • options Object optional

    Setup-Parameters to customize additional object properties.

    Accepted options-properties are

    • enabled (defaults to true) Boolean optional
    • mirrored (defaults to true) Boolean optional
    • horizontalAnchor Number optional
    • rotate.roll (defaults to 0) Number optional
    • rotate.tilt (defaults to 0) Number optional
    • rotate.heading (defaults to 0) Number optional
    • scale.x (defaults to 1) Number optional
    • scale.y (defaults to 1) Number optional
    • scale.z (defaults to 1) Number optional
    • translate.x (defaults to 0) Number optional
    • translate.y (defaults to 0) Number optional
    • translate.z (defaults to 0) Number optional
    • onClick Function optional
    • onLoaded Function optional
    • onError Function optional

Methods

destroy

()

Inherited from ARchitectObject

Destroys the object.

isLoaded

() Boolean

Allows checking if the Model has already been loaded successfully.

Returns:

Boolean:

true if the Model is already loaded, false if the Model is not yet loaded.

Properties

destroyed

Boolean

Inherited from ARchitectObject

Indicates if the object has already been destroyed.

enabled

Boolean

Inherited from Drawable

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

heading

Number deprecated

Inherited from Drawable

Deprecated: Use rotate.heading instead.

mirrored

Boolean

Inherited from Drawable

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

roll

Number deprecated

Inherited from Drawable

Deprecated: Use rotate.roll instead.

rotate.heading

Number

Inherited from Drawable

Defines a rotation of the Drawable around the y-axis, 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.roll

Number

Inherited from Drawable

Defines a rotation of the Drawable around the z-axis, 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.tilt

Number

Inherited from Drawable

Defines a rotation of the Drawable around the x-axis, 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

scale.x

Number

The scale in x-direction. Must be non-negative.

Default: 1

scale.y

Number

The scale in y-direction. Must be non-negative.

Default: 1

scale.z

Number

The scale in z-direction. Must be non-negative.

Default: 1

tilt

Number deprecated

Inherited from Drawable

Deprecated: Use rotate.tilt instead.

translate.x

Number

The horizontal offset to the calculated position of the Model, in SDUs. A positive x causes the Model to move right, a negative offsetX causes it to move left.

Default: 0

translate.y

Number

The vertical offset to the calculated position of the Model, in SDUs. A positive y causes the Model to move up, a negative offsetX causes it to move down.

Default: 0

translate.z

Number

The depth-offset to the calculated position of the Model, in SDUs. A positive z causes the Model to move towards the user, a negative offsetX 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

Inherited from Drawable

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 ARObject

    the ARObject the clicked Drawable is attached to.

  • modelPart String

    the 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.

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.

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.

triggers.onClick

deprecated

Inherited from Drawable

Deprecated: Use onClick instead.