bounding_box 0.2.0

A library for rectilinear, 2-dimensional bounding boxes
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

bounding_box
============

A lightweight library for handling 2D bounding boxes / bounding rectangles.

[`BoundingBox`]: https://docs.rs/bounding_box/0.2.0/bounding_box/struct.BoundingBox.html
[`contains_point`]: https://docs.rs/bounding_box/0.2.0/bounding_box/struct.BoundingBox.html#method.contains_point
[`approx_contains_point`]: https://docs.rs/bounding_box/0.2.0/bounding_box/struct.BoundingBox.html#method.approx_contains_point

A [minimum two-dimensional bounding box / bounding rectangle](https://en.wikipedia.org/wiki/Minimum_bounding_rectangle)
describes the extents of an entity (shape, point set, line, ...) or a collection thereof in x-y coordinates. 

Bounding boxes are very useful in computational geometry. For example, if the
bounding boxes of two entities don't intersect, the entities themselves also
don't intersect. This property can be used to short-circuit intersection
algorithms. In a similar fashion, they can be used as a first stage of an
algorithm which checks if an entity contains a point. 

Another use case is to find the minimum space required for displaying an entity
on a rectangular monitor. By comparing the bounding box to the actually
available monitor space, scaling factors can be obtained so the entire entity
can be shown on the monitor at once.

This library offers a ightweight struct [`BoundingBox`] (defined by only four
`f64`) which has various methods to e.g. calculate its dimensions, find its
center, transform it, unite it with other [`BoundingBox`] instances, find
intersections between [`BoundingBox`] instances and many more ...

It is recommended to implement `From<&T> for BoundingBox` for types which can
derive a bounding box from themselves


The full API documentation is available at
[https://docs.rs/bounding_box/0.2.0/bounding_box/](https://docs.rs/bounding_box/0.2.0/bounding_box/).

As an example, the following code snippet shows how a [`BoundingBox`] can be
used with a `Circle` type:

```rust
use bounding_box::BoundingBox;

struct Circle {
    center: [f64; 2],
    radius: f64
}

impl From<&Circle> for BoundingBox {
    fn from(c: &Circle) -> BoundingBox {
        return BoundingBox::new(c.center[0] - c.radius, 
                                c.center[0] + c.radius,
                                c.center[1] - c.radius, 
                                c.center[1] + c.radius);
    }
}

let c1 = Circle {center: [0.0, 0.0], radius: 1.0};
let c2 = Circle {center: [0.0, 2.0], radius: 1.0};
let c3 = Circle {center: [0.0, 2.0], radius: 2.0};

// ===============================================================
// Intersection

/// This is an incomplete example of an intersection algorithm
fn circles_intersect(left: &Circle, right: &Circle) -> &'static str {
    let bb_l: BoundingBox = left.into();
    let bb_r: BoundingBox = right.into();

    // Short-circuit the evaluation here
    if !(bb_l.intersects(&bb_r)) {
        return "The circles definitely don't intersect!";
    }

    // Implement the detailed (expensive) algorithm here
    // ...

    return "The circles might intersect ...";
}

assert_eq!(circles_intersect(&c1, &c2), "The circles definitely don't intersect!");
assert_eq!(circles_intersect(&c1, &c3), "The circles might intersect ...");

// ===============================================================
// Contains a point

/// This is an incomplete example of a containment check algorithm
fn circle_contains_point(c: &Circle, pt: [f64; 2]) -> &'static str {
    if !BoundingBox::from(c).contains_point(pt) {
        return "The point is not within the circle!";
    }

    // Implement the detailed (expensive) algorithm here
    // ...

    return "The point might be within the circle ...";
}

assert_eq!(circle_contains_point(&c1, [5.0, 1.0]), "The point is not within the circle!");
assert_eq!(circle_contains_point(&c1, [0.0, 0.5]), "The point might be within the circle ...");

// ===============================================================
// Find the common bounding box of all circles

// Using an iterator
let bb_common_iter = BoundingBox::from_bounded_entities([&c1, &c2, &c3].into_iter()).expect("iterator has at least one element");
assert_eq!(bb_common_iter.xmin(), -2.0);
assert_eq!(bb_common_iter.xmax(), 2.0);
assert_eq!(bb_common_iter.ymin(), -1.0);
assert_eq!(bb_common_iter.ymax(), 4.0);

// Alternatively, the bounding box could also be found by manually uniting the individual bounding boxes
let bb_common_man = BoundingBox::from(&c1).union(&BoundingBox::from(&c2).union(&BoundingBox::from(&c3)));
assert_eq!(bb_common_man, bb_common_iter);
```

The following code snippet shows how to find the smallest bounding box containing a given vertex set.

```rust
use bounding_box::BoundingBox;

let bb_all_pts = BoundingBox::from_vertices([[-1.0, -1.0], [1.0, 1.0]].into_iter()).expect("iterator has at least one element");
assert_eq!(bb_all_pts.xmin(), -1.0);
assert_eq!(bb_all_pts.xmax(), 1.0);
assert_eq!(bb_all_pts.ymin(), -1.0);
assert_eq!(bb_all_pts.ymax(), 1.0);
```

# Feature flags


All features are disabled by default.

## Serialization and deserialization


Bounding boxes can be serialized and deserialized using the
[serde](https://crates.io/crates/serde) crate.

This functionality is gated behind the  `serde ` feature flag.

## Tolerances


Some methods of [`BoundingBox`] are gated behind the  `approx ` feature flag.
Enabling this flag adds the [approx](https://crates.io/crates/approx) crate as a
dependency. The gated methods are prefixed with `approx_` and are variants of
other methods which habe absolute and ULPs (units of least precision) tolerances
as additional arguments. For example, [`approx_contains_point`] is the tolerance 
variant of [`contains_point`] and checks if a given point is *approximately* in
the bounding box.