Merge pull request #15 from holomorfo:develop

Add documentation for Tonal Universe, update readme

HelpSource/Classes/TonalUniverse.schelp

@@ -1,10 +1,10 @@
 TITLE:: TonalUniverse
 summary:: Set of tonalities and relations between them
-categories:: Harmony
+categories:: Harmony, Chords, Tonality
 
 
 DESCRIPTION::
-Defines a TonalUniverse that consists in an set of Tonalities, functions and relations among them. It can be used to analyze a chord relation to any tonality
+Defines a TonalUniverse that consists in an set of Tonalities, functions and relations among them. It can be used to analyze a chord relation to any major and minor tonality.
 
 Part of link::Guides/superharmony::, a library with utilities for tonal analysis of chords.
 
@@ -24,7 +24,7 @@ subsection:: Accessing
 
 
 METHOD:: getHarmonyList
-From a string of roman numeral functions, returns a proposal of chords with those tonal functions.
+Parses a string with tonality and harmonies information in roman notation and, returns a list harmonies/chords with those tonal functions.
 code::
 (
 u=TonalUniverse();
@@ -41,12 +41,91 @@ C,m: V7/V V7 I
 ::
 
 ARGUMENT::
-String with current tonality and harmonies in roman numerals separeted by space.
+String with current tonality and harmonies in roman numerals separeted by space. Each line represents a tonality, the base and type are defined at the begining. After the colon the Roman numbers are added separated by space, it can have seventh or secondary functions.
+code::
+"BASE_NOTE,TYPE_SCALE: ROMAN_NUMBER"
+::
+
+RETURNS::
+List of link::Classes/Harmony:: with those tonal functions.
+
+
+METHOD:: degreeSimple
+Returns the roman degree of the input Harmony with respect to the passed tonality
+code::
+u=TonalUniverse();
+c = Tonality(0,"M")
+u.degreeSimple(Harmony([0,4,7]), c) // 1
+u.degreeSimple(Harmony([9,12,16]), c) // 6
+u.degreeSimple(Harmony.create(5,"M"), c) // 4
+::
+
+ARGUMENT::
+link::Classes/Harmony:: to check.
+
+ARGUMENT::
+link::Classes/Tonality:: Tonality as reference.
+
+RETURNS::
+Integer value with degree of note (1-7) if harmony is part of the Tonality, 0 if its not part.
+
+
+METHOD:: degreeSimpleCurrent
+Returns the roman degree of the input Harmony with respect to current selected tonality in the tonality universe.
+code::
+u=TonalUniverse()
+u.setCurrentScale(9,"M");
+
+u.degreeSimpleCurrent(Harmony([0,4,7])) // 0
+u.degreeSimpleCurrent(Harmony([9,13,16])) // 1
+u.degreeSimpleCurrent(Harmony.create(1,"m")) // 3
+::
+
+ARGUMENT::
+link::Classes/Harmony:: to check.
 
 RETURNS::
-List of Harmonies with those tonal functions.
+Integer value with degree of note (1-7) if harmony is part of the Tonality, 0 if its not part.
 
 
+METHOD:: degreeSecondary
+Finds the degrees to which the input harmony has a secondary function in the passed tonality, for example a secondary dominant or any other combination like V/II  III/VI, etc.
+code::
+u=TonalUniverse();
+c = Tonality(0,"M")
+u.degreeSecondary(Harmony([0,4,7]), c).print // scale 1 M degree: 1 label-
+u.degreeSecondary(Harmony([9,12,16]), c).print // scale 1 M degree: 6 label
+u.degreeSecondary(Harmony.create(2,"D7"), c).print // scale 5 M degree: 5 label
+::
+
+ARGUMENT::
+link::Classes/Harmony:: to check.
+
+ARGUMENT::
+link::Classes/Tonality:: Tonality as reference.
+
+RETURNS::
+link::Classes/TonalCoordinate:: with the information for the secondary function of the harmony with respect to the tonality.
+
+
+
+
+METHOD:: getVectorPercentages
+Finds the percentage, value between 0 and 1 of the notes that belong to each tonality 12 mayor and 12 minor.
+code::
+u=TonalUniverse();
+c = Tonality(0,"M")
+u.getVectorPercentages([0,4,7])
+// -> [ 1.0, 0.33333333333333, 0.66666666666667, 0.66666666666667, 0.33333333333333, 1.0, 0.0, 1.0, 0.66666666666667, 0.33333333333333, 0.66666666666667, 0.33333333333333, 0.66666666666667, 0.66666666666667, 0.66666666666667, 0.0, 1.0, 1.0, 0.0, 0.66666666666667, 0.66666666666667, 0.66666666666667, 0.33333333333333, 0.66666666666667 ]
+
+::
+
+ARGUMENT::
+List of notes, interger values
+
+
+RETURNS::
+Array of 24 values with percentage of notes that belong to each tonality, first 12 values are 12 mayor tonalities, next 12 values are the 12 minor tonalities starting with C.
 
 
 section:: Authors

HelpSource/Guides/superharmony.schelp

@@ -2,17 +2,104 @@ title:: Superharmony
 summary:: Harmony universe utilities
 categories:: Libraries>superharmony
 
-Superharmony is a diverse library of utilities for exploring tonality.
+Superharmony is a library of utilities for exploring tonality. It containes classes for defining a link::Classes/Harmony::, link::Classes/Tonality::, link::Classes/TonalUniverse:: as a set of notes and functions between them.
 
 section:: Components
 
 subsection:: Harmony
 
+You can create and manipulate harmonies as a set of notes and functions. For example:
+
+code::
+a = Harmony.new([0,4,7])
+b = Harmony([0,4,7])
+// C minor chord [0,3,7,12]
+a = Harmony.create(0,"m")
+
+// A major chord [9,13,16,21]
+b = Harmony.create(9,"M")
+
+a= Harmony([0,4,7,11]) // CM7
+a.print
+// Fundamental: C M7  7
+// Notes: [ 0, 4, 7, 11 ]
+// Simplified Notes[ 0, 4, 7, 11 ]
+// Interval types[ 1, 3, 5, 7 ]
+::
+
+
 subsection:: Tonality
 
+We can create a tonality object that will give information about harmonies in it and their tonal functions. For example:
+
+code::
+a = Tonality.new(0,"M")
+b = Tonality(0,"m")
+
+Tonality.degreeRoman2Number("I") // 0
+Tonality.degreeRoman2Number("iii") // 2
+Tonality.degreeRoman2Number("VII") // 6
+
+
+// Get Closest chord
+a= Harmony([0,4,7,12])
+b= Harmony.create(9,"D7")
+b.print
+
+c=Tonality.getClosestChord(a,b)
+c.print
+// [9,13,16,19]
+
+// Get notes percentages that belong to a tonality.
+
+a = Tonality(0,"M") // [0,2,4,5,7,9,11]
+a.notesPercentage([0,2,4]) // 1.0
+a.notesPercentage([1,3,6]) // 0.0
+a.notesPercentage([4,6,7]) // 0.666...
+a.notesPercentage([0,1]) // 0.5
+
+// Get Harmony from degree
+a = Tonality(0,"M") // [0,2,4,5,7,9,11]
+h = a.getHarmonyfromDegree("I") // Harmony
+h.printSimple // CM
+a.getHarmonyfromDegree("i").printSimple // CM since its case insensitive
+a.getHarmonyfromDegree("II").printSimple // Dm
+a.getHarmonyfromDegree("III").printSimple // Em
+::
+
+
+
 subsection:: TonalUniverse
 
+With tonal universe you can get information about what chord belongs to what tonality and create sequences of chords from a string of roman degree numbers:
+
+In this string, each line represents a tonality and FUNDAMENTAL,MAJOR/MINOR, separeted by a colon. After this a sequence of roman numerals are added, and you can add secondary functions like the fifht degree of the sixt V7/VI. When passed to the "getHarmonyList" function, this is parsed and we return an array of chords that we can pass a view bean
+
+code::
+(
+u=TonalUniverse();
+~str=
+"C,m:  I V7/VI VI V VI II II7 IV VII7 I
+E,m: V7 I IV V7/V I
+C,m: V7/V V7 I
+";
+// This function takes a while and logs the progress in the console.
+~chords=u.getHarmonyList(~str);
+~arrayNotes=~chords.collect({arg ar; ar.notesHarmony[0..3]});
+)
+// -> [ [ 0, 3, 7, 12 ], [ -2, 3, 7, 13 ], [ -4, 3, 8, 12 ], [ -5, 2, 7, 11 ], [ -4, 3, 8, 12 ], [ -4, 5, 8, 14 ], [ -7, 2, 8, 12 ], [ -7, 0, 8, 12 ], [ -7, -1, 8, 14 ], [ -9, 0, 7, 15 ], [ -9, -1, 9, 18 ], [ -8, -1, 7, 19 ], [ -8, 0, 9, 21 ], [ -8, 1, 6, 22 ], [ -8, -1, 7, 23 ], [ -10, -3, 6, 24 ], [ -10, -5, 5, 23 ], [ -9, -5, 3, 24 ] ]
+(
+Pbind(
+	\note, Pseq(~arrayNotes.flat,1),
+	\dur, 0.2
+).play
+)
+~arrayNotes.flat.plot("Sequence", discrete:true)
+::
+
+image::graph.png::
 
 section:: Author
 Cristian Banuelos,
-dr_holomorfo
+dr_holomorfo
+