ARchi VR Functions

Revision Info: Documentation for ARchi VR Version 2.91 - April 2022

Table of Contents

Predicates and Expressions
- Operators
- Inline Functions
Custom Functions

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:

array example: data[1]
array example: array[FIRST] specifies the first element in the array
array example: array[LAST] specifies the last element in the array
array example: array[SIZE]returns the size of the array
dictionary example: data['key']
dictionary example: data.key // short version of the above
dictionary example: floor.notion.labels.name // returns array of names
filtering: SUBQUERY(floor.notion.labels, $lbl, length($lbl.name) > 8).name') // returns filtered array

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

example: "type == 'Space'"

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

example: "type == 'Space' AND subtype == 'Single Room'"

Range comparison: IN, BETWEEN

example: "data.str IN {‘Office’, ‘Home’, ‘Shop’}"
example: "'chair' IN detected.labels"
example: "data.num BETWEEN {3, 7}"

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

add [c] for case insensitive: lowercase & uppercase values are treated the same, e.g., CONTAINS[c]
add [d] for diacritic insensitive: special characters treated as the base character, e.g., CONTAINS[d]
use "*?" wildcards with LIKE, e.g., name LIKE 'M*'
example: "location.city LIKE[cd] 'Zürich'"
example: "walls[0].floorId BEGINSWITH 'D96B5F4A'"
example: "walls[0].floorId BEGINSWITH 'D96B5F4A'"

Aggregate operators: ANY, ALL, NONE

example: "ANY walls.material == 'Concrete'"

Type Casting

Automatic type casting is not performed. Use the CAST() operator to convert a key path or variable into a matching type:

To cast a value to a number, use CAST(key, 'NSNumber')
To cast a value to a string, use CAST(key, 'NSString')
To cast a value to a date, use CAST(key, "NSDate")
example: "function('data.numval', 'eval:', 'user.yaw * 180.0 / const.pi');function(CAST(data.numval, 'NSString'), 'status')"

Array functions

average, sum, count, median, mode, stddev, min, max

example: average({1, 2, 2, 3, 4, 7, 9})
example: sum({1, 2, 2, 3, 4, 7, 9})
example: count({1, 2, 2, 3, 4, 7, 9}
example: median({1, 2, 2, 3, 4, 7, 9})
example: mode({1, 2, 2, 3, 4, 7, 9})
example: stddev({1, 2, 2, 3, 4, 7, 9})
example: min({1, 2, 2, 3, 4, 7, 9})
example: max({1, 2, 2, 3, 4, 7, 9})

Statistics functions

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

example: "walls.@count > 2"
example: "items.mvertices@max > 10.0"

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') length('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:___',  'postScene') // post scene graph structure
    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', 'addon:', '_onID') // add item with _id on item with _onID
    function('_id', 'addto:', '_toID') // add visual node of item with _id to item with _toID
    function('_id', 'delete') // remove item with id from AR scene
    function('_id', 'remove') // same as delete
    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', 'color:', '_val') // set color, val as name ("red" or "#0000FF")
    function('_id', 'bgcolor:', '_val') // set background color of item
    function('_id', 'lock') // lock item
    function('_id', 'unlock') // unlock item

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.

Visual-related functions do change the visual representation of items in the AR scene but are not reflected or stored in the model.

    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', 'highlight') // highlight item
    function('_id', 'dehighlight') // dehighlight 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
    function('_id', 'animPosX:', '_from _to _dur _repeat _reverse') // animate geometry ofitem with _id or 3D node named _id
    function('_id', 'animPosY:', '_from _to _dur _repeat _reverse')
    function('_id', 'animPosZ:', '_from _to _dur _repeat _reverse')
    function('_id', 'animRotX:', '_from _to _dur _repeat _reverse')
    function('_id', 'animRotY:', '_from _to _dur _repeat _reverse')
    function('_id', 'animRotZ:', '_from _to _dur _repeat _reverse')
    function('_id', 'animScaleX:', '_from _to _dur _repeat _reverse')
    function('_id', 'animScaleY:', '_from _to _dur _repeat _reverse')
    function('_id', 'animScaleZ:', '_from _to _dur _repeat _reverse')
    function('_id', 'animOpacity:', '_from _to _dur _repeat _reverse')
    function('_id', 'stopAnim:', '_key')

For the animation functions check the parameter description of Animation task.

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('floor', 'skip') // skip floor and 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('occlusion', 'enable') // enable people occlusion in AR view
    function('occlusion', 'disable') // disable people occlusion in AR view
    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('https:_.mp3', 'loop') // loop audio stream
    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('screenrecording', 'start') // start capturing screen as video
    function('screenrecording', 'stop')
    function('photosequence', 'start') // start capturing photo sequence (for photogrammetry)
    function('photosequence', 'stop')
    function('UI', 'clear') // clear all labels in UI and hide center image
    function('UI._', 'hide') // hide UI element in AR view
    function('UI._', 'unhide') // unhide UI element in AR view
    function('UI._', 'set:', '_text') // set text label of 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

UI.status: The status text line on the top left
UI.warning: The warning text in the 2nd line on the top left
UI.center.image: The image (e.g. the target icon) in the center
UI.center.top: Text line on the top of the center image
UI.center.left: Text line on the left of the center image
UI.catalog: Catalog buttton in the bottom bar
UI.service: Service selector on mid right side
UI.traffic: Network analyzer on top right side

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

The following functions return a numeric value:

    "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!

function({'str1', 'str2', 'str3'}, 'join:', ', ')

Custom String and Array Functions

The following functions return a string:

    "function('str1', 'append:', ' str2')" // append strings
    "function({'str1', 'str2', 'str3'}, 'join:', ', ')" // join array elements by seperator

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 during AR session:

    "function('_id', 'exist')" // 0 or 1 if item with id exists in AR view 
    "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')" // toggle 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, UI or all
    "function('temp|cache', 'clear')" // delete temporary files o 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