api.geometry design

Design Goals

• Descriptive (declarative) syntax
• Contrast: procedural syntax, e.g. Postscript, SVG. We say line a b rather than a moveto b lineto
• Natural syntax
• Syntax: for now we stick with Clojure's prefix-n-parens syntax. Infix syntax is more natural, and macros can make it work for Clojure (see Incanter's use of $= for this) but for now we follow the path of least resistance.
• Terminology: "natural" means something like "standard mathematical terminology".

Design Decision Points

• One API or two? Drawing stuff always involves two things:
  • Computational geometry -- interpolating lines between points, finding tangents, computing the intersection of regions, etc. Computational geometry is device-independent, abstract.
  • Rendering -- mapping the results of computed geometries to display devices.

Most graphics toolkits combine these two functionalities - even the most primitive API must be capable of, e.g. computing the line between to points in order to implement a line function. But kits like JTS (Java Topology Suite) just do computational geometry. One reason you might want this is if you need to, say, compute some statistics (e.g. windspeed, accident rate, etc.) associated with a geographic region with no intention of actual drawing any pictures.

So the design question is whether to make two distinct API->protocol->implementation packages and how they would fit together.

• Coordinates: to parenthesize or not to parenthesize. Many geometry APIs do not parenthesize, e.g.

  • line a b c d But parenthesis is more natural: line (a,b) (c,d). The parens carry information. So we use parenthesized points.

• Fixity: prefix, infix, or postfix are the three "natural" ways to do it:

  • line (a,b) (c,d)
  • (a,b) line (c,d)
  • (a,b) (c,d) line

To support infix or postfix we would have to use a macro, e.g. ($= (a,b) line (c,d)). So we stick with prefix notation.

• To macroize or not to macroize. For example:
  1. (line '(0,0) '(1,1))
  2. (line (0,0) (1,1))

Here i is close to natural, but it has those pesky ' marks; ii is more natural. We can support this if we make "line" a macro.