Tulip  4.10.0
Better Visualization Through Research
BoundingBox.h
1 /*
2  *
3  * This file is part of Tulip (www.tulip-software.org)
4  *
5  * Authors: David Auber and the Tulip development Team
6  * from LaBRI, University of Bordeaux
7  *
8  * Tulip is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU Lesser General Public License
10  * as published by the Free Software Foundation, either version 3
11  * of the License, or (at your option) any later version.
12  *
13  * Tulip is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
16  * See the GNU General Public License for more details.
17  *
18  */
19 
20 #ifndef Tulip_BOUNDINGBOX_H
21 #define Tulip_BOUNDINGBOX_H
22 
23 #include <tulip/Vector.h>
24 #include <tulip/tulipconf.h>
25 
26 namespace tlp {
27 /**
28  * \ingroup Structures
29  * \brief This class represents the 3D bounding box of an object.
30  * It is mostly used to determine whether or not two object are in a state of collision.
31  *
32  * It is defined by two 3d points, the first one (A) being the lowest point, the second (B) being the highest.
33  * As a bounding box is a mathematical entity describing the lowest and highest points, whether these points are in the top-left corner or
34  * lower-right corner depends on the axes we use.
35  * Below is a crude ASCII-art description of the axes we use in our 3D world and the points where the min and max are thus positioned.
36  * Through the rest of this class's documentation, it will be assumed that this is the convention.
37  *
38  *
39  * @verbatim
40  y
41  |
42  |
43  |_____ x
44  /
45  /
46  z
47 
48  _________ B
49  / /|
50  / / |
51  /________/ |
52  | | |
53  | | |
54  | | /
55  |________|/
56  A
57 
58  @endverbatim
59  *
60  *
61  * Author : <a href="www.tulip-software.org">Tulip team</a>
62  */
63 struct TLP_SCOPE BoundingBox : public Array<Vec3f, 2> {
64 
65 
66  /**
67  * @brief Creates an invalid boundig box.
68  * The minimum is (1, 1, 1) and the maximum is (-1, -1, -1).
69  *
70  **/
71  BoundingBox();
72 
73  /**
74  * @brief Creates a bounding box that must be valid.
75  * Validity is checked in debug mode by an assert.
76  *
77  * @param min The lower left closest point of the box.
78  * @param max The higher right most farther point of the box.
79  **/
80  BoundingBox(const tlp::Vec3f& min, const tlp::Vec3f& max);
81 
82  /**
83  * @brief Returns the geometrical center of the bounding box.
84  * An assertion is raised in debug mode if the BoundingBox is not valid.
85  *
86  * @return The center of the bounding box :Vec3f
87  **/
88  Vec3f center() const;
89 
90  /**
91  * @brief Returns the width of the bounding box
92  * An assertion is raised in debug mode if the BoundingBox is not valid.
93  *
94  **/
95  float width() const;
96 
97  /**
98  * @brief Returns the height of the bounding box
99  * An assertion is raised in debug mode if the bounding box is not valid.
100  *
101  **/
102  float height() const;
103 
104  /**
105  * @brief Returns the depth of the bounding box
106  * An assertion is raised in debug mode if the bounding box is not valid.
107  *
108  **/
109  float depth() const;
110 
111 
112  /**
113  * @brief Expands the bounding box to one containing the vector passed as parameter.
114  * If the parameter is inside the bounding box, it remains unchanged.
115  *
116  * @param coord A point in the 3D space we want the bounding box to encompass.
117  * @return void
118  **/
119  void expand(const tlp::Vec3f& coord);
120 
121  /**
122  * @brief Translates the bounding box by the displacement given by the vector passed as parameter.
123  *
124  * @param vec The displacement vector in 3D space to translate this bounding box by.
125  * @return void
126  **/
127  void translate(const tlp::Vec3f& vec);
128 
129  /**
130  * @brief Scales the bounding box, i.e. multiplying its components by a vector passed as parameter.
131  *
132  * @param factor The factor vector to scale this bounding box by.
133  * @return void
134  **/
135  void scale(const tlp::Vec3f& factor);
136 
137  /**
138  * @brief Checks whether the bounding box's lowest point is less than it's highest point.
139  * "Less Than" means axis-by-axis comparison, i.e. x1 < x2 && y1 < y2 && z1 < z2.
140  *
141  * @return bool Whether this bounding box is valid.
142  **/
143  bool isValid() const;
144 
145  /**
146  * @brief Checks if the given vector is inside the current bounding box. If the bounding box is invalid the result is always false.
147  * @param coord A point in the 3D space.
148  * @return bool Wether coord is in the bounding box.
149  **/
150  bool contains(const tlp::Vec3f& coord) const;
151 
152  /**
153  * @brief Checks if the given bounding box is inside the current bounding box. If one of the bounding boxes is invalid the result is always false.
154  * @param boundingBox The bounding box to test inclusion
155  * @return bool Wether boundingBox is in the bounding box.
156  **/
157  bool contains(const tlp::BoundingBox& boundingBox) const;
158 
159  /**
160  * @brief Checks if the given bounding box intersect the current one. If one of the bounding box is invalid return false.
161  * @param boundingBox The bounding box to compare with.
162  * @return bool Wether the bounding boxes intersect.
163  **/
164  bool intersect(const tlp::BoundingBox& boundingBox) const;
165 
166  /**
167  * @brief Checks if the bounding box intersects a given line segment. If the bounding box is invalid the result is always false.
168  * @param segStart the start point of the line segment on which to check intersection
169  * @param segEnd the end point of the line segment on which to check intersection
170  * @return bool Wether the line segment intersects the bounding box
171  **/
172  bool intersect(const Vec3f& segStart, const Vec3f& segEnd) const;
173 
174 
175  /**
176  * @brief The vector passed as parameter is modified to contain the 8 points of the bounding box.
177  * The points are, in order :
178  * 0: lower leftmost closest point (the bounding box's minimum)
179  * 1: lower rightmost closest point
180  * 2: highest rightmost closest point
181  * 3: highest leftmost closest point
182  * 4: lower rightmost farthest point
183  * 5: lower rightmost farthest point
184  * 6: highest rightmost farthest point
185  * 7: highest leftmost farthest point
186  *
187  * Crude ASCII art again, sorry for your eyes.
188  *
189  * @verbatim
190 
191  6_________ 7
192  /| /|
193  / | / |
194  3/__|_____/2 |
195  | |_____|__|
196  | /4 | /5
197  | / | /
198  |/_______|/
199  0 1
200 
201  @endverbatim
202  *
203  * @param bb A vector in which to put the points of the bounding box.
204  * @return void
205  **/
206  void getCompleteBB(Vec3f bb[8]) const;
207 };
208 
209 }
210 
211 #endif // Tulip_BOUNDINGBOX_H
This class represents the 3D bounding box of an object. It is mostly used to determine whether or not...
Definition: BoundingBox.h:63
Fixed-size array encapsulation.In debug mode, a bound check is performed at each access. Stream operators implementations are provided.
Definition: Array.h:37