eu.bandm.music.entities

Class MeasureCollector<M extends MetrumIndication>

java.lang.Object

eu.bandm.music.entities.MeasureCollector<M>

public class MeasureCollector<M extends MetrumIndication>
extends Object

Calculates the notational durations and start points of all measures in a given TimeScape.

Usage: This class follows the "Collector" pattern: (1) An instance must be constructed and parametrized; (2) this will deliver a parser which can be applied directly to a parameter track, or built into some more complex parser (e.g. together with Tempo). This parser stores the recognized information in internal maps. (3) Call analyse(MessageReceiver,Iterable,Map,Vox), to store all information in the public Collections supplied in the construction step (1).

Measures are defined according the notion of metrum, since this is ruling the majority of CWN music. The tscore realization of a measure is the segment between two adjacent top level time points TpTop. Each such TpTop carries a number as its identifier, which normally is an integral number, but can be a decimal fraction, see below.
Each measure is identified by the numeric label of the left, i.e. the earlier of its two limiting time points. Esp. in the generated output maps, they are represented this way.

This interpetation requires that all top-level timepoints are labeled with strictly increasing decimal numbers, integer or fractional. This should be checked by the preceding time line parsing process. Beyond this, the concrete numeric values have no meaning. But it is recommended that these numbers have a distance of maximally 1.0, In case of denotating some existing piece of music with tscore, the numbers should be chosen to correspond to the traditional bar numbers.
In this context broken bar numbers become relevant: Historically numbers for bars and measures in printed music can be re-used verbatim, or qualified by appended letters, for repetition structures. The equivalent in tscore is to use broken numbers.

                                 ________     _________
                                |1.      |    | 2. 
          |          |          |          :||       |       |     bar lines 
          |          |          |          :||       |       |     
           103        104        105a          105b   106     107  conventional numbers
           103        104        105           105.5  106     107  tscore numbers
   

or even more fragmented

           o  o   o    o   o  o   o      o    o  o  o o  o  o  o  quarter notes
          |          |          |     :||  ||:  |       |         bar lines
          |          |          |     :||  ||:  |       |     
           103        104        105             106     107      conventional numbers
           103        104        105 105.3 105.7 106     107      tscore numbers
   

The other situation is with up-beats ("Auftakte"), or other incomplete measures, which may be marked by giving them broken numbers as identifiers:

              o   o    o   o  o   o  o  o     quarter notes
       CLEF:         |          |             bar lines
       CLEF:         |          |            
                       1          2           conventional numbers
              0.5      1          2           tscore numbers
   

But there is no necessity to do so, the integrity of broken-ness has no further meaning (as it had in older implementations!)

Metrum, Complete and Incomplete Measures

This algorithm extracts the specification of the valid metrum and of measure duration from one dedicated parameter track of one dedicated voice. (Identified by a parameter track name, given as parameter.) It distributes the values to subsequent measures and stores the result into different maps.
At every position in the score there is one(1) currently valid metrum.

The duration of each measure (ie. each segment between to top-level Tps, as explained above) is identical to the length of this metrum, iff there is no additional explicit duration indication at the beginning of the measure. Then this measure is a complete measure.
Iff there is an additional duration indication, then the measure is an incomplete measure, its duration is the explicitly given duration, and this must be shorter than the duration according to the metrum. Several adjacent incomplete measures must sum up to the duration of one complete measure, except at the very beginning or very end of a PART. (The syntax for metrum indication are plugged into this class.)
The sketches above, demonstrating a sensible usage of broken bar numbers, also show clearly where incomplete measures are required.
Specifications of durations must appear at the beginning of any incomplete measure. Changes of the metrum may only appear at the end of a complete measure, or at the end of a sequence of incomplete measures summing up to the metrum length.
Additionally, a specification of the metrum must stand at the beginning of the very first measure of a PART, even when its incomplete.
All Timepoints which are not top-level Tps must not carry measure or duration indication. This is currently not checked by this algorithm.
Completing an example like those from above:

           0.5       1          2.0   2.3     2.5      3       4   
           3/4[2/4]             [1/4] [1/4]   [1/4]            6/8 
   

Comprehension:
An incomplete measure must carry an additional duration indication, shorter than the current metrum.
An incomplete measure should start or end or start and end at a non-integral measure number.
Metrum indications must only appear at the limit of complete measures, or of incomplete measures summing up to a complete one.
Only exception: the very first time point must carry a Metrum indication, independent of the completeness of the following measure.

Field Summary

Fields

Modifier and Type	Field and Description
(package private) SortedMap<BigDecimal,Rational>	_barnum2duration Analysis result: All barnumbers/measure numbers to the valid duration.
(package private) SortedMap<BigDecimal,Rational>	_barnum2duration_explicit Analysis result: Some barnumbers/measure numbers to explicit duration.
(package private) SortedMap<BigDecimal,M>	_barnum2metric Analysis result: All barnumbers/measure numbers to the valid metric indication.
(package private) SortedMap<BigDecimal,M>	_barnum2metric_explicit Analysis result: Some barnumbers/measure numbers to explicit metric indication.
(package private) SortedMap<BigDecimal,Rational>	_barnum2startpos Analysis result: All barnumbers/measure numbers to their starting time point.
SortedMap<BigDecimal,Rational>	barnum2duration Return the explicitly and the inherited duration indications.
SortedMap<BigDecimal,Rational>	barnum2duration_explicit Return only the explicitly given duration indications.
SortedMap<BigDecimal,M>	barnum2metric Return the explicitly and the inherited metrum indications.
SortedMap<BigDecimal,M>	barnum2metric_explicit Return only the explicitly given metrum indications.
SortedMap<BigDecimal,Rational>	barnum2startpos Return the start positions of all top level time points, measures in notational CWN durations.
(package private) @Opt String	closeSign_duration The string follwing each duration indication.
(package private) Rational	currentLength Evident
static Translet.Parser<Rational>	durationParser Parser for positive (non-null) Rational numbersm used as durations.
(package private) Map<Event,Rational>	durations Intermediate output of parsing.
(package private) String	firstMeasureError Evident
(package private) Map<Event,M>	metra Intermediate output of parsing.
(package private) Translet.Parser<M>	metricParser The parser for the metric specificaion.
(package private) String	openSign_duration The string preceding each duration indication.

Constructor Summary

Constructors

Constructor and Description
MeasureCollector(Translet.Parser<M> metricParser, String openSign_duration, String closeSign_duration) Initial configuration of a Collector.

Method Summary

Modifier and Type	Method and Description
void	addCompleteMeasure(M mt) Append a synthesized measure at the end of all measures.
void	analyse(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg, Iterable<TpTop> topTps, Map<TpTop,BigDecimal> tp2barnum, Vox vox) Is called after parsing, when all primary information is parsed and stored to internal maps, for distributing information, consistency checks and preparing the result collections.
void	dump(PrintStream p) Print all collected information Collections to PrintStream.
Translet.Parser<?>	parser() Delivers the complete parser.

Methods inherited from class java.lang.Object

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

Field Detail

metricParser

final Translet.Parser<M extends MetrumIndication> metricParser

The parser for the metric specificaion. Set once when constructing this.

openSign_duration

final String openSign_duration

The string preceding each duration indication. Set once when constructing this. May not be empty. (The duration indication is always a Rational >0)

closeSign_duration

@Opt
final @Opt String closeSign_duration

The string follwing each duration indication. Set once when constructing this, and may be empty or omitted.

metra

final Map<Event,M extends MetrumIndication> metra

Intermediate output of parsing. Maps events of the metric voice to a metric indication.

durations

final Map<Event,Rational> durations

Intermediate output of parsing. Maps events of the metric voice to an explicit duration.

_barnum2metric_explicit

final SortedMap<BigDecimal,M extends MetrumIndication> _barnum2metric_explicit

Analysis result: Some barnumbers/measure numbers to explicit metric indication.

_barnum2duration_explicit

final SortedMap<BigDecimal,Rational> _barnum2duration_explicit

Analysis result: Some barnumbers/measure numbers to explicit duration.

_barnum2metric

final SortedMap<BigDecimal,M extends MetrumIndication> _barnum2metric

Analysis result: All barnumbers/measure numbers to the valid metric indication.

_barnum2duration

final SortedMap<BigDecimal,Rational> _barnum2duration

Analysis result: All barnumbers/measure numbers to the valid duration.

_barnum2startpos

final SortedMap<BigDecimal,Rational> _barnum2startpos

Analysis result: All barnumbers/measure numbers to their starting time point.

barnum2metric_explicit

public final SortedMap<BigDecimal,M extends MetrumIndication> barnum2metric_explicit

Return only the explicitly given metrum indications.

barnum2duration_explicit

public final SortedMap<BigDecimal,Rational> barnum2duration_explicit

Return only the explicitly given duration indications.

barnum2metric

public final SortedMap<BigDecimal,M extends MetrumIndication> barnum2metric

Return the explicitly and the inherited metrum indications.

barnum2duration

public final SortedMap<BigDecimal,Rational> barnum2duration

Return the explicitly and the inherited duration indications.

barnum2startpos

public final SortedMap<BigDecimal,Rational> barnum2startpos

Return the start positions of all top level time points, measures in notational CWN durations.

currentLength

Rational currentLength

Evident

durationParser

public static final Translet.Parser<Rational> durationParser

Parser for positive (non-null) Rational numbersm used as durations.

firstMeasureError

final String firstMeasureError

Evident

See Also:

Constant Field Values

Constructor Detail

MeasureCollector

public MeasureCollector(Translet.Parser<M> metricParser,
                        String openSign_duration,
                        String closeSign_duration)

Initial configuration of a Collector.

Parameters:

metricParser - the parser of the metric indication. (NB the parser of the duration is fixed to positive rational numbers.)

openSign_duration - the symbol which leads in a duration input

closeSign_duration - the symbol which endin a duration input, maybe null

Method Detail

addCompleteMeasure

public void addCompleteMeasure(M mt)

Append a synthesized measure at the end of all measures. Its top-Tp number is set to the number of currently contained measures. (ATTENTION FIXME THIS IS WRONG, must be "lastnumber+1" !!! )

Parameters:

mt - the metric tree specification of the new measure, mandatory. (only its LENGTH is used here!?!?!) If this value is DIFFERENT then the current last measure, this measure is entered into both "explicit" sets, for duration and meter.

parser

public Translet.Parser<?> parser()

Delivers the complete parser. This must be applied explicitly (in step (2) of the recipie above) to some input parameter track.

analyse

public void analyse(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg,
                    Iterable<TpTop> topTps,
                    Map<TpTop,BigDecimal> tp2barnum,
                    Vox vox)

Is called after parsing, when all primary information is parsed and stored to internal maps, for distributing information, consistency checks and preparing the result collections.
FIXME further output: collect all processed tps on the fly !? optimization !?
GLO OUT _barnum2startpos, _barnum2duration, _barnum2duration_explicit, _barnum2metric, _barnum2metric_explicit !!!

Parameters:

topTps - an Iterable for all top level time points

tp2barnum - input parameter from parsing the tp sequence

vox - for diagnosis only

dump

public void dump(PrintStream p)

Print all collected information Collections to PrintStream.