"""
Basic objects such as Sphere, Box, Cone, etc.

AUTHORS:

- Robert Bradshaw 2007-02: initial version
- Robert Bradshaw 2007-08: obj/tachyon rendering, much updating
- Robert Bradshaw 2007-08: cythonization

EXAMPLES::

    sage: from sage.plot.plot3d.shapes import *
    sage: S = Sphere(.5, color='yellow')
    sage: S += Cone(.5, .5, color='red').translate(0,0,.3)
    sage: S += Sphere(.1, color='white').translate(.45,-.1,.15) + Sphere(.05, color='black').translate(.51,-.1,.17)
    sage: S += Sphere(.1, color='white').translate(.45, .1,.15) + Sphere(.05, color='black').translate(.51, .1,.17)
    sage: S += Sphere(.1, color='yellow').translate(.5, 0, -.2)
    sage: S.show()
    sage: S.scale(1,1,2).show()

.. PLOT::

    from sage.plot.plot3d.shapes import *
    S = Sphere(.5, color='yellow')
    S += Cone(.5, .5, color='red').translate(0,0,.3)
    S += Sphere(.1, color='white').translate(.45,-.1,.15) + Sphere(.05, color='black').translate(.51,-.1,.17)
    S += Sphere(.1, color='white').translate(.45, .1,.15) + Sphere(.05, color='black').translate(.51, .1,.17)
    S += Sphere(.1, color='yellow').translate(.5, 0, -.2)
    sphinx_plot(S)

::

    sage: from sage.plot.plot3d.shapes import *
    sage: Torus(.7, .2, color=(0,.3,0)).show()

.. PLOT::

    from sage.plot.plot3d.shapes import *
    sphinx_plot(Torus(.7, .2, color=(0,.3,0)))

"""

# ****************************************************************************
#       Copyright (C) 2007 Robert Bradshaw <robertwb@math.washington.edu>
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 2 of the License, or
# (at your option) any later version.
#                  https://www.gnu.org/licenses/
# ****************************************************************************

from libc.math cimport sqrt, sin, cos, tan, asin, acos, atan, M_PI
from sage.rings.real_double import RDF
from sage.modules.free_module_element import vector
from sage.misc.decorators import rename_keyword
from .base import Graphics3dGroup, Graphics3d
from .index_face_set cimport IndexFaceSet, PrimitiveObject
from .transform cimport point_c


# Helper function to check that Box input is right
def validate_frame_size(size):
    """
    Check that the input is an iterable of length 3 with all
    elements nonnegative and coercible to floats.

    EXAMPLES::

        sage: from sage.plot.plot3d.shapes import validate_frame_size
        sage: validate_frame_size([3,2,1])
        [3.0, 2.0, 1.0]

    TESTS::

        sage: from sage.plot.plot3d.shapes import validate_frame_size
        sage: validate_frame_size([3,2,-1])
        Traceback (most recent call last):
        ...
        ValueError: each box dimension must be nonnegative
        sage: validate_frame_size([sqrt(-1),3,2])
        Traceback (most recent call last):
        ...
        TypeError: each box dimension must coerce to a float
    """
    if not isinstance(size, (list, tuple)):
        raise TypeError("size must be a list or tuple")
    if len(size) != 3:
        raise TypeError("size must be of length 3")
    try:
        size = [float(x) for x in size]
    except TypeError:
        raise TypeError("each box dimension must coerce to a float")
    for x in size:
        if x < 0:
            raise ValueError("each box dimension must be nonnegative")
    return size


class Box(IndexFaceSet):
    """
    Return a box.

    EXAMPLES::

        sage: from sage.plot.plot3d.shapes import Box

    A square black box::
    
        sage: show(Box([1,1,1]), color='black')

    .. PLOT::

        from sage.plot.plot3d.shapes import Box
        sphinx_plot(Box([1,1,1], color='black'))

    A red rectangular box::

        sage: show(Box([2,3,4], color="red"))

    .. PLOT::

        from sage.plot.plot3d.shapes import Box
        sphinx_plot(Box([2,3,4], color="red"))

    A stack of boxes::
    
        sage: show(sum([Box([2,3,1], color="red").translate((0,0,6*i)) for i in [0..3]]))

    .. PLOT::

        from sage.plot.plot3d.shapes import Box
        P = sum([Box([2,3,1], color="red").translate((0,0,6*i)) for i in range(0,4)])
        sphinx_plot(P)

    A sinusoidal stack of multicolored boxes::
    
        sage: B = sum([Box([2,4,1/4], color=(i/4,i/5,1)).translate((sin(i),0,5-i)) for i in [0..20]])
        sage: show(B, figsize=6)

    .. PLOT::

        from sage.plot.plot3d.shapes import Box
        B = sum([Box([2,4,1/4], color=(i/4.0,i/5.0,1)).translate((sin(i),0,5-i)) for i in range(0,21)])
        sphinx_plot(B)

    """
    def __init__(self, *size, **kwds):
        """
        EXAMPLES::

            sage: from sage.plot.plot3d.shapes import Box
            sage: Box(10, 1, 1) + Box(1, 10, 1) + Box(1, 1, 10)
            Graphics3d Object
        """
        if isinstance(size[0], (tuple, list)):
            size = validate_frame_size(size[0])
        self.size = size
        x, y, z = self.size
        faces = [[(x, y, z), (-x, y, z), (-x,-y, z), ( x,-y, z)],
                 [(x, y, z), ( x, y,-z), (-x, y,-z), (-x, y, z)],
                 [(x, y, z), ( x,-y, z), ( x,-y,-z), ( x, y,-z)] ]
        faces += [list(reversed([(-x,-y,-z) for x,y,z in face])) for face in faces]
        IndexFaceSet.__init__(self, faces, enclosed=True, **kwds)

    def bounding_box(self):
        """
        EXAMPLES::

            sage: from sage.plot.plot3d.shapes import Box
            sage: Box([1,2,3]).bounding_box()
            ((-1.0, -2.0, -3.0), (1.0, 2.0, 3.0))
        """
        return tuple([-a for a in self.size]), tuple(self.size)

    def x3d_geometry(self):
        """
        EXAMPLES::

            sage: from sage.plot.plot3d.shapes import Box
            sage: Box([1,2,1/4]).x3d_geometry()
            "<Box size='1.0 2.0 0.25'/>"
        """
        return "<Box size='%s %s %s'/>" % tuple(self.size)


@rename_keyword(alpha='opacity')
def ColorCube(size, colors, opacity=1, **kwds):
    """
    Return a cube with given size and sides with given colors.

    INPUT:

    - ``size`` -- 3-tuple of sizes (same as for box and frame)
    - ``colors`` -- a list of either 3 or 6 colors
    - ``opacity`` -- (default: 1) opacity of cube sides
    - ``**kwds`` -- passed to the face constructor

    OUTPUT:

    a 3d graphics object

    EXAMPLES:

    A color cube with translucent sides::

        sage: from sage.plot.plot3d.shapes import ColorCube
        sage: c = ColorCube([1,2,3], ['red', 'blue', 'green', 'black', 'white', 'orange'], opacity=0.5)
        sage: c.show()

    .. PLOT::
    
        from sage.plot.plot3d.shapes import ColorCube
        c = ColorCube([1,2,3], ['red', 'blue', 'green', 'black', 'white', 'orange'], opacity=0.5)
        sphinx_plot(c)
    
    ::
    
        sage: list(c.texture_set())[0].opacity
        0.5

    If you omit the last 3 colors then the first three are repeated (with
    repeated colors on opposing faces)::

        sage: c = ColorCube([0.5,0.5,0.5], ['red', 'blue', 'green'])

    .. PLOT::

        from sage.plot.plot3d.shapes import ColorCube
        c = ColorCube([0.5,0.5,0.5], ['red', 'blue', 'green'])
        sphinx_plot(c)

    """
    if not isinstance(size, (tuple, list)):
        size = (size, size, size)
    box = Box(size)
    faces = box.face_list()
    if len(colors) == 3:
        colors = colors * 2
    all = []
    kwds['opacity'] = opacity

    from .texture import Texture
    for k in range(6):
        all.append(IndexFaceSet([faces[k]], enclosed=True,
             texture=Texture(colors[k], opacity=opacity),
             **kwds))
    return Graphics3dGroup(all)


cdef class Cone(ParametricSurface):
    """
    A cone, with base in the xy-plane pointing up the z-axis.

    INPUT:

    - ``radius`` -- positive real number

    - ``height`` -- positive real number

    - ``closed`` -- whether or not to include the base (default ``True``)

    - ``**kwds`` -- passed to the ParametricSurface constructor

    EXAMPLES::

        sage: from sage.plot.plot3d.shapes import Cone
        sage: c = Cone(3/2, 1, color='red') + Cone(1, 2, color='yellow').translate(3, 0, 0)
        sage: c.show(aspect_ratio=1)

    .. PLOT::

        from sage.plot.plot3d.shapes import Cone
        c = Cone(3/2, 1, color='red') + Cone(1, 2, color='yellow').translate(3, 0, 0)
        sphinx_plot(c)

    We may omit the base::

        sage: Cone(1, 1, closed=False)
        Graphics3d Object

    .. PLOT::

        from sage.plot.plot3d.shapes import Cone
        sphinx_plot(Cone(1, 1, closed=False))

    A spiky plot of the sine function::

        sage: sum(Cone(.1, sin(n), color='yellow').translate(n, sin(n), 0) for n in [0..10, step=.1])
        Graphics3d Object

    .. PLOT::

        from sage.plot.plot3d.shapes import Cone
        sphinx_plot(sum(Cone(.1, sin(n/10.0), color='yellow').translate(n/10.0, sin(n/10.0), 0) for n in range(0,100)))

    A Christmas tree::

        sage: T = sum(Cone(exp(-n/5), 4/3*exp(-n/5), color=(0, .5, 0)).translate(0, 0, -3*exp(-n/5)) for n in [1..7])
        sage: T += Cone(1/8, 1, color='brown').translate(0, 0, -3)
        sage: T.show(aspect_ratio=1, frame=False)
        
    .. PLOT::

        from sage.plot.plot3d.shapes import Cone
        T = sum(Cone(exp(-n/5.0), 4/3*exp(-n/5.0), color=(0, .5, 0)).translate(0, 0, -3*exp(-n/5.0)) for n in range(8))
        T += Cone(1/8, 1, color='brown').translate(0, 0, -3)
        sphinx_plot(T)
    
    """
    def __init__(self, radius, height, closed=True, **kwds):
        """
        TESTS::

            sage: from sage.plot.plot3d.shapes import Cone
            sage: c = Cone(1/2, 1, opacity=.5)
        """
        ParametricSurface.__init__(self, **kwds)
        self.radius = radius
        self.height = height
        self.closed = closed

    def x3d_geometry(self):
        """
        EXAMPLES::

            sage: from sage.plot.plot3d.shapes import Cone
            sage: Cone(1, 3).x3d_geometry()
            "<Cone bottomRadius='1.0' height='3.0'/>"
        """
        return "<Cone bottomRadius='%s' height='%s'/>" % (self.radius,
                                                          self.height)

    def get_grid(self, ds):
        """
        Return the grid on which to evaluate this parametric surface.

        EXAMPLES::

            sage: from sage.plot.plot3d.shapes import Cone
            sage: Cone(1, 3, closed=True).get_grid(100)
            ([1, 0, -1], [0.0, 1.2566..., 2.5132..., 3.7699..., 5.0265..., 0.0])
            sage: Cone(1, 3, closed=False).get_grid(100)
            ([1, 0], [0.0, 1.2566..., 2.5132..., 3.7699..., 5.0265..., 0.0])
            sage: len(Cone(1, 3).get_grid(.001)[1])
            38
        """
        cdef int k, t_res = min(max(int(2*M_PI*self.radius/ds), 5), 37)
        if self.closed:
            urange = [1,0,-1]
        else:
            urange = [1,0]
        vrange = [2*M_PI*k/t_res for k from 0 <= k < t_res] + [0.0]
        return urange, vrange

    cdef int eval_c(self, point_c *res, double u, double v) except -1:
        if u == -1:
            res.x, res.y, res.z = 0, 0, 0
        elif u == 0:
            res.x = self.radius*sin(v)
            res.y = self.radius*cos(v)
            res.z = 0
        else: # u == 1:
            res.x, res.y, res.z = 0, 0, self.height


cdef class Cylinder(ParametricSurface):
    """
    A cone, with base in the xy-plane pointing up the z-axis.

    INPUT:

    - ``radius`` -- positive real number

    - ``height`` -- positive real number

    - ``closed`` -- whether or not to include the ends (default ``True``)

    - ``**kwds`` -- passed to the ParametricSurface constructor

    EXAMPLES::

        sage: from sage.plot.plot3d.shapes import Cylinder
        sage: c = Cylinder(3/2, 1, color='red') + Cylinder(1, 2, color='yellow').translate(3, 0, 0)
        sage: c.show(aspect_ratio=1)

    .. PLOT::

        from sage.plot.plot3d.shapes import Cylinder
        c = Cylinder(3/2, 1, color='red') + Cylinder(1, 2, color='yellow').translate(3, 0, 0)
        sphinx_plot(c)

    We may omit the base::

        sage: Cylinder(1, 1, closed=False)
        Graphics3d Object

    .. PLOT::

        from sage.plot.plot3d.shapes import Cylinder
        sphinx_plot(Cylinder(1, 1, closed=False))

    Some gears::

        sage: G = Cylinder(1, .5) + Cylinder(.25, 3).translate(0, 0, -3)
        sage: G += sum(Cylinder(.2, 1).translate(cos(2*pi*n/9), sin(2*pi*n/9), 0) for n in [1..9])
        sage: G += G.translate(2.3, 0, -.5)
        sage: G += G.translate(3.5, 2, -1)
        sage: G.show(aspect_ratio=1, frame=False)

    .. PLOT::

        from sage.plot.plot3d.shapes import Cylinder
        G = Cylinder(1, .5) + Cylinder(.25, 3).translate(0, 0, -3)
        G += sum(Cylinder(.2, 1).translate(cos(2*pi*n/9.0), sin(2*pi*n/9.0), 0) for n in range(10))
        G += G.translate(2.3, 0, -.5)
        G += G.translate(3.5, 2, -1)
        sphinx_plot(G)

    """
    def __init__(self, radius, height, closed=True, **kwds):
        """
        TESTS::

            sage: from sage.plot.plot3d.shapes import Cylinder
            sage: Cylinder(1, 1, color='red')
            Graphics3d Object
        """
        ParametricSurface.__init__(self, **kwds)
        self.radius = radius
        self.height = height
        self.closed = closed

    def bounding_box(self):
        """
        EXAMPLES::

            sage: from sage.plot.plot3d.shapes import Cylinder
            sage: Cylinder(1, 2).bounding_box()
            ((-1.0, -1.0, 0), (1.0, 1.0, 2.0))
        """
        return ((-self.radius, -self.radius, 0),
                (self.radius, self.radius, self.height))

    def x3d_geometry(self):
        """
        EXAMPLES::

            sage: from sage.plot.plot3d.shapes import Cylinder
            sage: Cylinder(1, 2).x3d_geometry()
            "<Cylinder radius='1.0' height='2.0'/>"
        """
        return "<Cylinder radius='%s' height='%s'/>" % (self.radius,
                                                        self.height)

    def tachyon_repr(self, render_params):
        r"""
        EXAMPLES::

            sage: from sage.plot.plot3d.shapes import Cylinder
            sage: C = Cylinder(1/2, 4, closed=False)
            sage: C.tachyon_repr(C.default_render_params())
            'FCylinder\n   Base 0 0 0\n   Apex 0 0 4.0\n   Rad 0.5\n   texture...     '
            sage: C = Cylinder(1, 2)
            sage: C.tachyon_repr(C.default_render_params())
                ['Ring Center 0 0 0 Normal 0 0 1 Inner 0 Outer 1.0 texture...',
                 'FCylinder\n   Base 0 0 0\n   Apex 0 0 2.0\n   Rad 1.0\n   texture...     ',
                 'Ring Center 0 0 2.0 Normal 0 0 1 Inner 0 Outer 1.0 texture...']
        """
        transform = render_params.transform
        if not (transform is None or transform.is_uniform_on([(1,0,0),(0,1,0)])):
            # Tachyon can't do squashed
            return ParametricSurface.tachyon_repr(self, render_params)

        base, top = self.get_endpoints(transform)
        rad = self.get_radius(transform)
        cyl = """FCylinder
   Base %s %s %s
   Apex %s %s %s
   Rad %s
   %s     """%(base[0], base[1], base[2], top[0], top[1], top[2], rad, self.texture.id)
        if self.closed:
            normal = (0,0,1)
            if transform is not None:
                normal = transform.transform_vector(normal)
            base_cap = """Ring Center %s %s %s Normal %s %s %s Inner 0 Outer %s %s"""  \
                       % (base[0], base[1], base[2], normal[0], normal[1], normal[2], rad, self.texture.id)
            top_cap  = """Ring Center %s %s %s Normal %s %s %s Inner 0 Outer %s %s"""  \
                       % ( top[0],  top[1],  top[2], normal[0], normal[1], normal[2], rad, self.texture.id)
            return [base_cap, cyl, top_cap]
        else:
            return cyl

    def jmol_repr(self, render_params):
        r"""
        EXAMPLES::

            sage: from sage.plot.plot3d.shapes import Cylinder

        For thin cylinders, lines are used::

            sage: C = Cylinder(.1, 4)
            sage: C.jmol_repr(C.default_render_params())
            ['\ndraw line_1 width 0.1 {0 0 0} {0 0 4.0}\ncolor $line_1  [102,102,255]\n']

        For anything larger, we use a pmesh::

            sage: C = Cylinder(3, 1, closed=False)
            sage: C.jmol_repr(C.testing_render_params())
            ['pmesh obj_1 "obj_1.pmesh"\ncolor pmesh  [102,102,255]']
        """
        transform = render_params.transform
        base, top = self.get_endpoints(transform)
        rad = self.get_radius(transform)

        cdef double ratio = sqrt(rad*rad / ((base[0]-top[0])**2 + (base[1]-top[1])**2 + (base[2]-top[2])**2))

        if ratio > .02:
            if not (transform is None or transform.is_uniform_on([(1,0,0),(0,1,0)])) or ratio > .05:
                # Jmol can't do squashed
                return ParametricSurface.jmol_repr(self, render_params)

        name = render_params.unique_name('line')
        return ["""
draw %s width %s {%s %s %s} {%s %s %s}\n%s
""" % (name,
       rad,
       base[0], base[1], base[2],
       top [0], top [1], top [2],
       self.texture.jmol_str("$" + name)) ]

    def get_endpoints(self, transform=None):
        """
        EXAMPLES::

            sage: from sage.plot.plot3d.shapes import Cylinder
            sage: from sage.plot.plot3d.transform import Transformation
            sage: Cylinder(1, 5).get_endpoints()
            ((0, 0, 0), (0, 0, 5.0))
            sage: Cylinder(1, 5).get_endpoints(Transformation(trans=(1,2,3), scale=(2,2,2)))
            ((1.0, 2.0, 3.0), (1.0, 2.0, 13.0))
        """
        if transform is None:
            return (0,0,0), (0,0,self.height)
        else:
            return transform.transform_point((0,0,0)), transform.transform_point((0,0,self.height))

    def get_radius(self, transform=None):
        """
        EXAMPLES::

            sage: from sage.plot.plot3d.shapes import Cylinder
            sage: from sage.plot.plot3d.transform import Transformation
            sage: Cylinder(3, 1).get_radius()
            3.0
            sage: Cylinder(3, 1).get_radius(Transformation(trans=(1,2,3), scale=(2,2,2)))
            6.0
        """
        if transform is None:
            return self.radius
        radv = transform.transform_vector((self.radius, 0, 0))
        return sqrt(sum([x * x for x in radv]))

    def get_grid(self, ds):
        """
        Return the grid on which to evaluate this parametric surface.

        EXAMPLES::

            sage: from sage.plot.plot3d.shapes import Cylinder
            sage: Cylinder(1, 3, closed=True).get_grid(100)
            ([2, 1, -1, -2], [0.0, 1.2566..., 2.5132..., 3.7699..., 5.0265..., 0.0])
            sage: Cylinder(1, 3, closed=False).get_grid(100)
            ([1, -1], [0.0, 1.2566..., 2.5132..., 3.7699..., 5.0265..., 0.0])
            sage: len(Cylinder(1, 3).get_grid(.001)[1])
            38
        """
        cdef int k, v_res = min(max(int(2*M_PI*self.radius/ds), 5), 37)
        if self.closed:
            urange = [2,1,-1,-2]
        else:
            urange = [1,-1]
        vrange = [2*M_PI*k/v_res for k from 0 <= k < v_res] + [0.0]
        return urange, vrange

    cdef int eval_c(self, point_c *res, double u, double v) except -1:
        if u == -2:
            res.x, res.y, res.z = 0, 0, 0
        elif u == -1:
            res.x = self.radius*sin(v)
            res.y = self.radius*cos(v)
            res.z = 0
        elif u == 1:
            res.x = self.radius*sin(v)
            res.y = self.radius*cos(v)
            res.z = self.height
        else: # u == 2:
            res.x, res.y, res.z = 0, 0, self.height


@rename_keyword(alpha='opacity')
def LineSegment(start, end, thickness=1, radius=None, **kwds):
    """
    Create a line segment, which is drawn as a cylinder from start to
    end with radius ``radius``.

    EXAMPLES::

        sage: from sage.plot.plot3d.shapes import LineSegment, Sphere
        sage: P = (0,0,0.1)
        sage: Q = (0.5,0.6,0.7)
        sage: S = Sphere(.2, color='red').translate(P)
        sage: S += Sphere(.2, color='blue').translate(Q)
        sage: S += LineSegment(P, Q, .05, color='black')
        sage: S.show()

    .. PLOT::

        from sage.plot.plot3d.shapes import LineSegment, Sphere
        P = (0,0,0.1)
        Q = (0.5,0.6,0.7)
        S = Sphere(.2, color='red').translate(P)
        S += Sphere(.2, color='blue').translate(Q)
        S += LineSegment(P, Q, .05, color='black')
        sphinx_plot(S)

    ::

        sage: S = Sphere(.1, color='red').translate(P)
        sage: S += Sphere(.1, color='blue').translate(Q)
        sage: S += LineSegment(P, Q, .15, color='black')
        sage: S.show()

    .. PLOT::

        from sage.plot.plot3d.shapes import LineSegment, Sphere
        P = (0,0,0.1)
        Q = (0.5,0.6,0.7)
        S = Sphere(.1, color='red').translate(P)
        S += Sphere(.1, color='blue').translate(Q)
        S += LineSegment(P, Q, .15, color='black')
        sphinx_plot(S)

    AUTHOR:

    - Robert Bradshaw
    """
    if radius is None:
        radius = thickness/50.0
    start = vector(RDF, start, sparse=False)
    end   = vector(RDF, end, sparse=False)
    zaxis = vector(RDF, (0,0,1), sparse=False)
    diff  = end - start
    height= sqrt(diff.dot_product(diff))
    cyl   = Cylinder(radius, height, **kwds)
    axis  = zaxis.cross_product(diff)
    if axis == 0:
        if diff[2] < 0:
            return cyl.translate(end)
        else:
            return cyl.translate(start)
    else:
        theta = -acos(diff[2]/height)
        return cyl.rotate(axis, theta).translate(start)


def arrow3d(start, end, width=1, radius=None, head_radius=None, head_len=None, **kwds):
    """
    Create a 3d arrow.

    INPUT:

    - start -- (x,y,z) point; the starting point of the arrow
    - end -- (x,y,z) point; the end point
    - width -- (default: 1); how wide the arrow is
    - radius -- (default: width/50.0) the radius of the arrow
    - head_radius -- (default: 3*radius); radius of arrow head
    - head_len -- (default: 3*head_radius); len of arrow head

    EXAMPLES:

    The default arrow::

        sage: arrow3d((0,0,0), (1,1,1), 1)
        Graphics3d Object

    .. PLOT::

        sphinx_plot(arrow3d((0,0,0), (1,1,1), 1))

    A fat arrow::

        sage: arrow3d((0,0,0), (1,1,1), radius=0.1)
        Graphics3d Object

    .. PLOT::

        sphinx_plot(arrow3d((0,0,0), (1,1,1), radius=0.1))

    A green arrow::

        sage: arrow3d((0,0,0), (1,1,1), color='green')
        Graphics3d Object

    .. PLOT::

        sphinx_plot(arrow3d((0,0,0), (1,1,1), color='green'))

    A fat arrow head::

        sage: arrow3d((2,1,0), (1,1,1), color='green', head_radius=0.3, aspect_ratio=[1,1,1])
        Graphics3d Object

    .. PLOT::

        sphinx_plot(arrow3d((2,1,0), (1,1,1), color='green', head_radius=0.3, aspect_ratio=[1,1,1]))

    Many arrows arranged in a circle (flying spears?)::

        sage: sum([arrow3d((cos(t),sin(t),0),(cos(t),sin(t),1)) for t in [0,0.3,..,2*pi]])
        Graphics3d Object

    .. PLOT::

        t=0
        G=Graphics()
        while (t<=2*pi):
            G += arrow3d((cos(t),sin(t),0),(cos(t),sin(t),1))
            t +=0.3
        sphinx_plot(G)

    Change the width of the arrow. (Note: for an arrow that scales with zoom, please consider
    the ``line3d`` function with the option ``arrow_head=True``)::

        sage: arrow3d((0,0,0), (1,1,1), width=1)
        Graphics3d Object

    .. PLOT::

        sphinx_plot(arrow3d((0,0,0), (1,1,1), width=1))

    TESTS:

    If the arrow is too long, the shaft and part of the head is cut off. ::

        sage: a = arrow3d((0,0,0), (0,0,0.5), head_len=1)
        sage: len(a.all)
        1
        sage: type(a.all[0])
        <... 'sage.plot.plot3d.shapes.Cone'>

    Arrows are always constructed pointing up in the z direction from
    the origin, and then rotated/translated into place. This works for
    every arrow direction except the -z direction.  We take care of the
    anomaly by testing to see if the arrow should point in the -z
    direction, and if it should, just scaling the constructed arrow by
    -1 (i.e., every point is sent to its negative). The scaled arrow
    then points downwards. The doctest just tests that the scale of -1
    is applied to the arrow. ::

        sage: a = arrow3d((0,0,0), (0,0,-1))
        sage: a.all[0].get_transformation().transform_point((0,0,1))
        (0.0, 0.0, -1.0)
    """
    if radius is None:
        radius = width/50.0
    if head_radius is None:
        head_radius = 3*radius
    if head_len is None:
        head_len = 3*head_radius
    start = vector(RDF, start, sparse=False)
    end = vector(RDF, end, sparse=False)
    zaxis = vector(RDF, (0,0,1), sparse=False)
    diff = end - start
    length = sqrt(diff.dot_product(diff))
    if length <= head_len:
        arrow = Cone(head_radius*length/head_len, length, **kwds)
    else:
        arrow = Cylinder(radius, length-head_len, **kwds) \
                + Cone(head_radius, head_len, **kwds).translate(0, 0, length-head_len)
    axis = zaxis.cross_product(diff)
    if axis == 0:
        if diff[2] >= 0:
            return arrow.translate(start)
        else:
            return arrow.scale(-1).translate(start)
    else:
        theta = -acos(diff[2]/length)
        return arrow.rotate(axis, theta).translate(start)


cdef class Sphere(ParametricSurface):
    """
    This class represents a sphere centered at the origin.

    EXAMPLES::

        sage: from sage.plot.plot3d.shapes import Sphere
        sage: Sphere(3)
        Graphics3d Object

    .. PLOT::

        from sage.plot.plot3d.shapes import Sphere
        sphinx_plot(Sphere(3))

    Plot with aspect_ratio=1 to see it unsquashed::

        sage: S = Sphere(3, color='blue') + Sphere(2, color='red').translate(0,3,0)
        sage: S.show(aspect_ratio=1)

    .. PLOT::

        from sage.plot.plot3d.shapes import Sphere
        S = Sphere(3, color='blue') + Sphere(2, color='red').translate(0,3,0)
        sphinx_plot(S)

    Scale to get an ellipsoid::

        sage: S = Sphere(1).scale(1,2,1/2)
        sage: S.show(aspect_ratio=1)
        
    .. PLOT::

        from sage.plot.plot3d.shapes import Sphere
        S = Sphere(1).scale(1,2,1/2)
        sphinx_plot(S)

    """
    def __init__(self, radius, **kwds):
        """
        TESTS::

            sage: from sage.plot.plot3d.shapes import Sphere
            sage: Sphere(3)
            Graphics3d Object
        """
        ParametricSurface.__init__(self, **kwds)
        self.radius = radius

    def bounding_box(self):
        """
        Return the bounding box that contains this sphere.

        EXAMPLES::

            sage: from sage.plot.plot3d.shapes import Sphere
            sage: Sphere(3).bounding_box()
            ((-3.0, -3.0, -3.0), (3.0, 3.0, 3.0))
        """
        return ((-self.radius, -self.radius, -self.radius),
                (self.radius, self.radius, self.radius))

    def x3d_geometry(self):
        """
        EXAMPLES::

            sage: from sage.plot.plot3d.shapes import Sphere
            sage: Sphere(12).x3d_geometry()
            "<Sphere radius='12.0'/>"
        """
        return "<Sphere radius='%s'/>"%(self.radius)

    def tachyon_repr(self, render_params):
        r"""
        Tachyon can natively handle spheres. Ellipsoids rendering is done
        as a parametric surface.

        EXAMPLES::

            sage: from sage.plot.plot3d.shapes import Sphere
            sage: S = Sphere(2)
            sage: S.tachyon_repr(S.default_render_params())
            'Sphere center 0 0 0 Rad 2.0 texture...'
            sage: S.translate(1, 2, 3).scale(3).tachyon_repr(S.default_render_params())
            [['Sphere center 3.0 6.0 9.0 Rad 6.0 texture...']]
            sage: S.scale(1,1/2,1/4).tachyon_repr(S.default_render_params())
            [['TRI V0 0 0 -0.5 V1 0.308116 0.0271646 -0.493844 V2 0.312869 0 -0.493844',
              'texture...',
               ...
              'TRI V0 0.308116 -0.0271646 0.493844 V1 0.312869 0 0.493844 V2 0 0 0.5',
              'texture...']]
        """
        transform = render_params.transform
        if not (transform is None or transform.is_uniform()):
            return ParametricSurface.tachyon_repr(self, render_params)

        if transform is None:
            cen = (0,0,0)
            rad = self.radius
        else:
            cen = transform.transform_point((0,0,0))
            radv = transform.transform_vector((self.radius,0,0))
            rad = sqrt(sum([x*x for x in radv]))
        return "Sphere center %s %s %s Rad %s %s" % (cen[0], cen[1], cen[2], rad, self.texture.id)

    def jmol_repr(self, render_params):
        r"""
        EXAMPLES::

            sage: from sage.plot.plot3d.shapes import Sphere

        Jmol has native code for handling spheres::

            sage: S = Sphere(2)
            sage: S.jmol_repr(S.default_render_params())
            ['isosurface sphere_1  center {0 0 0} sphere 2.0\ncolor isosurface  [102,102,255]']
            sage: S.translate(10, 100, 1000).jmol_repr(S.default_render_params())
            [['isosurface sphere_1  center {10.0 100.0 1000.0} sphere 2.0\ncolor isosurface  [102,102,255]']]

        It cannot natively handle ellipsoids::

            sage: Sphere(1).scale(2, 3, 4).jmol_repr(S.testing_render_params())
            [['pmesh obj_2 "obj_2.pmesh"\ncolor pmesh  [102,102,255]']]

        Small spheres need extra hints to render well::

            sage: Sphere(.01).jmol_repr(S.default_render_params())
            ['isosurface sphere_1 resolution 100 center {0 0 0} sphere 0.01\ncolor isosurface  [102,102,255]']
        """
        name = render_params.unique_name('sphere')
        transform = render_params.transform
        if not (transform is None or transform.is_uniform()):
            return ParametricSurface.jmol_repr(self, render_params)

        if transform is None:
            cen = (0,0,0)
            rad = self.radius
        else:
            cen = transform.transform_point((0,0,0))
            radv = transform.transform_vector((self.radius,0,0))
            rad = sqrt(sum([x*x for x in radv]))
        if rad < 0.5:
            res = "resolution %s" % min(int(7/rad), 100)
        else:
            res = ""
        return ["isosurface %s %s center {%s %s %s} sphere %s\n%s" % (name, res, cen[0], cen[1], cen[2], rad, self.texture.jmol_str("isosurface"))]

    def get_grid(self, double ds):
        """
        Return the range of variables to be evaluated on to render as a
        parametric surface.

        EXAMPLES::

            sage: from sage.plot.plot3d.shapes import Sphere
            sage: Sphere(1).get_grid(100)
            ([-10.0, ..., 10.0],
             [0.0, ..., 3.141592653589793, ..., 0.0])
        """
        cdef int K, u_res, v_res
        u_res = min(max(int(M_PI*self.radius/ds), 6), 20)
        v_res = min(max(int(2*M_PI * self.radius/ds), 6), 36)
        urange = [-10.0] + [M_PI * k/u_res - M_PI/2 for k in range(1, u_res)] + [10.0]
        vrange = [2*M_PI * k/v_res for k in range(v_res)] + [0.0]
        return urange, vrange

    cdef int eval_c(self, point_c *res, double u, double v) except -1:
        if u == -10:
            res.x, res.y, res.z = 0, 0, -self.radius
        elif u == 10:
            res.x, res.y, res.z = 0, 0,  self.radius
        else:
            res.x = self.radius*cos(v) * cos(u)
            res.y = self.radius*sin(v) * cos(u)
            res.z = self.radius * sin(u)


cdef class Torus(ParametricSurface):
    """
    INPUT:

    - R -- (default: 1) outer radius
    - r -- (default: .3) inner radius

    OUTPUT:

    a 3d torus

    EXAMPLES::

        sage: from sage.plot.plot3d.shapes import Torus
        sage: Torus(1, .2).show(aspect_ratio=1)

    .. PLOT::

        from sage.plot.plot3d.shapes import Torus
        sphinx_plot(Torus(1, .2))

    ::

        sage: Torus(1, .7, color='red').show(aspect_ratio=1)

    .. PLOT::

        from sage.plot.plot3d.shapes import Torus
        sphinx_plot(Torus(1, .7, color='red'))

    A rubberband ball::

        sage: show(sum([Torus(1, .03, color=(1, t/30.0, 0)).rotate((1,1,1),t) for t in range(30)]))

    .. PLOT::

        from sage.plot.plot3d.shapes import Torus
        sphinx_plot(sum([Torus(1, .03, color=(1, t/30.0, 0)).rotate((1,1,1),t) for t in range(30)]))

    Mmm... doughnuts::

        sage: D = Torus(1, .4, color=(.5, .3, .2)) + Torus(1, .3, color='yellow').translate(0, 0, .15)
        sage: G = sum(D.translate(RDF.random_element(-.2, .2), RDF.random_element(-.2, .2), .8*t) for t in range(10))
        sage: G.show(aspect_ratio=1, frame=False)

    .. PLOT::

        from sage.plot.plot3d.shapes import Torus
        D = Torus(1, .4, color=(.5, .3, .2)) + Torus(1, .3, color='yellow').translate(0, 0, .15)
        G = sum(D.translate(RDF.random_element(-.2, .2), RDF.random_element(-.2, .2), .8*t) for t in range(10))
        sphinx_plot(G)

    """
    def __init__(self, R=1, r=.3, **kwds):
        """
        TESTS::

            sage: from sage.plot.plot3d.shapes import Torus
            sage: T = Torus(1, .5)
        """
        ParametricSurface.__init__(self, None, **kwds)
        self.R = R
        self.r = r

    def get_grid(self, ds):
        """
        Return the range of variables to be evaluated on to render as a
        parametric surface.

        EXAMPLES::

            sage: from sage.plot.plot3d.shapes import Torus
            sage: Torus(2, 1).get_grid(100)
            ([0.0, -1.047..., -3.141592653589793, ..., 0.0],
             [0.0, 1.047..., 3.141592653589793, ..., 0.0])
        """
        cdef int k, u_divs, v_divs
        u_divs = min(max(int(4*M_PI * self.R/ds), 6), 37)
        v_divs = min(max(int(4*M_PI * self.r/ds), 6), 37)
        urange = [0.0] + [-2*M_PI * k/u_divs for k in range(1, u_divs)] + [0.0]
        vrange = [ 2*M_PI * k/v_divs for k in range(v_divs)] + [0.0]
        return urange, vrange

    cdef int eval_c(self, point_c *res, double u, double v) except -1:
        res.x = (self.R+self.r*sin(v))*sin(u)
        res.y = (self.R+self.r*sin(v))*cos(u)
        res.z = self.r*cos(v)


class Text(PrimitiveObject):
    """
    A text label attached to a point in 3d space. It always starts at the
    origin, translate it to move it elsewhere.

    EXAMPLES::

        sage: from sage.plot.plot3d.shapes import Text
        sage: Text("Just a lonely label.")
        Graphics3d Object

    .. PLOT::

        from sage.plot.plot3d.shapes import Text
        sphinx_plot(Text("Just a lonely label. "))

    ::

        sage: pts = [(RealField(10)^3).random_element() for k in range(20)]
        sage: sum(Text(str(P)).translate(P) for P in pts)
        Graphics3d Object

    .. PLOT::

        from sage.plot.plot3d.shapes import Text
        pts = [(RealField(10)**3).random_element() for k in range(20)]
        sphinx_plot(sum(Text(str(P)).translate(P) for P in pts))

    """
    def __init__(self, string, **kwds):
        """
        TESTS::

            sage: from sage.plot.plot3d.shapes import Text
            sage: T = Text("Hi")
        """
        PrimitiveObject.__init__(self, **kwds)
        self.string = string

    def x3d_geometry(self):
        """
        EXAMPLES::

            sage: from sage.plot.plot3d.shapes import Text
            sage: Text("Hi").x3d_geometry()
            "<Text string='Hi' solid='true'/>"
        """
        return "<Text string='%s' solid='true'/>"%self.string

    def obj_repr(self, render_params):
        """
        The obj file format does not support text strings::

            sage: from sage.plot.plot3d.shapes import Text
            sage: Text("Hi").obj_repr(None)
            ''
        """
        return ''

    def tachyon_repr(self, render_params):
        """
        Strings are not yet supported in Tachyon, so we ignore them for now::

            sage: from sage.plot.plot3d.shapes import Text
            sage: Text("Hi").tachyon_repr(None)
            ''
        """
        return ''
        # Text in Tachyon not implemented yet.
        # I have no idea what the code below is supposed to do.
##         transform = render_params.transform
##         if not (transform is None or transform.is_uniform()):
##             return ParametricSurface.tachyon_repr(self, render_params)
##
##         if transform is None:
##             cen = (0,0,0)
##             rad = self.radius
##         else:
##             cen = transform.transform_point((0,0,0))
##             radv = transform.transform_vector((self.radius,0,0))
##             rad = sqrt(sum([x*x for x in radv]))
##         return "Sphere center %s %s %s Rad %s %s" % (cen[0], cen[1], cen[2], rad, self.texture.id)

    def jmol_repr(self, render_params):
        """
        Labels in jmol must be attached to atoms.

        EXAMPLES::

            sage: from sage.plot.plot3d.shapes import Text
            sage: T = Text("Hi")
            sage: T.jmol_repr(T.testing_render_params())
            ['select atomno = 1', 'color atom  [102,102,255]', 'label "Hi"']
            sage: T = Text("Hi").translate(-1, 0, 0) + Text("Bye").translate(1, 0, 0)
            sage: T.jmol_repr(T.testing_render_params())
            [[['select atomno = 1', 'color atom  [102,102,255]', 'label "Hi"']],
             [['select atomno = 2', 'color atom  [102,102,255]', 'label "Bye"']]]
        """
        cen = (0,0,0)
        if render_params.transform is not None:
            cen = render_params.transform.transform_point(cen)
        render_params.atom_list.append(cen)
        atom_no = len(render_params.atom_list)
        return ['select atomno = %s' % atom_no,
                self.get_texture().jmol_str("atom"),
                'label "%s"' % self.string] #.replace('\n', '|')]

    def bounding_box(self):
        """
        Text labels have no extent::

            sage: from sage.plot.plot3d.shapes import Text
            sage: Text("Hi").bounding_box()
            ((0, 0, 0), (0, 0, 0))
        """
        return (0,0,0), (0,0,0)
