Package 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 Details

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

    • _startpos2barnum

      final SortedMap<Rational,BigDecimal> _startpos2barnum
      Analysis result: All starting points to barnumbers/measure numbers.

    • 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:

  • Constructor Details

    • MeasureCollector

      public MeasureCollector(Translet.Parser<M> metricParser, String openSign_duration, @Opt @Opt 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 Details

    • 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<eu.bandm.tools.util.xml.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.

    • fromRational

      public MeasureCollector<M>.BarnumRelativePosition fromRational(Rational when)
      Translate a a rational number relative to the start of the very first event into a bar number and an offset. According to the parsed measure lenghts and bar numbers.

    • toRational

      public Rational toRational(MeasureCollector<M>.BarnumRelativePosition when)
      Translate a bar number relative position into a rational number relative to the start of the very first event. According to the parsed measure lenghts and bar numbers.