Follow

Appendix 1: EML Language Specification

Introduction

XavierComposer™ is a hardware emulator for the Emotiv Software Development Kit. Using XavierComposer, game developers can emulate the behavior of Emotiv EmoEngine™ without needing to spend time in the real Emotiv EPOC™. XavierComposer operates in two modes, interactive and EmoScript playback. In the interactive mode, XavierComposer provides game developers with real time control over generating emulated detection events. XavierComposer also responds to a game’s requests in real time. In EmoScript mode, game developers can pre-define these two-way interactions by preparing an XavierComposer Markup Language (EML) document. EML documents are XML documents that can be interpreted by XavierComposer. This section outlines the EML specification.

 

EML Example

Apart from standard headers (lines 1-3 and 39), an EML document consists of two sections:

  • config: Section to configure global parameter for the XavierComposer behaviors.
  • sequence: Section to define detection events as they would occur in a real Emotiv SDK.

EML Header

Line 1-3 specifies the EML header.  EML is a special implementation of a generic XML document which uses UTF-8 encoding and English US language.  Line 2 is a normal XML comment to specify the document type and is optional.

EmoState Events in EML

EmoState events are defined within the <sequence> element.  In the below listing, the <sequence> element is between line 9 and line 38:

The <sequence> section consists of a series of discrete times at which there are events that will be sent from the XavierComposer to the game.  These time events are ascending in time.  Since each second is divided into 32 ticks (or frames), the time value in this example should be understood as follows:

Time

Line Number

Description

value = "0s15t"

10

This event is at 0 seconds and 15th frame

value = "2s4t"

20

This event is at 2 seconds and 4th frame

value = "3s6t"

28

This event is at 3 seconds and 6th frame

At each time event, game developers can specify up to six different parameters, corresponding to the five distinct detection groups plus the current signal quality:

Detection Group

Events

Notes

cognitiv

push

pull

lift

drop

left

right

rotate_left

rotate_right

rotate_clockwise

rotate_counter_clockwise

rotate_forwards

rotate_reverse

disappear

 

expressiv_eye

blink

wink_left

wink_right

look_left

look_right

“value” attribute is treated as a boolean (0 or not 0) to determine whether to set the specified eye state.

expressiv_upperface

eyebrow_raised

furrow

 

expressiv_lowerface

smile

clench

laugh

smirk_left

smirk_right

 

affectiv

excitement_short_term

excitement_long_term

engagement_boredom

Notes:

1. The affectiv tag is a special case in that it is allowed to appear multiple times, in order to simulate output from all the Affectiv detections.

2. In order to simulate the behavior of the EmoEngine™, both short and long term values should be specified for excitement.

signal_quality

value

This tag has been deprecated.  It has been replaced with the contact_quality tag. 

Expects “value” attribute to be formatted as 18 comma-separated floating point values between 0 and 1.  The first two values must be the same.

contact_quality

value

Expects “value” attribute to be formatted as 18 comma-separated character codes that correspond to valid CQ constants:
G = EEG_CQ_GOOD
F = EEG_CQ_FAIR
P = EEG_CQ_POOR
VB = EEG_CQ_VERY_BAD
NS = EEG_CQ_NO_SIGNAL

The first two values must be the same, and can only be set to G, VB, or NS, in order to most accurately simulate possible values produced by the Emotiv neuroheadset hardware.

The order of the character codes is the same as the contants in the EE_InputChannels_enum declared in EmoStateDLL.h.  Note that two of the channels, FP1 and FP2, do not currently exist on the SDK or EPOC neuroheadsets.

Detection group names are created by grouping mutually exclusive events together.  For example, only one of {blink, wink_left, wink_right, look_left, look_right} can happen at a given time, hence the grouping expressiv_eye.

The cognitiv detection group belongs to the Mental Commands Detection Suite.  Expressiv_eye, Expressiv_upperface, and Expressiv_lowerface detection groups belong to the Facial Expressions Detection Suite.  Affectiv detection group belongs to the Performance Metrics Detection Suite.

In its simplest form, a detection definition parameter looks like: <cognitiv event="push" value="0.85" />, which is a discrete push action of the Cognitiv detection group with a value of 0.85.  In EML, the maximum amplitude for any detection event is 1.  By default, the detection event retains its value for this detection group until the game developer explicitly set it to a different value.  However, game developers can also alter the reset behaviors as shown in the config section where the values for blink, wink_left, wink_right of the expressiv_eye detection group automatically reset themselves.

Instead of a discrete detection event as above, game developers can also define a series of detection events based on an event template function.  An event template function generates a burst of discrete events according to the following parameters:

  • shape: “normal” or “triangle”
  • offset_left, offset_right, scale_width: A template has a 1 second width by default.  These three parameters allow game developers to morph the template shape in the time domain.
  • scale_height: A template, by default, has maximum amplitude of 1.  This parameter allows game developers to morph the template’s height.

Normal and Triangle shapes are shown below:

An example of morphing template to specify detection event is: 

The above detection event can be illustrated as below:

First, we start with a normal template with height = 1 and width = 1.  Second, the template is adjusted by offset_left and offset_right.  It now has a height of 1 and a width of 1-0.4-0.2 = 0.4.

Last, after height is scaled by scale_height and width is scaled by scale_width, the template becomes:

Full specifications of an event’s attributes is shown below:

Attribute

Description

Required

[detection_group]

One of six available detection groups as specified in Table 5.

Yes

event=[event_name]

Corresponding values of the [detection_group] as specified in Table 5.

Yes

value=[value]

A detection event can be interpreted as either a discrete event or a series of events whose values are determined by an event template function.

The presence of the “value” attribute indicates that this is a discrete event.

Either “value” or “shape” attribute must be specified.

If “value” is present, none of the event template attributes (shape, offset_left, offset_right, scale_width, scale_height) are allowed

 

shape=[shape]

The presence of the “shape” attribute indicates that this represents the starting point for a series of events generated according to an event template function.

Allowed values are “normal” and “triangle”.

Either “value” or “shape” attribute must be specified.

If “shape” is present, then the “value” attribute is not allowed.

 

offset_left=[offset_left]

This attribute is a parameter of an event template function (see above for a detailed description of its meaning).

offset_left+offset_right must be less than 1.

The “shape” attribute must also be specified.

The “value” attribute can not be specified.

 

offset_right=[offset_right]

This attribute is a parameter of an event template function (see above for a detailed description of its meaning).

offset_left+offset_right must be less than 1.

The “shape” attribute must also be specified.

The “value” attribute can not be specified.

 

scale_width=[scale_width]

This attribute is a parameter of an event template function (see above for a detailed description of its meaning).

Must be greater than 0.

 

The “shape” attribute must also be specified.

The “value” attribute can not be specified.

 

scale_height=[scale_height]

This attribute is a parameter of an event template function (see above for a detailed description of its meaning).

0 < scale_height <= 1

 

- The “shape” attribute must also be specified.

- The “value” attribute can not be specified.

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk