Terminology: rename "bounding function" -> "envelope"; "boundary function" -> "boundary"

[fryguybob]

(Imported from http://code.google.com/p/diagrams/issues/detail?id=61. Original issue from byor...@gmail.com on November 13, 2011, 08:34:39 PM UTC)

I've never really liked the locution "bounding function", and now that Taejo is working on an implementation of "boundary functions" (to give you points actually on the boundary), the terminology situation looks quite dire. I propose renaming "bounding function" to "envelope" and calling the new "boundary function" just the "boundary".

Concretely, this would mean changing

• The "Boundable" class to "Enveloped"
• getBounds to getEnvelope, etc. etc.
• Go through the tutorial and user manual and change every occurrence of the terminology

These changes would be annoying and tedious, but I fear otherwise users will just be confused. Suggestions for alternative names are also welcome.

[fryguybob]

(Imported. Original comment by peterj...@gmail.com on January 20, 2012, 08:22:05 PM UTC)

I don't really like envelope so much. It's an extra metaphor that doesn't convey the difference between the two things.

I'm not so familiar with the API, but the difference sounds like a boundary function gives you the exact boundary, while a bounding function gives you the smallest convex boundary.

Perhaps convexBoundary would be more descriptive and self-documenting. We could also add rectBoundary, so there would be 3 levels of bounding precision. The new boundary function can be exactBoundary or just boundary.

[fryguybob]

(Imported. Original comment by byor...@gmail.com on January 20, 2012, 08:39:51 PM UTC)

The boundary function does give you the exact boundary (at least, it is an extensional encoding of the exact boundary). However, a "bounding function" (what I propose calling an "envelope") does NOT give you the smallest convex boundary. It is a function which tells you the minimum distance in any given direction to reach a perpendicular (hyper)plane which completely encloses the diagram on one side of it. See http://projects.haskell.org/diagrams/manual/diagrams-manual.html#bounding-functions-and-local-vector-spaces for more detail and some examples.

I don't think there IS any single name for this which would be self-documenting. That's why I propose using a name which is related but doesn't immediately suggest a particular obvious meaning. That way users will be forced to actually learn what the "envelope" is, with less wrong intuitions to get in the way and confuse them.

[fryguybob]

(Imported. Original comment by peterj...@gmail.com on January 20, 2012, 09:06:23 PM UTC)

Ah yes, you're right (of course).

What about approxBoundary, or erm, envelope :)

[fryguybob]

(Imported. Original comment by byor...@gmail.com on February 18, 2012, 03:05:01 PM UTC)

Heads up, I just pushed some patches implementing this. Various things may break, e.g. if you used 'getBounds' or 'setBounds' or 'withBounds' anywhere, you now have to replace them with '{get,set,with}Envelope'. Working on updating the user manual now.