Class Graphics

Create a new empty Graphics objects with all the defaults.

EXAMPLES:
    sage: G = Graphics()

Overrides: object.__init__

Set the aspect ratio.

INPUT:
    ratio  -- a positive real number

EXAMPLES:
We create a plot of a circle, and it doesn't look quite round:
    sage: P = circle((1,1), 1); P

So we set the aspect ratio and now it is round:
    sage: P.set_aspect_ratio(1)
    sage: P

Note that the aspect ratio is inherited upon addition (which takes the
max of aspect ratios of objects whose aspect ratio has been set):
    sage: P + circle((0,0), 0.5)           # still square

In the following example, both plots produce a circle that looks twice
as wide as tall:
    sage: Q = circle((0,0), 0.5); Q.set_aspect_ratio(2)
    sage: P + Q
    sage: Q + P

Get the current aspect ratio.

OUTPUT:
    either None if the aspect ratio hasn't been set or a positive float

EXAMPLES:
    sage: P = circle((1,1), 1)
    sage: P.aspect_ratio() is None
    True
    sage: P.set_aspect_ratio(2)
    sage: P.aspect_ratio()
    2.0

Set the ranges of the $x$ and $y$ axes.

INPUT:
    xmin, xmax, ymin, ymax -- floats

EXAMPLES:
    sage: L = line([(1,2), (3,-4), (2, 5), (1,2)])
    sage: L.axes_range(-1, 20, 0, 2)
    sage: L.xmin(), L.xmax(), L.ymin(), L.ymax()
    (-1.0, 20.0, 0.0, 2.0)

Set the font size of axes labels and tick marks.

INPUT:
    s -- integer, a font size in points. 

If called with no input, return the current fontsize.

EXAMPLES:
    sage: L = line([(1,2), (3,-4), (2, 5), (1,2)])
    sage: L.fontsize()
    10
    sage: L.fontsize(20)
    sage: L.fontsize()
    20

All the numbers on the axes will be very large in this plot:
    sage: L

Set whether or not the $x$ and $y$ axes are shown by default.

INPUT:
    show -- bool

If called with no input, return the current axes setting.

EXAMPLES:
    sage: L = line([(1,2), (3,-4), (2, 5), (1,2)])

By default the axes are displayed.
    sage: L.axes()
    True

But we turn them off, and verify that they are off
    sage: L.axes(False)
    sage: L.axes()
    False

Displaying L now shows a triangle but no axes. 
    sage: L

Set the axes color.

If called with no input, return the current axes_color setting.

INPUT:
    c -- an rgb color 3-tuple, where each tuple entry is a
         float between 0 and 1

EXAMPLES:
We create a line, which has like everything a default axes color of black.
    sage: L = line([(1,2), (3,-4), (2, 5), (1,2)])
    sage: L.axes_color()
    (0, 0, 0)

We change the axes color to red and verify the change.
    sage: L.axes_color((1,0,0))
    sage: L.axes_color()
    (1.0, 0.0, 0.0)

When we display the plot, we'll see a blue triangle and bright red axes.
    sage: L

Set the axes labels.

INPUT:
    l -- (default: None) a list of two strings or None

OUTPUT:
    a 2-tuple of strings

If l is None, returns the current \code{axes_labels}, which is
itself by default None.  The default
labels are both empty.

EXAMPLES:
We create a plot and put x and y axes labels on it.
    sage: p = plot(sin(x), (x, 0, 10))
    sage: p.axes_labels(['x','y'])
    sage: p.axes_labels()
    ('x', 'y')

Now when you plot p, you see x and y axes labels:
    sage: p

Set the color of the axes labels.

The axes labels are placed at the edge of the x and y axes,
and are not on by default (use the \code{axes_labels} command
to set them; see the example below).  This function just changes
their color.

INPUT:
    c -- an rgb 3-tuple of numbers between 0 and 1

If called with no input, return the current axes_label_color setting.

EXAMPLES:
We create a plot, which by default has axes label color black.
    sage: p = plot(sin, (-1,1))
    sage: p.axes_label_color()
    (0, 0, 0)

We change the labels to be red, and confirm this:
    sage: p.axes_label_color((1,0,0))
    sage: p.axes_label_color()
    (1.0, 0.0, 0.0)

We set labels, since otherwise we won't see anything.
    sage: p.axes_labels(['$x$ axis', '$y$ axis'])

In the plot below, notice that the labels are red:
    sage: p

Set the axes width.  Use this to draw a plot with really fat
or really thin axes.

INPUT:
    w -- a float

If called with no input, return the current \code{axes_width} setting.

EXAMPLE:
We create a plot, see the default axes width (with funny Python float rounding),
then reset the width to 10 (very fat). 
    sage: p = plot(cos, (-3,3))
    sage: p.axes_width()
    0.80000000000000004
    sage: p.axes_width(10)
    sage: p.axes_width()
    10.0

Finally we plot the result, which is a graph with very fat axes. 
    sage: p

Set the color of the axes tick labels.

INPUT:
    c -- an rgb 3-tuple of numbers between 0 and 1

If called with no input, return the current tick_label_color setting.

EXAMPLES:
    sage: p = plot(cos, (-3,3))
    sage: p.tick_label_color()
    (0, 0, 0)
    sage: p.tick_label_color((1,0,0))
    sage: p.tick_label_color()
    (1.0, 0.0, 0.0)
    sage: p

EXAMPLES:
    sage: G = Graphics(); print G
    Graphics object consisting of 0 graphics primitives
    sage: G.xmax()
    1
    sage: G.xmax(2)
    2.0
    sage: G.xmax()
    2.0            

EXAMPLES:
    sage: G = Graphics(); print G
    Graphics object consisting of 0 graphics primitives
    sage: G.xmin()
    -1
    sage: G.xmax(2)
    2.0
    sage: G.xmax()
    2.0

EXAMPLES:
    sage: G = Graphics(); print G
    Graphics object consisting of 0 graphics primitives
    sage: G.ymax()
    1
    sage: G.ymax(2)
    2.0
    sage: G.ymax()
    2.0

EXAMPLES:
    sage: G = Graphics(); print G
    Graphics object consisting of 0 graphics primitives
    sage: G.ymin()
    -1
    sage: G.ymin(2)
    2.0
    sage: G.ymin()
    2.0

Show this graphics objects.

If the \code{show_default} function has been called with True
(the default), then you'll see this graphics object displayed.
Otherwise you'll see a text representation of it.

EXAMPLES:
We create a plot and call \code{_repr_} on it, which causes it
to be displayed as a plot:
    sage: P = plot(cos, (-1,1))
    sage: P._repr_()
    ''

Just doing this also displays the plot:
    sage: P

Note that printing P with the \code{print} statement does not display the plot:
    sage: print P
    Graphics object consisting of 1 graphics primitive
    
Now we turn off showing plots by default:
    sage: show_default(False)

Now we just get a string.  To show P you would have to do \code{show(P)}.
    sage: P._repr_()
    'Graphics object consisting of 1 graphics primitive'
    sage: P
    Graphics object consisting of 1 graphics primitive

Finally, we turn \code{show_default} back on:
    sage: show_default(True)

Return string representation of this plot.

EXAMPLES:
    sage: S = circle((0,0), 2); S.__str__()
    'Graphics object consisting of 1 graphics primitive'
    sage: print S
    Graphics object consisting of 1 graphics primitive

WARNING: \code{__str__} is not called when printing lists of graphics
objects, which can be confusing, since they will all pop up.  One
workaround is to call \code{show_default}:

For example, below when we do \code{print v} two plots are displayed:
    sage: v = [circle((0,0), 2), circle((2,3), 1)]
    sage: print v
    [, ]

However, if we call \code{show_default} then we see the text representations
of the graphics:
    sage: show_default(False)
    sage: print v
    [Graphics object consisting of 1 graphics primitive, Graphics object consisting of 1 graphics primitive]
    sage: v
    [Graphics object consisting of 1 graphics primitive,
     Graphics object consisting of 1 graphics primitive]
     
    sage: show_default(True)

Overrides: object.__str__

Returns the ith graphics primitive object:

EXAMPLE:
    sage: G = circle((1,1),2) + circle((2,2),5); print G
    Graphics object consisting of 2 graphics primitives
    sage: G[1]
    Circle defined by (2.0,2.0) with r=5.0

If G is of type Graphics, then len(G)
gives the number of distinct graphics
primitives making up that object.

EXAMPLES:
    sage: G = circle((1,1),1) + circle((1,2),1) + circle((1,2),5); print G
    Graphics object consisting of 3 graphics primitives
    sage: len(G)
    3

If G is of type Graphics, then del(G[i])
removes the ith distinct graphic
primitive making up that object.

EXAMPLES:
    sage: G = circle((1,1),1) + circle((1,2),1) + circle((1,2),5); print G
    Graphics object consisting of 3 graphics primitives
    sage: len(G)
    3
    sage: del(G[2])
    sage: print G
    Graphics object consisting of 2 graphics primitives
    sage: len(G)
    2

You can replace a GraphicPrimitive (point, line, circle, etc...)
in a Graphics object G with any other GraphicPrimitive

EXAMPLES:
    sage: G = circle((1,1),1) + circle((1,2),1) + circle((1,2),5); print G
    Graphics object consisting of 3 graphics primitives

    sage: p = polygon([[1,3],[2,-2],[1,1],[1,3]]); print p
    Graphics object consisting of 1 graphics primitive

    sage: G[1] = p[0]
    sage: G    # show the plot

Compute and return other + this graphics object.

This only works when other is a Python int equal to 0. In all
other cases a TypeError is raised.  The main reason for this
function is to make suming a list of graphics objects easier.

EXAMPLES:
    sage: S = circle((0,0), 2)
    sage: print int(0) + S
    Graphics object consisting of 1 graphics primitive
    sage: print S + int(0)
    Graphics object consisting of 1 graphics primitive

The following would fail were it not for this function:
    sage: v = [circle((0,0), 2), circle((2,3), 1)]
    sage: print sum(v)
    Graphics object consisting of 2 graphics primitives

If you have any Graphics object G1, you can always add any
other amount of Graphics objects G2,G3,...  to form a new
Graphics object: G4 = G1 + G2 + G3.

The xmin, xmax, ymin, and ymax properties of the graphics objects
are expanded to include all objects in both scenes.  If the aspect
ratio property of either or both objects are set, then the larger
aspect ratio is chosen. 

EXAMPLES:
    sage: g1 = plot(abs(sqrt(x^3-1)), (x,1,5))
    sage: g2 = plot(-abs(sqrt(x^3-1)), (x,1,5), rgbcolor=(1,0,0))
    sage: g1 + g2  # displays the plot

Draw a 2d plot this graphics object, which just returns this
object since this is already a 2d graphics object.

EXAMPLES:
    sage: S = circle((0,0), 2)
    sage: S.plot() is S
    True

Overrides: structure.sage_object.SageObject.plot

Returns an embedding of this 2D plot into the xy-plane of 3D space, as 
a 3D plot object. An optional parameter z can be given to specify the
z-coordinate. 

EXAMPLES: 
    sage: sum([plot(z*sin(x), 0, 10).plot3d(z) for z in range(6)])

Show this graphics image with the default image viewer.

OPTIONAL INPUT:
    filename     -- (default: None) string
    dpi          -- dots per inch
    figsize      -- [width, height]
    aspect_ratio -- the perceived width divided by the
                    perceived height.  If the aspect ratio is
                    set to 1, circles will look round.  If it
                    is set to 2 they will look twice as wide
                    as they are tall.  This is the
                    aspect_ratio of the image, not of the
                    frame that contains it.  If you want to
                    set the aspect ratio of the frame, use
                    figsize.
    axes         -- (default: True)
    axes_labels  -- (default: None) list (or tuple) of two strings;
                    the first is used as the label for the horizontal
                    axis, and the second for the vertical axis.
    fontsize     -- (default: current setting -- 10) positive
                    integer; used for axes labels; if you make
                    this very large, you may have to increase
                    figsize to see all labels.

    frame        -- (default: False) draw a frame around the image

EXAMPLES:
    sage: c = circle((1,1), 1, rgbcolor=(1,0,0))
    sage: c.show(xmin=-1, xmax=3, ymin=-1, ymax=3)

To correct the apect ratio of certain graphics, it is necessary
to show with a `\code{figsize}' of square dimensions.

    sage: c.show(figsize=[5,5], xmin=-1, xmax=3, ymin=-1, ymax=3)

You can turn off the drawing of the axes:

    sage: show(plot(sin,-4,4), axes=False)

You can also label the axes:

    sage: show(plot(sin,-4,4), axes_labels=('x','y'))

You can turn on the drawing of a frame around the plots:
    
    sage: show(plot(sin,-4,4), frame=True)

Save the graphics to an image file of type: PNG, PS, EPS, SVG, SOBJ,
depending on the file extension you give the filename.
    Extension types can be: \file{.png}, \file{.ps}, \file{.eps}, \file{.svg},
    and \file{.sobj} (for a \sage object you can load later). 

EXAMPLES:
    sage: c = circle((1,1),1,rgbcolor=(1,0,0))
    sage: c.show(xmin=-1,xmax=3,ymin=-1,ymax=3)

    To correct the apect ratio of certain graphics, it is necessary
    to show with a '\code{figsize}' of square dimensions.

    sage: c.show(figsize=[5,5],xmin=-1,xmax=3,ymin=-1,ymax=3)

Overrides: structure.sage_object.SageObject.save