Dance Animations Reference

This application lets you design and play dance animations to help illustrate the movements within the dances.

The application is implemented as a Web page. It uses Scalable Vector Graphics (SVG) to draw the dancers and JavaScript to provide the design interactions and animation. It was originally written by Keith Wood in 2010 and is featured on the Dance Kaleidoscope Web site.

To run the application locally you need to run a local Web server to get around the browser's security settings. I use the HTTP server built into Node/NPM.

You'll need to install Node.js and NPM if you don't already have it. See https://docs.npmjs.com/downloading-and-installing-node-js-and-npm. Then you can install NPX - https://www.npmjs.com/package/npx. And finally open a command terminal, navigate to the folder containing the animation files and run the server: npx http-server. This will respond with the IP address and port to use in the browser, e.g. http://127.0.0.1:8080/dance.html.

Animation Player

Animation area The animation player reads in the list of available dances from the dances.xml file in the same directory as the Web page. The format of this file is shown below. Each line lists one dance, indicating its definition file and its name. Include categories for the dance as a space-separated list in the type attribute. An underscore (_) in these values is replaced by a space when displayed on the page. Select a category from the drop-down list on the page to filter the list of dances by that type.

<?xml version="1.0" encoding="UTF-8"?>
<dances>
	<dance def="AlbertsQuadrille.xml" type="Colonial Square_set">Alberts Quadrille</dance>
	<dance def="AustralianLadies.xml" type="Scottish 4_couple Longways">Australian Ladies</dance>
	...
</dances>

Once selected, the dance is loaded, its information is displayed at the top of the page, and the initial position is shown in the animation area. Gents are shown in blue and ladies are shown in pink. You can then use the elements at the bottom of the page to control the animation.

Animation controls

Position
This drop-down shows the current position (bar) within the dance and lets you change to another position.
Prev
Move to the previous position within the dance.
Next
Move to the next position within the dance.
Step
Animate the dancers to the next position within the dance.
Play
Continually animate the dancers through the dance from the current position.
With music
Check this box to play the music synchronised with the animation. If no music is defined for the dance the caption reads 'no music'. While the music is loading the caption reads 'loading music'. Hover over this control to see the name of the music.
Call sheet
Display the full text description of all the dance steps, along with the bar count.
Design/Display
Switch modes between displaying and designing the dance. In design mode several tabs appear beneath these controls and a dancer panel appears to the right of the animation area. These are described further below.

Animation Designer Top

Designer area The designer consists of the dancer and coordinates panels to the right of the animation area and several tabs at the bottom of the page. Together these allow you to modify all aspects of the dance and produce a new definition for it. Note that the resulting definition must be manually copied to a separate file since JavaScript cannot access the local file system.

The active dancer is shown highlighted in green. The large triangle represents their previous location and orientation, while the small triangle represents their midpoint location and orientation. If there is no midpoint specified, the small triangle overlays the large one.

Dancer Panel Top

Dancer panel The dancer panel shows the location and orientation details for a single dancer. Select a dancer by clicking on them in the animation panel - that dancer turns green and their label shows in the top-left of the panel. For each position within the dance, each dancer has an endpoint and an optional midpoint. Select the midpoint by clicking on the midpoint arrow in the animation panel or by selecting the Midpoint radio button in this panel.

Midpoint/Endpoint
Switch between the midpoint and endpoint for the current dancer. When selecting a new dancer it defaults back to the endpoint.
X/Y
Set the x- and y-coordinates of the dancer's midpoint/endpoint. The centre of the animation area is 0,0 with positive x-values moving to the right and positive y-values moving down.
Clear
This button only appears when midpoint is selected and clears the midpoint by synchronising it with the endpoint.
Nudge
Click the arrows to move the dancer in that direction by the amount specified in the input field. I've found the default value of 25 useful as the dancer icons are 100 wide.
Angle
Set the angle that the dancer faces at the midpoint/endpoint. This is measured in degrees with 0 facing directly down, 90 facing to the left, 180 facing up, and 270 facing to the right.
Clockwise
Check the box to have the dancer turn clockwise from their previous position into the new position, or clear it to turn anti-clockwise.
Turn
Click the arrows to orient the dancer in that direction.
All selected positions
Check this box to apply changes to the same dancer in all positions selected on the Positions Tab. This checkbox is only enabled when the current position is one of those selected. Changes only apply to the current position if this box is disabled. Be careful when checking this box as it can make many changes that may be hard to undo.
Replicate
Check this box to have positions automatically replicated to other dancers. Use the Config button to configure how that replication is done.
Move
Click this button to animate just the current dancer from their previous position.

Replicate Dancers Dialog Top

Replicate dancers dialog The Replicate Dancers dialog lets you configure how replication is applied. It should only be used during the first repetition of the dance as it assumes couples are arranged in numeric order.

Replication type
Select the type of replication.
Longways set
Dancers are replicated along the line, i.e. vertically on screen. Spare dancers at the end are ignored.
Square set
Dancers are replicated across or around a square set.
Circle
Dancers are replicated around the circle.
Dancers offset
Enter the number of dancers between two replicated positions. For example, in a duple-minor longways set, an offset of 4 would be used since there are four dancers in each minor set. In a square set, use 4 to replicate opposites or 2 to replicate all couples. In a circle, use 4 to replicate every second couple, or 2 to replicate all couples.
Distance
Enter the distance by which the replicated dancers are moved in the y-direction (vertically). In the duple-minor longways set this is the distance from the start of one set to the start of the next, typically 250 pixels. This setting only applies to longways sets.

Coordinates Panel Top

Coordinates panel The coordinates panel allows you to calculate the coordinates of a location given its angle and distance from the centre. This is very useful for dances that are danced in a circle.

Angle/Dist
Enter the angle (from 0 facing down, increasing clockwise) and distance of the location from the centre. You may enter a second angle and distance that will be offset from the first one.
Calculate
Click this button to calculate the coordinates from the given angle(s) and distance(s).
Coordinates
The resulting coordinates. In this example, moving down 100 and then up and left 50 you reach the point -35, 65.

Dance Tab Top

Dance tab The Dance tab shows basic information about the dance, and allows a new dance to be started.

New dance
Click this button to start a new dance. The resulting dialog is described below.
Name
Enter the name of this dance.
Formation
Enter the starting formation for this dance. For example, 'Duple minor longways set' or 'Four couples in a square set'.
Music
Enter the name and/or length and style of music for this dance.
Source
Enter the author's name and/or reference a book or Web site where the dance was described.
Notes
Enter any additional information about the dance, it's music, or movements.
Synch music
Enter the name of the MP4 file that contains the music for this dance. It must reside in the music directory beneath the one containing this page.
Period/Delay
Enter the length of each bar (in milliseconds) and the delay (in milliseconds) at the start of the music before beginning the animation.
Dancers
This list shows all the dancers depicted in the dance and lets you set their label and whether they are Gents or Ladies.

Create a New Dance Dialog Top

New dance dialog The Create a New Dance dialog captures basic information about a new dance. When OK is clicked any existing dance definition is deleted.

Name
Enter the name of the new dance.
No. of dancers
Enter the number of dancers required for this dance. For a longways set up to six couples fit within the animation area.
Formation
Enter the starting formation for this dance.
No. of positions
Enter the initial number of positions. Each position represents one bar of music. Generally it is best to start with only the starting position (0) and add new positions incrementally.

Positions Tab Top

Positions tab The Positions tab shows all of the positions in the dance and lets you manipulate them. Move to a position by clicking on it in this list, or by selecting it from the Position drop-down.

Action: Add
Choose this action to add new positions to the dance. Enter the number of new positions and the current position to place them after. That current position is duplicated (removing any midpoint information) for the new positions.
Action: Delete
Select the positions to be deleted by clicking the checkboxes next to them in the list. You can select a continuous range by clicking on the first one and then holding down the Shift key when clicking on the last. Deletion must be confirmed before it is actioned.
Action: Copy/Move
Select the positions to be copied/moved by clicking the checkboxes next to them in the list. You can select a continuous range by clicking on the first one and then holding down the Shift key when clicking on the last. Then select the current position after which the copies are placed. Select any changes to the dancers positions during the copy/move from the list provided. Copying leaves the original positions as they were, while moving deletes the original positions.
Transpose
Swap dancers' positions around during the copy/move process.
Progress linearly
Progress dancers up or down the floor during the copy/move process.
Progress 3 in 4
Progress dancers as in a Scottish set during the copy/move process.
Progress Becket
Progress dancers around a Becket set during the copy/move process.
Flip
Flip dancers horizontally or vertically during the copy/move process.
Rotate
Rotate all the dancers around the centre point during the copy/move process.
Action: Insert
Insert a file of basic moves into the dance. Select the moves from the drop-down list and the position after which they are added. The list of moves is loaded from the dancesMoves.xml file, which references movement files that are cut-down dance files.
Call
Enter the description of the dance movements for this section of the dance. The call applies to the current position and those following it until a new call is entered.

Transpose Dancers Dialog Top

Transpose dialog The Transpose Dancers dialog allows you to map dancers in one or more positions being copied/moved onto other dancers in the new positions. For each dancer just select which dancer they should become. Note that all dancers must appear in the final mapping - duplicates are not allowed.

This can be very useful in a progressive set dance. Once you have animated a single pass through the dance, you can copy the entire set of positions and change who is dancing in which location. For example, if displaying a four couple set and the progression ends with couple 1 moving to the bottom, then the transpose dialog would look like the image shown.

Linear Progression Dialog Top

Linear progression dialog The Linear Progression dialog lets you move dancers up and down the floor during a copy/move to repeat the selected movements at their new positions. Specify the number of dancers per row and the distance that they have moved up/down the floor. A previously idle couple at the end of a longways set will be brought into the dance and a couple that has just reached the top will now remain idle.

3 in 4 Progression Dialog Top

3 in 4 progression dialog The 3 in 4 Progression dialog allows you to repeat a set of steps in a standard Scottish triple-minor dance during a copy/move. Specify the distance that the first couple has moved down the floor. They will then dance with the 3rd and 4th couples, while the 2nd couple is idle at the top of the set.

Becket Progression Dialog Top

Becket progression dialog The Becket Progression dialog lets you move dancers around a set that is in Becket formation during a copy/move. Specify the distance progressed and the direction of progression - clockwise (normal) or anticlockwise (reverse).

Flip Dancers Dialog Top

Flip dialog The Flip Dancers dialog allows you to mirror dance positions, either horizontally or vertically, during a copy/move. Select which direction to use.

Rotate Dancers Dialog Top

Rotate dancers dialog The Rotate Dancers dialog lets you rotate the entire set around its centre point during a copy/move. This is useful when a square set is lead by each couple in turn, or in a circle dance where couples lead in turn. (You may need to follow the rotation with a copy/transpose combination to swap the new couples into the lead.) Specify the angle of rotation desired, being in degrees clockwise around the set.

Output Tab Top

Output tab The Output tab shows the definition of the dance animation as XML. This text is regenerated whenever you open this tab. Since JavaScript doesn't have access to the native file system, you must copy the definition into a separate file and save it manually.

  1. Open the Output tab.
  2. Click in the output text area.
  3. Press Ctrl-A to select the entire contents, then Ctrl-C to copy it.
  4. Open your favourite text editor and start a new file.
  5. Press Ctrl-V to paste the dance definition.
  6. Save the file as DanceName.xml.

Once you have saved the dance definition, don't forget to update the dances.xml file to include a link to that new file.

Config Tab Top

Config tab The Config tab lets you set some configuration options for the application.

Show grid
Check this box to show a grid on the animation area, or clear it to hide the grid.
Period (ms)
Set the time interval (milliseconds) for animating one step of the dance.
Floor size
Set the size of the dance floor (animation area). This value is the number of pixels (height and width) to be shown. The actual animation area doesn't resize, but its contents do. Thus a larger number makes the dancers smaller. The default of 800 is suitable for most dances.

Tips and Tricks Top

Contact

For questions or problems contact Keith Wood (wood.keith{at}optusnet.com.au).