Graphics.Rendering.Diagrams.Bounds

Graphics.Rendering.Diagrams defines the core library of primitives forming the basis of an embedded domain-specific language for describing and rendering diagrams.

The Bounds module defines a data type and type class for functional bounding regions.

Bounding regions

newtype Bounds v

Every diagram comes equipped with a bounding function. Intuitively, the bounding function for a diagram tells us the minimum distance we have to go in a given direction to get to a (hyper)plane entirely containing the diagram on one side of it. Formally, given a vector v, it returns a scalar s such that

• for every vector u with its endpoint inside the diagram, if the projection of u onto v is s' *^ v, then s' <= s.
• s is the smallest such scalar.

This could probably be expressed in terms of a Galois connection; this is left as an exercise for the reader.

Essentially, bounding functions are a functional representation of (a conservative approximation to) convex bounding regions. The idea for this representation came from Sebastian Setzer; see http://byorgey.wordpress.com/2009/10/28/collecting-attributes/#comment-2030.

Constructors

Bounds

Fields

appBounds :: v -> Scalar v

Instances

Show (Bounds v)

(Ord (Scalar v), AdditiveGroup (Scalar v)) => Monoid (Bounds v)

Bounding functions form a monoid, with the constantly zero function (i.e. the empty region) as the identity, and pointwise maximum as composition. Hence, if b1 is the bounding function for diagram d1, and b2 is the bounding function for d2, then b1 `mappend` b2 is the bounding function for d1 `atop` d2.

(InnerSpace v, AdditiveGroup (Scalar v), Fractional (Scalar v)) => HasOrigin (Bounds v)

The local origin of a bounding function is the point with respect to which bounding queries are made, i.e. the point from which the input vectors are taken to originate.

(HasLinearMap v, InnerSpace v, Floating (Scalar v), AdditiveGroup (Scalar v)) => Transformable (Bounds v)

(InnerSpace v, OrderedField (Scalar v)) => Boundable (Bounds v)

class (InnerSpace (V b), OrderedField (Scalar (V b))) => Boundable b where

Boundable abstracts over things which can be bounded.

Methods

getBounds :: b -> Bounds (V b)

Given a boundable object, compute a functional bounding region for it. For types with an intrinsic notion of "local origin", the bounding function will be based there. Other types (e.g. Trail) may have some other default reference point at which the bounding function will be based; their instances should document what it is.

Instances

Boundable b => Boundable [b]

(OrderedField (Scalar v), InnerSpace v) => Boundable (Point v)

(InnerSpace v, OrderedField (Scalar v)) => Boundable (Bounds v)

(HasLinearMap v, InnerSpace v, OrderedField (Scalar v)) => Boundable (AnnDiagram b v m)

Utility functions

diameter :: Boundable a => V a -> a -> Scalar (V a)

Compute the diameter of a boundable object along a particular vector.

radius :: Boundable a => V a -> a -> Scalar (V a)

Compute the radius (1/2 the diameter) of a boundable object along a particular vector.

boundaryV :: Boundable a => V a -> a -> V a

Compute the vector from the local origin to a separating hyperplane in the given direction.

boundary :: Boundable a => V a -> a -> Point (V a)

Compute the point on the boundary in the given direction. Caution: this point is only valid in the local vector space of the Boundable object. If you want to compute boundary points of things which are subparts of a larger diagram (and hence embedded within a different vector space), you must use boundaryFrom instead.

boundaryFrom :: Boundable a => Point (V a) -> V a -> a -> Point (V a)

boundaryFrom o v a computes the point along the boundary of a in the direction of v, assuming that a's local origin is located at the point o of the vector space we care about.

Miscellaneous

class (Fractional s, Floating s, Ord s, AdditiveGroup s) => OrderedField s

When dealing with bounding regions we often want scalars to be an ordered field (i.e. support all four arithmetic operations and be totally ordered) so we introduce this class as a convenient shorthand.

Instances

(Fractional s, Floating s, Ord s, AdditiveGroup s) => OrderedField s