ARchi VR Functions

Revision Info: Documentation for ARchi VR Version 2.8 - Nov 2021

Table of Contents

Up to ARchi VR Content Creation


Predicates and Expressions

Tasks in Actions do support conditions and function calls which can be used for scripting and which are based on predicate and expression syntax. Functions have access to the run-time context of the actual AR session.

For a more general introduction to predicates and expressions, consult the Predicate Programming Guide in Apple developer documentation.

The following operators and functions are standard in the predicate and expression syntax:

Operators

Data queries:

Basic comparisons: ==, !=, >, >=, <, <=

Basic compound predicates: AND, && (logical AND); OR, || (logical OR); NOT, ! (logical NOT)

Range comparison: IN, BETWEEN

String comparison operators: BEGINSWITH, CONTAINS, ENDSWITH, LIKE, MATCHES

Aggregate operators: ANY, ALL, NONE

Statistics functions

Evaluate lists by keypath collection queries: @avg (average) @sum @count @min @max @median @mode @stddev

Arithmetic functions

+ (add) - (subtract) * (multiply) / (divide) ** (power) modulus:by:(23,4) abs(2.45) sqrt(2) log(2) ln(2) exp(2)

Bounding functions

ceiling(2.45) trunc(2.45) floor(2.45)

Random functions

random() random(5)

Date functions

now()

String functions

lowercase('Berlin') uppercase('Berlin')

Custom Functions

Custom functions are expressions typically with a side effect in the current AR session of the running ARchi VR App. If a function is run succesfully it returns with 1/true, otherwise 0/false. Therefore you can use function calls in conditions such as function(_) == 1.

Action-loading Functions

The following functions are available for loading new content (as Actions) into the scene:

function('https:___', 'getJSON') // get a static Action function('https:___', 'postUser') // post User function('https:___', 'postSpace') // post Space function('https:___', 'postUserSpace') // post User & Space function('https:___', 'postContext') // post AR session context function('https:___', 'postCam') // post camera image without augmentations function('https:___', 'postUserCam') // post User & camera function('https:___', 'postScreen') // post screen shot of AR view function('https:___', 'postMap') // post AR map (feature points, anchors, planes) function('https:___', 'postHits') // post raycast hits (generated upfront by 'raycast') function('https:___', 'post:', '_request') // post request (e.g., 'POST:USER, POST:HITS')

You may create a story throughout several AR scenes by dynamically loading Actions.

Item-manipulating Functions

The following functions are available for manipulating the model using an item's id:

function('_id', 'add') // add item with id at origin 0/0/0 function('_id', 'delete') // remove item with id from AR scene function('_id', 'replace:', '_withID') // replace item with another item function('_id', 'moveto:::', 1.0, 2.0, 3.0) // set absolute position of item function('_id', 'moveby:::', 0.5, 0.0, 1.0) // move the item relative to its position function('_id', 'turnto:', 90.0) // absolute y rotatation of item in degrees, clock wise function('_id', 'turnby:', -5.0) // relative y rotatation of item in degrees, clock wise function('_id', 'posX:', 0.0) // x position of visual rep of item function('_id', 'posY:', 0.0) // y position of visual rep of item function('_id', 'posZ:', 0.0) // z position of visual rep of item function('_id', 'rotX:', 0.0) // radiant x rotation of visual rep of item, counter clock wise function('_id', 'rotY:', 0.0) // radiant y rotation of visual rep of item function('_id', 'rotZ:', 0.0) // radiant z rotation of visual rep of item function('_id', 'scale:', 0.0) // scale factor of visual rep of item function('_id', 'scaleX:', 0.0) // x scale factor of visual rep of item function('_id', 'scaleY:', 0.0) // y scale factor of visual rep of item function('_id', 'scaleZ:', 0.0) // z scale factor of visual rep of item function('_id', 'setR:', 0.4) // set red value in RGB color function('_id', 'setG:', 0.0) // set green value in RGB color function('_id', 'setB:', 1.0) // set blue value in RGB color function('_id', 'transparency:', 1.0) // set transparency function('_id', 'hightlight') // hightlight item function('_id', 'dehightlight') // dehightlight item function('_id', 'lock') // lock item function('_id', 'unlock') // unlock item function('_id', 'pulsate') // pulsate item function('_id', 'depulsate') // depulsate item function('_id', 'hide') // hide item in AR scene function('_id', 'unhide') // unhide item in AR scene

If the id for delete ends with an asterix (*), such as in "function('net.metason.demo.*', 'delete')", then it will be interpreted as a wildcard and will delete all items with their id starting with the term before the asterix. A typical use case is that elements are removed with the delete function before an new action will load new items using a get/post function.

The replace function also interpretes wildcard asterix (*). This can be used to replace an item of any id family with a concrete other id.

UI Functions

The following functions are available for setting user interface (UI) elements:

function('_text', 'status') // set status text in UI function('_text', 'warning') // set warning text in UI function('walls', 'skip') // skip wall capturing function('camera', 'enable') // enable camera button function('camera', 'disable') // disable camera button function('help', 'enable') // enable help button function('help', 'disable') // disable help button function('save', 'enable') // enable save button function('save', 'disable') // disable save button function('undo', 'enable') // enable undo button function('undo', 'disable') // disable undo button popup function('scene', 'save') // save AR session function('snapshot', 'take') // take a camera snapshot function('save', 'avoid') // avoid save of scene function('_url', 'exit') // exit AR session without save; optional: open url afterwards function('_text', 'say') // talk via Text-to-Speech (TTS) function('_langCode', 'language') // language of TTS voice: en, en-US, de, fr, ... function('_male', 'gender') // gender of TTS voice: male/female function('once', 'vibrate') // one second vibration function('twice', 'vibrate') // two short consecutive vibrations function('_sndID', 'play') // play System Sound, e.g., 1106 function('https:_.mp3', 'stream') // stream audio function('audio', 'pause') // pause audio stream function('audio', 'play') // play paused audio stream function('audio', 'restart') // jump to start of audio stream function('video', 'pause') // pause video panel or video overlay function('video', 'play') // play paused video stream function('video', 'restart') // jump to start of video stream function('UI._', 'hide') // hide UI element in AR view function('UI._', 'unhide') // unhide UI element in AR view function('UI._', 'uninstall') // uninstall transient, scene-specific UI function('UI.catalog', 'open') // open model catalog function('UI.service', 'open') // open service selector function('UI.inspector', 'open') // open data inspecctor function('UI.help', 'open') // open help function('UI.traffic', 'open') // open traffic inspector function('_id', 'position') // open xyz pad controller for positioning item function('_id', 'resize') // open wxhxd pad controller for resizing item function('UI.center', 'raycast') // create raycast hit from screen center (hint: show target icon) function('_id', 'raycast') // create raycast hit(s) from overlay with id (e.g. from BBoxLabel) function('_key', 'inspect') // show inspector with context data filtered by key function('Title', 'prompt:', 'Message text') // show info popup function('Will you do this?', 'confirm::', 'function(`___`, `___`)') // show dialog, if confirmed then execute function(s) function('Will you do this?', 'confirm::', 'function(`___`, `___`)', 'function(`___`, `___`)') // show dialog, if confirmed then execute first else execute second function(s)

The id for UI elements in the AR view are

You may use wildcard asterix (*) notation for the id, so UI.* would select all UI elements in the AR view using the hide or unhide function.

Hint: Do NOT miss the colon in confirm:, otherwise no window appears. Do NOT miss the two colons in confirm:: for the yes-no selection dialog, otherwise no dialog appears.

For function calls embedded in a function call, use back quotes ` (single left ticks) for their string parameters.

Custom Math Functions

"function(_num, 'sinus')", // sin "function(_num, 'cosinus')", // cos "function(_num, 'tangent')", // tan "function(_num, 'arcsinus')", // asin "function(_num, 'arccosinus')", // acos "function(_num, 'arctangent')", // atan "function(_num, 'signum')", // sign "function(_num, 'factorial')", // num!

Conditional Functions

"op": "function('data.val == 5', 'ifthen:', 'function(`___`, `___`)')" // if predicate evaluates to true then execute function "op": "function('data.val == 5', 'ifthenelse::', 'function(`___`, `___`)', 'function(`___`, `___`)')" // if predicate evaluates to true then execute first else execute second function(s)

For function calls embedded in a function call, use back quotes ` (single left ticks) for their string parameters.

Spatial Functions

The following functions are available to be used in conditions:

"function('_id', 'visible')" // 0 or 1 if item with id is visible by user "function('_id', 'proximity')" // distance in meters from camera to item with id "function('_id', 'gazingAt')" // 0 or 1 if gazing at item with id "function('_id', 'within')" // 0 or 1 if user is within 2D region of item with id "function('_latitude, _longitude', 'distance')" // distance in meters from current place as comma-separated lat-long string "function(_latitude, 'distance', _longitude)" // distance in meters from current place as lat and long numbers

An example of a spatial condition for testing proximity, in this case unhiding an element when the user gets near to it:

{ "dispatch": "stated", "if": "function('_id', 'proximity') < 1.2", "do": "execute", "op": "function('_id', 'unhide')" }

The latitude-longitude coordinates as string are in decimal degrees (e.g., '39.40338, 1.27403') or in degrees, minutes, and seconds using the backslash (\) escape character for the single and double quotes (e.g., 41°24'12.2"N 2°10'26.5"E as '41°24\'12.2\"N 2°10\'26.5\"E').

{ "dispatch": "stated", "if": "function('47.3769, 8.5417', 'distance') < 30.0", "do": "execute", "op": "function('https://___', 'getJSON')" // run an action }

Data Assignement

Funtions such as assign: and set: can be used to dynamically set data variables that are valid throughout an AR session:

"function('data._var0', 'assign:', 5.25)" // assign a numeric value (integer or float) to a variable "function('data._var0', 'increase:', 0.25)" // increase a numeric value (integer or float) "function('data._var1', 'decrease:', 1)" // decrease a numeric value (integer or float) "function('data._var0', 'multiply:', 5.0)" // multiply with numeric value (integer or float) "function('data._var1', 'devide:', 2)" // devide by a numeric value (integer or float) "function('data._var1', 'toggle')" // ttoggle a boolean data value "function('data._var2', 'set:', 'hello')" // set a string variable "function('data._var2', 'concat:', ' my dear')" // concat a string to an existing string variable "function('data._var2', 'addnum:', 5.3)" // add a number as string to an existing string variable "function('data._var3', 'eval:', '_exp')" // eval an expression and set variable with result "function('data|hits|tasks|*', 'clear')" // clear data, hits, dispatched tasks or all

Hint: Do NOT miss the colon at the end of the function calls such as in assign: and in set:, otherwise the variables will not be changed. Data variables will automatically be created when they do not already exist.

See ARchi VR Actions for the use of custom functions within ARchi VR.


Back to ARchi VR Content Creation


Copyright © 2020-2021 Metason - All rights reserved.