Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
262 lines (185 sloc) 7.28 KB


This workshop is designed to go over the most commonly used functions with Ronin. The list of all available functions and their usage is located here. You can also follow along our video tutorial.

  • Part 1: Images (import), (crop), (export)
  • Part 2: Draw (stroke), (fill), (gradient), (clear)
  • Part 3: Filters (pixels), (saturation), (convolve), (sharpen)
  • Part 4: Events (echo), (on "mouse-down"), (on "animate"), (on "/a")


This section will teach the basics of opening, cropping and saving an image file. You can use the $path helper to quickly get an image's path into Ronin, by writing $path and dragging a file onto the Ronin window.


To import an image onto the current canvas, type the following text, drag an image file onto the Ronin window, trace a shape in the canvas and press cmd+r:

(import $path 
  (guide $rect))

The previous code will import an image, and preserve its ratio. Alternatively, you could use a $line to stretch the image, or a $pos to simply draw the image at its original size.

(import $path 
  (guide $line))


To crop the canvas, type the following text, drag an image file onto the Ronin window press cmd+r:

(import $path 
  (pos 0 0))
  (rect 50 50 300 300))


To export the resulting image, type the following text, drag an image file onto the Ronin window, then drag a folder and add the new file's name, and press cmd+r:

(import $path)
(export $path)

For example, a version of that same code with file paths, might look something like the following:

(import "~/Desktop/photo.jpg")
(export "~/Desktop/export.png")

You could also generate the export path from the import path. To import ~/Desktop/photo.jpg, and automatically generate the export path ~/Desktop/photo-export.jpg, use this:

(def import-path $path)
(def export-path 
    (dirpath import-path) "/" 
    (filename import-path) "-export.jpg"))
(import import-path)
(export export-path)


This section will teach you how to draw some basic shapes and colorize them.


In Ronin, a shape is either a (rect), a (line), a (circle) or a (pos). To draw the outline of any shape, wrap the shape inside of a (stroke shape width color) function, like:

  (rect 100 100 300 200) "red" 10)

Or, if you would like to trace the shape with your mouse:

  $rect "red" 10)


To fill the inside of any shape, wrap it inside of a (fill shape color) function, like:

  (rect 100 100 300 200) "orange")


To colorize a stroke or a fill, with a gradient, use the (gradient line colors) where the colors is a list of colors like ("blue" "red" "yellow"):

  (circle 300 300 200) 
    (line 0 0 500 500) 
    ("white" "black")))

To better understand how the (line) affects the coloring of the circle, wrap the $line inside a (guide), as follows to preserve the guide interface:

  (circle 300 300 200) 
    (guide $line)
    ("white" "black")))


In the previous example, we used the (clear) function, which clears the canvas, but it can also be used to clear only a part of the canvas:

  frame "red")
  (rect 100 100 300 300))


This section will cover how to manipulate the pixels of an image.


First let's open an image, ideally one in color, and change every pixel of a selected area at (rect 100 100 200 200):

(import $path)
(pixels saturation 10 
  (rect 100 100 200 200))

The (pixels) function expects a function that returns 4 values(r,g,b,a), and so you can define a custom filter like:

(defn invert 
    (sub 255 pixel:0) 
    (sub 255 pixel:1) 
    (sub 255 pixel:2) pixel:3))
(pixels invert)


In the previous example, we increased the saturation of a region of the image, to desaturate an entire image, you can simply omit the (rect) which will select the entire canvas, and set the pixel filter to saturation and the value to 0.5(50% saturation):

(import $path)
(pixels saturation 0.5)


Effects which use the surrounding pixels, or convolution matrix, are used with the (convolve) function, you can learn more about this family of filters here.


(import $path)
(convolve (sharpen) $rect)

Custom convolve kernels can also be created like this:

(import $path)
(def (blur) 
    (-1 -1 -1) 
    (-1 5 -1) 
    (-1 -1 -1)))
(convolve (blur))


This section will demonstrate how to use events in Ronin to create interactive scripts.


You can print some content to the screen in Ronin, by using the (echo) function, for example, the following script will write the word hello at the bottom left of the interface:

(echo "hello")


Let's use the (debug) function to display the position of the mouse cursor in the interface.

(on "mouse-down" echo)

We can define a function that triggers when the mouse-down event is detected, or when you click on the canvas:

; define the function
(defn draw-rect 
  (fill e:circle "red"))
; use the function
(on "mouse-move" draw-rect)

For more examples of functions, see the examples.

You can find a more elaborate version of this example here.


The animate event fires around 30 times per second, and is a perfect tool to create animations. Following the previous example, and the pattern of creating a function and binding it to the event, let's make a function that will use the (time) to animate a box:

; define the function
(defn wob-rect 
    (def rect-x 300)
    (def rect-y (add (mul (sin (time 0.005)) 50) 300))
      (rect rect-x rect-y 100 100) "red")))
; use the function
(on "animate" wob-rect)

You can find a more elaborate version of this example here.


Other programs can communicate with Ronin via OSC with the previous pattern. For example, if you send OSC data to the port 49162, at the path /a, the event can be used in Ronin to trigger a function:

(on "/a" echo)

You can find a more elaborate version of this example here.

I hope this workshop has been enlightening, if you have questions or suggestions, please visit the community. Enjoy!

You can’t perform that action at this time.