Feat: Make matplotlib optional (#366)

Author: ajhynes7

HISTORY.rst

@@ -2,12 +2,28 @@
 History
 =======
 
+9.0.1 (2025-04-16)
+------------------
+
+Docs
+~~~~
+- Include single quotes in command: `pip install 'scikit-spatial[plotting]'`
+
+
+9.0.0 (2025-04-16)
+------------------
+
+Breaking Changes
+~~~~~~~~~~~~~~~~
+- Make matplotlib an optional dependency. It can be installed by `pip install 'scikit-spatial[plotting]'`
+
+
 8.1.0 (2024-12-23)
 ------------------
 
 Features
 ~~~~~~~~
-- Add optiont to return error for line and plane of best fit.
+- Add option to return error for line and plane of best fit.
 
 
 8.0.0 (2024-10-03)

README.md

@@ -150,6 +150,13 @@ $ conda install scikit-spatial -c conda-forge
 
 ```
 
+The `matplotlib` dependency is optional. To enable plotting, you can install scikit-spatial with the extra `plotting`.
+
+```bash
+   $ pip install 'scikit-spatial[plotting]'
+
+```
+
 # Example Usage
 
 ## Measurement

docs/source/plotting.rst

@@ -6,6 +6,13 @@ Plotting
 
 This library uses ``matplotlib`` to enable plotting of all of its spatial objects. Each object has a ``plot_2d`` and/or ``plot_3d`` method. For example, a :class:`Point` object can be plotted in 2D or 3D, while a :class:`Sphere` object can only be plotted in 3D.
 
+The ``matplotlib`` dependency is optional. To install it, you can install scikit-spatial with the extra `plotting`.
+
+.. code-block:: console
+
+   $ pip install 'scikit-spatial[plotting]'
+
+
 The ``plot_2d`` methods require an instance of :class:`~matplotlib.axes.Axes` as the first argument, while the ``plot_3d`` methods require an instance of :class:`~mpl_toolkits.mplot3d.axes3d.Axes3D`. This allows for placing multiple spatial objects on the same plot, which is useful for visualizing computations such as projection or intersection.
 
 The methods also pass keyword arguments to ``matplotlib`` functions. For example, ``Point.plot_2d`` uses :meth:`~matplotlib.axes.Axes.scatter` under the hood, so any keyword arguments to :meth:`~matplotlib.axes.Axes.scatter` can also be input to the method. Some plotting methods have additional keyword arguments that are not passed to ``matplotlib``, such as ``Line.plot_2d``, which takes parameters ``t_1`` and ``t_2`` to determine the start and end points of the line.

docs/source/requirements.txt

@@ -1,6 +1,6 @@
 Sphinx==5.3.0
 numpydoc==1.5.0
-scikit-spatial==8.1.0
+scikit-spatial[plotting]==9.0.1
 setuptools==70.0.0
 sphinx-bootstrap-theme==0.8.1
 sphinx-gallery==0.9.0

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "scikit-spatial"
-version = "8.1.0"
+version = "9.0.1"
 description = "Spatial objects and computations based on NumPy arrays."
 
 license = { text = "BSD-3-Clause" }
@@ -31,13 +31,15 @@ classifiers = [
 requires-python = ">=3.8"
 
 dependencies = [
-    "matplotlib>=3",
     "numpy>1.24; python_version >= '3.12'",
     "numpy>=1; python_version < '3.12'",
     "scipy>1.11; python_version >= '3.12'",
     "scipy>=1; python_version < '3.12'",
 ]
 
+[project.optional-dependencies]
+plotting = ["matplotlib>=3"]
+
 [project.urls]
 repository = "https://github.com/ajhynes7/scikit-spatial"
 documentation = "https://scikit-spatial.readthedocs.io"

src/skspatial/objects/_base_sphere.py

@@ -1,5 +1,7 @@
 """Module for base class of Circle and Sphere."""
 
+from typing import cast
+
 import numpy as np
 
 from skspatial._functions import _contains_point
@@ -85,4 +87,4 @@ def project_point(self, point: array_like) -> Point:
 
         vector_to_point = Vector.from_points(self.point, point)
 
-        return self.point + self.radius * vector_to_point.unit()
+        return cast(Point, self.point + self.radius * vector_to_point.unit())

src/skspatial/objects/circle.py

@@ -5,9 +5,7 @@
 import math
 from typing import Tuple, cast
 
-import matplotlib.pyplot as plt
 import numpy as np
-from matplotlib.axes import Axes
 
 from skspatial._functions import np_float
 from skspatial.objects._base_sphere import _BaseSphere
@@ -368,8 +366,8 @@ def intersect_line(self, line: Line) -> Tuple[Point, Point]:
         point_2 = point_1 + line.direction.unit()
 
         # Translate the points on the line to mimic the circle being centered on the origin.
-        point_translated_1: Point = point_1 - self.point
-        point_translated_2: Point = point_2 - self.point
+        point_translated_1 = point_1 - self.point
+        point_translated_2 = point_2 - self.point
 
         x_1, y_1 = point_translated_1
         x_2, y_2 = point_translated_2
@@ -465,7 +463,7 @@ def best_fit(cls, points: array_like) -> Circle:
 
         return cls(center, radius)
 
-    def plot_2d(self, ax_2d: Axes, **kwargs) -> None:
+    def plot_2d(self, ax_2d, **kwargs) -> None:
         """
         Plot the circle in 2D.
 
@@ -493,6 +491,8 @@ def plot_2d(self, ax_2d: Axes, **kwargs) -> None:
             >>> limits = plt.axis([-10, 10, -10, 10])
 
         """
+        import matplotlib.pyplot as plt
+
         circle = plt.Circle(tuple(self.point), self.radius, **kwargs)
 
         ax_2d.add_artist(circle)

src/skspatial/objects/cylinder.py

@@ -7,7 +7,6 @@
 from typing import List, Optional, Tuple, cast
 
 import numpy as np
-from mpl_toolkits.mplot3d import Axes3D
 from scipy.optimize import minimize
 
 from skspatial._functions import _solve_quadratic
@@ -639,7 +638,7 @@ def _spherical_to_cartesian(spherical_coordinates: _SphericalCoordinates) -> Vec
 
         return cls(point_a, vector_ab, radius)
 
-    def plot_3d(self, ax_3d: Axes3D, n_along_axis: int = 100, n_angles: int = 30, **kwargs) -> None:
+    def plot_3d(self, ax_3d, n_along_axis: int = 100, n_angles: int = 30, **kwargs) -> None:
         """
         Plot a 3D cylinder.
 

src/skspatial/objects/line.py

@@ -5,14 +5,11 @@
 from typing import Optional, cast
 
 import numpy as np
-from matplotlib.axes import Axes
-from mpl_toolkits.mplot3d import Axes3D
 
 from skspatial.objects._base_line_plane import _BaseLinePlane
 from skspatial.objects.point import Point
 from skspatial.objects.points import Points
 from skspatial.objects.vector import Vector
-from skspatial.plotting import _connect_points_2d, _connect_points_3d
 from skspatial.transformation import transform_coordinates
 from skspatial.typing import array_like
 
@@ -265,7 +262,7 @@ def to_point(self, t: float = 1) -> Point:
         """
         vector_along_line = t * self.direction
 
-        return self.point + vector_along_line
+        return cast(Point, self.point + vector_along_line)
 
     def project_point(self, point: array_like) -> Point:
         """
@@ -787,7 +784,7 @@ def transform_points(self, points: array_like) -> np.ndarray:
 
         return column.flatten()
 
-    def plot_2d(self, ax_2d: Axes, t_1: float = 0, t_2: float = 1, **kwargs) -> None:
+    def plot_2d(self, ax_2d, t_1: float = 0, t_2: float = 1, **kwargs) -> None:
         """
         Plot a 2D line.
 
@@ -821,12 +818,14 @@ def plot_2d(self, ax_2d: Axes, t_1: float = 0, t_2: float = 1, **kwargs) -> None
             >>> grid = ax.grid()
 
         """
+        from skspatial.plotting import _connect_points_2d
+
         point_1 = self.to_point(t_1)
         point_2 = self.to_point(t_2)
 
         _connect_points_2d(ax_2d, point_1, point_2, **kwargs)
 
-    def plot_3d(self, ax_3d: Axes3D, t_1: float = 0, t_2: float = 1, **kwargs) -> None:
+    def plot_3d(self, ax_3d, t_1: float = 0, t_2: float = 1, **kwargs) -> None:
         """
         Plot a 3D line.
 
@@ -862,6 +861,8 @@ def plot_3d(self, ax_3d: Axes3D, t_1: float = 0, t_2: float = 1, **kwargs) -> No
             >>> line.point.plot_3d(ax, s=100)
 
         """
+        from skspatial.plotting import _connect_points_3d
+
         point_1 = self.to_point(t_1)
         point_2 = self.to_point(t_2)
 

src/skspatial/objects/line_segment.py

@@ -5,14 +5,11 @@
 import math
 
 import numpy as np
-from matplotlib.axes import Axes
-from mpl_toolkits.mplot3d import Axes3D
 
 from skspatial.objects._base_spatial import _BaseSpatial
 from skspatial.objects.line import Line
 from skspatial.objects.point import Point
 from skspatial.objects.vector import Vector
-from skspatial.plotting import _connect_points_2d, _connect_points_3d
 from skspatial.typing import array_like
 
 
@@ -157,7 +154,7 @@ def intersect_line_segment(self, other: LineSegment, **kwargs) -> Point:
 
         return point_intersection
 
-    def plot_2d(self, ax_2d: Axes, **kwargs) -> None:
+    def plot_2d(self, ax_2d, **kwargs) -> None:
         """
         Plot a 2D line segment.
 
@@ -190,9 +187,11 @@ def plot_2d(self, ax_2d: Axes, **kwargs) -> None:
             >>> grid = ax.grid()
 
         """
+        from skspatial.plotting import _connect_points_2d
+
         _connect_points_2d(ax_2d, self.point_a, self.point_b, **kwargs)
 
-    def plot_3d(self, ax_3d: Axes3D, **kwargs) -> None:
+    def plot_3d(self, ax_3d, **kwargs) -> None:
         """
         Plot a 3D line segment.
 
@@ -226,4 +225,6 @@ def plot_3d(self, ax_3d: Axes3D, **kwargs) -> None:
             >>> segment.plot_3d(ax, c='k')
 
         """
+        from skspatial.plotting import _connect_points_3d
+
         _connect_points_3d(ax_3d, self.point_a, self.point_b, **kwargs)