When you're presenting your virtual objects to your users you may want to add custom transitions to reveal them. It's easy to add transparency/visibility reveals to the objects in your 3D scenes using the web editor UI. But sometimes you may want to add custom reveals. This guide gives you a simple example of how to get started.

Upload an asset (e.g. an image or video) to your media library. Then click on the use button and add it into your scene. Then click on the left of the 2 orange buttons in the bottom right corner to see a list of the objects in the scene. Click on the (i) button of the object you want and copy the projection id. Keep this value to use below.

Upload a black and white image to your media library that you will use as your alpha mask. Below is an example of a simple image you can use for a left-to-right swipe reveal. Once your image has uploaded click on the (i) button and copy the asset id. Keep this value to use below.

Now lets add some custom code that creates the transition animation you want. You can copy and paste the code below into the custom code section of your awe project (e.g. /settings/custom_code) and click Done. Then follow the instructions below to use it.

This code can also provide a template for you to create your own transition effects.

This code downloads the alpha image we uploaded to your media library above. Then it runs an animation that draws this to an HTML canvas, moving it a little each time. Then it uses this animating canvas to provide an alpha mask over the top of your object's projection. The projection is the part of your object that you actually see and this contains your image or video asset.

You can follow the comments inline in the code below to see how this works.

NOTE: You need to replace the ALPHA_IMAGE_ASSET_ID with the asset id you copied above.

// start transition code
(() => {
  var alpha_asset_id = ALPHA_IMAGE_ASSET_ID; // setup asset id for alpha-image.png

  // load the image
  var img = new Image();
  img.crossOrigin = 'anonymous';
  img.src = awe.util.get_asset_file_url(alpha_asset_id,'ld');

  // setup the canvas
  var canvas = document.createElement('canvas');
  var ctx = canvas.getContext('2d');
  ctx.fillStyle = 'white';
  canvas.width = "1024";
  canvas.height = "1024";

  // setup variables
  var counter = 0;
  var start, duration, p, m;

  // function to setup the alpha map for a defined projection
  function setup_alpha_map(projection_id) {
    p = awe.projections.view(projection_id);
    m = p.get_three_mesh().material;
    m.transparent = true;
    m.side = THREE.DoubleSide;
    m.alphaMap = new THREE.CanvasTexture(canvas);
  }

  // function to handle a step in the animation
  function animation_step() {
    var now = performance.now();
    var delta = (now-start)/duration;
    var x = 1024*delta;
    ctx.fillStyle = 'white';
    ctx.fillRect(0,0,1024,1024);
    ctx.drawImage(img,x,0,1024,1024);
    m.alphaMap.needsUpdate = true;
    awe.scene_needs_rendering = 1;
    if (now < start+duration) {
      requestAnimationFrame(animation_step);
    }
  }

  // function the play the transition animation on a specific projection
  function play_transition(projection_id, duration_in_seconds) {
    start = performance.now();
    duration = duration_in_seconds*1000;
    setup_alpha_map(projection_id);
    animation_step();
    p.parent().update({ visible:true }); // make the object visible in case it started as invisible
  }
  window.play_transition = play_transition; // make this function available everywhere
})();
// end transition code

Now you can add some code that plays your transition. You may like to setup your object as invisible to start. Select your object in the object editor UI and then click on the ... button. Then uncheck the Visibility checkbox. This object will now start out hidden when this scene loads. If you need to select/edit this object you can click on the eye icon in the top menu and all hidden objects will be shown in ghost mode.

Now add an Action or to one of your objects and select Run custom javascript. You may want to attach it to this invisible object and have the Action play On load so the transition starts as soon as the scene has loaded. Or you may like to attach it to another object that is already visible and use the On select option so this code runs when a user taps or clicks on this object.

Once you have decided how you want your interaction to work, cut and paste the code below into the Action editor UI and then click Done.

NOTE: You need to replace the PROJECTION_ID with the projection id you copied above. Also change DURATION_IN_SECONDS to the number of seconds you want your reveal to take.

play_transition(PROJECTION_ID, DURATION_IN_SECONDS);

Now you're ready to test your effect. Reload your project/scene to ensure the javascript in the /settings/custom_code is loaded. Then click on the object (or do whatever it was you wired up to run this transition) and you should see your object reveal itself.