feat: add boolean within

README.md

@@ -56,6 +56,8 @@ It supports below features:
 
 - [Boolean](https://github.com/omanges/turfpy/blob/master/boolean.md)
 
+- [Joins](https://github.com/omanges/turfpy/blob/master/joins.md)
+
 ## Documentation
 
 Documentation can be found at: [docs](https://turfpy.readthedocs.io/en/latest/)

boolean.md

@@ -38,4 +38,36 @@ from turfpy.boolean import boolean_intersects
 feature_1 = Feature(geometry=Point((19.0760, 72.8777)))
 feature_2 = Feature(geometry=Point((29.0760, 72.8777)))
 boolean_intersects(feature_1, feature_2)
+```
+
+* boolean_within : Takes two features and returns (TRUE) if the intersection of the two geometries is NOT an empty set.
+
+| Argument| Type | Description|
+| -------   |------ | ----------- |
+| `feature_1`  |Feature  | Feature 1 |
+| `feature_2`  |Feature  | Feature 2 |
+
+| Return  | Type | Description |
+| ------- | ------ | ----------- |
+| `bool`  | bool  | Return true or false |
+
+```python
+from geojson import Feature, Point, Polygon
+from turfpy.boolean import boolean_within
+
+poly = Polygon(
+    [
+        [
+            (1, 1),
+            (1, 10),
+            (10, 10),
+            (10, 1),
+            (1, 1)
+        ]
+    ]
+)
+
+feature_1 = Feature(geometry=Point((4, 4)))
+feature_2 = Feature(geometry=poly)
+boolean_within(feature_1, feature_2)
 ```

docs/source/boolean/boolean_within.rst

@@ -0,0 +1,28 @@
+Boolean Within 
+==============
+Boolean-within returns true if the first geometry is completely within the second geometry. The interiors of both geometries must intersect and, the interior and boundary of the primary (geometry a) must not intersect the exterior of the secondary (geometry b).
+
+Example
+-------
+
+.. jupyter-execute::
+
+    from geojson import Feature, Point, Polygon
+    from turfpy.boolean import boolean_within
+
+    poly = Polygon(
+        [
+            [
+                (1, 1),
+                (1, 10),
+                (10, 10),
+                (10, 1),
+                (1, 1)
+            ]
+        ]
+    )
+
+    feature_1 = Feature(geometry=Point((4, 4)))
+    feature_2 = Feature(geometry=poly)
+    boolean_within(feature_1, feature_2)
+

docs/source/index.rst

@@ -70,6 +70,12 @@ A Python library for performing geospatial data analysis which reimplements `tur
   Boolean Disjoint <boolean/boolean_disjoint>
   Boolean Intersects <boolean/boolean_intersects>
 
+  .. toctree::
+  :maxdepth: 1
+  :caption: Joins
+
+  Points Within Polygon <joins/points_within_polygon>
+
 .. toctree::
   :maxdepth: 1
   :caption: Feature Conversion

docs/source/measurements/points_within_polygon.rst → docs/source/joins/points_within_polygon.rst

@@ -9,7 +9,7 @@ Interactive Example
 .. jupyter-execute::
 
     from geojson import Feature, FeatureCollection, Point, Polygon
-    from turfpy.measurement import points_within_polygon
+    from turfpy.joins import points_within_polygon
     from ipyleaflet import Map, GeoJSON
 
     p1 = Feature(geometry=Point((-46.6318, -23.5523)))

docs/source/turfpy.joins.rst

@@ -0,0 +1,8 @@
+turfpy.joins module
+=========================
+
+.. automodule:: turfpy.joins
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:

examples/boolean.ipynb

@@ -51,6 +51,40 @@
     "feature_2 = Feature(geometry=Point((29.0760, 72.8777)))\n",
     "boolean_intersects(feature_1, feature_2)"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Boolean Within\n",
+    "Boolean-within returns true if the first geometry is completely within the second geometry. The interiors of both geometries must intersect and, the interior and boundary of the primary (geometry a) must not intersect the exterior of the secondary (geometry b)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from geojson import Feature, Point, Polygon\n",
+    "from turfpy.boolean import boolean_within\n",
+    "\n",
+    "poly = Polygon(\n",
+    "    [\n",
+    "        [\n",
+    "            (1, 1),\n",
+    "            (1, 10),\n",
+    "            (10, 10),\n",
+    "            (10, 1),\n",
+    "            (1, 1)\n",
+    "        ]\n",
+    "    ]\n",
+    ")\n",
+    "\n",
+    "feature_1 = Feature(geometry=Point((4, 4)))\n",
+    "feature_2 = Feature(geometry=poly)\n",
+    "boolean_within(feature_1, feature_2)"
+   ]
   }
  ],
  "metadata": {

examples/joins.ipynb

@@ -0,0 +1,57 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Joins\n",
+    "This notebook demonstrates all the examples of joins"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Points within Polygon\n",
+    "Finds Points or MultiPoint coordinate positions that fall within (Multi)Polygon(s)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from turfpy.joins import points_within_polygon\n",
+    "from geojson import Point, MultiPolygon, Feature\n",
+    "\n",
+    "point = Feature(geometry=Point([-77, 44]))\n",
+    "polygon = Feature(geometry=MultiPolygon([([(-81, 41), (-81, 47), (-72, 47), (-72, 41), (-81, 41)],),\n",
+    "([(3.78, 9.28), (-130.91, 1.52), (35.12, 72.234), (3.78, 9.28)],)]))\n",
+    "\n",
+    "points_within_polygon(point, polygon)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.10"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

examples/measurements.ipynb

@@ -316,28 +316,6 @@
     "point_on_feature(feature)"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Point In Polygon\n",
-    "Takes a Point or a Point Feature and Polygon or Polygon Feature as input and returns True if Point is in given Feature."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from turfpy.measurement import boolean_point_in_polygon\n",
-    "from geojson import Point, MultiPolygon, Feature\n",
-    "point = Feature(geometry=Point([-77, 44]))\n",
-    "polygon = Feature(geometry=MultiPolygon([([(-81, 41), (-81, 47), (-72, 47), (-72, 41), (-81, 41)],),\n",
-    "([(3.78, 9.28), (-130.91, 1.52), (35.12, 72.234), (3.78, 9.28)],)]))\n",
-    "boolean_point_in_polygon(point, polygon)"
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},

joins.md

@@ -0,0 +1,40 @@
+## Joins Examples :
+* points_within_polygon : Find Point(s) that fall within (Multi)Polygon(s).
+
+| Argument    | Type                                                     | Description                                    |
+| ------- |   ---------------------------------------------------------- | ---------------------------------------------- |
+| `points`    | Feature/FeatureCollection of Points                      | FeatureCollection of Points to find            |
+| `polygons`  | Feature/FeatureCollection of Polygon(s)/MultiPolygon(s)  | FeatureCollection of Polygon(s)/MultiPolygon(s)|
+| `chunk_size`  | int                                                    | Number of chunks each process to handle. The default value is 1, for a large number of features please use `chunk_size` greater than 1 to get better results in terms of performance.|
+
+| Return      | Type               | Description                                                       |
+| ----------- | ------------------ | ----------------------------------------------------------------- |
+| `points`    | FeatureCollection  | A FeatureCollection of Points in given Polygon(s)/MultiPolygon(s) |
+
+```python
+from geojson import Feature, FeatureCollection, Point, Polygon
+from turfpy.joins import points_within_polygon
+
+p1 = Feature(geometry=Point((-46.6318, -23.5523)))
+p2 = Feature(geometry=Point((-46.6246, -23.5325)))
+p3 = Feature(geometry=Point((-46.6062, -23.5513)))
+p4 = Feature(geometry=Point((-46.663, -23.554)))
+p5 = Feature(geometry=Point((-46.643, -23.557)))
+
+points = FeatureCollection([p1, p2, p3, p4, p5])
+
+poly = Polygon(
+    [
+        [
+            (-46.653, -23.543),
+            (-46.634, -23.5346),
+            (-46.613, -23.543),
+            (-46.614, -23.559),
+            (-46.631, -23.567),
+            (-46.653, -23.560),
+            (-46.653, -23.543),
+        ]
+    ]
+)
+result = points_within_polygon(points, FeatureCollection([poly]))
+```