transform: Add transform Function

Author: johannes-wolf

CHANGES.md

@@ -17,6 +17,7 @@
 - Added a new element `svg-path` that accepts a subset of SVG
   commands to construct paths
 - Fixed a bug with `brace` and `flip: true` (#1017)
+- Added a new `transform` function that multiplies a given transformation matrix with the current one (#1019)
 
 # 0.4.2
 - The `tree` element now has a `anchor:` argument to position the tree (#929)

docs/api/draw-functions/transformations/transformations.md

@@ -1,6 +1,6 @@
 # Transformations
 
-All transformation functions push a transformation matrix onto the current transform stack. To apply transformations scoped use the [`group`](../grouping/group.mdx) draw function.
+All transformation functions but `set-transform` push a transformation matrix onto the current transform stack. To apply transformations scoped use the [`group`](../grouping/group.mdx) or [`scope`](../grouping/scope.mdx') draw function.
 
 Transformation matrices get multiplied in the following order:
 

manual.pdf

@@ -1,5 +1,5 @@
 #import "draw/grouping.typ": intersections, group, scope, anchor, copy-anchors, set-ctx, get-ctx, for-each-anchor, on-layer, hide, floating
-#import "draw/transformations.typ": set-transform, rotate, translate, scale, set-origin, move-to, set-viewport
+#import "draw/transformations.typ": set-transform, transform, rotate, translate, scale, set-origin, move-to, set-viewport
 #import "draw/styling.typ": set-style, fill, stroke, register-mark
 #import "draw/shapes.typ": circle, circle-through, arc, arc-through, mark, line, grid, content, rect, bezier, bezier-through, catmull, hobby, merge-path, polygon, compound-path, n-star, rect-around, svg-path
 #import "draw/projection.typ": ortho, on-xy, on-xz, on-yz

src/draw.typ

@@ -21,9 +21,9 @@
   }
 }
 
-/// Sets the transformation matrix.
+/// Overwrites the transformation matrix.
 ///
-/// - mat (none, matrix): The 4x4 transformation matrix to set. If `none` is passed, the transformation matrix is set to the identity matrix (`matrix.ident()`).
+/// - mat (none, matrix): The 4x4 transformation matrix to set. If `none` is passed, the transformation matrix is set to the identity matrix (`matrix.ident(4)`).
 #let set-transform(mat) = {
   let mat = if mat == none {
     matrix.ident(4)
@@ -45,6 +45,33 @@
   },)
 }
 
+/// Applies a $4 times 4$ transformation matrix to the current transformation.
+///
+/// Given the current transformation $C$ and the new transformation $T$,
+/// the function sets the new canvas' transformation $C'$ to $C' = C T$.
+///
+/// - mat (none, matrix): The 4x4 transformation matrix to set. If `none` is passed, the transformation matrix is set to the identity matrix (`matrix.ident(4)`).
+#let transform(mat) = {
+  let mat = if mat == none {
+    matrix.ident(4)
+  } else {
+    matrix.round(mat)
+  }
+
+  assert(
+    type(mat) == array,
+    message: "Transformtion matrix must be of type array, got: " + repr(mat))
+  assert.eq(
+    mat.len(),
+    4,
+    message: "Transformation matrix must be of size 4x4, got: " + repr(mat))
+
+  (ctx => {
+    ctx.transform = matrix.mul-mat(ctx.transform, mat)
+    return (ctx: ctx)
+  },)
+}
+
 /// Rotates the transformation matrix on the z-axis by a given angle or other axes when specified.
 ///
 /// ```example

src/draw/transformations.typ

@@ -0,0 +1,21 @@
+#set page(width: auto, height: auto)
+
+#import "/src/lib.typ": *
+#import "/tests/helper.typ": *
+
+#let arrow = draw.polygon((0, 0), 3)
+
+#test-case({
+  import draw: *
+
+  transform(none)
+  arrow
+})
+
+#test-case({
+  import draw: *
+
+  transform(matrix.transform-rotate-z(45deg))
+  transform(matrix.transform-scale((1, 0.5, 1)))
+  arrow
+})