Source code for dipy.core.subdivide_octahedron

"""Create a unit sphere by subdividing all triangles of an octahedron
recursively.

The unit sphere has a radius of 1, which also means that all points in this
sphere (assumed to have centre at [0, 0, 0]) have an absolute value (modulus)
of 1. Another feature of the unit sphere is that the unit normals of this
sphere are exactly the same as the vertices.

This recursive method will avoid the common problem of the polar singularity,
produced by 2d (lon-lat) parameterization methods.

"""

from dipy.core.sphere import HemiSphere, unit_octahedron
from dipy.testing.decorators import warning_for_keywords




@warning_for_keywords()
def create_unit_sphere(*, recursion_level=2):
    """Creates a unit sphere by subdividing a unit octahedron.

    Starts with a unit octahedron and subdivides the faces, projecting the
    resulting points onto the surface of a unit sphere.

    Parameters
    ----------
    recursion_level : int
        Level of subdivision, recursion_level=1 will return an octahedron,
        anything bigger will return a more subdivided sphere. The sphere will
        have $4^recursion_level+2$ vertices.

    Returns
    -------
    Sphere :
        The unit sphere.

    See Also
    --------
    create_unit_hemisphere, Sphere
    """
    if recursion_level > 7 or recursion_level < 1:
        raise ValueError("recursion_level must be between 1 and 7")
    return unit_octahedron.subdivide(n=recursion_level - 1)





@warning_for_keywords()
def create_unit_hemisphere(*, recursion_level=2):
    """Creates a unit sphere by subdividing a unit octahedron, returns half
    the sphere.

    Parameters
    ----------
    recursion_level : int
        Level of subdivision, recursion_level=1 will return an octahedron,
        anything bigger will return a more subdivided sphere. The sphere will
        have $(4^recursion_level+2)/2$ vertices.

    Returns
    -------
    HemiSphere :
        Half of a unit sphere.

    See Also
    --------
    create_unit_sphere, Sphere, HemiSphere
    """
    sphere = create_unit_sphere(recursion_level=recursion_level)
    return HemiSphere.from_sphere(sphere)