decoration: Allow dynamic amplitudes (#756)

* decoration: Allow dynamic amplitudes

* decoration: Sample amplitude twice per segment

* decoration: Add square decoration

* decoration: Refine amplitude array

Author: johannes-wolf

src/lib/decorations.typ

@@ -1,2 +1,2 @@
 #import "decorations/brace.typ": brace, brace-default-style, flat-brace, flat-brace-default-style
-#import "decorations/path.typ": zigzag, wave, coil
+#import "decorations/path.typ": zigzag, wave, coil, square

src/lib/decorations/path.typ

@@ -14,7 +14,11 @@
   /// Length of a single segments
   segment-length: none,
 
-  /// Amplitude of a segment in the direction of the segments normal
+  /// Amplitude of a segment in the direction of the segments normal.
+  /// The following types are supported:
+  ///   - float
+  ///   - function ratio -> float (the segment ratio is given as argument)
+  ///   - array of floats (the rounded down segment number is used as index modulo the array length)
   amplitude: 1,
   /// Decoration start
   start: 0%,
@@ -59,6 +63,24 @@
   factor: 150%,
 )
 
+// Square default style
+#let square-default-style = (
+  ..default-style,
+  /// Midpoint factor
+  factor: 50%,
+)
+
+#let resolve-amplitude(amplitude, segment, num-segments) = {
+  segment = calc.max(0, calc.min(segment, num-segments))
+  return if type(amplitude) == function {
+    (amplitude)(segment / num-segments * 100%)
+  } else if type(amplitude) == array {
+    amplitude.at(calc.rem(int(2*segment), amplitude.len()), default: 0)
+  } else {
+    amplitude
+  }
+}
+
 #let resolve-style(ctx, segments, style) = {
   assert(not (style.segments == none and style.segment-length == none),
     message: "Only one of segments or segment-length must be set, while the other must be auto")
@@ -169,12 +191,12 @@
 
     (p0, p1) = util.revert-transform(ctx.transform, p0, p1)
 
-    let dir = vector.sub(p1, p0)
-    let norm = vector.norm(vector.cross(dir, if p0.at(2) != p1.at(2) {
+    let dir = vector.norm(vector.sub(p1, p0))
+    let norm = vector.cross(dir, if p0.at(2) != p1.at(2) {
       style.z-up
     } else {
       style.xy-up
-    }))
+    })
 
     pts += fn(i, p0, p1, norm)
   }
@@ -221,11 +243,10 @@
   // list of points for the line-strip.
   let fn(i, a, b, norm) = {
     let ab = vector.sub(b, a)
-
     let f = .25 - (50% - style.factor) / 50% * .25
     let q-dir = vector.scale(ab, f)
-    let up = vector.scale(norm, style.amplitude / 2)
-    let down = vector.scale(up, -1)
+    let up = vector.scale(norm, resolve-amplitude(style.amplitude, i + .25, num-segments) / 2)
+    let down = vector.scale(norm, -resolve-amplitude(style.amplitude, i + .75, num-segments) / 2)
 
     let m1 = vector.add(vector.add(a, q-dir), up)
     let m2 = vector.add(vector.sub(b, q-dir), down)
@@ -301,7 +322,8 @@
   //
   let fn(i, a, b, norm) = {
     let ab = vector.sub(b, a)
-    let up = vector.scale(norm, style.amplitude / 2)
+    let amplitude = resolve-amplitude(style.amplitude, i, num-segments)
+    let up = vector.scale(norm, amplitude / 2)
     let dist = vector.dist(a, b)
 
     let d = vector.norm(ab)
@@ -381,9 +403,8 @@
   //
   let fn(i, a, b, norm) = {
     let ab = vector.sub(b, a)
-    let up = vector.scale(norm, style.amplitude / 2)
-    let down = vector.scale(
-      up, -1)
+    let up = vector.scale(norm, +resolve-amplitude(style.amplitude, i + .25, num-segments) / 2)
+    let down = vector.scale(norm, -resolve-amplitude(style.amplitude, i + .75, num-segments) / 2)
 
     let ma = vector.add(vector.add(a, vector.scale(ab, .25)), up)
     let m  = vector.add(a, vector.scale(ab, .50))
@@ -408,3 +429,70 @@
     close: close,
     ..style)
 })
+
+/// Draw a square-wave along a path using a line-strip
+///
+/// The number of phases can be controlled via the `segments` or `segment-length` style key, and the width via `amplitude`.
+///
+/// ```typc example
+/// line((0,0), (2,1), stroke: gray)
+/// cetz.decorations.square(line((0,0), (2,1)), amplitude: .25, start: 10%, stop: 90%)
+/// ```
+///
+/// - target (drawable): Target path
+/// - close (auto,bool): Close the path
+/// - name (none,string): Element name
+/// - ..style (style): Style
+///
+/// ## Styling
+/// *Root*: `squre`
+///
+/// - factor (ratio) = 50% Square-Wave midpoint
+#let square(target, close: auto, name: none, ..style) = draw.get-ctx(ctx => {
+  let style = styles.resolve(ctx, merge: style.named(),
+    base: square-default-style, root: "square")
+
+  let (segments, close) = get-segments(ctx, target)
+  let style = resolve-style(ctx, segments, style)
+  let num-segments = style.segments
+  let factor = calc.max(0, calc.min(style.factor / 100%, 1))
+
+  // Return a list of points for the line-strip
+  //
+  //   +----+        ▲
+  //   |    |        │ Up
+  // ..a....m....b.. '
+  //        |    |
+  //        +----+
+  //
+  let fn(i, a, b, norm) = {
+    let ab = vector.sub(b, a)
+    let up = vector.scale(norm, +resolve-amplitude(style.amplitude, i + .25, num-segments) / 2)
+    let down = vector.scale(norm, -resolve-amplitude(style.amplitude, i + .75, num-segments) / 2)
+    let m  = vector.add(a, vector.scale(ab, factor))
+
+    if not close {
+      if i == 0 {
+        return (a, vector.add(a, up),
+                vector.add(m, up), vector.add(m, down),
+                vector.add(b, down))
+      } else if i == num-segments - 1 {
+        return (vector.add(a, up),
+                vector.add(m, up), vector.add(m, down),
+                vector.add(b, down), b)
+      }
+    }
+
+    return (vector.add(a, up),
+            vector.add(m, up), vector.add(m, down),
+            vector.add(b, down))
+  }
+
+  return draw.merge-path(
+    finalize-path(ctx, segments, style, draw.line(
+      .._path-effect(ctx, segments, fn, close: close, style),
+      close: close), close: close) ,
+    name: name,
+    close: close,
+    ..style)
+})

tests/decorations/path/ref/1.png

@@ -2,55 +2,23 @@
 #import "/src/lib.typ": *
 #import "/tests/helper.typ": *
 
-#import decorations: zigzag, coil, wave
+#import decorations: zigzag, coil, wave, square
 
-#box(stroke: 2pt + red, canvas(length: 1cm, {
-  import draw: *
-
-  zigzag(line((0,0), (4,0)))
-  zigzag(line((0,1), (4,1)), amplitude: .5)
-}))
-
-#box(stroke: 2pt + red, canvas(length: 1cm, {
-  import draw: *
-
-  wave(line((0,0), (4,0)))
-  wave(line((0,1), (4,1)), amplitude: .5)
-}))
-
-#box(stroke: 2pt + red, canvas(length: 1cm, {
-  import draw: *
-
-  coil(line((0,0), (4,0)))
-  coil(line((0,1), (4,1)), amplitude: .5)
-}))
+#let all-fns = (zigzag, coil, wave, square)
 
-#box(stroke: 2pt + red, canvas(length: 1cm, {
+#test-case(fn => {
   import draw: *
 
-  zigzag(hobby((0,0), (4,0), (6,2)))
-}))
+  fn(line((0,0), (4,0)))
+  fn(line((0,1), (4,1)), amplitude: .5)
+  fn(line((0,2), (4,2)), amplitude: t => { 1 - .5 * t / 50% })
+  fn(line((0,3), (4,3)), amplitude: (0, .5, 1))
+}, args: all-fns)
 
-#box(stroke: 2pt + red, canvas(length: 1cm, {
+#test-case(fn => {
   import draw: *
-
-  coil(hobby((0,0), (4,0), (6,2)))
-}))
-
-#box(stroke: 2pt + red, canvas(length: 1cm, {
-  import draw: *
-
-  wave(hobby((0,0), (4,0), (6,2)))
-}))
-
-#box(stroke: 2pt + red, canvas(length: 1cm, {
-  import draw: *
-
-  set-style(radius: .9)
-  zigzag(circle((0,0)), amplitude: .2, segments: 20, factor: 0%)
-  zigzag(circle((0,2)), amplitude: .2, segments: 20, factor: 50%, stroke: blue)
-  zigzag(circle((0,4)), amplitude: .2, segments: 20, factor: 100%, stroke: red)
-}))
+  fn(hobby((0,0), (4,0), (6,2)))
+}, args: all-fns)
 
 #box(stroke: 2pt + red, canvas(length: 1cm, {
   import draw: *
@@ -70,33 +38,30 @@
   wave(circle((0,4)), amplitude: .2, segments: 20, tension: 1, stroke: red)
 }))
 
-
-#test-case({
+#box(stroke: 2pt + red, canvas(length: 1cm, {
   import draw: *
 
-  zigzag(line((0,0), (3,0)), start: 10%, stop: 90%)
-  zigzag(line((0,2), (3,2)), start: 1, stop: 2)
-})
+  set-style(radius: .9)
+  square(circle((0,2)), amplitude: .2, segments: 20)
+}))
 
-#test-case({
+#test-case(fn => {
   import draw: *
 
-  coil(line((0,0), (3,0)), start: 10%, stop: 90%)
-  coil(line((0,2), (3,2)), start: 1, stop: 2)
-})
+  fn(line((0,0), (3,0)), start: 10%, stop: 90%, amplitude: .5)
+  fn(line((0,1), (3,1)), start: 1, stop: 2, amplitude: .5)
+}, args: all-fns)
 
-#test-case({
+#test-case(fn => {
   import draw: *
 
-  wave(line((0,0), (3,0)), start: 10%, stop: 90%)
-  wave(line((0,2), (3,2)), start: 1, stop: 2)
-})
+  fn(line((0,0,-1), (0,0,1)), start: 10%, stop: 90%)
+}, args: all-fns)
 
-#test-case({
+#test-case(factor => {
   import draw: *
-
-  wave(line((0,0,-1), (0,0,1)), start: 10%, stop: 90%)
-})
+  square(line((0,0), (3,0)), factor: factor)
+}, args: (25%, 50%, 75%))
 
 #test-case({
   import draw: *