.. _spheres:

Spheres and circles
===================

A :py:class:`~ddg.geometry.spheres.Sphere` of dimension :math:`k` is initialized by its center, radius and an (optional) :math:`k+1` dimensional :py:class:`~ddg.geometry.subspaces.Subspace`.


Spheres can be defined in any dimension and in any Cayley-Klein geometry. If neither a ``subspace`` nor a ``geometry`` is given at initialization, we
get by default a hypersphere in Euclidean geometry.

Since we consider spheres to be lying in :math:`\mathbb{K}\mathrm P^n`, our points are always given in homogeneous coordinates.

.. doctest::

    >>> import ddg
    >>> import numpy as np
    >>> from ddg.geometry.spheres import Sphere

    >>> center = np.array([0.0, 4.0, 2.0, 0.0, 8.0])
    >>> sphere = Sphere(center, 10.0)

    >>> print(sphere)
    Hypersphere in 4D Euclidean Geometry
    Center: [0. 4. 2. 0. 8.],
    Radius: 10.0.

    >>> sphere.dimension
    3


After initialization, the geometry of sphere can be changed to any :py:class:`~ddg.geometry.geometries.CayleyKleinGeometry` using method ``set_geometry``

.. doctest::

    >>> sphere.set_geometry("hyperbolic")

    >>> print(sphere)
    Hypersphere in 4D Hyperbolic Geometry
    Center: [0. 4. 2. 0. 8.],
    Radius: 10.0.


Here is another example where we initialize a Circle in :math:`\mathbb{R}\mathrm P^4`

.. doctest::

    >>> P1 = np.array([12.0, 0.0, 1.0, 0.0, 9.0])
    >>> P2 = np.array([0.0, 23.0, 0.0, 0.0, 1.0])
    >>> P3 = np.array([1.0, 5.0, 4.0, 7.0, 21.0])
    >>> center = P1 - P3
    >>> circle = Sphere(center, 10.0, subspace=[P1, P2, P3])

    >>> print(circle)
    Circle in 4D Euclidean Geometry
    Center: [ 11.  -5.  -3.  -7. -12.],
    Radius: 10.0,
    Subspace coordinates:
      [[12.  0.  1.]
       [ 0. 23.  5.]
       [ 1.  0.  4.]
       [ 0.  0.  7.]
       [ 9.  1. 21.]]

    >>> circle.dimension
    1


Visualization in Blender
------------------------

A guide on how to visualize ddg objects, including spheres can be found :ref:`here <to_blender_object>` .