Juggling Markup Language (JML) description

Juggling Markup Language (JML) is the primary juggling pattern description language used by the Juggling Lab animation program. This document describes JML and the pattern model it enables.

JML is a detailed juggling notation

JML is quite detailed compared with other popular juggling notations such as siteswap notation, causal diagrams, or Multi-Hand Notation. This reflects the primary design goals of Juggling Lab, which are to:

• Develop an internal pattern model (JML) with sufficient detail to encompass all of the "common" juggling notations
• Use an architecture of notation components to animate common juggling notations via conversion to JML
• Animate patterns in a physically-realistic manner, with correct timing and trajectory of throws and hands

As JML is a detailed description language, it is primarily intended to be read and written by machine. Users will likely create JML using a notation component as described above, and edit JML using graphical tools (for example, the visual editor within Juggling Lab).

JML is a type of XML

As you might have guessed from the name, JML is based on Extensible Markup Language (XML). This choice was made because:

• XML allows us to define our own juggling-specific tags using a JML Document Type Definition (DTD)
• Many free parsers to read and validate XML are available in Java; in fact this functionality is included in the standard Java 1.4 libraries
• The syntax provided by XML is sufficient for our purpose

JML examples

There are two basic kinds of JML documents: Patterns and pattern lists. The pattern type describes a single juggling pattern, while the pattern list type describes multiple patterns in a single document.

Example 1 – Pattern type

Below is an example of the pattern type of JML document, in this case Burke's Barrage with three balls. Here the JML is simply describing the elements required to construct a spacetime diagram: A bunch of setup information, followed by at least one <event> tag to do the real work. The individual tags are described in a section below.

<jml>
   <pattern>
      <title>Burke's Barrage</title>
      <prop type="ball"/>
      <setup jugglers="1" paths="3" props="1,1,1"/>
      <symmetry type="delay" pperm="(1)(2)(3)" delay="1.3714"/>
      <symmetry type="switchdelay" jperm="(1,1*)" pperm="(1,2)(3)"/>

      <event x="1.2854" y="11.6921" z="0" t="0.0919" hand="1:left">
         <throw path="1" type="toss"/>
      </event>
      <event x="-0.0837" y="77.4015" z="0" t="0.1505" hand="1:right">
         <holding path="2"/>
      </event>
      <event x="-18.5196" y="18.3529" z="0" t="0.2143" hand="1:left">
         <catch path="3"/>
      </event>
      <event x="33.9434" y="51.0847" z="0" t="0.3763" hand="1:right">
         <holding path="2"/>
      </event>
      <event x="-20" y="0" z="0" t="0.4027" hand="1:left">
         <throw path="3" type="toss"/>
      </event>
      <event x="16.9726" y="44.0451" z="0" t="0.5586" hand="1:left">
         <catch path="1"/>
      </event>
   </pattern>
</jml>

Example 2 – Pattern list type

The JML pattern list document type is simpler than the pattern type; see the example below. Each line in the list requires four items to define it:

1. "display" attribute. This defines the text to represent the pattern in the visual pattern list displayed by Juggling Lab.
2. "animprefs" attribute (optional). Settings for the animator, in the same format used for the Animated GIF web service.
3. "notation" attribute (optional). Name of a notation component within Juggling Lab ("siteswap" and "jml" are the most common examples).
4. "pattern" attribute (optional). This text is sent to the notation component for conversion to JML, and then animated.

<jml>
   <patternlist>
      <title>Siteswap Patterns</title>

      <line display="3 cascade" animprefs="stereo=true" notation="siteswap"
         pattern="pattern=3;dratio=0.5;tps=3.572;hands={(32.5)(10)}"/>
      <line display="42 two in one hand" notation="siteswap"
         pattern="pattern=42;dratio=0.5;tps=4.331;hands={(32.5)(10)}"/>
      <line display="423" notation="siteswap"
         pattern="pattern=423;dratio=0.5;tps=4.331;hands={(20)(20)}"/>
      <line display="441" notation="siteswap"
         pattern="pattern=441;tps=5.371;hands={(32.5)(10)}"/>
      <line display="531" notation="siteswap"
         pattern="pattern=531;tps=4.98;hands={(32.5)(10)}"/>
   </patternlist>
</jml>