Revision Info: Documentation for ARchi VR Version 2.4 - February 2021
Table of Contents
Up to ARchi VR Content Creation
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:
Data queries:
data[1]
data.key
Basic comparisons: ==, !=, >, >=, <, <=
"type == 'Space'"
Basic compound predicates: AND, &&
(logical AND); OR, ||
(logical OR); NOT, !
(logical NOT)
"type == 'Space' AND subtype == 'Single Room'"
Range comparison: IN, BETWEEN
"data.str IN {‘Office’, ‘Home’, ‘Shop’}"
"data.num BETWEEN {3, 7}"
String comparison operators: BEGINSWITH, CONTAINS, ENDSWITH, LIKE, MATCHES
[c]
for case insensitive: lowercase & uppercase values are treated the same, e.g., CONTAINS[c]
[d]
for diacritic insensitive: special characters treated as the base character, e.g., CONTAINS[d]
"location.city LIKE[cd] 'Zürich'"
"walls[0].floorId BEGINSWITH 'D96B5F4A'"
Aggregate operators: ANY, ALL, NONE
"ANY walls.material == 'Concrete'"
Evaluate lists by keypath collection queries:
@avg (average) @sum @count @min @max @median @mode @stddev
"walls.@count > 2"
+
(add) -
(subtract) *
(multiply) /
(divide) **
(power)
modulus:by:(23,4) abs(2.45) sqrt(2) log(2) ln(2) exp(2)
ceiling(2.45) trunc(2.45) floor(2.45)
random() random(5)
now()
lowercase('Berlin') uppercase('Berlin')
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
.
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 screen image
function('https:___', 'postUserCam') // post User & screen
function('https:___', 'postMap') // post AR map (feature points, anchors, planes)
You may create a story throughout several AR scenes by dynamically loading Actions.
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 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.
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('_key', 'inspect') // show inspector with context data filtered by key
function('UI._', 'hide') // hide UI element in AR view
function('UI._', 'unhide') // unhide UI element in AR view
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
UI.status
: The status text line on the top leftUI.warning
: The warning text in the 2nd line on the top leftUI.center.image
: The image (e.g. the target icon) in the centerUI.center.top
: Text line on the top of the center imageUI.center.left
: Text line on the left of the center imageUI.catalog
: Catalog buttton in the bottomUI.service
: Service selector on mid right sideUI.traffic
: Network analyzer on top right sideYou 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.
"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!
"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.
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
}
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|tasks|*', 'clear')" // clear all data or dispatched tasks or both
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.