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

- 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
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
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
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
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
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
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
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
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
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
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
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
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
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
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.
- Open the Output tab.
- Click in the output text area.
- Press Ctrl-A to select the entire contents, then Ctrl-C to copy it.
- Open your favourite text editor and start a new file.
- Press Ctrl-V to paste the dance definition.
- 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
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
- Use a basic nudge factor of 25 as this fits
well with the dancer icon size (100).
- Animate in small chunks, adding
two or four positions at a time.
- Use the replication abilities to animate the other dancers.
- For progressive longways sets, show four or five couples so that the
progression can be seen.
- Generate the dance output and save it on a regular
basis (every eight bars perhaps).
Contact
For questions or problems contact Keith Wood (wood.keith{at}optusnet.com.au).