vlib: add 2D version of point in box function

Include also ctypes-based test and documentation of both the 2D and the original 3D version.

The 2D version has suffix _2d. There are some functions in the lib already which are using this style.
The 3D version has same name for compatibility reasons. There are some other functions which are just 2D
these might need _3d versions one day.

Alternative or an additional solution would be one function which would either use additional variable
like with_z or it would accept coordinates as pointers so that z could be NULL pointer.
This could make some caller code shorter.


git-svn-id: https://svn.osgeo.org/grass/grass/trunk@66459 15284696-431f-4ddb-bdfa-cd5b030d7da7

lib/vector/Vlib/box.c

@@ -5,7 +5,7 @@
 
    Higher level functions for reading/writing/manipulating vectors.
 
-   (C) 2001-2009 by the GRASS Development Team
+   (C) 2001-2015 by the GRASS Development Team
 
    This program is free software under the 
    GNU General Public License (>=v2). 
@@ -20,13 +20,30 @@
 #include <grass/glocale.h>
 
 /*!
-   \brief Tests for point in box
-
-   \param x,y,z coordinates
-   \param Box boundary box
-
-   \return 1 point is in box
-   \return 0 point is not in box
+    \brief Tests if point is in 3D box
+
+    This function considers 3D point and 3D bounding box.
+
+    \par Example
+
+    \verbatim
+    struct bound_box bbox;
+    bbox.N = 135;
+    bbox.S = 125;
+    bbox.E = 220;
+    bbox.W = 215;
+    bbox.T = 340;
+    bbox.B = 330;
+    Vect_point_in_box(217, 130, 335, &bbox);
+    \endverbatim
+
+    \param x coordinate (W-E direction)
+    \param y coordinate (S-N direction)
+    \param z coordinate (B-T direction)
+    \param Box boundary box
+
+    \returns 1 if point is in box
+    \returns 0 if point is not in box
  */
 int Vect_point_in_box(double x, double y, double z, const struct bound_box *Box)
 {
@@ -37,6 +54,25 @@ int Vect_point_in_box(double x, double y, double z, const struct bound_box *Box)
 }
 
 /*!
+    \brief Tests if point is in 2D box
+
+    Only x and y are tested. Top and bottom of the bounding box are ignored.
+
+    \param x coordinate (W-E direction)
+    \param y coordinate (S-N direction)
+    \param Box boundary box (only W, E, S, N are used)
+
+    \returns 1 if point is in box
+    \returns 0 if point is not in box
+ */
+int Vect_point_in_box_2d(double x, double y, const struct bound_box *Box)
+{
+
+    return (x >= Box->W && x <= Box->E &&
+            y >= Box->S && y <= Box->N);
+}
+
+/*!
    \brief Tests for overlap of two boxes
 
    \param A boundary box A

lib/vector/Vlib/testsuite/test_vlib_box.py

@@ -0,0 +1,86 @@
+"""
+TEST:      box.c
+
+AUTHOR(S): Vaclav Petras
+
+PURPOSE:   Test functions related to bounding box
+
+COPYRIGHT: (C) 2015 Vaclav Petras, and by the GRASS Development Team
+
+           This program is free software under the GNU General Public
+           License (>=v2). Read the file COPYING that comes with GRASS
+           for details.
+"""
+
+import ctypes
+import grass.lib.vector as libvect
+
+from grass.gunittest.case import TestCase
+from grass.gunittest.main import test
+
+
+class TestPointInBoundingBox(TestCase):
+    """Test functions related to point in bounding box"""
+
+    def setUp(self):
+        """Create bbox object"""
+        self.c_bbox = ctypes.pointer(libvect.bound_box())
+        # x range
+        self.c_bbox.contents.E = 220
+        self.c_bbox.contents.W = 215
+        # y range
+        self.c_bbox.contents.N = 135
+        self.c_bbox.contents.S = 125
+        # z range
+        self.c_bbox.contents.T = 340
+        self.c_bbox.contents.B = 330
+
+    def test_bbox_3d_in(self):
+        """Check Vect_point_in_box() function with 3D points inside bbox"""
+        self.check_point_in_3d(217, 130, 335)
+        self.check_point_in_3d(219.999999, 125.000001, 339.999999)
+
+    def test_bbox_3d_out(self):
+        """Check Vect_point_in_box() function with 3D points outside bbox"""
+        self.check_point_out_3d(100, 100, 100)
+        self.check_point_out_3d(500, 593, 900)
+        self.check_point_out_3d(-220, 130, 335)
+        self.check_point_out_3d(220, -130, 335)
+        self.check_point_out_3d(220, 130, -335)
+
+    def check_point_in_3d(self, x, y, z):
+        """Wraps Vect_point_in_box() with assert and a message"""
+        self.assertTrue(libvect.Vect_point_in_box(x, y, z, self.c_bbox),
+                        msg="Point should be inside the bbox")
+
+    def check_point_out_3d(self, x, y, z):
+        """Wraps Vect_point_in_box() with assert and a message"""
+        self.assertFalse(libvect.Vect_point_in_box(x, y, z, self.c_bbox),
+                         msg="Point should be outside the bbox")
+
+    def test_bbox_2d_in(self):
+        """Check Vect_point_in_box_2d() function with 2D points inside bbox"""
+        self.check_point_in_2d(217, 130)
+        self.check_point_in_2d(219.999999, 125.000001)
+
+    def test_bbox_2d_out(self):
+        """Check Vect_point_in_box_2d() function with 2D points outside bbox"""
+        self.check_point_out_2d(100, 100)
+        self.check_point_out_2d(500, 593)
+        self.check_point_out_2d(-220, 130)
+        self.check_point_out_2d(220, -130)
+        self.check_point_out_2d(-220, -130)
+
+    def check_point_in_2d(self, x, y):
+        """Wraps Vect_point_in_box_2d() with assert, message and bbox"""
+        self.assertTrue(libvect.Vect_point_in_box_2d(x, y, self.c_bbox),
+                        msg="Point should be inside the bbox")
+
+    def check_point_out_2d(self, x, y):
+        """Wraps Vect_point_in_box_2d() with assert, message and bbox"""
+        self.assertFalse(libvect.Vect_point_in_box_2d(x, y, self.c_bbox),
+                         msg="Point should be outside the bbox")
+
+
+if __name__ == '__main__':
+    test()