Implement unified FormulaGrid visualizer

[gwhitney]

In overhauling both Grid and ShiftCompare for the alpha release, we have come to realize that they are both examples of a more general visualizer dubbed "FormulaGrid" whose behavior can be specified by supplying a relatively modest number of formulas. Therefore, we have decided to implement this FormulaGrid visualizer, and then we will re-implement Grid aka Spiral and ShiftCompare aka SelfSimilarity as lightweight simplified "skins" over FormulaGrid. This issue concerns itself with just the unified grid-cell-based formula-specified visualizer.

[gwhitney]

@katestange @Vectornaut here's the proposed doc intro for the new visualizer, which lays out at least in schematic form exactly what the visualizer will do: simply visit grid cells in some specified order, and in each one, evaluate a series of formulas associated with shapes, and draw the shape with the color resulting from the formula in the current cell being visited. I would very much welcome feedback on either the specified behavior or the writing. I do understand that this writeup is perhaps a bit overly occupied with color computations, but right now we don't have those ideas anywhere else an I wanted to get them down. In particular, it seems as though the math makes the most sense using "premultiplied alpha" color coordinates, in which case the formula for the color l resulting from laying color d on top of color c is just l = d + c(1 - alpha(d)).

---

This visualizer divides the rectangular canvas into a grid of r by c
identical rectangular cells. Each cell has an x coordinate, a y coordinate,
and a number of spiral steps s from the "spiral center" of the rectangle.
In each frame, Formula Grid will draw one or more shapes in each of the next
group of consecutive cells in the grid. It provides a selection of supported
shapes (rectangle, small square, ellipse, small circle, hexagon, and triangle).
Note that the centers and geometric details of the hexagons and triangles
mean that they will tile the plane, and if the proper aspect ratio for the
cells is selected, these shapes will be regular as well.

The (RGBA) color of each shape drawn is determined by a formula that may use
the parameters x, y, r, c, and s described above, as well as i,
the index of the cell in the order they are filled in, and the function symbol
a such that a(k) gives the _k_th entry in the sequence being visualized.
These formulas are expected to produce color values: They may use the basic
color constructor rgba(r, g, b, a) (note the alpha argument a defaults to
1, i.e. opaque, and all parameters are floating point numbers from 0 to 1
inclusive). They may also use opaque color constants such as white,
blue, yellow, etc., and color operations of addition (note c + d means
"d over c" and is associative but not commutative -- in particular if d
is opaque then it produces exactly d) and scalar multiplication (of all
components). In particular, any color times zero produces a completely
transparent hueless color. To support the possible need for pure additive
blending, we also overload the left shift >> on a number and a color to set
the alpha channel of a color, leaving its hue values completely alone (i.e.,
not premultiplying them by alpha as usual; you can also specify
rgba(0.5, 0.2, 0.3, 0, false) to disable the usual premultiplication and
produce a purely emissive color with no occlusion). For example, 1 >> c
denotes the opaque color with the same hue as c whereas c * 1 = 1 * c = c,
as one might expect from the notation. If a supplied color formula produces
just a number rather than a color object, it will be clamped to the range
[0,1] and then interpreted as a greyscale value, with 0 black and 1 white.

Finally, the fill order of the cells can be controlled by two formulas giving
the x and y coordinates of the _i_th cell to be visited. These formulas
default to filling the cells left to right, top to bottom, and a preset is
also provided to fill the cells in spiral order starting from the spiral center.
Note that it is not required that a given cell in the grid is visited exactly
once as a result of these formulas; it could equally well never be visited
or be visited multiple times. For example, one can make a typical point plot
of a sequence by using i for the x formula and r - a(i) for the y
formula (becaue the rows of the grid are numbered from zero at the top row
to r at the bottow row, rather than in typical Cartesian coordinate fashion).

[gwhitney]

In particular, in order to compute with colors in mathjs, we will need to define our own color class, because (a) the p5 color class isn't compatible with mathjs because of how strongly it is tied with a specific sketch, and (b) we want to support colors in non-p5 sketches which are coming sooner or later. (Incidentally this effort should ultimately help with the "INVALID_COLOR" problem, if we migrate to using our color class and constructing actual p5 colors once the sketch is created.)

As suggested above, I plan to use an explicitly premultiplied rgba color representation with addition of colors by overlay, to keep things simple at least to begin with. (I was hoping to use https://github.com/gka/chroma.js but it is unfortunately poor/broken at overlaying with alpha, which I feel tends to be our default.)

In case the "explicitly premultiplied" modifier isn't familiar to you, it just means that the "r g b" channels are each interpreted as emission from 0 (none) to 1 (maximum perceptible) and the "a" channel is interpreted as the fraction that the "color" occludes underlying colors. So the typical encoding of "50% opaque red" would be (0.5, 0, 0, 0.5) rather than (1, 0, 0, 0.5) in the "non-premultiplied" representation. This representation (a) simplifies the overlay computation of color d over color c to d + c*(1-d_a) as an ordinary vector computation, and (b) allows one to support additive mixing with the same operation by using colors with 0 alpha, i.e. no occlusion -- conceptually one is just putting the "LEDs" for the two colors next to each other so they both emit, and then looking at the result. (In such a case you have to clamp the channel values back to the range [0,1].)

What use as the class name of our color class? Feedback welcome:

(a) Color -- I worry that every color class under the sun is called Color, including p5.Color, so this could be confusing.
(b) NSColor -- A little verbose, reminiscent of NextStep, but presumably unambiguous in our context
(c) Kolor -- Too cutesy?
(d) RGBA/Rgba/PMrgba/EOrgba -- makes the rep explicit in the name; the motivation for PM would be to highlight that these are premultiplied, and for EO similar -- Emission Occlusion rgba.
(e) EOColor -- again highlight the emssion/occlusion aspect.

For now, I am going to use RGBA to correspond to the rgba function symbol I proposed above; this casing looks more symmetric to me than Rgba. But I can easily search/replace to any other name if some other option seems better.

[gwhitney]

Actually, I have had a change of heart based on https://www.vis4.net/blog/avoid-equidistant-hsv-colors/ -- the comments about choosing colors for data scientists really seemed apropos. So I think we will definitely be able to make use of chroma.js many color scales/interpolation modes. So I will import its Color class as Chroma and use that. And I will just hand-implement the alpha-compositing overlay of two colors as the + operation in mathjs using Chroma objects -- very oddly that color operation is not implemented in chroma.js, which is why I skipped it the first time around. But it's not like it is so hard to implement on top of the operations chroma.js does provide.

[gwhitney]

I have submitted #528 which is a start at implementing color formulas. I could extend it to a PR for this visualizer if it was deemed best to submit them together.

I am currently thinking about the best parameters/UI for setting the number and aspect ratio of the cells of the grid. I feel the defaults if you fill nothing in should be decent: maybe in that case rows = columns, and so rows is roughly the square root of the number of terms if that is finite or 128 (?) if the number of terms is infinite. Then the aspect ratio of the cells is chosen to fill the canvas (i.e., equal to the canvas).

If you fill in only the number of rows, then I think again the assumption should be rows = columns, but now the number is fixed and so the length of the sequence is irrelevant, and the aspect ratio of the cells is again equal to the canvas.

If you fill in both the number of rows and number of columns, then the aspect ratio is chosen to fill the canvas (but now will be different than the aspect ratio of the canvas if rows ≠ columns).

I was thinking that I would use one parameter for the dimensions which could be unfilled, have just one number, or have two numbers. So there would be no way to set the number of columns but not the number of rows. Does that seem OK?

If you set the aspect ratio for the cells, but neither the number of rows or columns, then again if the sequence is finite, the number of rows would be selected to roughly show the whole sequence and fill the canvas. If the sequence is infinite, again the number of rows would default to 128 (?) and the number of columns would be chosen to fill the canvas.

If you set the aspect ratio for the cells and just the number of rows, the number of columns would be set to fill the canvas.

Finally, if you set all three values, then the requestedAspectRatio would be set accordingly. This is the only condition under which less than the full canvas would be used.

How do those parameters/behavior sound? Happy to have your thoughts/feedback/suggestions of different/better controls.

[gwhitney]

We discussed variable names today and decided on

r,c -- coordinates (rows and columns)
R, C -- total number of rows and columns
s -- sequential number of the fill, starting from 1
f, l -- sequence first and last indices
n -- f+s-1 (sth sequence index)
u -- the position of a cell along the spiral path (for Ulam). So when drawing in spiral path order, u = s; but having this variable allows you to recover the spiral position even when filling in the grid in a different order.

[gwhitney]

Completed via merging of #542 into ui2.