Javascript : load external settings

Posted by DusX on 2 August 2015 | Comments

Tags: , ,

In response to a Isadora forum thread, I decided to put together a little tutorial that shows a method of using the Javascript actor in Isadora to load externally stored and editable settings.

This can be very useful for containing settings that may change from night to night, or venue to venue. It allows a user to adjust a show without the need to edit the Isadora file.
With many different use cases, the ability to make changes outside Isadora is a feature that is valuable to learn.

For this tutorial I am going to build a Isadora (version 2) scene that outputs text via the 'Text Draw' actor with a coloured background. Next the X and Y positions of each corner of a Rectangle map (Izzy map : default projection mapping shape) will be adjusted to create a skew/perspective (quad distort) type effect.
Each of the 8 X and Y settings as well as the Text drawn will be set from an external text file using very simple Javascript.

Get Started

  • Open Isadora V2
  • add a 'Javascript' actor to the scene
  • add a 'Text Draw' actor to the scene
  • add a 'Projector' to the scene
  • Connect 'output 1' from the 'Javascript' actor to the 'text' input of the 'Text Draw' actor
  • Connect the 'video' output of the 'Text Draw' actor to the 'video' inout of the 'Projector' actor.
  • add a 'Background Color' actor, and connect its output to the 'video' input of the 'Text Draw' actor.
  • Adjust the 'color' input of the 'Background Color' actor to a color you like.
  • Create a text file next to your Isadora file. (rename it: 'data.js')
  • Edit the text of the 'data.js' file (in your favorite text editor), add '// data file' (that should be the only text in the file.. // depicts a Javascript comment)

Great, the basics are in place, and you can now open your stage to take a look if you like (I am not going to get into detail on this topic)

Add Some Code

 I am going to assume that you have a least gone thru the basic 'Getting Started With Javascript' and will move past variable declaration and outputting values to Isadora, and rather focus on setting up an external file where you can set your editable values.

The first thing you need to add to your Javascript actor is a call to include the external file.
It is going to look like this:

include('data.js');

Pretty simple right!
There are really only four things here I can point out.

  1. This code MUST be the first line of code in your 'Javascript' actor 
  2. Quotes contain the path to your file and the filename. Here I am using just the filename because the file is located in the same folder as my Isadora file.
  3. The file-type must be plain text. This means that '.txt' would be standard, but I prefer to use '.js' so that I can open the file in Notepad++ and have Javascript code formatting.
  4. The file must exist, and must not be empty (this is why we created the file and added the Javascript comment earlier) otherwise Isadora will raise an error.

Inside the External File

Everything in the external file (in our case 'data.js') will be parsed as Javascript by Isadora, and must therefore be valid code.
Also it will be parsed first, before the code that follows in the 'Javascript' actor.

The code I have in my 'data.js' file is:

var dx_name = "Loading External Data"; //use var to declare variable to this scope (global). 

// Mapper Quad settings. (naming loosely based on CSS standards) 
var dx_quad_tl_x = 0.2; // top left x 
var dx_quad_tl_y = -0.25; // top left y 
var dx_quad_tr_x = -0.33; // top right x 
var dx_quad_tr_y = -0.05; // top right y 
var dx_quad_br_x = -0.03; // bottom right x 
var dx_quad_br_y = 0.32; // bottom right y 
var dx_quad_bl_x = 0.07; // bottom left x 
var dx_quad_bl_y = 0.07; // bottom left y

 As you can see it is basic Javascript, simply setting a variable name to a value on each line.
Hopefully the comments help to clarify the code.

Output the Values

Currently we have an external file with valid javascript code, being included into our 'Javascript' actor.
We need to add a little more code so the values are passed along to the outputs. (this is covered in more detail in 'Getting Started With Javascript').
Here is my updated 'Javascript' actor code:

include('data.js');

function main()
{
var data = []; //define array variable

data[0] = dx_name;  // set first position of array to the text value

// set output values to X Y data pairs
data[1] = dx_quad_tl_x;
data[2] = dx_quad_tl_y;

data[3] = dx_quad_tr_x;
data[4] = dx_quad_tr_y;

data[5] = dx_quad_br_x;
data[6] = dx_quad_br_y;

data[7] = dx_quad_bl_x;
data[8] = dx_quad_bl_y;

// output all data
return data;
}

Next the 'outputs' value of the 'Javascript' actor needs to be adjusted to match the number of variables being output by the 'return' statement.
In this case we will set the value to 9.
Exit the scene and then re-enter it. The values in the external file should now be output from the 'Javascript' actor. The text displayed by the 'Text Draw' actor should now match the text set in the 'data.js' file.

NOTE: in this example we are setting the values of many variables in the external file. This works well, and is easiest for a first demonstration, but another method can offer more power. Setting a variable to a JSON object/data structure can offer many more advanced parsing options. If you are looking to store complex data that is passed to Isadora, JSON might be something you want to look into.

Control Video Mapping

What we need to do to publish the X and Y offsets of each corner of the rectangle video slice in Izzy map is covered in this tutorial, so please be sure you have read it.
Quickly the steps are:

  1. doubleclick the 'Projector' to open Izzy map
  2. switch to the Output view (tab key)
  3. select the slice
  4. right click each corner and publish the X offset, and then the Y offset
    start topLeft, topRight, bottomRight, and finally bottomLeft, this will help with the order of our connections as well as logically tie them in with the variable names
  5. close Izzy map
  6. link the corresponding Javascript outputs to the matching published parameters (we can't rename this input/outputs, so keeping this organized is important)

You should now have a working externally set quad distort using the new Izzy mapper.

I have added a little to the tutorial files.. just having some fun with animating the text and corner pins.
Simply enter the scene, leave and re-enter to see the 'enter-scene' animations (they use some input Init settings so that its repeatable)

 DOWNLOAD tutorial files

Copyright (c) 2015 by Ryan Webber [DusXproductions.com]. 
This work is made available under the terms of the Creative Commons Attribution-ShareAlike 3.0 license, http://creativecommons.org/licenses/by-sa/3.0/.