.. figure:: images/logo.svg
:align: left
:width: 70%
.. image:: https://img.shields.io/pypi/v/scikit-spatial.svg
:target: https://pypi.python.org/pypi/scikit-spatial
.. image:: https://anaconda.org/conda-forge/scikit-spatial/badges/version.svg
:target: https://anaconda.org/conda-forge/scikit-spatial
.. image:: https://img.shields.io/pypi/pyversions/scikit-spatial.svg
:target: https://pypi.python.org/pypi/scikit-spatial
.. image:: https://github.com/ajhynes7/scikit-spatial/actions/workflows/main.yml/badge.svg
:target: https://github.com/ajhynes7/scikit-spatial/actions/workflows/main.yml
.. image:: https://results.pre-commit.ci/badge/github/ajhynes7/scikit-spatial/master.svg
:target: https://results.pre-commit.ci/latest/github/ajhynes7/scikit-spatial/master
:alt: pre-commit.ci status
.. image:: https://readthedocs.org/projects/scikit-spatial/badge/?version=latest
:target: https://scikit-spatial.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://codecov.io/gh/ajhynes7/scikit-spatial/branch/master/graph/badge.svg
:target: https://codecov.io/gh/ajhynes7/scikit-spatial
|
Introduction
------------
This package provides spatial objects based on NumPy arrays, as well as computations using these objects. The package includes computations for 2D, 3D, and higher-dimensional space.
The following spatial objects are provided:
- Point
- Points
- Vector
- Line
- LineSegment
- Plane
- Circle
- Sphere
- Triangle
- Cylinder
Most of the computations fall into the following categories:
- Measurement
- Comparison
- Projection
- Intersection
- Fitting
- Transformation
All spatial objects are equipped with plotting methods based on ``matplotlib``. Both 2D and 3D plotting are supported. Spatial computations can be easily visualized by plotting multiple objects at once.
Why this instead of ``scipy.spatial`` or ``sympy.geometry``?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This package has little to no overlap with the functionality of ``scipy.spatial``. It can be viewed as an object-oriented extension.
While similar spatial objects and computations exist in the ``sympy.geometry`` module, ``scikit-spatial`` is based on NumPy rather than symbolic math. The primary objects of ``scikit-spatial`` (``Point``, ``Points``, and ``Vector``) are actually subclasses of the NumPy *ndarray*. This gives them all the regular functionality of the *ndarray*, plus additional methods from this package.
>>> from skspatial.objects import Vector
>>> vector = Vector([2, 0, 0])
Behaviour inherited from NumPy:
>>> vector.size
3
>>> vector.mean().round(3)
0.667
Additional methods from ``scikit-spatial``:
>>> vector.norm()
2.0
>>> vector.unit()
Vector([1., 0., 0.])
``Point`` and ``Vector`` are based on a 1D NumPy array, and ``Points`` is based on a 2D NumPy array, where each row represents a point in space. The ``Line`` and ``Plane`` objects have ``Point`` and ``Vector`` objects as attributes.
Note that most methods inherited from NumPy return a regular *ndarray*, instead of the spatial object class.
>>> vector.sum()
array(2)
This is to avoid getting a spatial object with a forbidden shape, like a zero dimension ``Vector``. Trying to convert this back to a ``Vector`` causes an exception.
>>> Vector(vector.sum())
Traceback (most recent call last):
...
ValueError: The array must be 1D.
Because the computations of ``scikit-spatial`` are also based on NumPy, keyword arguments can be passed to NumPy functions. For example, a tolerance can be specified while testing for collinearity. The ``tol`` keyword is passed to ``numpy.linalg.matrix_rank``.
>>> from skspatial.objects import Points
>>> points = Points([[1, 2, 3], [4, 5, 6], [7, 8, 8]])
>>> points.are_collinear()
False
>>> points.are_collinear(tol=1)
True
Installation
------------
The package can be installed with pip.
.. code-block:: bash
$ pip install scikit-spatial
It can also be installed with conda.
.. code-block:: bash
$ conda install scikit-spatial -c conda-forge
Example Usage
-------------
Measurement
~~~~~~~~~~~
Measure the cosine similarity between two vectors.
>>> from skspatial.objects import Vector
>>> Vector([1, 0]).cosine_similarity([1, 1]).round(3)
0.707
Comparison
~~~~~~~~~~
Check if multiple points are collinear.
>>> from skspatial.objects import Points
>>> points = Points([[1, 2, 3, 4], [5, 6, 7, 8], [9, 10, 11, 12]])
>>> points.are_collinear()
True
Projection
~~~~~~~~~~
Project a point onto a line.
>>> from skspatial.objects import Line
>>> line = Line(point=[0, 0, 0], direction=[1, 1, 0])
>>> line.project_point([5, 6, 7])
Point([5.5, 5.5, 0. ])
Intersection
~~~~~~~~~~~~
Find the intersection of two planes.
>>> from skspatial.objects import Plane
>>> plane_a = Plane(point=[0, 0, 0], normal=[0, 0, 1])
>>> plane_b = Plane(point=[5, 16, -94], normal=[1, 0, 0])
>>> plane_a.intersect_plane(plane_b)
Line(point=Point([5., 0., 0.]), direction=Vector([0, 1, 0]))
An error is raised if the computation is undefined.
>>> plane_b = Plane(point=[0, 0, 1], normal=[0, 0, 1])
>>> plane_a.intersect_plane(plane_b)
Traceback (most recent call last):
...
ValueError: The planes must not be parallel.
Fitting
~~~~~~~
Find the plane of best fit for multiple points.
>>> points = [[0, 0, 0], [1, 0, 0], [0, 1, 0], [1, 1, 0]]
>>> Plane.best_fit(points)
Plane(point=Point([0.5, 0.5, 0. ]), normal=Vector([0., 0., 1.]))
Transformation
~~~~~~~~~~~~~~
Transform multiple points to 1D coordinates along a line.
>>> line = Line(point=[0, 0, 0], direction=[1, 2, 0])
>>> points = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
>>> line.transform_points(points).round(3)
array([ 2.236, 6.261, 10.286])
Acknowledgment
--------------
This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.
.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
Raw data
{
"_id": null,
"home_page": "https://github.com/ajhynes7/scikit-spatial",
"name": "scikit-spatial",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<3.13",
"maintainer_email": "",
"keywords": "NumPy,matplotlib,visualization,spatial,linear algebra",
"author": "Andrew Hynes",
"author_email": "andrewjhynes@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/8c/f8/f717434379f527d62d1b37a5a27872eca4add895057992a0dc88a72cbf17/scikit_spatial-7.2.0.tar.gz",
"platform": null,
"description": "\n.. figure:: images/logo.svg\n :align: left\n :width: 70%\n\n.. image:: https://img.shields.io/pypi/v/scikit-spatial.svg\n :target: https://pypi.python.org/pypi/scikit-spatial\n\n.. image:: https://anaconda.org/conda-forge/scikit-spatial/badges/version.svg\n :target: https://anaconda.org/conda-forge/scikit-spatial\n\n.. image:: https://img.shields.io/pypi/pyversions/scikit-spatial.svg\n :target: https://pypi.python.org/pypi/scikit-spatial\n\n.. image:: https://github.com/ajhynes7/scikit-spatial/actions/workflows/main.yml/badge.svg\n :target: https://github.com/ajhynes7/scikit-spatial/actions/workflows/main.yml\n\n.. image:: https://results.pre-commit.ci/badge/github/ajhynes7/scikit-spatial/master.svg\n :target: https://results.pre-commit.ci/latest/github/ajhynes7/scikit-spatial/master\n :alt: pre-commit.ci status\n\n.. image:: https://readthedocs.org/projects/scikit-spatial/badge/?version=latest\n :target: https://scikit-spatial.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\n.. image:: https://codecov.io/gh/ajhynes7/scikit-spatial/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/ajhynes7/scikit-spatial\n\n|\n\nIntroduction\n------------\n\nThis package provides spatial objects based on NumPy arrays, as well as computations using these objects. The package includes computations for 2D, 3D, and higher-dimensional space.\n\nThe following spatial objects are provided:\n\n - Point\n - Points\n - Vector\n - Line\n - LineSegment\n - Plane\n - Circle\n - Sphere\n - Triangle\n - Cylinder\n\nMost of the computations fall into the following categories:\n\n - Measurement\n - Comparison\n - Projection\n - Intersection\n - Fitting\n - Transformation\n\nAll spatial objects are equipped with plotting methods based on ``matplotlib``. Both 2D and 3D plotting are supported. Spatial computations can be easily visualized by plotting multiple objects at once.\n\n\nWhy this instead of ``scipy.spatial`` or ``sympy.geometry``?\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThis package has little to no overlap with the functionality of ``scipy.spatial``. It can be viewed as an object-oriented extension.\n\nWhile similar spatial objects and computations exist in the ``sympy.geometry`` module, ``scikit-spatial`` is based on NumPy rather than symbolic math. The primary objects of ``scikit-spatial`` (``Point``, ``Points``, and ``Vector``) are actually subclasses of the NumPy *ndarray*. This gives them all the regular functionality of the *ndarray*, plus additional methods from this package.\n\n>>> from skspatial.objects import Vector\n\n>>> vector = Vector([2, 0, 0])\n\nBehaviour inherited from NumPy:\n\n>>> vector.size\n3\n>>> vector.mean().round(3)\n0.667\n\nAdditional methods from ``scikit-spatial``:\n\n>>> vector.norm()\n2.0\n>>> vector.unit()\nVector([1., 0., 0.])\n\n``Point`` and ``Vector`` are based on a 1D NumPy array, and ``Points`` is based on a 2D NumPy array, where each row represents a point in space. The ``Line`` and ``Plane`` objects have ``Point`` and ``Vector`` objects as attributes.\n\nNote that most methods inherited from NumPy return a regular *ndarray*, instead of the spatial object class.\n\n>>> vector.sum()\narray(2)\n\nThis is to avoid getting a spatial object with a forbidden shape, like a zero dimension ``Vector``. Trying to convert this back to a ``Vector`` causes an exception.\n\n>>> Vector(vector.sum())\nTraceback (most recent call last):\n...\nValueError: The array must be 1D.\n\n\nBecause the computations of ``scikit-spatial`` are also based on NumPy, keyword arguments can be passed to NumPy functions. For example, a tolerance can be specified while testing for collinearity. The ``tol`` keyword is passed to ``numpy.linalg.matrix_rank``.\n\n>>> from skspatial.objects import Points\n\n>>> points = Points([[1, 2, 3], [4, 5, 6], [7, 8, 8]])\n\n>>> points.are_collinear()\nFalse\n>>> points.are_collinear(tol=1)\nTrue\n\n\n\nInstallation\n------------\n\nThe package can be installed with pip.\n\n.. code-block:: bash\n\n $ pip install scikit-spatial\n\n\nIt can also be installed with conda.\n\n.. code-block:: bash\n\n $ conda install scikit-spatial -c conda-forge\n\n\nExample Usage\n-------------\n\nMeasurement\n~~~~~~~~~~~\n\nMeasure the cosine similarity between two vectors.\n\n>>> from skspatial.objects import Vector\n\n>>> Vector([1, 0]).cosine_similarity([1, 1]).round(3)\n0.707\n\n\nComparison\n~~~~~~~~~~\n\nCheck if multiple points are collinear.\n\n>>> from skspatial.objects import Points\n\n>>> points = Points([[1, 2, 3, 4], [5, 6, 7, 8], [9, 10, 11, 12]])\n\n>>> points.are_collinear()\nTrue\n\n\nProjection\n~~~~~~~~~~\n\nProject a point onto a line.\n\n>>> from skspatial.objects import Line\n\n>>> line = Line(point=[0, 0, 0], direction=[1, 1, 0])\n\n>>> line.project_point([5, 6, 7])\nPoint([5.5, 5.5, 0. ])\n\n\nIntersection\n~~~~~~~~~~~~\n\nFind the intersection of two planes.\n\n>>> from skspatial.objects import Plane\n\n>>> plane_a = Plane(point=[0, 0, 0], normal=[0, 0, 1])\n>>> plane_b = Plane(point=[5, 16, -94], normal=[1, 0, 0])\n\n>>> plane_a.intersect_plane(plane_b)\nLine(point=Point([5., 0., 0.]), direction=Vector([0, 1, 0]))\n\n\nAn error is raised if the computation is undefined.\n\n>>> plane_b = Plane(point=[0, 0, 1], normal=[0, 0, 1])\n\n>>> plane_a.intersect_plane(plane_b)\nTraceback (most recent call last):\n...\nValueError: The planes must not be parallel.\n\n\nFitting\n~~~~~~~\n\nFind the plane of best fit for multiple points.\n\n>>> points = [[0, 0, 0], [1, 0, 0], [0, 1, 0], [1, 1, 0]]\n\n>>> Plane.best_fit(points)\nPlane(point=Point([0.5, 0.5, 0. ]), normal=Vector([0., 0., 1.]))\n\n\nTransformation\n~~~~~~~~~~~~~~\n\nTransform multiple points to 1D coordinates along a line.\n\n>>> line = Line(point=[0, 0, 0], direction=[1, 2, 0])\n>>> points = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]\n\n>>> line.transform_points(points).round(3)\narray([ 2.236, 6.261, 10.286])\n\n\nAcknowledgment\n--------------\n\nThis package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.\n\n.. _Cookiecutter: https://github.com/audreyr/cookiecutter\n.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Spatial objects and computations based on NumPy arrays.",
"version": "7.2.0",
"project_urls": {
"Documentation": "https://scikit-spatial.readthedocs.io",
"Homepage": "https://github.com/ajhynes7/scikit-spatial",
"Repository": "https://github.com/ajhynes7/scikit-spatial"
},
"split_keywords": [
"numpy",
"matplotlib",
"visualization",
"spatial",
"linear algebra"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fb32a8f105076916aea411dca698302b2af1d9a0f6830fb4e20f765028146945",
"md5": "49b67f12a57a0196855dd08eb9ea0b4c",
"sha256": "f5ac268667dcfeb71df0e137f9fcdd3c0a5c75ec5b722fcd33119c5145ddf148"
},
"downloads": -1,
"filename": "scikit_spatial-7.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "49b67f12a57a0196855dd08eb9ea0b4c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<3.13",
"size": 49051,
"upload_time": "2024-02-13T01:29:10",
"upload_time_iso_8601": "2024-02-13T01:29:10.204718Z",
"url": "https://files.pythonhosted.org/packages/fb/32/a8f105076916aea411dca698302b2af1d9a0f6830fb4e20f765028146945/scikit_spatial-7.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8cf8f717434379f527d62d1b37a5a27872eca4add895057992a0dc88a72cbf17",
"md5": "674dc3592f06b464f656f5096abbe577",
"sha256": "ccc85dda61fd1cb76c66cbd772e285fac40f593a0189852083af73598e7646f6"
},
"downloads": -1,
"filename": "scikit_spatial-7.2.0.tar.gz",
"has_sig": false,
"md5_digest": "674dc3592f06b464f656f5096abbe577",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<3.13",
"size": 37252,
"upload_time": "2024-02-13T01:29:12",
"upload_time_iso_8601": "2024-02-13T01:29:12.066835Z",
"url": "https://files.pythonhosted.org/packages/8c/f8/f717434379f527d62d1b37a5a27872eca4add895057992a0dc88a72cbf17/scikit_spatial-7.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-13 01:29:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ajhynes7",
"github_project": "scikit-spatial",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "scikit-spatial"
}
JSON
