Prismatic <ml-quad> HTML Element

Note: <ml-quad> is deprecated in favor of 3D Detached CSS Transforms.

The <ml-quad></ml-quad> is an HTML element with inline attributes and CSS styling that allows web developers to render 2D images that pop off of the page. The <ml-quad> tag works similarly to <ml-model>, the exception being that you set an image (PNG or JPEG) as the source.

  • The width and height of the quad images are specified using CSS width and height attributes.
  • The position of the quad image on the x (horizontal) and y (vertical) axes are specified using CSS transforms.
  • The position on the z (out of the browser) axis is specified using the z-offset attribute.
  <!-- quad at the center of viewport on the x and y axes and 400px forward on the z axis -->
  <!-- quad has a width of 300px, height of 350px -->
  <ml-quad
    src="/images/couch.png"
    style="position: fixed; top: 50%; left: 50%; transform: translate(-50%, -50%);
           width: 300px; height: 350px;"
    z-offset="400px">
  </ml-quad>

Supported File Formats

The following file types are supported:

  • PNG
  • JPG

Quad Attributes

The <ml-quad></ml-quad> HTML element supports attributes to manage or alter a quad image on an HTML page. These attributes can be set inline or with JavaScript.

src

The path to the image file.

src="(path to image)"

<ml-quad
  id="couch"
  src="/images/couch.png">
</ml-quad>
...
couch.src = '/images/couch.png';

visibility

This attribute sets the visibility of a quad image to visible or hidden1.

visibility="(visible|hidden)"

<ml-quad
  id="couch"
  src="/images/couch.png"
  visibility="hidden">
</ml-quad>
...
couch.visibility = 'hidden';

color

This attribute sets a color overlay on the quad image. The color value can be of any CSS color value.

color="(color value)"

<ml-quad
  id="couch"
  src="/images/couch.png"
  color="#FF6347">
</ml-quad>
...
couch.color = '#FF6347';


z-offset

This sets the position of the quad image on the z axis (out of the browser). By default, quad images are positioned 150px forward on the z axis . The z-offset value can be provided in pixels (default), centimeters, or millimeters. When the value is provided in centimeters or millimeters, it is converted to pixels. The z-offset value does not correspond to a real life dimension.

z-offset="(value in pixels, cm, or mm)"

<!-- Position quad image 300px behind the browser, left position to 100px and top position to 250px-->
<ml-quad
  id="couch"
  src="/images/couch.png"
  z-offset="-300px"
  style="position: absolute; left: 100px; top:250px; width: 300px; height: 350px;" >
</ml-quad>
...
couch.zOffset = '-300px'; //Set z position to 300px behind the browser.
couch.style.left = '100px'; //Set left position to 100px
couch.style.top = '250px'; //Set top position to 250px

scale

This attribute applies a static transform scale on the quad image. It accepts a scale value for each of the axes as a percentage delimited by a space or a comma.

scale="(x, y, z)"

<!-- Scale down the quad image on the x and y axes to 50% of the specified size. -->
<ml-quad
  id="couch"
  src="/images/couch.png"
  scale="0.5, 0.5, 0">
</ml-quad>
...
//Scale down the quad image on the x and y axes to 50% of the specified size.
couch.scale = '0.5, 0.5, 0';

raycast

This attribute offers direct interaction with digital content through Raycasting. The raycast events are dispatched when the Head position or the Control's pointer raycast points directly at a node.
Quad images have raycast enabled by default. This attribute can be used to disable raycasting on a quad image.

raycast="(true|false)"

<ml-quad
  id="couch"
  src="/images/couch.png"
  raycast="false">
</ml-quad>
...
couch.raycast = false;

extractable

The extractable attribute is used to allow users to grab the image off of the web page and place it in their physical environment. Quad images are not extractable by default. Set this attribute to true to extract a quad image. Note that quad images that are placed outside the viewport must have raycast enabled for extraction to work. Quad images have raycast enabled by default.

extractable="(true|false)"

<ml-quad
  id="couch"
  src="/images/couch.png"
  extractable="true">
</ml-quad>
...
couch.extractable = true;


extracted-size

The extracted-size attribute is used to specify the dimensions in meters of the quad image once the image is placed in your physical space.

extracted-size="width, height"

<!-- Quad will be resized once extracted to have a width of 2 meters, height of 2 meters -->
<ml-quad
  id="couch"
  src="/images/couch.png"
  extractable="true"
  extracted-size="2, 2">
</ml-quad>
...
//Quad image will be resized once extracted to have
//width of 2 meters
//height of 2 meters
couch.extractedSize = '2, 2';

extracted-scale

As an alternative to using extracted-size, you can use the extracted-scale attribute to specify a multiplier which scales your quad image once the image is placed in your physical space.

extracted-scale="(number)"

<!-- Quad will be resized once extracted to be 5 time bigger than the size on the web page -->
<ml-quad
  id="couch"
  src="/images/couch.png"
  extractable="true"
  extracted-scale="5">
</ml-quad>
...
//Quad image will be resized once extracted to be 5 time bigger than the size on the web page
couch.extractedScale = '5';


extracted-link

The extracted-link attribute is used to link your extracted content to a different page. All extracted content link back to its origin page by default when you click on it, even after you have closed the web page.

extracted-link="(URL)"

<ml-quad
  id="couch"
  src="/images/couch.png"
  extractable="true"
  extracted-link="magicleaphelio.com">
</ml-quad>
...
//make the quad image extractable
couch.extractable = true;

//link the extracted quad image to magicleaphelio.com
couch.extractedLink = 'magicleaphelio.com';

rotation

This attribute applies a static transform rotation on the node. It accepts the angle of rotation for each of the axes in radians (default unit) or degrees, delimited by a space or a comma.

rotation="(angle on x, angle on y, angle on z)"

<!-- Rotate the quad image 45 degrees on the y axes -->
<ml-quad
  id="couch"
  src="/images/couch.png"
  rotation="0, 45deg, 0">
</ml-quad>
...
//Rotate the quad image 45 degrees on the y axes
couch.rotation = '0, 45deg, 0';

instance

This attribute is used to create an instance of another <ml-quad> by reusing the quad image resources. The value of the instance attribute must be the id name of the <ml-quad> instancing from. One or more instances of the same <ml-quad> could be created.

instance="(id name of <ml-quad>)"

 <!-- Create two instances of the duck model -->
 <ml-quad id="couch" src="/images/couch.png"></ml-quad>
 <ml-quad id="red-couch"  instance="couch" z-offset="400"></ml-quad>
 <ml-quad id="blue-couch" instance="couch" rotation="0, 45deg, 0"></ml-quad>

Transform Animations

Transform animations differ from static transform in that the transform is animated over a period of time. There are several transform animations supported in Prismatic:

You can apply one or more transform animations to the same node. When there are more than one transform animations applied on the same node, the parameter Track Number can be used to allow you to queue your transform animations on your nodes.
If you want your transform animations to run sequentially, place them on the same Track Number (for example, track 1). If you want your animations to run simultaneously, place them on separate Track Number (for example, track 1, track 2, and so on).
You can stop a transform animation immediately by calling the stopTransformAnimations() on the <ml-quad> HTML element.

move-to

This attribute applies a move-to transform animation on the node on each axis specified over a period of time. It accepts offset values for each axis, the duration of the transform animation in seconds, and the track number.

Parameters
OffsetOffset values to move the node to on each of the axis. The values are relative to the browser window calculated from the window top/left edge (0, 0) for the x and y axes and on top the browser window for the z axes (0). Each value is delimited by comma.
For the x axis you can use: left, middle, center, right or a number in pixels, where 0 is on the left edge of the browser. You could use stay to not move on this axes.
For the y axis you can use: top, middle, center, bottom or a number in pixels, where 0 is the top edge of the browser. You could use stay to not move on this axes.
For the z axis you can use a number in pixels where 0 is on top of the browser window. You can use stay to not move on this axis.
DurationDuration of the move-to animation in seconds
Track NumberThe track number to do the move-to animation.
 
move-to="(offset: x, y, z; duration: time in seconds; track: track number)"

<!-- Move the node to: 200px from the left of the browser window on the x axis, the middle of the browser window on the y axis, and 200px behind the browser window on the z axis in 10 seconds on track 1-->
<ml-quad
  id="couch"
  src="/images/couch.png"
  move-to="offset: 200px, middle, -200px; duration: 10s; track: 1">
</ml-quad>
//Move the node to: 200px from the left of the browser window on the x axis,
//Move the node to: middle of the browser window on the y axis,
//Move node to: 200px behind the browser window on the z axis
//Move the node in 10 seconds on track 1
couch.moveTo='offset: 200px, middle, -200px; duration: 10s; track: 1';

move-by

This attribute applies a move-by transform animation on the node on each of the axis over a period of time. It accepts the axes values to move by on each of the axis, the duration of the transform animation in seconds and the track number.

Parameters
AxesAxes values to move the node by on each of the axis.
DurationDuration of the move-by animation in seconds
Track NumberThe track number to do the move-by animation.
 
move-by="(axes: x, y, z; duration: time in seconds; track: track number)"

<!-- Move the node by: 200px on the x axes, stay in place on the y axes, and 200px forward on the z axes in 10 seconds on track 1.-->
<ml-quad
  id="couch"
  src="/images/couch.png"
  move-by="axes: 200px, 0, -200px; duration: 10s; track: 1">
</ml-quad>
//Move the node by: 200px on the x axes,
//Move the node by: 0px (stay in place) on the y axes
//Move the node by: 200px forward on the z axes
//Move the node in 10 seconds on track 1
couch.moveBy='axes: 200px, 0, -200px; duration: 10s; track: 1';

  • scale-to

This attribute applies a scale-to transform animation on the node on each of the axis over a period of time. It accepts the axes percentage values to scale-to for each of the axis, the duration of the transform animation in seconds and the track number.

Parameters
AxesAxes percentage values to scale to the node on each of the axis.
DurationDuration of the scale-to animation in seconds
Track NumberThe track number to do the scale-to animation.
 
scale-to="(axes: x, y, z; duration: time in seconds; track: track number)"

<!-- Animate the scale down of quad on the x, y and z axes to 50% of the specified size. -->
<ml-quad
  id="couch"
  src="/images/couch.png"
  scale-to="axes: 0.5, 0.5, 0.5; duration: 10s; track: 1">
</ml-quad>
...
//Animate the scale down of quad on the x, y and z axes to 50% of the specified size.
quad.scaleTo = 'axes: 0.5, 0.5, 0.5; duration: 10s; track: 1';

  • scale-by

This attribute applies a scale-by transform animation on the node on each of the axis over a period of time. It accepts the axes percentage values to scale-by for each of the axis, the duration of the transform animation in seconds and the track number.

Parameters
AxesAxes percentage values to scale by the node on each of the axis.
DurationDuration of the scale-by animation in seconds
Track NumberThe track number to do the scale-by animation.
 
scale-by="(axes: x, y, z; duration: time in seconds; track: track number)"

<!-- Animate the scale up of quad on the x, y and z axes to 50% of the specified size.-->
<ml-quad
  id="couch"
  src="/images/couch.png"
  scale-by="axes: 1.5, 1.5, 1.5; duration: 10s; track: 1">
</ml-quad>
...
//Animate the scale up of the quad image on the x, y and z axes to 50% of the specified size.
quad.scaleBy = 'axes: 1.5, 1.5, 1.5; duration: 10s; track: 1';

  • spin

This attribute applies a spin transform animation on the node around specified axis and rate for a duration of time.

Parameters
AxesArray of three elements, one for each axes [x, y, z] and with values of 0 or 1 to specify in which axis the spin occurs.
RateAn angle in radians (default unit) or degrees to specifies the angles per second. This is NOT how many degrees the node will spin.
DurationDuration of the spin animation in seconds
Track NumberThe track number to do the spin animation.
 
spin="(axes: [x, y, z]; rate: angle; duration: time in seconds; track: track number)"

<!-- Spin quad image around the y axes at 90 degrees per second for 300 seconds on track 1 -->
<ml-quad
  id="couch"
  src="/images/couch.png"
  spin="axes: 0 1 0; angle: 90deg; duration: 300s; track: 1">
</ml-quad>
...
//Spin node around the y axes at 90 degrees per second for 300 seconds on track 1.
couch.spin = 'axes: 0 1 0; angle: 90deg; duration: 300s; track: 1';


  • rotate-to-angles

This attribute applies a rotation transform animation on the node over a period of time. It accepts angles to rotate-to for each of the axis in radians (default unit) or degrees delimited by a space or a comma, the duration of the transform animation in seconds and the track number.

Parameters
AnglesAngles to rotate-to each of the axis in radians (default unit) or degrees delimited by a space or a comma
DurationDuration of the rotate-to-angles animation in seconds
Track NumberThe track number to do the rotate-to-angles animation.
 
rotate-to-angles="(angles: x, y, z; duration: time in seconds; track: track number)"

<!-- Animate rotation of the quad image to 1.57 radian on the y axes for 5 seconds on track 1 -->
<ml-quad
  id="couch"
  src="/images/couch.png"
  rotate-to-angles="angles: 0 1.57 0; duration: 5s; track: 1">
</ml-quad>
...
//Animate rotation of the node to 1.57 radian on  y axes for 5 seconds on track 1
couch.rotateToAngles='angles: 0 1.57 0; duration: 5s; track: 1';

  • rotate-by-angles

This attribute applies a rotation transform animation on the node over a period of time. It accepts angles to rotate-by for each of the axis in radians (default unit) or degrees delimited by a space or a comma, the duration of the transform animation in seconds and the track number.

Parameters
AnglesAngles to rotate-by each of the axis in radians (default unit) or degrees delimited by a space or a comma
DurationDuration of the rotate-by-angles animation in seconds
Track NumberThe track number to do the rotate-by-angles animation.
 
rotate-by-angles="(angles: x, y, z; duration: time in seconds; track: track number)"

<!-- Animate rotation of the quad image by 90 degrees on the x axes for 10 seconds on track 1 -->
<ml-quad
  id="couch"
  src="/images/couch.png"
  rotate-by-angles="angles: 90deg, 0, 0; duration: 10s; track: 1">
</ml-quad>
...
//Animate rotation of the nod4 by 90 degrees on the x axes for 10 seconds on track 1
couch.rotateByAngles='angles: 90deg, 0, 0; duration: 10s; track: 1';


Quad Effects:

Prismatic currently offers three methods for adding effects to nodes.

  • fadeIn

The fadeIn() method gradually modifies the color alpha channel (opacity) of a node to go from visible to hidden. This method takes an optional speed parameter to control how fast the node goes from visible to hidden. By default the speed value is 0.1, but you can enter any value between 0 to 1 inclusive.

couch.fadeIn();

  • fadeOut

The fadeOut() method gradually modifies the color alpha channel (opacity) of a node to go from hidden to visible. This method takes an optional speed parameter to control how fast the node goes from hidden to visible. By default the speed value is 0.1, but you can enter any value between 0 to 1 inclusive.

couch.fadeOut(0.5);

  • wiggle

The wiggle() method creates a back and forward movement on the specified axis. The wiggle method takes an optional parameter referring to the axis in which the wiggle effect occurs. This parameter is an array of three elements, one for each axes [x, y, z] and with values of 0 or 1.
If no array is specified, the default value for this parameter is [0, 1, 0], which performs the wiggle in the Y axes.

movement.wiggle([1,0,0]);

Quad Events:

There are several events being dispatched from the <ml-quad></ml-quad> HTML element.

  • transform-animation-end

This event is dispatched once a transform animation set on a node ends. This event applies for all transform animations: move-to, move-by, scale-to, spin, rotate-by-angles and rotate-to-angles.
In the detail property of the event you can find the track property which contains the track number of the transform animation that just ended.

 //Move the node by: 100px forward on the z axes in 10 seconds on track 1.
 couch.moveBy='axes: 0, 0, 100px; duration: 10s; track: 1';

 //Spin node on the x axes at 45 degrees per second for 300 seconds on track 2.
 couch.spin = 'axes: 1 0 0; angle: 45deg; duration: 300s; track: 2';  

 couch.addEventListener('transform-animation-end', (event) => {
   //move by the node back 100px in 5 seconds when the spin transform animation on track 2 ends.
   if (event.detail.track === 2) {
     couch.moveBy='axes: 0, 0, -100px; duration: 5s; track: 1';
   }
 });

  • quad-displayed

This event is dispatched once the quad image is ready to be displayed.
Note that this event will be dispatched even if the quad image was set to be hidden by using the visibility attribute.

 //Start playing a video once the quad is ready to be displayed.
 couch.addEventListener('quad-displayed', (event) => {
   myVideo.play();
 });

  • node-raycast

This event is dispatched when the Head position or the Control's pointer raycast points directly to a node.
In the detail property of the node-raycast event, you can find the inputType property (event.detail.inputType) which is the input type of the raycast event. Possible values are headpos and control.

  • Input type is headpos when the head position points directly to the node.
  • Input type is control when the Control's Cursor points directly to the node.

You can also find in the detail property of the node-raycast event, the type property (event.detail.type).

The possible values for the type property change depending of the inputType.

When the input type is headpos, these are the possible values for the type property:

  • nodeOnHeadEnter, when the head position raycast enters the node
  • nodeOnHeadMove, when the head position raycast moves within the node
  • nodeOnHeadExit, when the head position raycast exits the node
  //Start spin transform animation when you look at the quad.
  //Stop transform animation when the you look away from the quad.
  couch.addEventListener('node-raycast', function (event) {
   if (event.detail.inputType === 'headpos') {
     if (event.detail.type === 'nodeOnHeadEnter') {
       //Spin node on the y axes at 45 degrees per second for 3000 seconds on track 1.
       couch.spin = 'axes: 0 1 0; angle: 45deg; duration: 3000s; track: 1';
     }
     else if (event.detail.type === 'nodeOnHeadExit') {
       couch.stopTransformAnimations();
     }
   }
 })

When the input type is control, these are the possible values for the type property:

  • nodeOnControlEnter, when the raycast of the Control pointer enters the node
  • nodeOnControlMove, when the raycast of the Control pointer moves within the node
  • nodeOnControlExit, when the raycast of the Control pointer exits the node
  //Start spin transform animation when you point control laser at the quad.
  //Stop transform animation when the you point control laser away from the quad.
  couch.addEventListener('node-raycast', function (event) {
   if (event.detail.inputType === 'control') {
     if (event.detail.type === 'nodeOnControlEnter') {
       //Spin node on the y axes at 45 degrees per second for 3000 seconds on track 1.
       couch.spin = 'axes: 0 1 0; angle: 45deg; duration: 3000s; track: 1';
     }
     else if (event.detail.type === 'nodeOnControlExit') {
       couch.stopTransformAnimations();
     }
   }
  })

  • mlextraction

This event is dispatched when the trigger on the control is long pressed while the cursor is on the node.
Prismatic listens for this mlextraction event on nodes with the extractable attribute set to true to initiate the placement of the node in your physical space.

 //Event is dispatched when user long press the trigger on the control while cursor is on the quad.
 couch.addEventListener('mlextraction', function (event) {
   console.log(`trigger was long pressed on the quad image.`)
 });

  • extracting-node

This event is dispatched from the <ml-quad></ml-quad> HTML element with the extractable attribute set to true, right before Prismatic initiates the placement of the quad image in your physical environment.

 //Play audio when the quad image is about to be extracted.
 couch.addEventListener('extracting-node', function (event) {
   extractingAudio.play();
 });

  • node-extracted

This event is dispatched from the <ml-quad></ml-quad> HTML element with the extractable attribute set to true, right after the placement of the node in your physical environment.

   //Do a wiggle effect on the quad on the page once the quad image is extracted.
 couch.addEventListener('node-extracted', (e) => {
   couch.wiggle();
 });
Last updated on 2019-12-6
← <ml-model>Extraction from HTML element →