Configuring CWASA for HTML5 web pages

From Virtual Humans
Revision as of 17:12, 7 February 2017 by John.Glauert (talk | contribs) (Starting on GUI creation.)
Jump to navigation Jump to search

Home >> JASigning

JASigning 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.

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:

  • Introduction of a WebGL renderer in place of OpenGL via Java. SiGML processing continues via a simplified Java applet.
  • 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.
  • Fully client-side operation using a JavaScript implementation of Animgen.

All but the final stage has been completed (2017-02).

JASigning Installation

An installation of JASigning 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.
  • 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 Web Applet Signing Avatar)

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:

  • 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.
  • Installation settings held in a file cwacfg.json in the cwa folder in the installation.
  • Installation-depended default settings applied by the initialisation script.

Parameters are in two classes:

  • 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. Unrecognised settings (such as description) are ignored without comment.

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 no Animgen server is specified, the deprecated Java applets will be used. The default is to use a server, but a setting of null for animgenServer will force use of applets.

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.
  • 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.

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

Default installation configuration:

  "description"     : "========  CWASA installation configuration data  ========",
  "jasBase"         : "",
  "jasVersionTag"   : "vhg2017",
  "sigmlBase"       : "sigml",
  "avJARBase"       : "avatars",
  "avJSONBase"      : "avjson",
  "useAvatarJARs"   : true,
  "animgenFPS"      : 50,
  "animgenServer"   : "",
  "avs" : [
    "anna", "marc", "francoise"
  "avsfull" : [
    "beatrice", "candy", "darshan", "francoise", "genie", "luna",
    "marc", "max", "monkey", "otis", "robotboy", "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 ],
      "allowFrameSteps":  true,
      "initSiGMLURL":     "iTakeMug.sigml",
      "allowSiGMLText":   true

Example: cwa/clientcfg.json

Configuration for Clients using the (deprecated) Java applet:

  "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 adding the CWASA software on a 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.
  • GUI Elements: CWASA-plus-bespoke-gui.html. Individual HTML elements defining the GUI.

The final three have very similar appearance, illustrating the alternative approaches. The first two include elements according to layout parameters in the configuration, while the final approaches choose elements directly.

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.

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>

Home >> JASigning