MTree (BandM signal & music)

java.lang.Object
- eu.bandm.music.entities.MTree_<MTree>
- - eu.bandm.music.entities.MTree

All Implemented Interfaces:

MetrumIndication
```
public class MTree
extends MTree_<MTree>
```
Each instance has been created from a MTreeSpec by install(MTreeSpec,MTree.Parameters). It is dynamic, since new subnodes and alternatives can be added, e.g. when MSplitter requests new divisions and alternatives.
It maintains additionally the configuration parameters for "essential" proportional brackets and flags/beams.
(In an earlier implementation these were given separately to the split process ("MetricSplitter.Parameters_beam"), but have been moved here, because considered genuin part of a metric configuration.)
Additionally each instance holds ("quasi-transient") constant cache fields for the work of MCover/MSplitter.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`MTree.EssentialBracket` Models a proportional bracket, spanning note heads, which is unavoidable due to the prime factors of the denominators of the duration values.
`static class`	`MTree.Parameters` Parameters for the automated insertion of essential brackets and for the selection of beams, beamlets and flags.
`class`	`MTree.Visitor` Central means for evaluating an MTree.

Field Summary

Fields
Modifier and Type	Field and Description
`protected MTree.EssentialBracket`	`bracketCont` The essential bracket not starting with this node but covering it on its definition level.
`protected @Opt MTree.EssentialBracket`	`bracketStart` The essential bracket starting with this node and required to write its duration.
`protected int`	`flagCount` Number of flags or beams to notate the duration of the node.
`protected @Opt StemEnd`	`genStemEnd` Number of beams/beamlets to the left/right.
`protected int`	`level` The distance from the toplevel node, which is ==0, counting towards neg inf.
`static int`	`NOFLAGSFOUND` Value entered in `flagCount` if this is not applicable = the node not writeable in one single symbol.
`protected MTree.Parameters`	`parameters` Parameters for the automated insertion of essential brackets and for the selection of beams, beamlets and flags.
`protected RationalDuration.DottedBaseDuration`	`symbol_pause` Iff pause event can be written in ONLY ONE symbol, then this is stored here.
`protected RationalDuration.DottedBaseDuration`	`symbol_sound` Iff sounding event can be written in ONLY ONE symbol, then this is stored here.
`protected boolean`	`synthetic` Whether this node comes from an spontantuous division when rendering a given rhythm.
`protected int`	`weight` Metric weight, equal to `level` but for the first sibling, for which is equal to parent's "weight".

Fields inherited from class eu.bandm.music.entities.MTree_
alternative, duration, end, equidist, explicitDuration, implicit, initialized, parent, position, start, subs

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`MTree()` Only called by MSplitter for "Free Sectionings" and MCover for "synthetic alternatives", and here by `x_divide(int,boolean,boolean)`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`collect_genuine_beams()` Generate beam information for all sub-nodes and for alternatives.
`protected void`	`collectBrackets_topLevel()` Service provider which calculates all essential brackets.
`protected void`	`collectBrackets(@Opt MTree.EssentialBracket predecBracket, PrimeFactors parentFactors, boolean secondPass)` Calculation of essential brackets for all nodes below the top node of a MTree, calls itself recursively.
`protected void`	`copyTreeValues(MTree fresh)` Copy the scalar values defined in this class into the argument, additionally to those copied by `MTree_.copyTimeValues(MTree_)`. Context pointers are not copied (.parent,.alternative, .subs.)
`protected void`	`descend_collect(@Opt MTree.EssentialBracket predecBracket, PrimeFactors parentFactors)` After having assigned one or zero EB to all childs, descend into the childs and assign EBs to their childs by calling `collectBrackets(EssentialBracket,PrimeFactors,boolean)` recursively.
`@Opt MTree.EssentialBracket`	`directEB()` Look for the EssentialBracket directly spanning this node.
`(package private) void`	`divide_new_subs(int num)` Adds a number of equidistant sub-trees.
`protected void`	`do_collect_genuine_beams(StemEnd se_parent, List<MTree> subtrees)`
`void`	`get_subs_binary()` Creates a sub-tree with a division factor of two(2), iff no children currently exist.
`static MTree`	`install(MTreeSpec mt, MTree.Parameters params)` Only factory method for a user to create an MTree.
`protected void`	`linkBracket(MTree.EssentialBracket eb, int startPos, int endPos)` Enter the bracket into the fields `bracketStart` and `bracketCont` of all childs of this node, in the given ragen of indexes.
`@Opt MTree.EssentialBracket`	`lowestEB()` Look for the lowest EssentialBracket spannung this node.
`Rational`	`lowestEBProportion()` Deliver the proportion of the lowest EB spanning this node, returned by `lowestEB()`.
`protected void`	`makeBracket(@Opt MTree.EssentialBracket predec, PrimeFactors factors, int startPos, int endPos)` Possibly make a new `MTree.EssentialBracket` covering the given sub-range of child nodes and link it to all those by the fields `bracketStart` and `bracketCont`.
`protected @Opt Rational`	`requiredBracketFactor(int parentEnum, int childCount)` FIXME NOT YET USED! Unify "collectBrackets()", calculate beams and x_divide().
`protected MTree`	`self()` Necessary to avoid "unchecked cast" warning when returning "this" instance in the parameterized superclass `MTree_`.
`protected void`	`smoothen(int[] values)` The smaller value will be doubled until the absolute distance to the larger is minimal.
`protected void`	`x_divide(int num, boolean implicit, boolean synth)` Divides a subnode equidistantly into "num".
`protected int`	`x_smoothen(int lower, int upper)` The smaller value will be doubled until the absolute distance to the larger is minimal.

Methods inherited from class eu.bandm.music.entities.MTree_
addAlternative, calcStartEnd, compoundName, constantRationalMeasureDuration, copyTimeValues, dump, dump, dump, durationName, get_alternative, get_duration, get_end, get_explicitDuration, get_implicit, get_initialized, get_parent, get_position, get_size_binary, get_size, get_start, get_subs, getFollowing, getFollowingSibling, getPrecedingSibling, getTopNode, is_equi_binary, isFollowingSiblingOf, propagateDown_alt, propagateDown, propagateUp, toString

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - parameters
```
protected MTree.Parameters parameters
```
    Parameters for the automated insertion of essential brackets and for the selection of beams, beamlets and flags. Set once by install(MTreeSpec,Parameters).
  - bracketStart
```
@Opt
protected @Opt MTree.EssentialBracket bracketStart
```
    The essential bracket starting with this node and required to write its duration. Is set by collectBrackets_topLevel(), which is called in initialization.
  - bracketCont
```
protected MTree.EssentialBracket bracketCont
```
    The essential bracket not starting with this node but covering it on its definition level. Is set by collectBrackets_topLevel(), which is called in initialization. ATTENTION only used during collecting. FIXME DOKU
  - synthetic
```
protected boolean synthetic
```
    Whether this node comes from an spontantuous division when rendering a given rhythm.
  - symbol_sound
```
@Opt
protected RationalDuration.DottedBaseDuration symbol_sound
```
    Iff sounding event can be written in ONLY ONE symbol, then this is stored here. Filled once by install(MTreeSpec,Parameters).
  - symbol_pause
```
@Opt
protected RationalDuration.DottedBaseDuration symbol_pause
```
    Iff pause event can be written in ONLY ONE symbol, then this is stored here. Filled once by install(MTreeSpec,Parameters).
  - flagCount
```
protected int flagCount
```
    Number of flags or beams to notate the duration of the node. (Only makes sense if notatable in one symbol). Filled once by install(MTreeSpec,Parameters). Only needed as a START VALUE for collect_genuine_beams().
  - NOFLAGSFOUND
```
public static final int NOFLAGSFOUND
```
    Value entered in flagCount if this is not applicable = the node not writeable in one single symbol.
    
    See Also:
    
    Constant Field Values
  - genStemEnd
```
@Opt
protected @Opt StemEnd genStemEnd
```
    Number of beams/beamlets to the left/right. (Only makes sense if notatable in one symbol). Filled once by install(MTreeSpec,Parameters).
  - level
```
protected int level
```
    The distance from the toplevel node, which is ==0, counting towards neg inf.
  - weight
```
protected int weight
```
    Metric weight, equal to level but for the first sibling, for which is equal to parent's "weight".
- Constructor Detail
  - MTree
```
protected MTree()
```
    Only called by MSplitter for "Free Sectionings" and MCover for "synthetic alternatives", and here by x_divide(int,boolean,boolean). FIXME evtl. hierhin verschieben !?!?
- Method Detail
  - install
```
public static MTree install(MTreeSpec mt,
                            MTree.Parameters params)
```
    Only factory method for a user to create an MTree. The MTreeSpec is deep-copied to an MTree, a reference to the parameters is stored in the MTree. Then all duration value specifications are completed, checked and distributed. Then for each sub-node "Essential Brackets" are constructed and memorized, and maybe single symbols for sound and pause separately. (There may be different allowances for prolongation dots.)
  - self
```
protected MTree self()
```
    Necessary to avoid "unchecked cast" warning when returning "this" instance in the parameterized superclass MTree_.
    
    Specified by:
    
    self in class MTree_<MTree>
  - copyTreeValues
```
protected void copyTreeValues(MTree fresh)
```
    Copy the scalar values defined in this class into the argument, additionally to those copied by MTree_.copyTimeValues(MTree_).
    Context pointers are not copied (.parent,.alternative, .subs.)
  - collectBrackets_topLevel
```
protected void collectBrackets_topLevel()
```
    Service provider which calculates all essential brackets. Is called only once from MTree installation only for this as the top-level node.
  - collectBrackets
```
protected void collectBrackets(@Opt
                               @Opt MTree.EssentialBracket predecBracket,
                               PrimeFactors parentFactors,
                               boolean secondPass)
```
    Calculation of essential brackets for all nodes below the top node of a MTree, calls itself recursively.
    Operation: Step through all child nodes of this node: For the longest sequence of equal durations create a EB iff that duration introduces a new prime factor in the denominator, compared to "parentFactors".
    Execute recursively for all child nodes.
    Not supported: automated sectioning of over-complete brackets as from
```
  5/12
  |--------3:2------|
    |\ |\ |\    |\ |\     
    x  x  x     x  x
  
```
    into
```
  5/12
  ,---3:2---, ,--3:2--,
    |\ |\ |\    |\ |\     
    x  x  x     x  x
  
```
    Instead, this can/must currently be done explicitly on the MTreeSpec level, e.g. by replacing "5*1/12" with "3*1/12+2*1/12".
    Not yet supported: renamed brackets:
```
   ,------------- 3:2 ------------,
    |          |         |
    x          x         x
   ,------------- 9:8 ------------,
    |\ |\ |\   |\ |\ |\  |\ |\ |\ 
    x  x  x    x  x  x   x  x  x  
  
```
    Now supported: vanishing brackets. A VB is a bracket of some parent node which will show up only when this node as such is printed, but not when its child nodes are printed, because not all of these share the new denominator factor. (In other words: some child nodes need this factor and sum up with simpler durations of their neighbours to a sum with this factor. Of course this may happen not in very conventional sheet music, but frequently in avantgardistic notation styles, ethnological transcriptions, bird songs. etc.)
    Example:
```
   [1/3-------->  1/3------->]
   
    ,--3:2--,        ,-3:2-,  
     |            |    |\     
    o             x    x      

  may vanish to:

       ,-3:2-,       ,-3:2-,  
    |    |\           |    |\     
    x    x        x    x      


   or
   
   [5/12-------->]
  ,---3:2---,  
    |      |\
   o______x      

  may become

         ,-3:2-,  
    |      |
    x      x      
  
```
    Parameters:
    
    predecBracket - the next higher (relevant, non-vanishing) bracket covering this node.
    
    parentFactors - the odd denominator factors already to apply by all brackets of the higher node levels.
    
    secondPass - indicates that the predecBracket of a first pass has been recognized as "vanishing" (i.e. at least one child node has a simpler duration denominator than the parent), and so this bracket has been marked and a second pass re-started from the beginning, NOT considering this predec bracket (and all vanishing predec brackets).
  - descend_collect
```
protected void descend_collect(@Opt
                               @Opt MTree.EssentialBracket predecBracket,
                               PrimeFactors parentFactors)
```
    After having assigned one or zero EB to all childs, descend into the childs and assign EBs to their childs by calling collectBrackets(EssentialBracket,PrimeFactors,boolean) recursively.
    
    Parameters:
    
    predecBracket - the next higher (relevant, non-vanishing) bracket covering this node.
    
    parentFactors - all prime factors imposed on this node by all brackets atop.
  - makeBracket
```
protected void makeBracket(@Opt
                           @Opt MTree.EssentialBracket predec,
                           PrimeFactors factors,
                           int startPos,
                           int endPos)
```
    Possibly make a new MTree.EssentialBracket covering the given sub-range of child nodes and link it to all those by the fields bracketStart and bracketCont. Is only called by the recursive descent in collectBrackets(EssentialBracket,PrimeFactors,boolean).
    
    Parameters:
    
    predec - the next higher (relevant, non-vanishing) bracket covering this node.
    
    factors - the new factors which shall be introduced by this EB
    
    startPos - the number of the first child node to cover. (The value of -1 returns immediately and means that no bracket is required.)
    
    endPos - the number of the first child which is after the bracket (needs not to exist)
  - linkBracket
```
protected void linkBracket(MTree.EssentialBracket eb,
                           int startPos,
                           int endPos)
```
    Enter the bracket into the fields bracketStart and bracketCont of all childs of this node, in the given ragen of indexes. Currently only used by x_divide(int,boolean,boolean), which creates one new EB explicitly.
    
    Parameters:
    
    eb - the EB
    
    startPos - index of the first child
    
    endPos - index of the first child which is after the bracket (needs not to exist)
  - lowestEB
```
@Opt
public @Opt MTree.EssentialBracket lowestEB()
```
    Look for the lowest EssentialBracket spannung this node. Steps upward through the chain of parent nodes for the first EB.
  - lowestEBProportion
```
public Rational lowestEBProportion()
```
    Deliver the proportion of the lowest EB spanning this node, returned by lowestEB(). If this is ==null, then the proportion is Rational.ONE.
  - directEB
```
@Opt
public @Opt MTree.EssentialBracket directEB()
```
    Look for the EssentialBracket directly spanning this node. (= entered in bracketStart or bracketCont.
  - requiredBracketFactor
```
@Opt
protected @Opt Rational requiredBracketFactor(int parentEnum,
                                                   int childCount)
```
    FIXME NOT YET USED! Unify "collectBrackets()", calculate beams and x_divide().
    Calculates the factor required for a sequence of adjacent child nodes. The odd factor of the denominator of the parent is already realized by some EB on a higher level. Therefore here only the odd factors in "parentEnumerator" and in "childCount" must be considered.
    Eg., no bracket is required required when dividing a node of duration 5/16 by 5 or 15/17 by 3.
```
        odd                           odd              1         newChildNodeCount
 rPf =  ---         rPf = 1    rPf =  ---       rPf = ---       --------------------
        odd                            1              odd      enumOfDurOfParentNode
   
```
  - get_subs_binary
```
public void get_subs_binary()
```
    Creates a sub-tree with a division factor of two(2), iff no children currently exist. This mirrors the default division by two(2) implicitly allowed for every node in CWN. Called only by MCover.doFC_bin(MTree) and MCover.makeSyntheticAlternative(MTree,int).
    
    Throws:
    
    IllegalStateException - if the node is already divided other than equidist by two.
  - divide_new_subs
```
void divide_new_subs(int num)
```
    Adds a number of equidistant sub-trees. ONLY used when synthesizing new subnode divisions by MCover. ASSUME only called with this being a FRESH instance, as a synthetic node, which is required because such a division does not exist.
  - x_divide
```
protected void x_divide(int num,
                        boolean implicit,
                        boolean synth)
```
    Divides a subnode equidistantly into "num". Creates and adds the required subnodes and simulates all things normally done by installing an MTreeSpec (duration propagation, flag adjustment, essential bracket detection).
  - smoothen
```
protected void smoothen(int[] values)
```
    The smaller value will be doubled until the absolute distance to the larger is minimal. If equidistant, the lower variant is returned: 2,3,4 delivers 2; 8,12,16 delivers 8.
    
    Parameters:
    
    values - two different integers. The smaller of both will be replaced by the result of x_smoothen(int,int).
  - x_smoothen
```
protected int x_smoothen(int lower,
                         int upper)
```
    The smaller value will be doubled until the absolute distance to the larger is minimal. If equidistant, the lower variant is returned: 2,3,4 delivers 2; 8,12,16 delivers 8. (Currently only called by requiredBracketFactor(int,int) and x_divide(int,boolean,boolean).)
  - collect_genuine_beams
```
protected void collect_genuine_beams()
```
    Generate beam information for all sub-nodes and for alternatives. Assume the genStemEnd (=the stem end for the node itself) has already been set (for the top-level node by "install()", for all others by recursive call). Only called from install(MTreeSpec,Parameters)] for initial MTree generation, and from x_divide(int,boolean,boolean), whenever later expanding the MTree.
  - do_collect_genuine_beams
```
protected void do_collect_genuine_beams(StemEnd se_parent,
                                        List<MTree> subtrees)
```

Class MTree

Nested Class Summary

Field Summary

Fields inherited from class eu.bandm.music.entities.MTree_

Constructor Summary

Method Summary

Methods inherited from class eu.bandm.music.entities.MTree_

Methods inherited from class java.lang.Object

Field Detail

parameters

bracketStart

bracketCont

synthetic

symbol_sound

symbol_pause

flagCount

NOFLAGSFOUND

genStemEnd

level

weight

Constructor Detail

MTree

Method Detail

install

self

copyTreeValues

collectBrackets_topLevel

collectBrackets

descend_collect

makeBracket

linkBracket

lowestEB

lowestEBProportion

directEB

requiredBracketFactor

get_subs_binary

divide_new_subs

x_divide

smoothen

x_smoothen

collect_genuine_beams

do_collect_genuine_beams