Merge pull request #249 from ajhynes7/add_cylinder_class

Add Cylinder class

.pre-commit-config.yaml

@@ -26,6 +26,7 @@ repos:
                 - flake8-comprehensions==3.3.0
                 - flake8-eradicate==1.0.0
                 - flake8-import-order==0.18.1
+                - flake8-rst-docstrings==0.0.14
     - repo: https://github.com/PyCQA/pydocstyle
       rev: 5.1.1
       hooks:

README.rst

@@ -36,6 +36,7 @@ The following spatial objects are provided:
    - Circle
    - Sphere
    - Triangle
+   - Cylinder
 
 Most of the computations fall into the following categories:
 

docs/source/api_reference/skspatial.objects.Cylinder.rst

@@ -0,0 +1,18 @@
+
+skspatial.objects.Cylinder
+==========================
+
+.. autoclass:: skspatial.objects.Cylinder
+
+
+Methods
+-------
+.. autosummary::
+   :toctree: Cylinder/methods
+
+   ~skspatial.objects.Cylinder.from_points
+   ~skspatial.objects.Cylinder.is_point_within
+   ~skspatial.objects.Cylinder.length
+   ~skspatial.objects.Cylinder.plot_3d
+   ~skspatial.objects.Cylinder.to_mesh
+   ~skspatial.objects.Cylinder.volume

docs/source/objects/cylinder.rst

@@ -0,0 +1,31 @@
+Cylinder
+--------
+
+A :class:`~skspatial.objects.Cylinder` object is defined by a point, a vector, and a radius.
+
+The point is the centre of the cylinder base. The vector is normal to the base, and the length of the cylinder is the length of this vector.
+The point and vector must be 3D.
+
+>>> from skspatial.objects import Cylinder
+
+>>> cylinder = Cylinder(point=[0, 0, 0], vector=[0, 0, 5], radius=1)
+
+>>> cylinder
+Cylinder(point=Point([0, 0, 0]), vector=Vector([0, 0, 5]), radius=1)
+
+>>> cylinder.length()
+5.0
+
+>>> cylinder.volume().round(3)
+15.708
+
+You can check if a point is inside (or on the surface of) the cylinder.
+
+>>> cylinder.is_point_within([0, 0, 0])
+True
+>>> cylinder.is_point_within([0, 0, 5])
+True
+>>> cylinder.is_point_within([1, 0, 3])
+True
+>>> cylinder.is_point_within([2, 0, 3])
+False

setup.cfg

@@ -20,6 +20,10 @@ exclude = __init__.py
 max-line-length = 120
 import-order-style = pycharm
 application-import-names = skspatial
+rst-directives =
+    autosummary,plot
+rst-roles =
+    class,func,meth
 
 [mypy]
 mypy_path = stubs

skspatial/objects/__init__.py

@@ -1,6 +1,7 @@
 """Package containing spatial objects."""
 
 from skspatial.objects.circle import Circle
+from skspatial.objects.cylinder import Cylinder
 from skspatial.objects.line import Line
 from skspatial.objects.plane import Plane
 from skspatial.objects.point import Point
@@ -9,4 +10,4 @@
 from skspatial.objects.triangle import Triangle
 from skspatial.objects.vector import Vector
 
-__all__ = ['Circle', 'Line', 'Plane', 'Point', 'Points', 'Sphere', 'Triangle', 'Vector']
+__all__ = ['Circle', 'Cylinder', 'Line', 'Plane', 'Point', 'Points', 'Sphere', 'Triangle', 'Vector']

skspatial/objects/_base_array.py

@@ -4,8 +4,8 @@
 
 import numpy as np
 
-from skspatial._base_spatial import _BaseSpatial
 from skspatial._functions import _allclose
+from skspatial.objects._base_spatial import _BaseSpatial
 from skspatial.typing import array_like
 
 

skspatial/objects/_base_line_plane.py

@@ -4,8 +4,8 @@
 
 import numpy as np
 
-from skspatial._base_spatial import _BaseSpatial
 from skspatial._functions import _contains_point, _sum_squares
+from skspatial.objects._base_spatial import _BaseSpatial
 from skspatial.objects.point import Point
 from skspatial.objects.vector import Vector
 from skspatial.typing import array_like

skspatial/objects/_base_sphere.py

@@ -2,8 +2,8 @@
 
 import numpy as np
 
-from skspatial._base_spatial import _BaseSpatial
 from skspatial._functions import _contains_point
+from skspatial.objects._base_spatial import _BaseSpatial
 from skspatial.objects.point import Point
 from skspatial.objects.vector import Vector
 from skspatial.typing import array_like
@@ -37,7 +37,7 @@ def distance_point(self, point: array_like) -> np.float64:
         return abs(distance_to_center - self.radius)
 
     def contains_point(self, point: array_like, **kwargs: float) -> bool:
-        """Check if the line/plane contains a point."""
+        """Check if the circle/sphere contains a point."""
         return _contains_point(self, point, **kwargs)
 
     def project_point(self, point: array_like) -> Point:

skspatial/objects/_mixins.py

@@ -0,0 +1,55 @@
+"""Mixin classes."""
+
+from typing import Callable, Tuple
+
+import numpy as np
+
+from skspatial._functions import _mesh_to_points
+from skspatial.objects.points import Points
+
+
+class _ToPointsMixin:
+
+    to_mesh: Callable[..., Tuple[np.ndarray, np.ndarray, np.ndarray]]
+
+    def to_points(self, **kwargs) -> Points:
+        """
+        Return points on the surface of the object.
+
+        Parameters
+        ----------
+        kwargs: dict, optional
+            Additional keywords passed to the `to_mesh` method of the class.
+
+        Returns
+        -------
+        Points
+            Points on the surface of the object.
+
+        Examples
+        --------
+        >>> from skspatial.objects import Sphere
+
+        >>> sphere = Sphere([0, 0, 0], 1)
+
+        >>> sphere.to_points(n_angles=3).round().unique()
+        Points([[ 0., -1.,  0.],
+                [ 0.,  0., -1.],
+                [ 0.,  0.,  1.],
+                [ 0.,  1.,  0.]])
+
+        >>> sphere.to_points(n_angles=4).round(3).unique()
+        Points([[-0.75 , -0.433, -0.5  ],
+                [-0.75 , -0.433,  0.5  ],
+                [ 0.   ,  0.   , -1.   ],
+                [ 0.   ,  0.   ,  1.   ],
+                [ 0.   ,  0.866, -0.5  ],
+                [ 0.   ,  0.866,  0.5  ],
+                [ 0.75 , -0.433, -0.5  ],
+                [ 0.75 , -0.433,  0.5  ]])
+
+        """
+        X, Y, Z = self.to_mesh(**kwargs)
+        points = _mesh_to_points(X, Y, Z)
+
+        return Points(points)

skspatial/objects/circle.py

@@ -244,7 +244,7 @@ def plot_2d(self, ax_2d: Axes, **kwargs) -> None:
         ax_2d : Axes
             Instance of :class:`~matplotlib.axes.Axes`.
         kwargs : dict, optional
-            Additional keywords passed to :Class:`matplotlib.patches.Circle`.
+            Additional keywords passed to :class:`matplotlib.patches.Circle`.
 
         Examples
         --------