movements
Class MovementGenerator

java.lang.Object
  movements.MovementGenerator

public class MovementGenerator

extends java.lang.Object

DOCUMENT ME!

Version:

$Revision: 1.2 $

Author:

$author$

Nested Class Summary

private class	MovementGenerator.FigurePlacement Defines where a figure is placed on the dance floor.
private class	MovementGenerator.HandHoldRange Each object of this class represents a period of time over which all the hands in the hand hold are 'in range'.
private class	MovementGenerator.IntermediateHandHold DOCUMENT ME!
class	MovementGenerator.ParticipantData DOCUMENT ME!

Field Summary

private int[]	comfortableHandPositionForwards
private int[]	comfortableHandPositionSideways
private DanceDefinition	danceDefinition The XML tree returned by the XML parser.
private HandMovements[][]	handMovementsByHand
private java.util.Vector[][]	intermediateHandHoldsByHand A two dimensional array of Vectors where each vector contains a list of hand holds.
private java.util.Vector	intermediateHandHoldsForAllPeople A Vector containing a list of all hand holds in the dance.
private int	numberOfTicksInDance
private ParticipantMovements[]	peopleMovements
(package private) int	ticksPerBar The number of time ticks in each bar.
private java.util.Vector	warningMessages The warnings that were generated during the previous call to the buildDanceDataFromXML method.

Constructor Summary

MovementGenerator()

Method Summary

private void	AddHandMovements() Calculates the actual hand movements.
private void	AddHandMovementsStep1() When hands are taken, that means hands are to be taken only if the people taking hands are 'in range'.
private void	AddHandMovementsStep2() When a hand is involved in two different hand holds then there is a transition period of at least half a bar.
DanceData	buildDanceDataFromXML(org.xml.sax.InputSource source, int ticksPerBar) Creates a DanceData object from a dance specification given in XML format.
private PersonMovement[]	calculateMovementsInFigure(FigureDefinition figureDefinition, MovementGenerator.FigurePlacement figurePlacement, MovementGenerator.ParticipantData[] participantsData, int figureStartTick)
private int	Degrees(double radians)
private DanceData	generateMovements(DanceDefinition danceDefinition, int ticksPerBar) DOCUMENT ME!
java.util.Iterator	getWarningsIterator() Get the warnings, if any, that were generated during the previous call to the buildDanceDataFromXML method.
private double	Radians(int degrees) Convert degrees to radians.
private void	StandStill(TransitionGenerator transitionGenerator, int ticks) Make a participant stand still for a while.
private java.lang.String	ticksToString(int ticks) Helper function to format a bar count for messages.
void	Trace()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

comfortableHandPositionForwards

private int[] comfortableHandPositionForwards

comfortableHandPositionSideways

private int[] comfortableHandPositionSideways

danceDefinition

private DanceDefinition danceDefinition

The XML tree returned by the XML parser.

warningMessages

private java.util.Vector warningMessages

The warnings that were generated during the previous call to the buildDanceDataFromXML method. This is a collection of String objects.

intermediateHandHoldsByHand

private java.util.Vector[][] intermediateHandHoldsByHand

A two dimensional array of Vectors where each vector contains a list of hand holds. The indexes into this array are [person index][hand index] where person index is the index of the person in the dance and hand index is 0 = left hand and 1 = right hand.

Each element in the vectors is of type IntermediateHandHold.

intermediateHandHoldsForAllPeople

private java.util.Vector intermediateHandHoldsForAllPeople

A Vector containing a list of all hand holds in the dance. Every hand hold in the dance is represented in this list. This array is useful when one needs to process through all hand holds in a dance in no particular order and processing no hand hold twice. This vector contains all the elements contained in all the vectors in intermediateHandHoldsByHand. However, while a hand hold will occur in multiple vectors in intermediateHandHoldsByHand (in the vector for each hand), each hand hold occurs only once in this list.

Each element in the vector is of type IntermediateHandHold.

peopleMovements

private ParticipantMovements[] peopleMovements

handMovementsByHand

private HandMovements[][] handMovementsByHand

numberOfTicksInDance

private int numberOfTicksInDance

ticksPerBar

int ticksPerBar

The number of time ticks in each bar.

Constructor Detail

MovementGenerator

public MovementGenerator()

Method Detail

Radians

private double Radians(int degrees)

Convert degrees to radians. This is a simple multiplication by pi/180, nothing more. All angles in the parsedtree package are in degrees but all angles in this package are in radians.

Degrees

private int Degrees(double radians)

ticksToString

private java.lang.String ticksToString(int ticks)

Helper function to format a bar count for messages. If one bar then append " bar", otherwise append "bars".

Parameters:

ticks - The number of ticks into the dance or the figure.

Returns:

Text that describes the bar.

buildDanceDataFromXML

public DanceData buildDanceDataFromXML(org.xml.sax.InputSource source,
                                       int ticksPerBar)
                                throws org.xml.sax.SAXException,
                                       java.io.IOException,
                                       AnimationException,
                                       MusicException

Creates a DanceData object from a dance specification given in XML format.

Parameters:

source - The XML input. The XML must contain a dance specification.

ticksPerBar - All times are given using a 'tick'. It is recommended that you use 24 ticks per bar.

Returns:

A DanceData object. This object can provide the position of each person at any point of time, including the direction in which the person is facing. This object can also give the position of each hand at any point of time.

Throws:

org.xml.sax.SAXException - An error occured parsing the XML. Either the XML is not well formed or it did not pass the initial parsing.

java.io.IOException - An error occured reading the input.

AnimationException - An error occured in the XML. This error prevents animation. Errors of this kind tend to be more complex. These errors are generated during the final process of creating the DanceData object from the XML tree.

MusicException - An error occured in the music. The music is contained in an element and must be in abc format. The abc format is a widely used format and there are many country dance tunes available on the Internet in abc format. Because of this, and because the country dance animation project is more concerned with the XML describing the animation, the error messages for errors in the music are very terse and not that helpful.

getWarningsIterator

public java.util.Iterator getWarningsIterator()

Get the warnings, if any, that were generated during the previous call to the buildDanceDataFromXML method.

Returns:

An iterator that iterates over a collection of String objects. Each String object contains the text for a single warning. If there were no warnings then the iterator will iterate over an empty collection. The iterator will remain valid even if a subsequent call to buildDanceDataFromXML is made. The iterator will continue to iterate over the original collection of warnings.

generateMovements

private DanceData generateMovements(DanceDefinition danceDefinition,
                                    int ticksPerBar)
                             throws AnimationException,
                                    MusicException

DOCUMENT ME!

Parameters:

danceDefinition - DOCUMENT ME!

ticksPerBar - DOCUMENT ME!

Returns:

DOCUMENT ME!

Throws:

AnimationException - DOCUMENT ME!

MusicException - DOCUMENT ME!

calculateMovementsInFigure

private PersonMovement[] calculateMovementsInFigure(FigureDefinition figureDefinition,
                                                    MovementGenerator.FigurePlacement figurePlacement,
                                                    MovementGenerator.ParticipantData[] participantsData,
                                                    int figureStartTick)
                                             throws AnimationException

Throws:

AnimationException

AddHandMovementsStep1

private void AddHandMovementsStep1()
                            throws AnimationException

When hands are taken, that means hands are to be taken only if the people taking hands are 'in range'. For example, consider eight bars of rights and lefts (or, for English dancers, a circular hay with hands). The XML author can specify that everyone takes rights hands with partner and left hands with neighbor for the entire eight bars. This does not mean the hands are holding throughout the entire eight bars. It means hands are taken only when the people concerned are in a position to take hands. This function determines the periods in which people are in a position to take hands. The list of hand hold periods is converted to a list of actual hand holds. In the above example of rights and lefts, the number of actual hand holds is double the number of hand hold periods. While the hand hold ranges are most important for hand holds outside units, the ranges are also calculated for hand holds within units. Normally within a unit people all stay in the same position relative to one another so would not be moving in and out of range. However, people may be transitioning in and out of the unit during the period of existence of the unit. We need to know the period over which hands are within range. A good example is six hands around. It is unlikely hands will be in range at the start of the bar at which the six hands around commences.

Throws:

AnimationException - DOCUMENT ME!

AddHandMovementsStep2

private void AddHandMovementsStep2()
                            throws AnimationException

When a hand is involved in two different hand holds then there is a transition period of at least half a bar. (This does not apply to gaps in ranges within the same hand hold). This function calculates adjusted start and end times for hand holds that ensure this transition time. This must be calculated ahead of step 3 because if a hand hold time is adjusted, it must be adjusted for all hands in the hand hold. Hand holds within units take priority over hand holds outside units. What is meant by that is that if the time between a hand taking part in a hand hold in a unit and a hand hold outside a unit is less than half a bar then the hand hold outside the unit is shorten to ensure a gap of half a bar. If both hand holds are inside a unit or both hand holds are outside a unit then both hand holds are shortened equally. If two hand holds are within half a bar from each other then we look at the ranges within the hand holds, and, if necessary, overlap equally into the last range of the prior hand hold and the first range of the following hand hold. If a hand hold starts within half a bar of the start of the dance (or ends within half a bar of the end of the dance) then the first half a bar of the dance (or the last half a bar of the dance) is the hand transition period.

Throws:

AnimationException - DOCUMENT ME!

AddHandMovements

private void AddHandMovements()
                       throws AnimationException

Calculates the actual hand movements.

A list of hand holds was built when calculating the movements for each person. However a number of steps must be taken to get the actual hand movements from the list of hand holds. We must determine the ranges during which the hands are in fact able to take hands, we must calculate the transitions of the hands into and out of the hand holds, and we must calculate the positions of the hand holds.

Throws:

AnimationException - At this time this exception is never thrown. Amazingly enough, no invalid hand hold details in the specification can make it to this function. It may be that two people are never close enough for a hand hold to take place but that is not an error, it simply results in the hands never being taken.

Trace

public void Trace()

StandStill

private void StandStill(TransitionGenerator transitionGenerator,
                        int ticks)
                 throws PositionRequiredButNoPriorMovementException,
                        PositionRequiredButImmediatelyAfterTransitionException

Make a participant stand still for a while. This function is called when time gaps are found in a participant's movements. The participant stands still at the position at which the previous movement ended.

Parameters:

transitionGenerator - DOCUMENT ME!

ticks - DOCUMENT ME!

Throws:

PositionRequiredButNoPriorMovementException - DOCUMENT ME!

PositionRequiredButImmediatelyAfterTransitionException - DOCUMENT ME!