Schema Documentation for http://studierstube.icg.tu-graz.ac.at/april

Author: Florian Ledermann (ledermann@ims.tuwien.ac.at)

To get an overview, the graphical schema representation is the recommended entry point.

Links to

APRIL provides language elements for describing

Global Elements

april

Description

The root element of every APRIL file.

Sub-Elements

setup

Description

Wrapper element for input and output device configuration. The config section of the APRIL file specified as src is imported (if present), and overlayed with the information of the local config section (this means that local elements with the same id as in the src file, and their child-elements, override the elements specified in the src file). The low-level tracking configuration is done in the OpenTracker file specified with the otsource attribute, or inline in the corresponding interaction elements (see below). If there is no setup element, APRIL looks for a file called "default.aps" in the presentations directory.

Attributes

src
xs:anyURI URI of external file containing the config section to use. If a src is specified, any inline specifications will be ignored and the configuration specified in the given file will be used. We should support something like overlays, i.e. the config loaded from file is overlayed with the inline definitions!
otfile
xs:anyURI URI of OpenTracker config file to use as a basis for the tracking configuration. Named OpenTracker nodes referenced in the APRIL file are referenced from this file.
workspacepath
xs:anyURI Path to the executable(s) of the traget platform.

Sub-Elements

host

Description

Wrapper element for all devices connected to a single computer. Multiple hosts are NOT IMPLEMENTED.

Sub-Elements

screen

Description

Configures a VGA output port.

Attributes

resolution
Vec2i Screen resolution in pixels.

host

display

Description

Defines a display for rendering content on. The containing displaytracking and/or headtracking elements define optional tracking, this elements configures the position of the display window on an output port, its resolution and the default camera pose in the world.

Attributes

id
xs:ID ID to uniquely identify this display.
screen
xs:int The screen number this display window should be rendered on.
screenPosition
ScreenSizeType position of the top left corner of the display window on the screen in pixels or percentage.
screenSize
ScreenSizeType Size of the display on screen in pixels or percentage.
stereo
xs:boolean Flag indicating if frame-interleved stereo should be used.
worldPosition
Vec3f The position of the center of the image plane in world coordinates. Overridden if a displaytracking element is used.
worldSize
Vec2f Size of the image plane in the world.
worldOrientation
Vec4f Orientation of the image plane in the world. Overridden if a displaytracking element is used.
eyeOffsetL
Vec3f Offest of the left eye for a stereo display.
eyeOffsetR
Vec3f Offest of the right eye for stereo displays.
viewpointPosition
Vec3f The world position of the viewpoint. Overridden if a headtrtacking element is used.
mode
"AR" (default value) displays the actors of the presentation. "VR" also renders the stage elements for a virtual reality view onto the scene.
debug
xs:boolean If set to true, debug information is shown in the display.

Sub-Elements

headtracking

of Type TrackableType

Description

Configures the headtracking for the parent display element.

Inherited Attributes

from TrackableType :
id
ID to identify this element.
otsource
DEF name of an OpenTracker node in the included OpenTracker file (or an earlier configured inline OT node)

display

displaytracking

of Type TrackableType

Description

Configures tracking of the center of the display.

Inherited Attributes

from TrackableType :
id
ID to identify this element.
otsource
DEF name of an OpenTracker node in the included OpenTracker file (or an earlier configured inline OT node)

display

pointer

Description

Configures a 2d-pointing device for the display, which can be used to interact with widgets or point on real/virtual things. Currently this is hard-coded to use the mouse input.

display

host

station

of Type TrackableType

Description

Defines a tracked artifact like a marker.

Inherited Attributes

from TrackableType :
id
ID to identify this element.
otsource
DEF name of an OpenTracker node in the included OpenTracker file (or an earlier configured inline OT node)

host

button

of Type TrackableType

Description

NOT IMPLEMENTED. A hardware button that can be used for user input.

Inherited Attributes

from TrackableType :
id
ID to identify this element.
otsource
DEF name of an OpenTracker node in the included OpenTracker file (or an earlier configured inline OT node)

host

setup

april

presentation

Description

This is the top-level wrapper element of a APRIL presentation.

Attributes

id
xs:ID Unique ID for this presentation. Depending on the implementation of the transformation of APRIL to a specific platform, this will be used for generating file- or folder names for the resulting files.
name
xs:string The name of the presentation. This can be used by target platforms as a human-readable title for the presentation.

Sub-Elements

story

Description

The content of this element specifies the logic (or the "story") of the presentation as a hierarchical state machine. The syntax is derived from XMI, the official UML-to-XML serialization syntax, but simplified for better readability.

presentation

cast

Description

This element holds all references to used media resources (models, images, sounds, scripts etc.).

Sub-Elements

stage

of Type VisibleActorType

Description

Defines geometry as a proxy for real world objects. In augmented reality applications, this is not displayed, but used for correct rendering of intersections between virtual and real content, for example. In VR and authoring setups, these objects may be rendered as regular scene objects.

Inherited Attributes

from VisibleActorType :
position
Position of the object in world coordinates.
orientation
Orientation of the object in the world.
scale
Scale factor for this object.
transparency
Transparency value for this object. DEPRECTED, use components for all your actors. Transparency for real-world objects doesn't make much sense...
visible
DEPRECATED

cast

actor

Description

Defines an actor of the presentation as an instance of a nAPRIL component. Inside the actor element, default values for its input fields can be set by using input elements.

Attributes

id
xs:ID Unique id of the actor.
src
xs:anyURI Source of the component definition file.

Sub-Elements

input

Description

Defines the default value for a specific input for this presentation.

Attributes

id
xs:normalizedString Id ofthe field to set.
value
xs:string Default value of that field.

actor

cast

light

Description

A light source, either real or virtual. NOT IMPLEMENTED.

cast

sound

Description

A sound to be played in the presentation. NOT IMPLEMENTED.

cast

presentation

behaviors

Description

The behaviours section binds behaviours of objects to states of the story logic.

Sub-Elements

behavior

Description

A behavior is a set of property changes bound to a state of the tory logic. Whenever the state is entered, the actions defined in the "entry" sub-element are performed. If the story is still in this state after perfomring the entry actions, the "do" actions are performed, and can be interrupted at any time by leaving the state. Upon leving the state, the "exit" actions are guaranteed to perform.

Attributes

scene
xs:IDREF ID of the scene this behavior should be bound to.

Sub-Elements

entry

of Type LabelType

Description

The "entry" actions are performed when the associated state is entered. Actions defined here are guaranteed to perform, now matter how long the story remains in this state. Actions should therefore only be "set" and "connect", and very short "animate"ions.

Inherited Attributes

from LabelType :

Attributes

duration
xs:duration Allows explicit setting of the duration of the entry substate. If this is not used, the dration is calculated from the set and animate elements inside.

behavior

do

of Type LabelType

Description

Actions in this group are performed as long as the story is in the associated state. Note that actions might not be called at all, if the state is immediately left. This is the only place where looped animations make sense, because they can be cancelled by leaving the state.

Inherited Attributes

from LabelType :

behavior

exit

of Type LabelType

Description

Actions defined here are executed when the associated state is left. They are guaranteed to perform.

Inherited Attributes

from LabelType :

behavior

behaviors

presentation

interactions

Description

Sub-Elements

event

Description

Attributes

id
xs:ID ID of the transition this interaction is mapped to.

Sub-Elements

timeout

of Type Interaction

Description

This triggers the associated transition automatically after a specified time.

Inherited Attributes

from Interaction :
auto
If set to true, the transition triggers automatically if it is the only available transition. NOT IMPLEMENTED

Attributes

time
xs:duration Time after which the transition should trigger.

event

disabled

of Type Interaction

Description

This disables a transition. Same as leaving it empty.

Inherited Attributes

from Interaction :
auto
If set to true, the transition triggers automatically if it is the only available transition. NOT IMPLEMENTED

event

always

of Type Interaction

Description

This always triggers the transition immediately.

Inherited Attributes

from Interaction :
auto
If set to true, the transition triggers automatically if it is the only available transition. NOT IMPLEMENTED

event

buttonaction

of Type Interaction

Description

This creates or uses a button when the transition becomes available, that can be pressed by the user to trigger the transition.

Inherited Attributes

from Interaction :
auto
If set to true, the transition triggers automatically if it is the only available transition. NOT IMPLEMENTED

Attributes

virtual
xs:boolean Whether to create a virtual button. DEPRECATED.
caption
xs:string The label printed on the (virtual) button.

event

rayaction

of Type Interaction

Description

This allows the user to use a raypicker to point at objects in the scene. If the specified actor or stage object is selected, the transition fires.

Inherited Attributes

from Interaction :
auto
If set to true, the transition triggers automatically if it is the only available transition. NOT IMPLEMENTED

Attributes

target
xs:IDREF ID of the actor or stage object that must be selected to trigger the transition.

event

evaluator

of Type Interaction

Description

Evaluates an output of an actor against a fixed value or another output. If the expression evaluates to true, the transition fires.

Inherited Attributes

from Interaction :
auto
If set to true, the transition triggers automatically if it is the only available transition. NOT IMPLEMENTED

Attributes

source
xs:IDREF Actor or tracking element that should be used as input.
output
xs:string Output field of the source to use. For tracking elements, position and orientation are available outputs.
comparator
The kind of comparison to perform. One of equal (default), lessThan, greaterThan, lessOrEqual, greaterOrEqual, notEqual, isInside (bounding box check), notInside.
value
xs:string The fixed value the source output should be compared to.
source2
xs:IDREF A second actor or tracking element that delivers the output for comparison.
output2
xs:string The output of the second source to be used.

event

interactions

presentation

april

scene

of Type Scene

Description

A state in a hierarchical state machine.

Inherited Attributes

from Scene :
name
Name of the state.
initial
Marker attribute for initial states.

transition

Description

A transition from one state to another, specifying the transition event name.

Attributes

event
xs:Name Name of the event to trigger the transition.
source
xs:Name Id of the source scene of the transition.
target
xs:Name Id of the target scene of the transition.
guard
xs:string A guard string, that can contian the id of another state. This means that the transition is only available if the story is currently in this state.

concurrentScene

of Type Scene

Description

Wrapper element to seperate multiple concurrent sub-engines inside a superstate.

Inherited Attributes

from Scene :
name
Name of the state.
initial
Marker attribute for initial states.

annotation

Description

Inside this element, any annotation might be added to describe what is happening inside this scene.

Global Simple Types

FloatList

Syntax

Description

list of double values, base type for restricted data types like vectors, rotations, etc.

IntegerList

Syntax

Description

list of integer values, useful for list of indices.

Vec2f

Syntax

Description

a simple type storing two float values, separated by spaces.

Vec3f

Syntax

Description

a simple type storing three float values separated by spaces.

Vec4f

Syntax

Description

a simple type storing four float values separated by spaces.

Vec2i

Syntax

Description

a simple type storing two integer values separated by spaces.

ScreenSizeType

Syntax

Description

either two numbers, indicating absolute pixels, or two percentage values, or the keyword "fullscreen".

Global Complex Types

Interaction

Syntax

Attributes

auto
If set to true, the transition triggers automatically if it is the only available transition. NOT IMPLEMENTED

Description

ActorType

Syntax

Attributes

type
The MIME-type of the content.
src
The URI to load the content from.
id
Unique id of this element.

Description

Base type for stage, actor, light and sound elements. DEPRECATED.

Sub elements

inline

Description

You can specify content inline by wrapping it with this tag and putting it as a first child of the actor element. Note that if a src attribute is present on the parent element, the inline content will be treated as if specified within an alt tag, i.e. only used when the content specified by src cannot be retrieved.

ActorType

alt

Description

Sub-Elements

inline

Description

You can specify content inline by wrapping it with this tag and putting it as a first child of the actor element. Note that if a src attribute is present on the parent element, the inline content will be treated as if specified within an alt tag, i.e. only used when the content specified by src cannot be retrieved.

alt

ActorType

ActionType

Syntax

Attributes

input
Which input field of the actor to set.
actor
The target actor.

Description

Base type for set, animate, connect and control elements.

LabelType

Syntax

Description

Base type for entry, exit, do elements.

Sub elements

set

of Type ActionType

Description

Sets the given input of a component instance to the given value.

Inherited Attributes

from ActionType :
input
Which input field of the actor to set.
actor
The target actor.

Attributes

to
xs:string New value for the input.
time
xs:duration Time after enter/exit the change should happen.

LabelType

animate

of Type ActionType

Description

Animates the given input. For further information, see the SMIL animation spec.

Inherited Attributes

from ActionType :
input
Which input field of the actor to set.
actor
The target actor.

Attributes

begin
xs:duration The start time of the animation, measured from the enter/exit time of the state.
duration
xs:duration The duration of the animation.
to
xs:string Target value of the input.
by
xs:string Relative target value of the input. NOT IMPLEMENTED
calcMode
xs:token CalcMode like defined in the SMIL animation spec. NOT IMPLEMENTED, always linear at the moment.

LabelType

connect

of Type ActionType

Description

Connects an input of an actor to an output of another actor (master). The connection remains for the duration of the container state.

Inherited Attributes

from ActionType :
input
Which input field of the actor to set.
actor
The target actor.

Attributes

master
xs:IDREF Master actor to connect the field from.
output
xs:string Which output of the master actor to use.

LabelType

control

of Type ActionType

Description

Allows the user to control an input of an actor. If the id of a station is given, this station is used to control the input (via its position and orientation outputs), otherwise PUC is used to control the input.

Inherited Attributes

from ActionType :
input
Which input field of the actor to set.
actor
The target actor.

Attributes

min
xs:anySimpleType Lower limit of the value range that can be set.
max
xs:anySimpleType Upper limit of the value range that can be set.
label
xs:string A label shown to the user together with the control for changing the input.
station
xs:string ID of a station (defined in the setup element) to be used to contol the property. Station inputs can only be used to control inputs with types SFVec3f or SFRotation.

LabelType

TrackableType

Syntax

Attributes

id
ID to identify this element.
otsource
DEF name of an OpenTracker node in the included OpenTracker file (or an earlier configured inline OT node)

Description

Base type for trackable objects. Allows specification of an OT source either by reference or by inline OT code.

VisibleActorType

Syntax

Attributes

position
Position of the object in world coordinates.
orientation
Orientation of the object in the world.
scale
Scale factor for this object.
transparency
Transparency value for this object. DEPRECTED, use components for all your actors. Transparency for real-world objects doesn't make much sense...
visible
DEPRECATED

Description

Base type for visible actors. DEPRECATED.

Scene

Syntax

Attributes

name
Name of the state.
initial
Marker attribute for initial states.

Description

Base type for scenes.

Comments