Tulip  4.1.0
Better Visualization Through Research
 All Classes Files Functions Variables Enumerations Enumerator Properties Groups Pages
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 1 and Inria Bordeaux - Sud Ouest
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 left 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 Checks whether the bounding box's lowest point is less than it's highest point.
131  * "Less Than" means axis-by-axis comparison, i.e. x1 < x2 && y1 < y2 && z1 < z2.
132  *
133  * @return bool Whether this bounding box is valid.
134  **/
135  bool isValid() const;
136 
137  /**
138  * @brief Checks if the given vector is inside the current bounding box. If the bounding box is invalid the result is always false.
139  * @param coord A point in the 3D space.
140  * @return bool Wether coord is in the bounding box.
141  **/
142  bool contains(const tlp::Vec3f& coord) const;
143 
144  /**
145  * @brief Checks if the given bounding box intersect the current one. If one of the bounding box is invalid return false.
146  * @param boundingBox The bounding box to compare with.
147  * @return bool Wether the bounding boxes intersect.
148  **/
149  bool intersect(const tlp::BoundingBox& boundingBox) const;
150 
151  /**
152  * @brief Checks if the bounding box intersects a given line segment. If the bounding box is invalid the result is always false.
153  * @param segStart the start point of the line segment on which to check intersection
154  * @param segEnd the end point of the line segment on which to check intersection
155  * @return bool Wether the line segment intersects the bounding box
156  **/
157  bool intersect(const Vec3f& segStart, const Vec3f& segEnd) const;
158 
159 
160  /**
161  * @brief The vector passed as parameter is modified to contain the 8 points of the bounding box.
162  * The points are, in order :
163  * 0: lower leftmost closest point (the bounding box's minimum)
164  * 1: lower rightmost closest point
165  * 2: highest rightmost closest point
166  * 3: highest leftmost closest point
167  * 4: lower rightmost farthest point
168  * 5: lower rightmost farthest point
169  * 6: highest rightmost farthest point
170  * 7: highest leftmost farthest point
171  *
172  * Crude ASCII art again, sorry for your eyes.
173  *
174  * @verbatim
175 
176  6_________ 7
177  /| /|
178  / | / |
179  3/__|_____/2 |
180  | |_____|__|
181  | /4 | /5
182  | / | /
183  |/_______|/
184  0 1
185 
186  @endverbatim
187  *
188  * @param bb A vector in which to put the points of the bounding box.
189  * @return void
190  **/
191  void getCompleteBB(Vec3f bb[8]) const;
192 };
193 
194 }
195 
196 #endif // Tulip_BOUNDINGBOX_H