Source code for bokeh.models.glyphs

# -*- coding: utf-8 -*-
''' Display a variety of visual shapes whose attributes can be associated
with data columns from ``ColumnDataSources``.

The full list of glyphs built into Bokeh is given below:

* :class:`~bokeh.models.glyphs.AnnularWedge`
* :class:`~bokeh.models.glyphs.Annulus`
* :class:`~bokeh.models.glyphs.Arc`
* :class:`~bokeh.models.glyphs.Bezier`
* :class:`~bokeh.models.glyphs.Ellipse`
* :class:`~bokeh.models.glyphs.HBar`
* :class:`~bokeh.models.glyphs.Image`
* :class:`~bokeh.models.glyphs.ImageRGBA`
* :class:`~bokeh.models.glyphs.ImageURL`
* :class:`~bokeh.models.glyphs.Line`
* :class:`~bokeh.models.glyphs.MultiLine`
* :class:`~bokeh.models.glyphs.Oval`
* :class:`~bokeh.models.glyphs.Patch`
* :class:`~bokeh.models.glyphs.Patches`
* :class:`~bokeh.models.glyphs.Quad`
* :class:`~bokeh.models.glyphs.Quadratic`
* :class:`~bokeh.models.glyphs.Ray`
* :class:`~bokeh.models.glyphs.Rect`
* :class:`~bokeh.models.glyphs.Segment`
* :class:`~bokeh.models.glyphs.Text`
* :class:`~bokeh.models.glyphs.VBar`
* :class:`~bokeh.models.glyphs.Wedge`

All these glyphs share a minimal common interface through their base class
``Glyph``:

.. autoclass:: Glyph
    :members:

'''
from __future__ import absolute_import

from ..core.enums import Anchor, Direction
from ..core.has_props import abstract
from ..core.properties import (AngleSpec, Bool, DistanceSpec, Enum, Float,
                               Include, Instance, Int, NumberSpec, StringSpec)
from ..core.property_mixins import FillProps, LineProps, TextProps
from ..model import Model

from .mappers import ColorMapper, LinearColorMapper

@abstract
[docs]class Glyph(Model): ''' Base class for all glyph models. '''
@abstract class XYGlyph(Glyph): ''' Base class of glyphs with `x` and `y` coordinate attributes. '''
[docs]class AnnularWedge(XYGlyph): ''' Render annular wedges. ''' __example__ = "examples/reference/models/AnnularWedge.py" # a canonical order for positional args that can be used for any # functions derived from this class _args = ('x', 'y', 'inner_radius', 'outer_radius', 'start_angle', 'end_angle', 'direction') x = NumberSpec(help=""" The x-coordinates of the center of the annular wedges. """) y = NumberSpec(help=""" The y-coordinates of the center of the annular wedges. """) inner_radius = DistanceSpec(help=""" The inner radii of the annular wedges. """) outer_radius = DistanceSpec(help=""" The outer radii of the annular wedges. """) start_angle = AngleSpec(help=""" The angles to start the annular wedges, as measured from the horizontal. """) end_angle = AngleSpec(help=""" The angles to end the annular wedges, as measured from the horizontal. """) direction = Enum(Direction, default=Direction.anticlock, help=""" Which direction to stroke between the start and end angles. """) line_props = Include(LineProps, use_prefix=False, help=""" The %s values for the annular wedges. """) fill_props = Include(FillProps, use_prefix=False, help=""" The %s values for the annular wedges. """)
[docs]class Annulus(XYGlyph): ''' Render annuli. ''' __example__ = "examples/reference/models/Annulus.py" # a canonical order for positional args that can be used for any # functions derived from this class _args = ('x', 'y', 'inner_radius', 'outer_radius') x = NumberSpec(help=""" The x-coordinates of the center of the annuli. """) y = NumberSpec(help=""" The y-coordinates of the center of the annuli. """) inner_radius = DistanceSpec(help=""" The inner radii of the annuli. """) outer_radius = DistanceSpec(help=""" The outer radii of the annuli. """) line_props = Include(LineProps, use_prefix=False, help=""" The %s values for the annuli. """) fill_props = Include(FillProps, use_prefix=False, help=""" The %s values for the annuli. """)
[docs]class Arc(XYGlyph): ''' Render arcs. ''' __example__ = "examples/reference/models/Arc.py" # a canonical order for positional args that can be used for any # functions derived from this class _args = ('x', 'y', 'radius', 'start_angle', 'end_angle', 'direction') x = NumberSpec(help=""" The x-coordinates of the center of the arcs. """) y = NumberSpec(help=""" The y-coordinates of the center of the arcs. """) radius = DistanceSpec(help=""" Radius of the arc. """) start_angle = AngleSpec(help=""" The angles to start the arcs, as measured from the horizontal. """) end_angle = AngleSpec(help=""" The angles to end the arcs, as measured from the horizontal. """) direction = Enum(Direction, default='anticlock', help=""" Which direction to stroke between the start and end angles. """) line_props = Include(LineProps, use_prefix=False, help=""" The %s values for the arcs. """)
[docs]class Bezier(Glyph): u''' Render Bézier curves. For more information consult the `Wikipedia article for Bézier curve`_. .. _Wikipedia article for Bézier curve: http://en.wikipedia.org/wiki/Bézier_curve ''' __example__ = "examples/reference/models/Bezier.py" # a canonical order for positional args that can be used for any # functions derived from this class _args = ('x0', 'y0', 'x1', 'y1', 'cx0', 'cy0', 'cx1', 'cy1') x0 = NumberSpec(help=""" The x-coordinates of the starting points. """) y0 = NumberSpec(help=""" The y-coordinates of the starting points. """) x1 = NumberSpec(help=""" The x-coordinates of the ending points. """) y1 = NumberSpec(help=""" The y-coordinates of the ending points. """) cx0 = NumberSpec(help=""" The x-coordinates of first control points. """) cy0 = NumberSpec(help=""" The y-coordinates of first control points. """) cx1 = NumberSpec(help=""" The x-coordinates of second control points. """) cy1 = NumberSpec(help=""" The y-coordinates of second control points. """) line_props = Include(LineProps, use_prefix=False, help=u""" The %s values for the Bézier curves. """)
[docs]class Ellipse(XYGlyph): u''' Render ellipses. ''' __example__ = "examples/reference/models/Ellipse.py" # a canonical order for positional args that can be used for any # functions derived from this class _args = ('x', 'y', 'width', 'height', 'angle') x = NumberSpec(help=""" The x-coordinates of the centers of the ellipses. """) y = NumberSpec(help=""" The y-coordinates of the centers of the ellipses. """) width = DistanceSpec(help=""" The widths of each ellipse. """) height = DistanceSpec(help=""" The heights of each ellipse. """) angle = AngleSpec(default=0.0, help=""" The angle the ellipses are rotated from horizontal. [rad] """) line_props = Include(LineProps, use_prefix=False, help=""" The %s values for the ovals. """) fill_props = Include(FillProps, use_prefix=False, help=""" The %s values for the ovals. """)
[docs]class HBar(Glyph): ''' Render horizontal bars, given a center coordinate, ``height`` and (``left``, ``right``) coordinates. ''' __example__ = "examples/reference/models/HBar.py" # a canonical order for positional args that can be used for any # functions derived from this class _args = ('y', 'height', 'right', 'left') y = NumberSpec(help=""" The y-coordinates of the centers of the horizontal bars. """) height = NumberSpec(help=""" The heights of the vertical bars. """) left = NumberSpec(default=0, help=""" The x-coordinates of the left edges. """) right = NumberSpec(help=""" The x-coordinates of the right edges. """) line_props = Include(LineProps, use_prefix=False, help=""" The %s values for the horizontal bars. """) fill_props = Include(FillProps, use_prefix=False, help=""" The %s values for the horizontal bars. """)
[docs]class Image(XYGlyph): ''' Render images given as scalar data together with a color mapper. In addition to the defined model properties, ``Image`` also can accept a keyword argument ``palette`` in place of an explicit ``color_mapper``. The value should be a list of colors, or the name of one of the built-in palettes in ``bokeh.palettes``. This palette will be used to automatically construct a ``ColorMapper`` model for the ``color_mapper`` property. If both ``palette`` and ``color_mapper`` are passed, a ``ValueError`` exception will be raised. If neither is passed, then the ``Greys9`` palette will be used as a default. ''' def __init__(self, **kwargs): if 'palette' in kwargs and 'color_mapper' in kwargs: raise ValueError("only one of 'palette' and 'color_mapper' may be specified") elif 'color_mapper' not in kwargs: # Use a palette (given or default) palette = kwargs.pop('palette', 'Greys9') mapper = LinearColorMapper(palette) kwargs['color_mapper'] = mapper super(Image, self).__init__(**kwargs) # a canonical order for positional args that can be used for any # functions derived from this class _args = ('image', 'x', 'y', 'dw', 'dh', 'dilate') # a hook to specify any additional kwargs handled by an initializer _extra_kws = { 'palette': ( 'str or list[color value]', 'a palette to construct a value for the color mapper property from' ) } image = NumberSpec(help=""" The arrays of scalar data for the images to be colormapped. """) x = NumberSpec(help=""" The x-coordinates to locate the image anchors. """) y = NumberSpec(help=""" The y-coordinates to locate the image anchors. """) dw = DistanceSpec(help=""" The widths of the plot regions that the images will occupy. .. note:: This is not the number of pixels that an image is wide. That number is fixed by the image itself. """) dh = DistanceSpec(help=""" The height of the plot region that the image will occupy. .. note:: This is not the number of pixels that an image is tall. That number is fixed by the image itself. """) dilate = Bool(False, help=""" Whether to always round fractional pixel locations in such a way as to make the images bigger. This setting may be useful if pixel rounding errors are causing images to have a gap between them, when they should appear flush. """) color_mapper = Instance(ColorMapper, help=""" A ``ColorMapper`` to use to map the scalar data from ``image`` into RGBA values for display. .. note:: The color mapping step happens on the client. """)
# TODO: (bev) support anchor property for Image # ref: https://github.com/bokeh/bokeh/issues/1763
[docs]class ImageRGBA(XYGlyph): ''' Render images given as RGBA data. ''' # a canonical order for positional args that can be used for any # functions derived from this class _args = ('image', 'x', 'y', 'dw', 'dh', 'dilate') image = NumberSpec(help=""" The arrays of RGBA data for the images. """) x = NumberSpec(help=""" The x-coordinates to locate the image anchors. """) y = NumberSpec(help=""" The y-coordinates to locate the image anchors. """) dw = DistanceSpec(help=""" The widths of the plot regions that the images will occupy. .. note:: This is not the number of pixels that an image is wide. That number is fixed by the image itself. """) dh = DistanceSpec(help=""" The height of the plot region that the image will occupy. .. note:: This is not the number of pixels that an image is tall. That number is fixed by the image itself. """) dilate = Bool(False, help=""" Whether to always round fractional pixel locations in such a way as to make the images bigger. This setting may be useful if pixel rounding errors are causing images to have a gap between them, when they should appear flush. """)
# TODO: (bev) support anchor property for ImageRGBA # ref: https://github.com/bokeh/bokeh/issues/1763
[docs]class ImageURL(XYGlyph): ''' Render images loaded from given URLs. ''' __example__ = "examples/reference/models/ImageURL.py" # a canonical order for positional args that can be used for any # functions derived from this class _args = ('url', 'x', 'y', 'w', 'h', 'angle', 'global_alpha', 'dilate') # TODO (bev) Why is this a NumberSpec?? url = NumberSpec(accept_datetime=False, help=""" The URLs to retrieve images from. .. note:: The actual retrieving and loading of the images happens on the client. """) x = NumberSpec(help=""" The x-coordinates to locate the image anchors. """) y = NumberSpec(help=""" The y-coordinates to locate the image anchors. """) w = DistanceSpec(default=None, help=""" The height of the plot region that the image will occupy in data space. The default value is ``None``, in which case the image will be displayed at its actual image size (regardless of the units specified here). """) h = DistanceSpec(default=None, help=""" The height of the plot region that the image will occupy in data space. The default value is ``None``, in which case the image will be displayed at its actual image size (regardless of the units specified here). """) angle = AngleSpec(default=0, help=""" The angles to rotate the images, as measured from the horizontal. """) global_alpha = Float(1.0, help=""" An overall opacity that each image is rendered with (in addition to any inherent alpha values in the image itself). """) dilate = Bool(False, help=""" Whether to always round fractional pixel locations in such a way as to make the images bigger. This setting may be useful if pixel rounding errors are causing images to have a gap between them, when they should appear flush. """) anchor = Enum(Anchor, help=""" What position of the image should be anchored at the `x`, `y` coordinates. """) retry_attempts = Int(0, help=""" Number of attempts to retry loading the images from the specified URL. Default is zero. """) retry_timeout = Int(0, help=""" Timeout (in ms) between retry attempts to load the image from the specified URL. Default is zero ms. """)
[docs]class Line(XYGlyph): ''' Render a single line. The ``Line`` glyph is different from most other glyphs in that the vector of values only produces one glyph on the Plot. ''' # a canonical order for positional args that can be used for any # functions derived from this class _args = ('x', 'y') __example__ = "examples/reference/models/Line.py" x = NumberSpec(help=""" The x-coordinates for the points of the line. """) y = NumberSpec(help=""" The y-coordinates for the points of the line. """) line_props = Include(LineProps, use_prefix=False, help=""" The %s values for the line. """)
[docs]class MultiLine(Glyph): ''' Render several lines. The data for the ``MultiLine`` glyph is different in that the vector of values is not a vector of scalars. Rather, it is a "list of lists". ''' __example__ = "examples/reference/models/MultiLine.py" # a canonical order for positional args that can be used for any # functions derived from this class _args = ('xs', 'ys') xs = NumberSpec(help=""" The x-coordinates for all the lines, given as a "list of lists". """) ys = NumberSpec(help=""" The y-coordinates for all the lines, given as a "list of lists". """) line_props = Include(LineProps, use_prefix=False, help=""" The %s values for the lines. """)
[docs]class Oval(XYGlyph): u''' Render ovals. This glyph renders ovals using Bézier curves, which are similar, but not identical to ellipses. In particular, widths equal to heights will not render circles. Use the ``Ellipse`` glyph for that. ''' __example__ = "examples/reference/models/Oval.py" # a canonical order for positional args that can be used for any # functions derived from this class _args = ('x', 'y', 'width', 'height', 'angle') x = NumberSpec(help=""" The x-coordinates of the centers of the ovals. """) y = NumberSpec(help=""" The y-coordinates of the centers of the ovals. """) width = DistanceSpec(help=""" The overall widths of each oval. """) height = DistanceSpec(help=""" The overall height of each oval. """) angle = AngleSpec(default=0.0, help=""" The angle the ovals are rotated from horizontal. [rad] """) line_props = Include(LineProps, use_prefix=False, help=""" The %s values for the ovals. """) fill_props = Include(FillProps, use_prefix=False, help=""" The %s values for the ovals. """)
[docs]class Patch(XYGlyph): ''' Render a single patch. The ``Patch`` glyph is different from most other glyphs in that the vector of values only produces one glyph on the Plot. ''' __example__ = "examples/reference/models/Patch.py" # a canonical order for positional args that can be used for any # functions derived from this class _args = ('x', 'y') x = NumberSpec(help=""" The x-coordinates for the points of the patch. .. note:: A patch may comprise multiple polygons. In this case the x-coordinates for each polygon should be separated by NaN values in the sequence. """) y = NumberSpec(help=""" The y-coordinates for the points of the patch. .. note:: A patch may comprise multiple polygons. In this case the y-coordinates for each polygon should be separated by NaN values in the sequence. """) line_props = Include(LineProps, use_prefix=False, help=""" The %s values for the patch. """) fill_props = Include(FillProps, use_prefix=False, help=""" The %s values for the patch. """)
[docs]class Patches(Glyph): ''' Render several patches. The data for the ``Patches`` glyph is different in that the vector of values is not a vector of scalars. Rather, it is a "list of lists". ''' __example__ = "examples/reference/models/Patches.py" # a canonical order for positional args that can be used for any # functions derived from this class _args = ('xs', 'ys') xs = NumberSpec(help=""" The x-coordinates for all the patches, given as a "list of lists". .. note:: Individual patches may comprise multiple polygons. In this case the x-coordinates for each polygon should be separated by NaN values in the sublists. """) ys = NumberSpec(help=""" The y-coordinates for all the patches, given as a "list of lists". .. note:: Individual patches may comprise multiple polygons. In this case the y-coordinates for each polygon should be separated by NaN values in the sublists. """) line_props = Include(LineProps, use_prefix=False, help=""" The %s values for the patches. """) fill_props = Include(FillProps, use_prefix=False, help=""" The %s values for the patches. """)
[docs]class Quad(Glyph): ''' Render axis-aligned quads. ''' __example__ = "examples/reference/models/Quad.py" # a canonical order for positional args that can be used for any # functions derived from this class _args = ('left', 'right', 'top', 'bottom') left = NumberSpec(help=""" The x-coordinates of the left edges. """) right = NumberSpec(help=""" The x-coordinates of the right edges. """) bottom = NumberSpec(help=""" The y-coordinates of the bottom edges. """) top = NumberSpec(help=""" The y-coordinates of the top edges. """) line_props = Include(LineProps, use_prefix=False, help=""" The %s values for the quads. """) fill_props = Include(FillProps, use_prefix=False, help=""" The %s values for the quads. """)
[docs]class Quadratic(Glyph): ''' Render parabolas. ''' __example__ = "examples/reference/models/Quadratic.py" # a canonical order for positional args that can be used for any # functions derived from this class _args = ('x0', 'y0', 'x1', 'y1', 'cx', 'cy') x0 = NumberSpec(help=""" The x-coordinates of the starting points. """) y0 = NumberSpec(help=""" The y-coordinates of the starting points. """) x1 = NumberSpec(help=""" The x-coordinates of the ending points. """) y1 = NumberSpec(help=""" The y-coordinates of the ending points. """) cx = NumberSpec(help=""" The x-coordinates of the control points. """) cy = NumberSpec(help=""" The y-coordinates of the control points. """) line_props = Include(LineProps, use_prefix=False, help=""" The %s values for the parabolas. """)
[docs]class Ray(XYGlyph): ''' Render rays. ''' __example__ = "examples/reference/models/Ray.py" # a canonical order for positional args that can be used for any # functions derived from this class _args = ('x', 'y', 'length', 'angle') x = NumberSpec(help=""" The x-coordinates to start the rays. """) y = NumberSpec(help=""" The y-coordinates to start the rays. """) angle = AngleSpec(help=""" The angles in radians to extend the rays, as measured from the horizontal. """) length = DistanceSpec(help=""" The length to extend the ray. Note that this ``length`` defaults to data units (measured in the x-direction). """) line_props = Include(LineProps, use_prefix=False, help=""" The %s values for the rays. """)
[docs]class Rect(XYGlyph): ''' Render rectangles. ''' __example__ = "examples/reference/models/Rect.py" # a canonical order for positional args that can be used for any # functions derived from this class _args = ('x', 'y', 'width', 'height', 'angle', 'dilate') x = NumberSpec(help=""" The x-coordinates of the centers of the rectangles. """) y = NumberSpec(help=""" The y-coordinates of the centers of the rectangles. """) width = DistanceSpec(help=""" The overall widths of the rectangles. """) height = DistanceSpec(help=""" The overall heights of the rectangles. """) angle = AngleSpec(default=0.0, help=""" The angles to rotate the rectangles, as measured from the horizontal. """) dilate = Bool(False, help=""" Whether to always round fractional pixel locations in such a way as to make the rectangles bigger. This setting may be useful if pixel rounding errors are causing rectangles to have a gap between them, when they should appear flush. """) line_props = Include(LineProps, use_prefix=False, help=""" The %s values for the rectangles. """) fill_props = Include(FillProps, use_prefix=False, help=""" The %s values for the rectangles. """)
[docs]class Segment(Glyph): ''' Render segments. ''' __example__ = "examples/reference/models/Segment.py" # a canonical order for positional args that can be used for any # functions derived from this class _args = ('x0', 'y0', 'x1', 'y1') x0 = NumberSpec(help=""" The x-coordinates of the starting points. """) y0 = NumberSpec(help=""" The y-coordinates of the starting points. """) x1 = NumberSpec(help=""" The x-coordinates of the ending points. """) y1 = NumberSpec(help=""" The y-coordinates of the ending points. """) line_props = Include(LineProps, use_prefix=False, help=""" The %s values for the segments. """)
[docs]class Text(XYGlyph): ''' Render text. ''' __example__ = "examples/reference/models/Text.py" # a canonical order for positional args that can be used for any # functions derived from this class _args = ('x', 'y', 'text', 'angle', 'x_offset', 'y_offset') x = NumberSpec(help=""" The x-coordinates to locate the text anchors. """) y = NumberSpec(help=""" The y-coordinates to locate the text anchors. """) text = StringSpec("text", help=""" The text values to render. """) angle = AngleSpec(default=0, help=""" The angles to rotate the text, as measured from the horizontal. """) x_offset = NumberSpec(default=0, help=""" Offset values to apply to the x-coordinates. This is useful, for instance, if it is desired to "float" text a fixed distance in screen units from a given data position. """) y_offset = NumberSpec(default=0, help=""" Offset values to apply to the y-coordinates. This is useful, for instance, if it is desired to "float" text a fixed distance in screen units from a given data position. """) text_props = Include(TextProps, use_prefix=False, help=""" The %s values for the text. """)
[docs]class VBar(Glyph): ''' Render vertical bars, given a center coordinate, width and (top, bottom) coordinates. ''' __example__ = "examples/reference/models/VBar.py" # a canonical order for positional args that can be used for any # functions derived from this class _args = ('x', 'width', 'top', 'bottom') x = NumberSpec(help=""" The x-coordinates of the centers of the vertical bars. """) width = NumberSpec(help=""" The widths of the vertical bars. """) bottom = NumberSpec(default=0, help=""" The y-coordinates of the bottom edges. """) top = NumberSpec(help=""" The y-coordinates of the top edges. """) line_props = Include(LineProps, use_prefix=False, help=""" The %s values for the vertical bars. """) fill_props = Include(FillProps, use_prefix=False, help=""" The %s values for the vertical bars. """)
[docs]class Wedge(XYGlyph): ''' Render wedges. ''' __example__ = "examples/reference/models/Wedge.py" # a canonical order for positional args that can be used for any # functions derived from this class _args = ('x', 'y', 'radius', 'start_angle', 'end_angle', 'direction') x = NumberSpec(help=""" The x-coordinates of the points of the wedges. """) y = NumberSpec(help=""" The y-coordinates of the points of the wedges. """) radius = DistanceSpec(help=""" Radii of the wedges. """) start_angle = AngleSpec(help=""" The angles to start the wedges, as measured from the horizontal. """) end_angle = AngleSpec(help=""" The angles to end the wedges, as measured from the horizontal. """) direction = Enum(Direction, default='anticlock', help=""" Which direction to stroke between the start and end angles. """) line_props = Include(LineProps, use_prefix=False, help=""" The %s values for the wedges. """) fill_props = Include(FillProps, use_prefix=False, help=""" The %s values for the wedges. """)
# XXX: allow `from bokeh.models.glyphs import *` from .markers import (Asterisk, Circle, CircleCross, CircleX, Cross, Diamond, DiamondCross, InvertedTriangle, Marker, Square, SquareCross, SquareX, Triangle, X) # Fool pyflakes (Asterisk, Circle, CircleCross, CircleX, Cross, Diamond, DiamondCross, InvertedTriangle, Marker, Square, SquareCross, SquareX, Triangle, X)