Revision Info: Documentation for ARchi VR Version 3.3 - April 2024
Table of Contents
Up to ARchi VR Content Creation
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]
array[FIRST]
specifies the first element in the arrayarray[LAST]
specifies the last element in the arrayarray[SIZE]
returns the size of the arraydata['key']
data.key
// short version of the abovefloor.notion.labels.name
// returns array of namesSUBQUERY(floor.notion.labels, $lbl, length($lbl.name) > 8).name')
// returns filtered arrayBasic 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’}"
"'chair' IN detected.labels"
"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]
name LIKE 'M*'
"location.city LIKE[cd] 'Zürich'"
"walls[0].floorId BEGINSWITH 'D96B5F4A'"
"walls[0].floorId BEGINSWITH 'D96B5F4A'"
Aggregate operators: ANY, ALL, NONE
"ANY walls.material == 'Concrete'"
Automatic type casting is not performed. Use the CAST() operator to convert a key path or variable into a matching type:
"eval('data.numval', 'user.yaw * 180.0 / const.pi'); status(CAST(data.numval, 'NSString'))"
average, sum, count, median, mode, stddev, min, max
average({1, 2, 2, 3, 4, 7, 9})
sum({1, 2, 2, 3, 4, 7, 9})
count({1, 2, 2, 3, 4, 7, 9})
median({1, 2, 2, 3, 4, 7, 9})
mode({1, 2, 2, 3, 4, 7, 9})
stddev({1, 2, 2, 3, 4, 7, 9})
min({1, 2, 2, 3, 4, 7, 9})
max({1, 2, 2, 3, 4, 7, 9})
Evaluate lists by keypath collection queries:
@avg (average) @sum @count @min @max @median @mode @stddev
"walls.@count > 2"
"items.mvertices@max > 10.0"
+
(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') length('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:
"getJSON('https:___') OR function('https:___', 'getJSON')" // get a static Action
"postUser('https:___') OR function('https:___', 'postUser')" // post User
"postSpace('https:___') OR function('https:___', 'postSpace')" // post Space
"postUserSpace('https:___') OR function('https:___', 'postUserSpace')" // post User & Space
"postContext('https:___') OR function('https:___', 'postContext')" // post AR session context
"postCam('https:___') OR function('https:___', 'postCam')" // post camera image without augmentations
"postHighResCam('https:___') OR function('https:___', 'postHighResCam')" // post high-resolution camera image without augmentations
"postUserCam('https:___') OR function('https:___', 'postUserCam')" // post User & camera
"postScreen('https:___') OR function('https:___', 'postScreen')" // post screen shot of AR view
"postMap('https:___') OR function('https:___', 'postMap')" // post AR map (feature points, anchors, planes)
"postScene('https:___') OR function('https:___', 'postScene')" // post scene graph structure
"postHits('https:___') OR function('https:___', 'postHits')" // post raycast hits (generated upfront by 'raycast')
"post('https:___', '_request') OR 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.
The following functions are available for manipulating the model using an item's id:
Setter Functions
"add('_id') OR function('_id', 'add')" // add item with _id at origin 0/0/0
"addon('_id', '_onID') OR function('_id', 'addon:', '_onID')" // add item with _id on item with _onID
"addto('_id', '_toID') OR function('_id', 'addto:', '_toID')" // add visual node of item with _id to item with _toID
"remove('_id') OR function('_id', 'remove')" // remove item with id from AR scene
"delete('_id') OR function('_id', 'delete')" // same as remove but also delete cached geometry to free memory
"replace('_id', '_withID') OR function('_id', 'replace:', '_withID')" // replace item with another item
"moveto('_id', 1.0, 2.0, 3.0) OR function('_id', 'moveto:::', 1.0, 2.0, 3.0)" // set absolute position of item
"moveby('_id', 0.5, 0.0, 1.0) OR function('_id', 'moveby:::', 0.5, 0.0, 1.0)" // move the item relative to its position
"turnto('_id', 90.0) OR function('_id', 'turnto:', 90.0)" // absolute y rotatation of item in degrees, clock wise
"turnby('_id', -5.0) OR function('_id', 'turnby:', -5.0)" // relative y rotatation of item in degrees, clock wise
"color('_id', '_val') OR function('_id', 'color:', '_val')" // set color, val as name ("red" or "#0000FF")
"bgcolor('_id', '_val') OR function('_id', 'bgcolor:', '_val')" // set background color of item
"txtcolor('_id', '_val') OR function('_id', 'txtcolor:', '_val')" // set text color of item
"lock('_id') OR function('_id', 'lock')" // lock item
"unlock('_id') OR function('_id', 'unlock')" // unlock item
If the id for remove
or delete
ends with an asterix (*), such as in "delete('net.metason.demo.*')"
, 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.
Getter Functions
"exist('_id') OR function('_id', 'exist')" // 0 or 1 if item with id exists in AR view
"visible('_id') OR function('_id', 'visible')" // 0 or 1 if item with id is visible by user
"proximity('_id') OR function('_id', 'proximity')" // distance in meters from camera to item with id
"gazingAt('_id') OR function('_id', 'gazingAt')" // 0 or 1 if user is gazing at item with id
"focused('_id') OR function('_id', 'focused')" // 0 or 1 if item with id is focused by user (is same as gazingAt)
"within('_id') OR function('_id', 'within')" // 0 or 1 if user is within 2D region of item with id
"distance(_latitude, _longitude) OR function(_latitude, 'distance:', _longitude)" // distance in meters from current place as lat and long numbers in decimal degrees
"width('_id') OR function('_id', 'width')" // width of item
"depth('_id') OR function('_id', 'width')" // depth of item
"height('_id') OR function('_id', 'width')" // height of item
"area('_id') OR function('_id', 'area')" // area (footprint) of item
"volume('_id') OR function('_id', 'volume')" // volume of item
"locked('_id') OR function('_id', 'locked')" // get lock status (0/1) of item
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').
Spatial getter functions may be used in conditions during AR session. An example of a spatial condition for testing proximity, in this case unhiding an element when the user gets near to it:
{
"as": "stated",
"if": "proximity('_id') < 1.2",
"do": "execute",
"op": "unhide('_id')"
}
{
"as": "stated",
"if": "distance('47.3769, 8.5417') < 30.0",
"do": "execute",
"op": "getJSON('https://___')" // run an action
}
Setter Functions
Visual-related functions do change the visual representation of items in the AR scene but are not reflected or stored in the model.
"posX('_id', 0.0) OR function('_id', 'posX:', 0.0)" // set x position of visual rep of item
"posY('_id', 0.0) OR function('_id', 'posY:', 0.0)" // set y position of visual rep of item
"posZ('_id', 0.0) OR function('_id', 'posZ:', 0.0)" // set z position of visual rep of item
"rotX('_id', 0.0) OR function('_id', 'rotX:', 0.0)" // set radiant x rotation of visual rep of item, counter clock wise
"rotY('_id', 0.0) OR function('_id', 'rotY:', 0.0)" // set radiant y rotation of visual rep of item
"rotZ('_id', 0.0) OR function('_id', 'rotZ:', 0.0)" // set radiant z rotation of visual rep of item
"scale('_id', 0.5) OR function('_id', 'scale:', 0.5)" // set scale factor of visual rep of item
"scaleX('_id', 0.5) OR function('_id', 'scaleX:', 0.5)" // set x scale factor of visual rep of item
"scaleY('_id', 0.5) OR function('_id', 'scaleY:', 0.5)" // set y scale factor of visual rep of item
"scaleZ('_id', 0.5) OR function('_id', 'scaleZ:', 0.5)" // set z scale factor of visual rep of item
"setR('_id', 0.4) OR function('_id', 'setR:', 0.4)" // set red value in RGB color
"setG('_id', 0.0) OR function('_id', 'setG:', 0.0)" // set green value in RGB color
"setB('_id', 1.0) OR function('_id', 'setB:', 1.0)" // set blue value in RGB color
"transparency('_id', 1.0) OR function('_id', 'transparency:', 1.0)" // set transparency
"occlude('_id') OR function('_id', 'occlude')" // set node of item to occlude
"highlight('_id') OR function('_id', 'highlight')" // highlight item
"dehighlight('_id') OR function('_id', 'dehighlight')" // dehighlight item
"pulsate('_id') OR function('_id', 'pulsate')" // pulsate item
"depulsate('_id') OR function('_id', 'depulsate')" // depulsate item
"hide('_id') OR function('_id', 'hide')" // hide item in AR scene
"unhide('_id') OR function('_id', 'unhide')" // unhide item in AR scene
"animPosX('_id', '_from _to _dur _repeat _reverse') OR function('_id', 'animPosX:', '_from _to _dur _repeat _reverse')" // animate geometry ofitem with _id or 3D node named _id
"animPosY('_id', '_from _to _dur _repeat _reverse') OR function('_id', 'animPosY:', '_from _to _dur _repeat _reverse')"
"animPosZ('_id', '_from _to _dur _repeat _reverse') OR function('_id', 'animPosZ:', '_from _to _dur _repeat _reverse')"
"animRotX('_id', '_from _to _dur _repeat _reverse') OR function('_id', 'animRotX:', '_from _to _dur _repeat _reverse')"
"animRotY('_id', '_from _to _dur _repeat _reverse') OR function('_id', 'animRotY:', '_from _to _dur _repeat _reverse')"
"animRotZ('_id', '_from _to _dur _repeat _reverse') OR function('_id', 'animRotZ:', '_from _to _dur _repeat _reverse')"
"animScaleX('_id', '_from _to _dur _repeat _reverse') OR function('_id', 'animScaleX:', '_from _to _dur _repeat _reverse')"
"animScaleY('_id', '_from _to _dur _repeat _reverse') OR function('_id', 'animScaleY:', '_from _to _dur _repeat _reverse')"
"animScaleZ('_id', '_from _to _dur _repeat _reverse') OR function('_id', 'animScaleZ:', '_from _to _dur _repeat _reverse')"
"animOpacity('_id', '_from _to _dur _repeat _reverse') OR function('_id', 'animOpacity:', '_from _to _dur _repeat _reverse')"
"stopAnim('_id', '_key') OR function('_id', 'stopAnim:', '_key')"
"enable('occlusion') OR function('occlusion', 'enable')" // enable people occlusion in AR view
"disable('occlusion') OR function('occlusion', 'disable')" // disable people occlusion in AR view
For the animation functions check the parameter description of Animation task.
Getter Functions
"posX('_id') OR function('_id', 'posX')" // get x position of visual rep of item
"posY('_id') OR function('_id', 'posY')" // get y position of visual rep of item
"posZ('_id') OR function('_id', 'posZ')" // get z position of visual rep of item
"rotX('_id') OR function('_id', 'rotX')" // get radiant x rotation of visual rep of item, counter clock wise
"rotY('_id') OR function('_id', 'rotY')" // get radiant y rotation of visual rep of item
"rotZ('_id') OR function('_id', 'rotZ')" // get radiant z rotation of visual rep of item
"scaleX('_id') OR function('_id', 'scaleX')" // get x scale factor of visual rep of item
"scaleY('_id') OR function('_id', 'scaleY')" // get y scale factor of visual rep of item
"scaleZ('_id') OR function('_id', 'scaleZ')" // get z scale factor of visual rep of item
"transparency('_id') OR function('_id', 'transparency')" // get transparency of visual rep of item
"hidden('_id') OR function('_id', 'hidden')" // get hidden status of visual rep of item
Setter Functions
The following functions are available for setting user interface (UI) elements:
"status('_text') OR function('_text', 'status')" // set status text in UI
"warning('_text') OR function('_text', 'warning')" // set warning text in UI
"skip('floor') OR function('floor', 'skip')" // skip floor and wall capturing
"skip('walls') OR function('walls', 'skip')" // skip wall capturing
"enable('camera') OR function('camera', 'enable')" // enable camera button
"disable('camera') OR function('camera', 'disable')" // disable camera button
"enable('help') OR function('help', 'enable')" // enable help button
"disable('help') OR function('help', 'disable')" // disable help button
"enable('service') OR function('service', 'enable')" // enable service button
"disable('service') OR function('service', 'disable')" // disable service button
"enable('traffic') OR function('traffic', 'enable')" // enable traffic button
"disable('traffic') OR function('traffic', 'disable')" // disable traffic button
"enable('catalog') OR function('catalog', 'enable')" // enable catalog button
"disable('catalog') OR function('catalog', 'disable')" // disable catalog button
"enable('save') OR function('save', 'enable')" // enable save button
"disable('save') OR function('save', 'disable')" // disable save button
"enable('undo') OR function('undo', 'enable')" // enable undo button
"disable('undo') OR function('undo', 'disable')" // disable undo button popup
"save('scene') OR function('scene', 'save')" // save AR session
"take('snapshot') OR function('snapshot', 'take')" // take a camera snapshot
"avoid('save') OR function('save', 'avoid')" // avoid save of scene
"exit('_url') OR function('_url', 'exit')" // exit AR session without save; optional: open url afterwards
"say('_text') OR function('_text', 'say')" // talk via Text-to-Speech (TTS)
"language('_langCode') OR function('_langCode', 'language')" // language of TTS voice: en, en-US, de, fr, ...
"gender('female') OR function('female', 'gender')" // gender of TTS voice: male/female
"vibrate('once') OR function('once', 'vibrate')" // one second vibration
"vibrate('twice') OR function('twice', 'vibrate')" // two short consecutive vibrations
"play('_sndID') OR function('_sndID', 'play')" // play System Sound, e.g., 1106
"stream('https:_.mp3') OR function('https:_.mp3', 'stream')" // stream audio
"loop('https:_.mp3') OR function('https:_.mp3', 'loop')" // loop audio stream
"pause('audio') OR function('audio', 'pause')" // pause audio stream
"play('audio') OR function('audio', 'play')" // play paused audio stream
"restart('audio') OR function('audio', 'restart')" // jump to start of audio stream
"pause('video') OR function('video', 'pause')" // pause video panel or video overlay
"play('video') OR function('video', 'play')" // play paused video stream
"restart('video') OR function('video', 'restart')" // jump to start of video stream
"start('screenrecording') OR function('screenrecording', 'start')" // start capturing screen as video
"start('screenrecording') OR function('screenrecording', 'stop')"
"start('photosequence') OR function('photosequence', 'start')" // start capturing photo sequence (for photogrammetry)
"stop('photosequence') OR function('photosequence', 'stop')"
"clear('UI') OR function('UI', 'clear')" // clear all labels in UI and hide center image
"hide('UI._') OR function('UI._', 'hide')" // hide UI element in AR view
"unhide('UI._') OR function('UI._', 'unhide')" // unhide UI element in AR view
"set('UI_', '_text') OR function('UI._', 'set:', '_text')" // set text label of UI element in AR view
"uninstall('UI_') OR function('UI._', 'uninstall')" // uninstall transient, scene-specific UI
"open('UI.catalog') OR function('UI.catalog', 'open')" // open model catalog
"open('UI.service') OR function('UI.service', 'open')" // open service selector
"open('UI.inspector') OR function('UI.inspector', 'open')" // open data inspecctor
"open('UI.help') OR function('UI.help', 'open')" // open help
"open('UI.traffic') OR function('UI.traffic', 'open')" // open traffic inspector
"position('_id') OR function('_id', 'position')" // open xyz pad controller for positioning item
"resize('_id') OR function('_id', 'resize')" // open wxhxd pad controller for resizing item
"raycast('UI.center') OR function('UI.center', 'raycast')" // create raycast hit from screen center (hint: show target icon)
"raycast('_id') OR function('_id', 'raycast')" // create raycast hit(s) from overlay with id (e.g. from BBoxLabel)
"inspect('_key') OR function('_key', 'inspect')" // show inspector with context data filtered by key
"prompt('Title', 'Message text') OR function('Title', 'prompt:', 'Message text')" // show info popup
"confirm('Will you do this?', 'function(`___`, `___`)') OR function('Will you do this?', 'confirm:', 'function(`___`, `___`)')" // show dialog, if confirmed then execute function(s)
"select('Will you do this?', 'function(`___`, `___`)', 'function(`___`, `___`)') OR function('Will you do this?', 'select::', '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.camera
: Camera buttton in the top barUI.help
: Help buttton in the top barUI.catalog
: Catalog buttton in the bottom barUI.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.
Getter Functions
"enabled('UI._') OR function('UI._', 'enabled')" // get enabled status of UI element
"hidden('UI._') OR function('UI._', 'hidden')" // get hidden status of UI element
Getter Functions
"getValue('_id') OR function('_id', 'getValue')" // get value for overlay type of Toggle, Menu, and Selector
"color('_id') OR function('_id', 'color')" // get color as string (such as '#FF0000') for overlay type of color picker
Setter Functions
"setValue('_id') OR function('_id', 'setValue:', 2)" // get value for overlay type of Toggle, Menu, and Selector
"color('_id', '#FF0000') OR function('_id', 'color:', '#FF0000')" // set color for overlay type of color picker
Functions to alter detectors installed by Actions.
"halt('_id') OR function('_id', 'halt')" // halt detector with id
"redetect('_id') OR function('_id', 'redetect')" // redetect/reactivate detector with id
"enable('meshing') OR function('meshing', 'enable')" // enable meshing of environment in AR view
"disable('meshing') OR function('meshing', 'disable')" // disable meshing of environment in AR view
"enable('depth') OR function('depth', 'enable')" // enable depth map in AR view
"disable('depth') OR function('depth', 'disable')" // disable depth map in AR view
"enable('behavior') OR function('behavior', 'enable')" // enable tracking of user behavior in AR view
"disable('behavior') OR function('behavior', 'disable')" // disable tracking of user behavior in AR view
The following functions return a numeric value:
"sinus(_num) OR function(_num, 'sinus')" // sin
"cosinus(_num) OR function(_num, 'cosinus')" // cos
"tangent(_num) OR function(_num, 'tangent')" // tan
"arcsinus(_num) OR function(_num, 'arcsinus')" // asin
"arccosinus(_num) OR function(_num, 'arccosinus')" // acos
"arctangent(_num) OR function(_num, 'arctangent')" // atan
"signum(_num) OR function(_num, 'signum')" // sign
"factorial(_num) OR function(_num, 'factorial')" // num!
The following functions return a string:
"append('str1', 'str2') OR function('str1', 'append:', ' tr2')" // returns the two strings as concated string
"join({'str1', 'str2', 'str3'}, ', ') OR function({'str1', 'str2', 'str3'}, 'join:', ', ')" // returns string of joined array elements with seperator inbetween
"ifThen('data.val == 5', 'function(`___`, `___`)') OR function('data.val == 5', 'ifThen:', 'function(`___`, `___`)')" // if predicate evaluates to true then execute function
"ifThenElse('data.val == 5', 'function(`___`, `___`)', 'function(`___`, `___`)') OR function('data.val == 5', 'ifThenElse::', 'function(`___`, `___`)', 'function(`___`, `___`)')" // if predicate evaluates to true then execute first else execute second function(s)
"forEach('_id1, _id2, _id3', 'function(`$ID`, , `___`)')" // IDs as comma-separated strings
"forEach({'_id1', '_id2', '_id3'}, 'hide(`$ID`)')" // IDs as array of strings
"repeatWhile('data.val <= 5', 'function(`___`, `___`); increase(`data.val`, 1)')"
For function calls embedded in a function call, use back quotes ` (single left ticks) for their string parameters.
Funtions such as assign:
and set:
can be used to dynamically set data variables that are valid throughout an AR session:
"assign('data._var0', 5.25) OR function('data._var0', 'assign:', 5.25)" // assign a numeric value (integer or float) to a variable
"increase('data._var0', 0.25) OR function('data._var0', 'increase:', 0.25)" // increase a numeric value (integer or float)
"decrease('data._var1', 1) OR function('data._var1', 'decrease:', 1)" // decrease a numeric value (integer or float)
"multiply('data._var0', 5.0) OR function('data._var0', 'multiply:', 5.0)" // multiply with numeric value (integer or float)
"devide('data._var1', 2) OR function('data._var1', 'devide:', 2)" // devide by a numeric value (integer or float)
"toggle('data._var1') OR function('data._var1', 'toggle')" // toggle a boolean data value
"set('data._var2', 'hello') OR function('data._var2', 'set:', 'hello')" // set a string variable
"concat('data._var2', ' my dear') OR function('data._var2', 'concat:', ' my dear')" // concat a string to an existing string variable
"addNum('data._var2', 5.3) OR function('data._var2', 'addNum:', 5.3)" // add a number as string to an existing string variable
"eval('data._var3', '_exp') OR function('data._var3', 'eval:', '_exp')" // eval an expression and set variable with result
"clear('data|hits|tasks|*') OR function('data|hits|tasks|*', 'clear')" // clear data, hits, dispatched tasks, UI or all
"clear('temp|cache') OR function('temp|cache', 'clear')" // delete temporary files or clear cached requests
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-2024 Metason - All rights reserved.