Copyright | (c) 2011-2015 diagrams-lib team (see LICENSE) |
---|---|

License | BSD-style (see LICENSE) |

Maintainer | diagrams-discuss@googlegroups.com |

Safe Haskell | None |

Language | Haskell2010 |

Bounding boxes are not very compositional (*e.g.* it is not
possible to do anything sensible with them under rotation), so they
are not used in the diagrams core. However, they do have their
uses; this module provides definitions and functions for working
with them.

## Synopsis

- data BoundingBox v n
- emptyBox :: BoundingBox v n
- fromCorners :: (Additive v, Foldable v, Ord n) => Point v n -> Point v n -> BoundingBox v n
- fromPoint :: Point v n -> BoundingBox v n
- fromPoints :: (Additive v, Ord n) => [Point v n] -> BoundingBox v n
- boundingBox :: (InSpace v n a, HasBasis v, Enveloped a) => a -> BoundingBox v n
- isEmptyBox :: BoundingBox v n -> Bool
- getCorners :: BoundingBox v n -> Maybe (Point v n, Point v n)
- getAllCorners :: (Additive v, Traversable v) => BoundingBox v n -> [Point v n]
- boxExtents :: (Additive v, Num n) => BoundingBox v n -> v n
- boxCenter :: (Additive v, Fractional n) => BoundingBox v n -> Maybe (Point v n)
- mCenterPoint :: (InSpace v n a, HasBasis v, Enveloped a) => a -> Maybe (Point v n)
- centerPoint :: (InSpace v n a, HasBasis v, Enveloped a) => a -> Point v n
- boxTransform :: (Additive v, Fractional n) => BoundingBox v n -> BoundingBox v n -> Maybe (Transformation v n)
- boxFit :: (InSpace v n a, HasBasis v, Enveloped a, Transformable a, Monoid a) => BoundingBox v n -> a -> a
- contains :: (Additive v, Foldable v, Ord n) => BoundingBox v n -> Point v n -> Bool
- contains' :: (Additive v, Foldable v, Ord n) => BoundingBox v n -> Point v n -> Bool
- inside :: (Additive v, Foldable v, Ord n) => BoundingBox v n -> BoundingBox v n -> Bool
- inside' :: (Additive v, Foldable v, Ord n) => BoundingBox v n -> BoundingBox v n -> Bool
- outside :: (Additive v, Foldable v, Ord n) => BoundingBox v n -> BoundingBox v n -> Bool
- outside' :: (Additive v, Foldable v, Ord n) => BoundingBox v n -> BoundingBox v n -> Bool
- boxGrid :: (Traversable v, Additive v, Num n, Enum n) => n -> BoundingBox v n -> [Point v n]
- union :: (Additive v, Ord n) => BoundingBox v n -> BoundingBox v n -> BoundingBox v n
- intersection :: (Additive v, Foldable v, Ord n) => BoundingBox v n -> BoundingBox v n -> BoundingBox v n

# Bounding boxes

data BoundingBox v n Source #

A bounding box is an axis-aligned region determined by two points
indicating its "lower" and "upper" corners. It can also represent
an empty bounding box - the points are wrapped in `Maybe`

.

## Instances

# Constructing bounding boxes

emptyBox :: BoundingBox v n Source #

An empty bounding box. This is the same thing as `mempty`

, but it doesn't
require the same type constraints that the `Monoid`

instance does.

fromCorners :: (Additive v, Foldable v, Ord n) => Point v n -> Point v n -> BoundingBox v n Source #

Create a bounding box from a point that is component-wise `(<=)`

than the
other. If this is not the case, then `mempty`

is returned.

fromPoint :: Point v n -> BoundingBox v n Source #

Create a degenerate bounding "box" containing only a single point.

fromPoints :: (Additive v, Ord n) => [Point v n] -> BoundingBox v n Source #

Create the smallest bounding box containing all the given points.

boundingBox :: (InSpace v n a, HasBasis v, Enveloped a) => a -> BoundingBox v n Source #

Create a bounding box for any enveloped object (such as a diagram or path).

# Queries on bounding boxes

isEmptyBox :: BoundingBox v n -> Bool Source #

Queries whether the BoundingBox is empty.

getCorners :: BoundingBox v n -> Maybe (Point v n, Point v n) Source #

Gets the lower and upper corners that define the bounding box.

getAllCorners :: (Additive v, Traversable v) => BoundingBox v n -> [Point v n] Source #

Computes all of the corners of the bounding box.

boxExtents :: (Additive v, Num n) => BoundingBox v n -> v n Source #

Get the size of the bounding box - the vector from the (component-wise) lesser point to the greater point.

boxCenter :: (Additive v, Fractional n) => BoundingBox v n -> Maybe (Point v n) Source #

Get the center point in a bounding box.

mCenterPoint :: (InSpace v n a, HasBasis v, Enveloped a) => a -> Maybe (Point v n) Source #

Get the center of a the bounding box of an enveloped object, return
`Nothing`

for object with empty envelope.

centerPoint :: (InSpace v n a, HasBasis v, Enveloped a) => a -> Point v n Source #

Get the center of a the bounding box of an enveloped object, return the origin for object with empty envelope.

boxTransform :: (Additive v, Fractional n) => BoundingBox v n -> BoundingBox v n -> Maybe (Transformation v n) Source #

Create a transformation mapping points from one bounding box to the
other. Returns `Nothing`

if either of the boxes are empty.

boxFit :: (InSpace v n a, HasBasis v, Enveloped a, Transformable a, Monoid a) => BoundingBox v n -> a -> a Source #

Transforms an enveloped thing to fit within a `BoundingBox`

. If the
bounding box is empty, then the result is also `mempty`

.

contains :: (Additive v, Foldable v, Ord n) => BoundingBox v n -> Point v n -> Bool Source #

Check whether a point is contained in a bounding box (including its edges).

contains' :: (Additive v, Foldable v, Ord n) => BoundingBox v n -> Point v n -> Bool Source #

Check whether a point is *strictly* contained in a bounding box.

inside :: (Additive v, Foldable v, Ord n) => BoundingBox v n -> BoundingBox v n -> Bool Source #

Test whether the first bounding box is contained inside the second.

inside' :: (Additive v, Foldable v, Ord n) => BoundingBox v n -> BoundingBox v n -> Bool Source #

Test whether the first bounding box is *strictly* contained
inside the second.

outside :: (Additive v, Foldable v, Ord n) => BoundingBox v n -> BoundingBox v n -> Bool Source #

Test whether the first bounding box lies outside the second (although they may intersect in their boundaries).

outside' :: (Additive v, Foldable v, Ord n) => BoundingBox v n -> BoundingBox v n -> Bool Source #

Test whether the first bounding box lies *strictly* outside the second
(they do not intersect at all).

boxGrid :: (Traversable v, Additive v, Num n, Enum n) => n -> BoundingBox v n -> [Point v n] Source #

`boxGrid f box`

returns a grid of regularly spaced points inside
the box, such that there are `(1/f)`

points along each dimension.
For example, for a 3D box with corners at (0,0,0) and (2,2,2),
`boxGrid 0.1`

would yield a grid of approximately 1000 points (it
might actually be `11^3`

instead of `10^3`

) spaced `0.2`

units
apart.

# Operations on bounding boxes

union :: (Additive v, Ord n) => BoundingBox v n -> BoundingBox v n -> BoundingBox v n Source #

Form the smallest bounding box containing the given two bound union. This
function is just an alias for `mappend`

.

intersection :: (Additive v, Foldable v, Ord n) => BoundingBox v n -> BoundingBox v n -> BoundingBox v n Source #

Form the largest bounding box contained within this given two
bounding boxes, or `Nothing`

if the two bounding boxes do not
overlap at all.