Difference between revisions of "Configuring CWASA for HTML5 web pages"

From Virtual Humans
Jump to navigation Jump to search
(Complete set of configuration parameters.)
m
 
(23 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[Main Page|Home]] >> [[JASigning]]
+
[[Main Page|Home]] >> [[CWA Signing Avatars|CWASA]]
 +
----
  
== JASigning Development ==
+
== CWASA Development ==
  
The [[JASigning]] (Java Avatar Signing) software was a reimplementation of earlier work using Java to create freestanding applications and web applets that can be scripted through JavaScript on web pages. [[SiGML]] data is converted to motion data for animation using the [[Animgen]] software, written in C++. Animation data is rendered using an OpenGL renderer written in Java using the JOGL bindings.
+
The [[JASigning]] (Java Avatar Signing) software was a reimplementation of earlier work based on C++ and Visual Basic. [[JASigning]] uses Java to create freestanding applications and web applets that can be scripted through JavaScript on web pages. [[SiGML]] data is converted to motion data for animation using the [[Animgen]] software, written in C++. Animation data is rendered using an OpenGL renderer written in Java using the JOGL bindings.
  
 
With the advent of '''HTML5''' and '''WebGL''' it has become practical to create software for use in web pages that is not dependent on Java. This development has become essential as Java is now deprecated in browsers and unsupported on major browsers such as '''Chrome''' and '''Opera'''.
 
With the advent of '''HTML5''' and '''WebGL''' it has become practical to create software for use in web pages that is not dependent on Java. This development has become essential as Java is now deprecated in browsers and unsupported on major browsers such as '''Chrome''' and '''Opera'''.
  
Development is taking place in a number of stages:
+
Development took place in a number of stages:
  
* Introduction of a WebGL renderer in place of OpenGL via Java. [[SiGML]] processing continues via a simplified Java applet.
+
* Introduction of a WebGL renderer in place of OpenGL via Java. [[SiGML]] processing continued via a simplified Java applet.
 
* [[SiGML]] processing delegated to an [[Animgen]] server located at UEA using a CGI script.
 
* [[SiGML]] processing delegated to an [[Animgen]] server located at UEA using a CGI script.
* Preprocessing of the [[HamNoSys]] variant of [[SiGML]] to the Gestural variant implemented in JavaScript.
+
* Preprocessing in JavaScript of the [[HamNoSys]] variant of [[SiGML]] to the Gestural variant.
 
* Fully client-side operation using a JavaScript implementation of [[Animgen]].
 
* Fully client-side operation using a JavaScript implementation of [[Animgen]].
  
All but the final stage has been completed.
+
== CWASA Installation ==
 
 
== JASigning Installation ==
 
  
An installation of [[JASigning]] contains a number of index web pages, web pages with embedded signing avatars, and several directories containing resources.
+
An open installation of [[CWASA]] contains a number of index web pages, web pages with embedded signing avatars, and several directories containing resources.
Here we describe only elements required for HTML5 software. More can be seen in a [[JASigning Local Installation]].
 
  
 
* '''avatars''' contains JARs with avatar definition data.
 
* '''avatars''' contains JARs with avatar definition data.
Line 28: Line 26:
 
See [[JASigning Local Installation]].
 
See [[JASigning Local Installation]].
  
== CWASA (CoffeeScript Web Applet Signing Avatar) ==
+
== CWASA (CoffeeScript WebGL ARP Signing Avatars) ==
  
 
The CWASA software is largely written in CoffeeScript which generates JavaScript that is combined into a single script file in the '''cwa''' directory.
 
The CWASA software is largely written in CoffeeScript which generates JavaScript that is combined into a single script file in the '''cwa''' directory.
CWASA is configured using settings in JSON objects. Four sources of settings are consulted, with earlier settings overriding later ones:
+
CWASA is configured using settings in JSON objects. Up to four sources of settings are consulted, with earlier settings overriding later ones:
  
 
* Initial settings provided as an optional argument when the CWASA software is initialised. This allows web pages to be self contained.
 
* Initial settings provided as an optional argument when the CWASA software is initialised. This allows web pages to be self contained.
* Client settings held in an optional file '''clientcfg.json''' at the same level as the webpage.
+
* Client settings held in an optional file '''clientcfg.json''' at the same level as the webpage. Normally bypassed if Initial settings are given.
* Installation settings held in a file '''cwacfg.json''' in the '''cwa''' folder in the installation.
+
* Installation settings held in a file '''cwacfg.json''' in the '''cwa''' folder of the installation.
* Installation-depended default settings applied by the initialisation script.
+
* Installation-depended default settings applied by the CWASA initialisation code.
  
Parameters are in two classes:
+
Parameters are in three classes:
  
 +
* Settings determining which configuration files are consulted.
 
* Installation settings providing locations for installation directories.
 
* Installation settings providing locations for installation directories.
 
* Settings for configuring a GUI for one or more avatar panels.
 
* Settings for configuring a GUI for one or more avatar panels.
  
Full example configuration files are given below. Initial settings are provided using a similar JavaScript JSON object.
+
Full example configuration files are given below. Initial settings are provided using a similar JavaScript JSON object as in '''appletframe.html''' in BSLExamples ([[CWASA Local Installation]]).
 
Unrecognised settings (such as '''description''') are ignored without comment.
 
Unrecognised settings (such as '''description''') are ignored without comment.
  
=== Installation Settings ===
+
== Configuration Consultation Settings ==
 +
 
 +
Users can use these settings to change the normal pattern of consulting configuration files:
 +
 
 +
* '''useClientConfig''': Controls whether '''clientcfg.json''' is consulted. Default '''true''' but bypassed if Initial settings are given unless explicitly overridden.
 +
* '''useCwaConfig''': Controls whether '''cwacfg.json''' is consulted. Default '''true'''.
 +
 
 +
Hence '''useClientConfig''' should be set to '''true''' by pages using Initial settings that also wish to consult a '''clientcfg.json''' file.
 +
 
 +
== CWASA Installation Settings ==
  
 
It is unlikely that users will need to change installation settings as these will be picked up from the installation when initialising CWASA. The settings are:
 
It is unlikely that users will need to change installation settings as these will be picked up from the installation when initialising CWASA. The settings are:
Line 57: Line 65:
 
* '''useAvatarJARs''': Flag choosing between JAR and JSON representation for avatars. Currently needs to be set '''true'''.
 
* '''useAvatarJARs''': Flag choosing between JAR and JSON representation for avatars. Currently needs to be set '''true'''.
 
* '''animgenFPS''': Frames per Second of generated animation data. Defaults to '''50'''.
 
* '''animgenFPS''': Frames per Second of generated animation data. Defaults to '''50'''.
* '''animgenServer''': Path to CGI script for [[Animgen]] server.
+
* '''animgenServer''': Path to CGI script for [[Animgen]] server if used.
  
If no [[Animgen]] server is specified, the deprecated Java applets will be used. The default is to use a server,
+
The default is to specify no [[Animgen]] server and client-side JavaScript will implement [[Animgen]].
but a setting of '''null''' for '''animgenServer''' will force use of applets.
+
Some example web pages specify a server that will be used instead. The public server is
 +
[http://vhg.cmp.uea.ac.uk/cgi-bin/animgen/animgenserver.pl http://vhg.cmp.uea.ac.uk/cgi-bin/animgen/animgenserver.pl].
 +
The deprecated Java Applet implementing [[Animgen]] can be accessed using a pseudo-server '''stoca:'''.
 +
Processing will fall back to the client-side implementation if Java is not supported in the chosen browser.
  
=== GUI Settings ===
+
== CWASA GUI Settings ==
  
 
A CWASA web page can display several avatars identified as '''av0''', '''av1''', etc. Each avatar has an associated list of possible avatar characters to be displayed.  
 
A CWASA web page can display several avatars identified as '''av0''', '''av1''', etc. Each avatar has an associated list of possible avatar characters to be displayed.  
Line 74: Line 85:
 
* '''avList''': Name of parameter holding avatar list. This will be '''avs''' by default.
 
* '''avList''': Name of parameter holding avatar list. This will be '''avs''' by default.
 
* '''initAv''': Name of avatar that is loaded initially. Should normally be already present in the '''avList'''.
 
* '''initAv''': Name of avatar that is loaded initially. Should normally be already present in the '''avList'''.
 +
* '''ambIdle''': Flag controlling whether ambient motion accompanies an idle avatar.
 
* '''background''': By default the canvas will have a transparent background but valid text for a style background in HTML can be provided. Set to '''null''' to force a transparent background.
 
* '''background''': By default the canvas will have a transparent background but valid text for a style background in HTML can be provided. Set to '''null''' to force a transparent background.
 
* '''initCamera''': Nine numbers that define the initial camera position when the avatar is loaded.
 
* '''initCamera''': Nine numbers that define the initial camera position when the avatar is loaded.
 +
* '''initSpeed''': Initial speed setting. See below.
 +
* '''rateSpeed''': Rate of change to speed in GUI. See below.
 +
 +
Note that an '''ambIdle''' setting may be given at installation level and will be inherited by each panel that does not provide its own setting.
 +
 +
The actual animation speed is given by '''2^(currSpeed/rateSpeed)''' where '''currSpeed''' is initially set to '''initSpeed''' and may be increased or decreased in the GUI. The rate determines how many steps are needed to change the speed by a factor of 2.
  
 
The remaining parameters are mostly needed when a GUI is generated automatically as a full panel:
 
The remaining parameters are mostly needed when a GUI is generated automatically as a full panel:
Line 83: Line 101:
 
* '''allowSiGMLText''': Flag selecting whether a field for entry of [[SiGML]] text is displayed. No field or text play button is displayed if the value is '''false'''.
 
* '''allowSiGMLText''': Flag selecting whether a field for entry of [[SiGML]] text is displayed. No field or text play button is displayed if the value is '''false'''.
  
 +
== CWASA Configuration Examples ==
 
=== Example: cwa/cwacfg.json ===
 
=== Example: cwa/cwacfg.json ===
 +
Example installation configuration:
 
  {
 
  {
   "description"    : "========  CWASA installation configuration data ========",
+
   "description"    : "========  CWASA installation configuration data : Main release ========",
 
+
   "jasBase"        : "http://vhg.cmp.uea.ac.uk/tech/jas/vhg2021/",
   "jasBase"        : "http://vhg.cmp.uea.ac.uk/tech/jas/vhg2017/",
+
   "jasVersionTag"  : "vhg2021",
   "jasVersionTag"  : "vhg2017",
+
 
 
 
   "sigmlBase"      : "sigml",
 
   "sigmlBase"      : "sigml",
 
   "avJARBase"      : "avatars",
 
   "avJARBase"      : "avatars",
 
   "avJSONBase"      : "avjson",
 
   "avJSONBase"      : "avjson",
 
   "useAvatarJARs"  : true,
 
   "useAvatarJARs"  : true,
 
+
   "animgenFPS"      : 50,
+
   "animgenFPS"      : 30,
  "animgenServer"  : "http://vhg.cmp.uea.ac.uk/cgi-bin/animgen/animgenserver.pl",
+
 
 
 
   "avs" : [
 
   "avs" : [
 
     "anna", "marc", "francoise"
 
     "anna", "marc", "francoise"
 
   ],
 
   ],
 
+
 
   "avsfull" : [
 
   "avsfull" : [
     "anna",
+
     "anna", "marc", "francoise",
    "beatrice", "candy", "darshan", "francoise", "genie", "luna",
+
     "luna", "siggi"
     "marc", "max", "monkey", "otis", "robotboy", "siggi"
 
 
   ],
 
   ],
 
+
 
 
   "avSettings" : [
 
   "avSettings" : [
 
     {
 
     {
Line 116: Line 133:
 
       "initAv":          "anna",
 
       "initAv":          "anna",
 
       "initCamera":      [ 0, 0.23, 3.24, 5, 18, 30, -1, -1 ],
 
       "initCamera":      [ 0, 0.23, 3.24, 5, 18, 30, -1, -1 ],
 +
      "initSpeed":        0,
 +
      "rateSpeed":        5
 
       "allowFrameSteps":  true,
 
       "allowFrameSteps":  true,
 
       "initSiGMLURL":    "iTakeMug.sigml",
 
       "initSiGMLURL":    "iTakeMug.sigml",
Line 124: Line 143:
  
 
=== Example: cwa/clientcfg.json ===
 
=== Example: cwa/clientcfg.json ===
 +
Configuration for Clients using client-side [[Animgen]] processing:
 
  {
 
  {
 
   "description"    : "========  CWASA client configuration data. No Animgen server ========",
 
   "description"    : "========  CWASA client configuration data. No Animgen server ========",
 
 
   "animgenServer": null,
 
   "animgenServer": null,
 
 
   "avSettings" : [
 
   "avSettings" : [
 
     {
 
     {
Line 149: Line 167:
 
   ]
 
   ]
 
  }
 
  }
 +
 +
== CWASA GUI Creation ==
 +
There are four approaches to incorporating the CWASA software on a web page. The installation contains example web pages, built using the different approaches:
 +
 +
* Complete GUI: '''WebGLAvTwo.html'''. A single '''div''' is populated with a panel containing an avatar canvas and GUI elements.
 +
* GUI Panels: '''CWASA-plus-gui-panel.html'''. A '''div''' for the avatar canvas and a separate '''div''' for the GUI.
 +
* GUI Elements: '''CWASA-plus-gui-elements.html'''. A number of '''div'''s and '''span'''s arranging different sections of the GUI.
 +
* Bespoke GUI: '''CWASA-plus-bespoke-gui.html'''. Individual HTML elements defining an equivalent GUI.
 +
 +
The first example displays two avatars on a page.
 +
The first two approaches select elements according to layout parameters in the configuration, while the final approaches choose elements directly.
 +
The final three examples have very similar appearance, illustrating the alternative approaches.
 +
 +
A CSS stylesheet controls appearance in all cases. The '''class''' attribute is also used by the CWASA script to identify elements of the GUI
 +
for attaching handlers and to change enabled state during animation. For a page that might use the Java applet it is necessary to include one instance of:
 +
<pre><div class="SToCA"></div></pre>
 +
This will be ignored if an [[Animgen]] server is used or the browser does not support Java.
 +
 +
A '''div''' or '''span''' that forms part of the CWASA GUI will have a class which identifies the GUI component and the avatar concerned. For example, a complete GUI panel for the first avatar would be specified by:
 +
<pre><div class="CWASAPanel av0"></div></pre>
 +
 +
=== Complete GUI ===
 +
* '''CWASAPanel''': A GUI, '''CWASAGUI''', to the left of an avatar canvas, '''CWASAAvatar'''.
 +
=== GUI Panels ===
 +
* '''CWASAGUI''': A combination of GUI elements, some omitted according to the avatar settings in the configuration.
 +
* '''CWASAAvatar''': A canvas for a WebGL avatar. The canvas fills the size of the enclosing element.
 +
=== GUI Elements ===
 +
* '''CWASAAvMenu''': A menu listing avatars in the expanded '''avList''' for the avatar.
 +
* '''CWASAAmbBox''': A checkbox controlling whether ambient motion is seen for an idle avatar.
 +
* '''CWASASpeed''': Controls for decreasing, increasing, and resetting the speed of animation.
 +
* '''CWASASiGMLURL''': Input to hold a SiGML URL. Omitted by '''CWASAGUI''' if no initial URL is given.
 +
* '''CWASASiGMLText''': Text area for entry of SiGML. Omitted by '''CWASAGUI''' if SiGML text is not allowed.
 +
* '''CWASAPlay''': Play and Stop buttons. Only included if corresponding SiGML URL or Text fields are present.
 +
* '''CWASAPlayExtra''': Suspend and Resume buttons. Only included if Play buttons are present. Omitted by '''CWASAGUI''' if frame steps are not allowed.
 +
* '''CWASAFrames''': Frame single step buttons. Only included if Play buttons are present. Omitted by '''CWASAGUI''' if frame steps are not allowed.
 +
* '''CWASAProgress''': Display of current sign and frame number, sign gloss, and actual FPS.
 +
* '''CWASAStatus''': Display of status information.
 +
=== Bespoke GUI ===
 +
Users are encouraged to use the defined GUI elements as these are not expected to change significantly. Localisation does not require the use of a bespoke GUI.
 +
For details on creating a bespoke GUI, if desired, examine the HTML file '''CWASA-plus-bespoke-gui.html'''. 
 +
Essentially, the example shows the HTML generated for GUI elements by CWASA. In order that the CWASA code will link to the GUI HTML elements it is necessary to use the appropriate classes where an avatar code is also given.
 +
 +
 +
Regrettably, some of the low-level GUI elements use classes with names that might clash with those already in use in an existing application.
 +
 +
Some examples illustrate that certain GUI elements, such as buttons, menus, and output fields, can be duplicated. CWASA will copy information to all fields and enable and disable all duplicated buttons.
 +
 +
== CWASA Web Pages ==
 +
 +
To use CWASA, include the following CSS file and JavaScript code, relative to the JASigning installation:
 +
<pre><link rel="stylesheet" href="http://vhg.cmp.uea.ac.uk/tech/jas/vhg2021/cwa/cwasa.css" />
 +
<script type="text/javascript" src="http://vhg.cmp.uea.ac.uk/tech/jas/vhg2021/cwa/allcsa.js"></script></pre>
 +
The method '''CWASA.init();''' should be called on loading the body of the page:
 +
<pre><body onload="CWASA.init();"></pre>
 +
Initial configuration parameters can be specified using a JSON object passed as a parameter to '''CWASA.init''', such
 +
as for example pages using a server or Java applets. To disable ambient animation by default, but use other '''clientcfg.json''' settings:
 +
<pre><body onload="CWASA.init({ambIdle:false,useClientConfig:true});"></pre>
 +
To change the initial camera position and make signing slightly slower:
 +
<pre><body onload="CWASA.init({useClientConfig:true,
 +
    avSettings:{initCamera:[0.00,0.53,2.06,-12.50,18.00,30.00,-1.00,-1.00],initSpeed:-1}});"></pre>
 +
 +
All methods to be used are found in the '''CWASA''' object. Examples of direct calls to CWASA are illustrated in the BSLExamples demo mentioned above,
 +
which also illustrates use of a JSON object for initial settings. The methods supported are:
 +
* '''CWASA.init(cfg)''': Initialise CWASA with optional configuration parameters as a JSON object.
 +
* '''CWASA.playSiGMLText(sigtext, av)''': Play SiGML given as text. The avatar panel index is given by the second parameter, defaulting to zero.
 +
* '''CWASA.playSiGMLURL(sigurl, av)''': Play SiGML at given URL. The avatar panel index is given by the second parameter, defaulting to zero.
 +
* '''CWASA.stopSiGML(av)''': Stop playing SiGML. The avatar panel index is given by the parameter, defaulting to zero.
 +
* '''CWASA.getLogger(logger, loggerlevel)''': Configure and receive a CWASA logger.
 +
* '''CWASA.addHook(typ fun, av)''': Install a hook function to be called on specific events for specific avatars.
 +
* '''CWASA.callHook(typ, msg, av)''': Post an event to be passed to appropriate hook functions.
 +
 +
==== Testing for Initialisation ====
 +
A call to '''CWASA.init''' sets up a promise at '''CWASA.ready''' that will be resolved when all the configuration data has been loaded.
 +
 +
To test when an avatar is loaded and rendered, it is possible to add a hook for the '''avatarready''' event. This will be called for each avatar panel and on switching avatars on a panel.
 +
 +
==== Examples ====
 +
Examples of use of these methods will be found on the '''OneAvClientTest.html''' example web page. The logging and event hook facilities are described under [[Logging and Event Hooks]].
  
 
----
 
----
[[Main Page|Home]] >> [[JASigning]]
+
[[Main Page|Home]] >> [[CWA Signing Avatars|CWASA]]

Latest revision as of 09:46, 31 July 2024

Home >> CWASA


CWASA Development

The JASigning (Java Avatar Signing) software was a reimplementation of earlier work based on C++ and Visual Basic. JASigning uses Java to create freestanding applications and web applets that can be scripted through JavaScript on web pages. SiGML data is converted to motion data for animation using the Animgen software, written in C++. Animation data is rendered using an OpenGL renderer written in Java using the JOGL bindings.

With the advent of HTML5 and WebGL it has become practical to create software for use in web pages that is not dependent on Java. This development has become essential as Java is now deprecated in browsers and unsupported on major browsers such as Chrome and Opera.

Development took place in a number of stages:

  • Introduction of a WebGL renderer in place of OpenGL via Java. SiGML processing continued via a simplified Java applet.
  • SiGML processing delegated to an Animgen server located at UEA using a CGI script.
  • Preprocessing in JavaScript of the HamNoSys variant of SiGML to the Gestural variant.
  • Fully client-side operation using a JavaScript implementation of Animgen.

CWASA Installation

An open installation of CWASA contains a number of index web pages, web pages with embedded signing avatars, and several directories containing resources.

  • avatars contains JARs with avatar definition data.
  • sigml contains example SiGML files.
  • cwa contains scripts used by HTML5 pages and further example web pages.

The use of CORS allows an installation to be used from other servers and even, in some circumstances, from files on a local file system. See JASigning Local Installation.

CWASA (CoffeeScript WebGL ARP Signing Avatars)

The CWASA software is largely written in CoffeeScript which generates JavaScript that is combined into a single script file in the cwa directory. CWASA is configured using settings in JSON objects. Up to four sources of settings are consulted, with earlier settings overriding later ones:

  • Initial settings provided as an optional argument when the CWASA software is initialised. This allows web pages to be self contained.
  • Client settings held in an optional file clientcfg.json at the same level as the webpage. Normally bypassed if Initial settings are given.
  • Installation settings held in a file cwacfg.json in the cwa folder of the installation.
  • Installation-depended default settings applied by the CWASA initialisation code.

Parameters are in three classes:

  • Settings determining which configuration files are consulted.
  • Installation settings providing locations for installation directories.
  • Settings for configuring a GUI for one or more avatar panels.

Full example configuration files are given below. Initial settings are provided using a similar JavaScript JSON object as in appletframe.html in BSLExamples (CWASA Local Installation). Unrecognised settings (such as description) are ignored without comment.

Configuration Consultation Settings

Users can use these settings to change the normal pattern of consulting configuration files:

  • useClientConfig: Controls whether clientcfg.json is consulted. Default true but bypassed if Initial settings are given unless explicitly overridden.
  • useCwaConfig: Controls whether cwacfg.json is consulted. Default true.

Hence useClientConfig should be set to true by pages using Initial settings that also wish to consult a clientcfg.json file.

CWASA Installation Settings

It is unlikely that users will need to change installation settings as these will be picked up from the installation when initialising CWASA. The settings are:

  • jasBase: Base installation directory.
  • jasVersionTag: Parameter used by deprecated Java applet.
  • sigmlBase: Directory for example SiGML files. Resolved relative to jasBase.
  • avJARBase: Directory for JAR files containing avatar definitions. Resolved relative to jasBase.
  • avJSONBase: Directory for JSON files containing avatar definitions. Resolved relative to jasBase.
  • useAvatarJARs: Flag choosing between JAR and JSON representation for avatars. Currently needs to be set true.
  • animgenFPS: Frames per Second of generated animation data. Defaults to 50.
  • animgenServer: Path to CGI script for Animgen server if used.

The default is to specify no Animgen server and client-side JavaScript will implement Animgen. Some example web pages specify a server that will be used instead. The public server is http://vhg.cmp.uea.ac.uk/cgi-bin/animgen/animgenserver.pl. The deprecated Java Applet implementing Animgen can be accessed using a pseudo-server stoca:. Processing will fall back to the client-side implementation if Java is not supported in the chosen browser.

CWASA GUI Settings

A CWASA web page can display several avatars identified as av0, av1, etc. Each avatar has an associated list of possible avatar characters to be displayed. Named avatar lists can be included in the CWASA parameters. By default, avs names the list of standard avatars that can be used freely: anna, marc, and francoise. The list avsfull contains all available avatars, but should only be used for evaluation.

Parameters for the avatars are given by entries in avSettings, an array of JSON objects. The settings for an avatar are:

  • width: Width in pixels of avatar canvas. This is mainly used when a complete GUI is generated automatically.
  • height: Height in pixels of avatar canvas. This is mainly used when a complete GUI is generated automatically.
  • avList: Name of parameter holding avatar list. This will be avs by default.
  • initAv: Name of avatar that is loaded initially. Should normally be already present in the avList.
  • ambIdle: Flag controlling whether ambient motion accompanies an idle avatar.
  • background: By default the canvas will have a transparent background but valid text for a style background in HTML can be provided. Set to null to force a transparent background.
  • initCamera: Nine numbers that define the initial camera position when the avatar is loaded.
  • initSpeed: Initial speed setting. See below.
  • rateSpeed: Rate of change to speed in GUI. See below.

Note that an ambIdle setting may be given at installation level and will be inherited by each panel that does not provide its own setting.

The actual animation speed is given by 2^(currSpeed/rateSpeed) where currSpeed is initially set to initSpeed and may be increased or decreased in the GUI. The rate determines how many steps are needed to change the speed by a factor of 2.

The remaining parameters are mostly needed when a GUI is generated automatically as a full panel:

  • allowFrameSteps: Includes buttons to suspend and resume playing, and to step forward and backwards, a frame at a time.
  • initSiGMLURL: Initial value for URL of SiGML file to display. No field or URL play button is displayed if the value is missing or null.
  • allowSiGMLText: Flag selecting whether a field for entry of SiGML text is displayed. No field or text play button is displayed if the value is false.

CWASA Configuration Examples

Example: cwa/cwacfg.json

Example installation configuration:

{
  "description"     : "========  CWASA installation configuration data : Main release ========",
  "jasBase"         : "http://vhg.cmp.uea.ac.uk/tech/jas/vhg2021/",
  "jasVersionTag"   : "vhg2021",

  "sigmlBase"       : "sigml",
  "avJARBase"       : "avatars",
  "avJSONBase"      : "avjson",
  "useAvatarJARs"   : true,

  "animgenFPS"      : 30,

  "avs" : [
    "anna", "marc", "francoise"
  ],

  "avsfull" : [
    "anna", "marc", "francoise",
    "luna", "siggi"
  ],
 
  "avSettings" : [
    {
      "description":      "Default if client configuration is missing or restricted",
      "width":            384,
      "height":           320,
      "avList":           "avs",
      "initAv":           "anna",
      "initCamera":       [ 0, 0.23, 3.24, 5, 18, 30, -1, -1 ],
      "initSpeed":        0,
      "rateSpeed":        5
      "allowFrameSteps":  true,
      "initSiGMLURL":     "iTakeMug.sigml",
      "allowSiGMLText":   true
    }
  ]
}

Example: cwa/clientcfg.json

Configuration for Clients using client-side Animgen processing:

{
  "description"     : "========  CWASA client configuration data. No Animgen server ========",
  "animgenServer": null,
  "avSettings" : [
    {
      "width":            384,
      "height":           320,
      "avList":           "avsfull",
      "initAv":           "luna",
      "initSiGMLURL":     "scotland-H.sigml"
    },
    {
      "width":            228,
      "height":           208,
      "background":       "Salmon",
      "avList":           "avs",
      "initAv":           "francoise",
      "allowFrameSteps":  false,
      "allowSiGMLText":   false,
      "initSiGMLURL":     "welkom-ngt.sigml"
    }
  ]
}

CWASA GUI Creation

There are four approaches to incorporating the CWASA software on a web page. The installation contains example web pages, built using the different approaches:

  • Complete GUI: WebGLAvTwo.html. A single div is populated with a panel containing an avatar canvas and GUI elements.
  • GUI Panels: CWASA-plus-gui-panel.html. A div for the avatar canvas and a separate div for the GUI.
  • GUI Elements: CWASA-plus-gui-elements.html. A number of divs and spans arranging different sections of the GUI.
  • Bespoke GUI: CWASA-plus-bespoke-gui.html. Individual HTML elements defining an equivalent GUI.

The first example displays two avatars on a page. The first two approaches select elements according to layout parameters in the configuration, while the final approaches choose elements directly. The final three examples have very similar appearance, illustrating the alternative approaches.

A CSS stylesheet controls appearance in all cases. The class attribute is also used by the CWASA script to identify elements of the GUI for attaching handlers and to change enabled state during animation. For a page that might use the Java applet it is necessary to include one instance of:

<div class="SToCA"></div>

This will be ignored if an Animgen server is used or the browser does not support Java.

A div or span that forms part of the CWASA GUI will have a class which identifies the GUI component and the avatar concerned. For example, a complete GUI panel for the first avatar would be specified by:

<div class="CWASAPanel av0"></div>

Complete GUI

  • CWASAPanel: A GUI, CWASAGUI, to the left of an avatar canvas, CWASAAvatar.

GUI Panels

  • CWASAGUI: A combination of GUI elements, some omitted according to the avatar settings in the configuration.
  • CWASAAvatar: A canvas for a WebGL avatar. The canvas fills the size of the enclosing element.

GUI Elements

  • CWASAAvMenu: A menu listing avatars in the expanded avList for the avatar.
  • CWASAAmbBox: A checkbox controlling whether ambient motion is seen for an idle avatar.
  • CWASASpeed: Controls for decreasing, increasing, and resetting the speed of animation.
  • CWASASiGMLURL: Input to hold a SiGML URL. Omitted by CWASAGUI if no initial URL is given.
  • CWASASiGMLText: Text area for entry of SiGML. Omitted by CWASAGUI if SiGML text is not allowed.
  • CWASAPlay: Play and Stop buttons. Only included if corresponding SiGML URL or Text fields are present.
  • CWASAPlayExtra: Suspend and Resume buttons. Only included if Play buttons are present. Omitted by CWASAGUI if frame steps are not allowed.
  • CWASAFrames: Frame single step buttons. Only included if Play buttons are present. Omitted by CWASAGUI if frame steps are not allowed.
  • CWASAProgress: Display of current sign and frame number, sign gloss, and actual FPS.
  • CWASAStatus: Display of status information.

Bespoke GUI

Users are encouraged to use the defined GUI elements as these are not expected to change significantly. Localisation does not require the use of a bespoke GUI. For details on creating a bespoke GUI, if desired, examine the HTML file CWASA-plus-bespoke-gui.html. Essentially, the example shows the HTML generated for GUI elements by CWASA. In order that the CWASA code will link to the GUI HTML elements it is necessary to use the appropriate classes where an avatar code is also given.


Regrettably, some of the low-level GUI elements use classes with names that might clash with those already in use in an existing application.

Some examples illustrate that certain GUI elements, such as buttons, menus, and output fields, can be duplicated. CWASA will copy information to all fields and enable and disable all duplicated buttons.

CWASA Web Pages

To use CWASA, include the following CSS file and JavaScript code, relative to the JASigning installation:

<link rel="stylesheet" href="http://vhg.cmp.uea.ac.uk/tech/jas/vhg2021/cwa/cwasa.css" />
<script type="text/javascript" src="http://vhg.cmp.uea.ac.uk/tech/jas/vhg2021/cwa/allcsa.js"></script>

The method CWASA.init(); should be called on loading the body of the page:

<body onload="CWASA.init();">

Initial configuration parameters can be specified using a JSON object passed as a parameter to CWASA.init, such as for example pages using a server or Java applets. To disable ambient animation by default, but use other clientcfg.json settings:

<body onload="CWASA.init({ambIdle:false,useClientConfig:true});">

To change the initial camera position and make signing slightly slower:

<body onload="CWASA.init({useClientConfig:true,
    avSettings:{initCamera:[0.00,0.53,2.06,-12.50,18.00,30.00,-1.00,-1.00],initSpeed:-1}});">

All methods to be used are found in the CWASA object. Examples of direct calls to CWASA are illustrated in the BSLExamples demo mentioned above, which also illustrates use of a JSON object for initial settings. The methods supported are:

  • CWASA.init(cfg): Initialise CWASA with optional configuration parameters as a JSON object.
  • CWASA.playSiGMLText(sigtext, av): Play SiGML given as text. The avatar panel index is given by the second parameter, defaulting to zero.
  • CWASA.playSiGMLURL(sigurl, av): Play SiGML at given URL. The avatar panel index is given by the second parameter, defaulting to zero.
  • CWASA.stopSiGML(av): Stop playing SiGML. The avatar panel index is given by the parameter, defaulting to zero.
  • CWASA.getLogger(logger, loggerlevel): Configure and receive a CWASA logger.
  • CWASA.addHook(typ fun, av): Install a hook function to be called on specific events for specific avatars.
  • CWASA.callHook(typ, msg, av): Post an event to be passed to appropriate hook functions.

Testing for Initialisation

A call to CWASA.init sets up a promise at CWASA.ready that will be resolved when all the configuration data has been loaded.

To test when an avatar is loaded and rendered, it is possible to add a hook for the avatarready event. This will be called for each avatar panel and on switching avatars on a panel.

Examples

Examples of use of these methods will be found on the OneAvClientTest.html example web page. The logging and event hook facilities are described under Logging and Event Hooks.


Home >> CWASA