Explainer: The Incredibly Useful Compare Guarded Actor


  • A user on the Isadora User Group on Facebook asked the following question:

    Hi all, I'm going off of Guru #13 (body tracking), specifically, measuring the absolute position of a performer in space. I'm looking to cue an audio track when a dancer hits a mark on stage. Is it possible to convert the Calc Angle 3D dist output to a simple trigger? 

    Some users suggested a simple Comparator actor. But this isn't the best solution for real-time data like position information from a Kinect, because the values may "jitter" at the trigger point, resulting in multiple unwanted triggers.

    Instead, the Compare Guarded actor is what you really want.

    The first step is to determine the value that means "on." For purposes of this example, we'll assume we'll consider the dancer to have hit the mark when the 'dist' output of the Calc Angle 3D is less than 0.2.

    With this in mind, I would suggest the following:

    1) Add a Compare Guarded actor, setting the 'low' value to 0.2 and the 'high' value to 0.4.
    2) The 'dist' output of the Calc Angle 3D is 1.0, which means the dancer is is 1.0 unit away from the mark. Then, they start moving closer and closer to the mark.
    3) The 'dist' output reads 0.9, 0.8... 0.3... as they approach the mark. Finally the distance goes below 0.2
    4) Immediately, the 'go below' trigger fires -- that means the dancer hit the mark. (In the case of the original question, you'd trigger the sound to start playing with this trigger.)
    5) But at the same time, they sway a little bit, causing the 'dist' value go up to 0.025 and then back down to 0.195. if you used a normal Comparator actor, this would send another trigger right after the first one, possibly triggering something twice that you only want triggered once.
    6) That's where the Compare Guarded actor is your friend. Before it will send another 'go below' trigger, the value *must* rise above the 'high' value. In other words, the dancer must move away from the mark until the distance is greater than 0.4. That's when the 'go above' trigger fires telling you the dancer is no longer on the mark.
    7) Only then can the dancer go back to the mark and trigger the 'go below' output again.

    Here's a diagram:

    After the first 'go below', there are two more times where the value goes from above 0.2 to below it. But no trigger is sent at that point, because the value has not gone above the 'high' value. Finally, the value does go above the high value, and the next time it falls below 0.2 you do indeed get a new trigger.

    I hope that makes the function of this actor clear, and shows why it is so important for handling triggers from real time data.

    Best Wishes,
    Mark

    P.S. This technique is analogous to the idea of "hysteresis" in electronic circuits, e.g., the Schmitt Trigger. If you want to nerd out a bit, check the Wikipedia article. https://en.wikipedia.org/wiki/Hysteresis