More tonnetz traversing methods and documentation

package.json

@@ -44,7 +44,7 @@
     "tone": "^14.8.49",
     "unique-names-generator": "^4.7.1",
     "vite-plugin-markdown": "^2.1.0",
-    "zifferjs": "^0.0.59",
+    "zifferjs": "^0.0.60",
     "zyklus": "^0.1.4",
     "zzfx": "^1.2.0"
   }

src/classes/ZPlayer.ts

@@ -362,6 +362,25 @@ export class Player extends AbstractEvent {
     if (this.atTheBeginning()) this.ziffers.powerTowers(tonnetz, repeats);
     return this;
   }
+  powerTower = this.powerTowers;
+
+  octaTower(tonnetz: TonnetzSpaces = [3, 4, 5], repeats: number = 3) {
+    if (this.atTheBeginning()) this.ziffers.octaTower(tonnetz, repeats);
+    return this;
+  }
+  octaTowers = this.octaTower;
+
+  borentzRegions(tonnetz: TonnetzSpaces = [3, 4, 5]) {
+    if (this.atTheBeginning()) this.ziffers.borentzRegions(tonnetz);
+    return this;
+  }
+  borentz = this.borentzRegions;
+
+  weitzmannRegions(tonnetz: TonnetzSpaces = [3, 4, 5]) {
+    if (this.atTheBeginning()) this.ziffers.weitzmannRegions(tonnetz);
+    return this;
+  }
+  weitzmann = this.weitzmannRegions;
 
   shuffle() {
     if (this.atTheBeginning()) this.ziffers.shuffle();
@@ -388,13 +407,18 @@ export class Player extends AbstractEvent {
     return this;
   }
 
+  at(value: number, ...rest: number[]) {
+    if (this.atTheBeginning()) this.ziffers.at(value, ...rest);
+    return this;
+  }
+
   keep() {
     this.ziffers.setRedo(0);
     return this;
   }
 
   repeat(amount: number) {
-    this.ziffers.setRedo(amount);
+    this.ziffers.setRedo(amount < 0 ? 0 : amount);
     return this;
   }
 

src/documentation/patterns/ziffers/ziffers_algorithmic.ts

@@ -8,7 +8,7 @@ export const ziffers_algorithmic = (application: Editor): string => {
 
   Ziffers provides shorthands for **many** numeric and algorithimic operations such as evaluating random numbers and creating sequences using list operations:
   
-  * **List operations:** Cartesian operation (_e.g._ <ic>(3 2 1)+(2 5)</ic>) using the <ic>+</ic> operator. All the arithmetic operators are supported.
+  * **List operations:** Element-wise operation (_e.g._ <ic>(3 2 1)+(2 5)</ic>) using the <ic>+</ic> operator. All the arithmetic operators are supported.
   
   ${makeExample(
     "Element-wise operations for melodic generation",
@@ -80,8 +80,10 @@ z1("s A=(0 (1,4)) B~(2 (3,8)) A B A B A")
 
 ## Generative functions
 
+  * <ic>at(index: number, ...args?: number[])</ic> Get event(s) at given index
   * <ic>repeat(amount: number)</ic> Repeat the generated pattern without re-evaluating random patterns
-  * <ic>shuffle()</ic> Shuffle the generated pattern
+  * <ic>keep()</ic> Keep the generated pattern without re-evaluating random patterns. Same as repeat(0).
+  * <ic>shuffle()</ic> Shuffle the pattern
   * <ic>deal(amount: number): Shuffle the generated pattern and deal given number of elements
   * <ic>retrograde()</ic> Reverse the generated pattern
   * <ic>invert()</ic> Invert the generated pattern

src/documentation/patterns/ziffers/ziffers_tonnetz.ts

@@ -210,8 +210,6 @@ In addition to the transformations, Ziffers implements cyclic methods that can b
 * <ic>hexaCycle(tonnetz: number[], repeats: number = 3)</ic>: Cycles through chords in the hexa cycle
 * <ic>octaCycle(tonnetz: number[], repeats: number = 4)</ic>: Cycles through chords in the octa cycle
 * <ic>enneaCycle(tonnetz: number[], repeats: number = 3)</ic>: Cycles through chords in the ennea cycle
-* <ic>powerTowers(tonnetz: number[], repeats: number = 3)</ic>: Cycles trough chords using the power towers
-* <ic>cubeDance(tonnetz: number[], repeats: number = 3)</ic>: Cycles trough chords in a cube dance
 
 HexaCycles are sequences of major and minor triads generated by the <ic>p</ic> and <ic>l</ic> transformations . Let's take the following example starting with a <ic>C</ic> chord: <ic>C -> Cm -> Ab -> Abm -> E -> Em</ic>. You can start on the chord of your choice.
 
@@ -222,7 +220,7 @@ Unlike HexaCycles and OctaCycles, EnneaCycles  are four-note chord sequences. Co
 ### Examples:
 
 ${makeExample(
-        "Arpeggio with ennea cycle",
+"Arpeggio with ennea cycle",
         `
 z1("0 2 -1 3")
   .enneaCycle()
@@ -236,7 +234,7 @@ z1("0 2 -1 3")
     )}
 
 ${makeExample(
-        "Variating arpeggios",
+"Variating arpeggios",
         `
 z1("s 0 3 2 1")
   .octaCycle()
@@ -278,9 +276,45 @@ By default hexaCycles and enneaCycles have <ic>3</ic> repetitions, while octaCyc
 
 * Remark E: These cycles in Tonnetz <ic>[3, 4, 5]</ic> are implemented based on the work of [Douthett & Steinbach (1998, pp. 245-247)](https://www.jstor.org/stable/843877)
 
-## :construction: Regions and OctaTowers
+## Traversing methods
 
- TBD: Implement and write about Weitzmann Regions, Boretz Regions, OctaTowers
+In addition to the cyclic traversing methods, Ziffers implements methods based on different theories that traverse the chords in the Tonnetz in different ways. These methods are:
+
+* <ic>powerTowers(tonnetz: number[], repeats: number = 3)</ic>: Cycles trough chords using the power towers
+* <ic>cubeDance(tonnetz: number[], repeats: number = 3)</ic>: Cycles trough chords in a cube dance
+* <ic>octaTowers(tonnetz: number[], repeats: number = 3)</ic>: Cycles trough chords using the octa towers
+* <ic>weitzmannRegions(tonnetz: number[])</ic>: Cycles trough chords in a Weitzmann region
+* <ic>boretzRegions(tonnetz: number[])</ic>: Cycles trough chords in a Boretz region
+
+We encourage you to explore these methods and their different parameters. The tonnetz traversing methods can be used in combination with the Ziffers generative methods to sequence, arpeggiate and to randomize the chords in different ways.
+
+${makeExample(
+  "Selecting subset of chords from the cube dance",
+  `
+  z1("1/2 0")
+  .cubeDance([3,4,5],4)
+  .at(0,8,2,rI(9,14))
+  .sound("triangle")
+  .ad(0.05,0.15)
+  .delay(2)
+  .out()
+`,
+  true
+)}
+
+${makeExample(
+"Selecting chords from the weitzmann region",
+`
+z1("1/8 0")
+  .weitzmannRegions()
+  .at(1,rI(0,7),4,6)
+  .arpeggio(0,2,1,rI(0,2))
+  .sound("sine")
+  .ad(0.15,0.15)
+  .out()
+`,
+true
+)}
 
 `;
 };

yarn.lock

@@ -4033,10 +4033,10 @@ yaml@^2.1.1:
   resolved "https://registry.yarnpkg.com/yaml/-/yaml-2.3.1.tgz#02fe0975d23cd441242aa7204e09fc28ac2ac33b"
   integrity sha512-2eHWfjaoXgTBC2jNM1LRef62VQa0umtvRiDSk6HSzW7RvS5YtkabJrwYLLEKWBc8a5U2PTSCs+dJjUTJdlHsWQ==
 
-zifferjs@^0.0.59:
+zifferjs@^0.0.60:
-  version "0.0.59"
+  version "0.0.60"
-  resolved "https://registry.yarnpkg.com/zifferjs/-/zifferjs-0.0.59.tgz#e18ad4f967f98092f6782abbe0a38c5a148c2bac"
+  resolved "https://registry.yarnpkg.com/zifferjs/-/zifferjs-0.0.60.tgz#c4e7f3b291d9357a3d730a868b311d1a5cfc3b34"
-  integrity sha512-bssE9Vtgmcoz2d6390pnX6YWQxsewtXi+3HWdNAmzoM+0bupOGOvpGat79fQ5FqXhV5jjrZl2JzDzLCfcwnM5w==
+  integrity sha512-Z47rZ16fHmPSJSCo9dLJVbKvzvov42e3INTPgB1ClSjSw35Vq3Drl4i+UHDeLrJPjkLYlcJ80J5RxjSpqr5gIQ==
 
 zyklus@^0.1.4:
   version "0.1.4"