Clojure2D: a Java2D creative coding library for Clojure

Java2D directly, with no JavaScript version

Clojure2D is described as a library supporting generative coding or glitching, and the key implementation fact is that it is based on Java2D directly, meaning there is no intermediary graphics abstraction and no shader pipeline to fight with. The project description calls it a Java2D wrapper with creative coding supporting functions, based on Processing and openFrameworks, which tells you the lineage: the API shape comes from Processing, the attitude comes from openFrameworks, and the host is the JVM. The scope is stated just as plainly. It's Clojure only, no ClojureScript version. That single constraint removes a large part of the Clojure ecosystem, and it is not a limitation the project apologises for. For someone who wants to reach the JVM's 2D drawing primitives, its BufferedImage and Graphics2D, from a Lisp without leaving the JVM, the trade is one of scope, and the people who would want it are exactly the people who would not have wanted ClojureScript anyway.

Display and canvas are decoupled, which is the whole idea

The What is special section lists the features, and the first one is the design decision the library is built around. Display and canvas are almost decoupled, with decoupled drawing and refreshing, so you can have as many windows as you want and as many canvases as you want, and the display repaints a selected canvas automatically in a separate thread. The consequence, as the README puts it, is that you can operate on the canvas at your own pace. That is the difference between a sketch that has to finish a frame before it can start the next one and a piece of code that can work on an image buffer indefinitely while a window shows it. The second point in the list is that it is still possible to code the Processing way, for example attaching a draw function to your Display, but the draw function keeps state between invocations, which allows you to avoid global state such as atoms and write more functional code. The same applies to events, since each Window has an assigned state that is passed through event calls. The library is a Lisp, so the Processing idiom is offered as a compatibility path rather than the point.

The namespaces you actually use

The core namespace is the main one and its functions fall into four groups: image file operations for loading and saving in jpg, png and bmp; canvas operations that are a wrapper for the Java2D BufferedImage and Graphics2D; window and event operations, a JFrame wrapper; and session handling, which covers the logger and a unique, sequential filename generator. The pixels namespace is the other half of the library's character. It defines a Pixels type as a representation of channel values of an image plus operations on pixels, and on top of that it offers pixel filters such as blur, erode, dilate, median, threshold, posterize and tint, the composition of Pixels, higher order functions which operate on Pixels in parallel, such as filter-channels and blend-channels, and a log density renderer. The parallel pixel operations are what make the difference between a filter you apply once and a filter you can sweep across a whole image channel by channel, and it is the kind of thing that comes from a library built by one person for their own work rather than assembled from abstractions.

Colour, palettes and gradients as a first-class concern

The colour namespace is treated as a subject rather than a utility. It provides color space converters and a huge collection of palettes and gradients, and the library contains plenty of named colors, palettes and gradients in total. The README is careful about provenance, listing the sources the collections are drawn from: colourlovers, thi.ng, paletteer, inigo quilez's palette articles and cpt-city. There are separate generated listings for color names, named palettes and named gradients, and the colour documentation is marked as work in progress. Blending gets its own namespace, clojure2d.color.blend, holding a collection of basic blending functions such as add, subtract, divide and difference, which is the level at which glitch work actually happens, where an image is put through a small arithmetic operation rather than through a conventional blend mode. The extra namespaces extend the same idea, with signal for signal processing, wave generators, effects and filters for sonification, overlays for postprocessing filters such as rgb and crt scanlines, segmentation for image segmentation, and glitch for glitching filters.

Generative extras, and the fastmath dependency

The extra namespace is the home for the higher level generative and glitch concepts the README lists as the main focus, including sonification support, vector field functions, colorspace operations and things like slitscan. One entry in that list carries its own warning: raymarching is described as a simple ray marching 3d scene renderer, abandoned. Utils provides ways to visualize objects, palettes, gradients, images and vector or scalar fields. All of the mathematics lives in a separate library, generateme/fastmath, and the README states plainly that all math functions are in the fastmath repository. That is a significant architectural decision. Rather than shipping its own numerics, Clojure2D depends on a dedicated fast implementation, which means the numerical core is maintained separately and can be used on its own. It also means the library's mathematics is not something you can fix by patching Clojure2D itself, and that the numerical layer is a project with its own release history.

Installing it, and the documentation you will actually use

Installation is a project.clj dependency, and the README's Installation section says to add the following line as a dependency to your project.clj, with the version shown as a Clojars badge rather than as text. The package is published on Clojars as clojure2d, and the version badge points at the latest release. There is no separate install command to copy, and the reason is that this is a plain Clojure library, so it enters your project the way any other library does. For the first use, the README is blunt that since there are still no tutorials available, you should see the documentation, and it links the codox-generated API docs with examples as well as a separate notebook-based documentation page for the colour namespace, which is marked work in progress. The 200 plus examples live in a separate repository, Clojure2D/clojure2d-examples, and the README's How to help section lists concrete tasks for newcomers, such as creating pixel filters and creating color spaces, and for more advanced contributors, speed optimizations and idiomatic clojure fixes. That is a good sign about how a small library expects to grow.

Where the project is the wrong choice

The README has a section called What's odd, and it is the most useful part of the document for anyone deciding. It's kind of a personal library which supports my, probably not optimal and not convenient for others, way of creating stuff. There are still plenty of bugs and not idiomatic code, it may be slower than Processing, and it eats a lot of memory because pixel code is generally immutable. Take that at face value. The author is describing a research instrument for a particular workflow, not a foundation for production software, and the Clojure-only constraint narrows the audience further. The comparison section is also worth reading with care. Asked whether it is a replacement for quil, thi.ng, clisk or possibly others, the answer is no, and the closest is quil, described as a really great library with Clojure and Clojurescript support, great documentation and webpage, functional mode and 3d support, while Clojure2D emphasises math, color and pixel operations and adds a lot of ready to use effects and filters in the extra namespaces. So the differentiation is a deliberate narrowing, and the honest comparison is with a Clojure library rather than with Processing itself.

Editorial conclusion

Clojure2D suits a Clojure developer who wants to sketch generative or glitch work with a REPL attached, since the decoupled display and canvas model and the live coding story are the reason to use it rather than a general graphics library. It is the wrong tool if you need a ClojureScript version, because the README states there is no ClojureScript version, and it is the wrong tool for production or for anyone who needs predictable performance, because the author states there are still plenty of bugs and not idiomatic code, it may be slower than Processing, and it eats a lot of memory since pixel code is generally immutable. Verify first which of the four core namespaces you actually need, since the whole library is optional at the namespace level, and note that the newest release is v1.1.0 from 2018-12-19 while the last push was on 2026-09-23.

Frequently asked questions

Official sources

1. Clojure2D/clojure2d on GitHub
2. Issues
3. License: EPL-1.0
4. README
5. Releases