1#----------------------------------------------------------------------------- 2# Copyright (c) 2012 - 2021, Anaconda, Inc., and Bokeh Contributors. 3# All rights reserved. 4# 5# The full license is in the file LICENSE.txt, distributed with this software. 6#----------------------------------------------------------------------------- 7''' Display a variety of visual shapes whose attributes can be associated 8with data columns from ``ColumnDataSources``. 9 10The full list of glyphs built into Bokeh is given below: 11 12* :class:`~bokeh.models.glyphs.AnnularWedge` 13* :class:`~bokeh.models.glyphs.Annulus` 14* :class:`~bokeh.models.glyphs.Arc` 15* :class:`~bokeh.models.glyphs.Bezier` 16* :class:`~bokeh.models.glyphs.Circle` 17* :class:`~bokeh.models.glyphs.Ellipse` 18* :class:`~bokeh.models.glyphs.HArea` 19* :class:`~bokeh.models.glyphs.HBar` 20* :class:`~bokeh.models.glyphs.HexTile` 21* :class:`~bokeh.models.glyphs.Image` 22* :class:`~bokeh.models.glyphs.ImageRGBA` 23* :class:`~bokeh.models.glyphs.ImageURL` 24* :class:`~bokeh.models.glyphs.Line` 25* :class:`~bokeh.models.glyphs.MultiLine` 26* :class:`~bokeh.models.glyphs.MultiPolygons` 27* :class:`~bokeh.models.glyphs.Oval` 28* :class:`~bokeh.models.glyphs.Patch` 29* :class:`~bokeh.models.glyphs.Patches` 30* :class:`~bokeh.models.glyphs.Quad` 31* :class:`~bokeh.models.glyphs.Quadratic` 32* :class:`~bokeh.models.glyphs.Ray` 33* :class:`~bokeh.models.glyphs.Rect` 34* :class:`~bokeh.models.glyphs.Scatter` 35* :class:`~bokeh.models.glyphs.Segment` 36* :class:`~bokeh.models.glyphs.Step` 37* :class:`~bokeh.models.glyphs.Text` 38* :class:`~bokeh.models.glyphs.VArea` 39* :class:`~bokeh.models.glyphs.VBar` 40* :class:`~bokeh.models.glyphs.Wedge` 41 42All these glyphs share a minimal common interface through their base class 43``Glyph``: 44 45.. autoclass:: Glyph 46 :members: 47 48''' 49 50#----------------------------------------------------------------------------- 51# Boilerplate 52#----------------------------------------------------------------------------- 53import logging # isort:skip 54log = logging.getLogger(__name__) 55 56#----------------------------------------------------------------------------- 57# Imports 58#----------------------------------------------------------------------------- 59 60# Bokeh imports 61from ..core.enums import Anchor, Direction, StepMode, enumeration 62from ..core.has_props import abstract 63from ..core.properties import ( 64 AngleSpec, 65 Bool, 66 DistanceSpec, 67 Enum, 68 Float, 69 Include, 70 Instance, 71 Int, 72 MarkerSpec, 73 NullDistanceSpec, 74 NumberSpec, 75 Override, 76 ScreenDistanceSpec, 77 Size, 78 String, 79 StringSpec, 80) 81from ..core.property.dataspec import field 82from ..core.property_mixins import ( 83 FillProps, 84 HatchProps, 85 LineProps, 86 ScalarFillProps, 87 ScalarHatchProps, 88 ScalarLineProps, 89 TextProps, 90) 91from ..util.deprecation import deprecated 92from .glyph import ( 93 ConnectedXYGlyph, 94 FillGlyph, 95 Glyph, 96 HatchGlyph, 97 LineGlyph, 98 TextGlyph, 99 XYGlyph, 100) 101from .mappers import ColorMapper, LinearColorMapper 102 103#----------------------------------------------------------------------------- 104# Globals and constants 105#----------------------------------------------------------------------------- 106 107__all__ = ( 108 'AnnularWedge', 109 'Annulus', 110 'Arc', 111 'Bezier', 112 'ConnectedXYGlyph', 113 'Ellipse', 114 'Glyph', 115 'HArea', 116 'HBar', 117 'HexTile', 118 'Image', 119 'ImageRGBA', 120 'ImageURL', 121 'Line', 122 'Marker', 123 'MultiLine', 124 'MultiPolygons', 125 'Oval', 126 'Patch', 127 'Patches', 128 'Quad', 129 'Quadratic', 130 'Ray', 131 'Rect', 132 'Segment', 133 'Step', 134 'Text', 135 'VArea', 136 'VBar', 137 'Wedge', 138 'XYGlyph', 139) 140 141#----------------------------------------------------------------------------- 142# General API 143#----------------------------------------------------------------------------- 144 145@abstract 146class Marker(XYGlyph, LineGlyph, FillGlyph, HatchGlyph): 147 ''' Base class for glyphs that are simple markers with line and 148 fill properties, located at an (x, y) location with a specified 149 size. 150 151 .. note:: 152 For simplicity, all markers have both line and fill properties 153 declared, however some marker types (`asterisk`, `cross`, `x`) 154 only draw lines. For these markers, the fill values are simply 155 ignored. 156 157 ''' 158 159 _args = ('x', 'y', 'size', 'angle') 160 161 x = NumberSpec(default=field("x"), help=""" 162 The x-axis coordinates for the center of the markers. 163 """) 164 165 y = NumberSpec(default=field("y"), help=""" 166 The y-axis coordinates for the center of the markers. 167 """) 168 169 hit_dilation = Size(default=1.0, help=""" 170 The factor by which to dilate the hit radius 171 which is responsible for defining the range in which a 172 marker responds to interactions with the Hover and Tap 173 tools. 174 """) 175 176 size = ScreenDistanceSpec(default=4, help=""" 177 The size (diameter) values for the markers in screen space units. 178 """) 179 180 angle = AngleSpec(default=0.0, help=""" 181 The angles to rotate the markers. 182 """) 183 184 line_props = Include(LineProps, use_prefix=False, help=""" 185 The %s values for the markers. 186 """) 187 188 fill_props = Include(FillProps, use_prefix=False, help=""" 189 The %s values for the markers. 190 """) 191 192 hatch_props = Include(HatchProps, use_prefix=False, help=""" 193 The %s values for the markers. 194 """) 195 196class AnnularWedge(XYGlyph, LineGlyph, FillGlyph, HatchGlyph): 197 ''' Render annular wedges. 198 199 ''' 200 201 __example__ = "examples/reference/models/AnnularWedge.py" 202 203 _args = ('x', 'y', 'inner_radius', 'outer_radius', 'start_angle', 'end_angle', 'direction') 204 205 x = NumberSpec(default=field("x"), help=""" 206 The x-coordinates of the center of the annular wedges. 207 """) 208 209 y = NumberSpec(default=field("y"), help=""" 210 The y-coordinates of the center of the annular wedges. 211 """) 212 213 inner_radius = DistanceSpec(default=field("inner_radius"), help=""" 214 The inner radii of the annular wedges. 215 """) 216 217 outer_radius = DistanceSpec(default=field("outer_radius"), help=""" 218 The outer radii of the annular wedges. 219 """) 220 221 start_angle = AngleSpec(default=field("start_angle"), help=""" 222 The angles to start the annular wedges, as measured from the horizontal. 223 """) 224 225 end_angle = AngleSpec(default=field("end_angle"), help=""" 226 The angles to end the annular wedges, as measured from the horizontal. 227 """) 228 229 direction = Enum(Direction, default=Direction.anticlock, help=""" 230 Which direction to stroke between the start and end angles. 231 """) 232 233 line_props = Include(LineProps, use_prefix=False, help=""" 234 The %s values for the annular wedges. 235 """) 236 237 fill_props = Include(FillProps, use_prefix=False, help=""" 238 The %s values for the annular wedges. 239 """) 240 241 hatch_props = Include(HatchProps, use_prefix=False, help=""" 242 The %s values for the annular wedges. 243 """) 244 245class Annulus(XYGlyph, LineGlyph, FillGlyph, HatchGlyph): 246 ''' Render annuli. 247 248 ''' 249 250 __example__ = "examples/reference/models/Annulus.py" 251 252 _args = ('x', 'y', 'inner_radius', 'outer_radius') 253 254 x = NumberSpec(default=field("x"), help=""" 255 The x-coordinates of the center of the annuli. 256 """) 257 258 y = NumberSpec(default=field("y"), help=""" 259 The y-coordinates of the center of the annuli. 260 """) 261 262 inner_radius = DistanceSpec(default=field("inner_radius"), help=""" 263 The inner radii of the annuli. 264 """) 265 266 outer_radius = DistanceSpec(default=field("outer_radius"), help=""" 267 The outer radii of the annuli. 268 """) 269 270 line_props = Include(LineProps, use_prefix=False, help=""" 271 The %s values for the annuli. 272 """) 273 274 fill_props = Include(FillProps, use_prefix=False, help=""" 275 The %s values for the annuli. 276 """) 277 278 hatch_props = Include(HatchProps, use_prefix=False, help=""" 279 The %s values for the annuli. 280 """) 281 282class Arc(XYGlyph, LineGlyph): 283 ''' Render arcs. 284 285 ''' 286 287 __example__ = "examples/reference/models/Arc.py" 288 289 _args = ('x', 'y', 'radius', 'start_angle', 'end_angle', 'direction') 290 291 x = NumberSpec(default=field("x"), help=""" 292 The x-coordinates of the center of the arcs. 293 """) 294 295 y = NumberSpec(default=field("y"), help=""" 296 The y-coordinates of the center of the arcs. 297 """) 298 299 radius = DistanceSpec(default=field("radius"), help=""" 300 Radius of the arc. 301 """) 302 303 start_angle = AngleSpec(default=field("start_angle"), help=""" 304 The angles to start the arcs, as measured from the horizontal. 305 """) 306 307 end_angle = AngleSpec(default=field("end_angle"), help=""" 308 The angles to end the arcs, as measured from the horizontal. 309 """) 310 311 direction = Enum(Direction, default='anticlock', help=""" 312 Which direction to stroke between the start and end angles. 313 """) 314 315 line_props = Include(LineProps, use_prefix=False, help=""" 316 The %s values for the arcs. 317 """) 318 319class Bezier(LineGlyph): 320 ''' Render Bezier curves. 321 322 For more information consult the `Wikipedia article for Bezier curve`_. 323 324 .. _Wikipedia article for Bezier curve: http://en.wikipedia.org/wiki/Bezier_curve 325 326 ''' 327 328 __example__ = "examples/reference/models/Bezier.py" 329 330 _args = ("x0", "y0", "x1", "y1", "cx0", "cy0", "cx1", "cy1") 331 332 x0 = NumberSpec(default=field("x0"), help=""" 333 The x-coordinates of the starting points. 334 """) 335 336 y0 = NumberSpec(default=field("y0"), help=""" 337 The y-coordinates of the starting points. 338 """) 339 340 x1 = NumberSpec(default=field("x1"), help=""" 341 The x-coordinates of the ending points. 342 """) 343 344 y1 = NumberSpec(default=field("y1"), help=""" 345 The y-coordinates of the ending points. 346 """) 347 348 cx0 = NumberSpec(default=field("cx0"), help=""" 349 The x-coordinates of first control points. 350 """) 351 352 cy0 = NumberSpec(default=field("cy0"), help=""" 353 The y-coordinates of first control points. 354 """) 355 356 cx1 = NumberSpec(default=field("cx1"), help=""" 357 The x-coordinates of second control points. 358 """) 359 360 cy1 = NumberSpec(default=field("cy1"), help=""" 361 The y-coordinates of second control points. 362 """) 363 364 line_props = Include(LineProps, use_prefix=False, help=""" 365 The %s values for the Bezier curves. 366 """) 367 368class Circle(Marker): 369 ''' Render circle markers. ''' 370 371 __example__ = "examples/reference/models/Circle.py" 372 373 _args = ('x', 'y') 374 375 radius = NullDistanceSpec(help=""" 376 The radius values for circle markers (in "data space" units, by default). 377 378 .. note:: 379 Circle markers are slightly unusual in that they support specifying 380 a radius in addition to a size. Only one of ``radius`` or ``size`` 381 should be given. 382 383 .. warning:: 384 Note that ``Circle`` glyphs are always drawn as circles on the screen, 385 even in cases where the data space aspect ratio is not 1-1. In all 386 cases where radius values are specified, the "distance" for the radius 387 is measured along the dimension specified by ``radius_dimension``. If 388 the aspect ratio is very large or small, the drawn circles may appear 389 much larger or smaller than expected. See :bokeh-issue:`626` for more 390 information. 391 392 """) 393 394 radius_dimension = Enum(enumeration('x', 'y', 'max', 'min'), help=""" 395 What dimension to measure circle radii along. 396 397 When the data space aspect ratio is not 1-1, then the size of the drawn 398 circles depends on what direction is used to measure the "distance" of 399 the radius. This property allows that direction to be controlled. 400 401 Setting this dimension to 'max' will calculate the radius on both the x 402 and y dimensions and use the maximum of the two, 'min' selects the minimum. 403 """) 404 405class Ellipse(XYGlyph, LineGlyph, FillGlyph, HatchGlyph): 406 ''' Render ellipses. 407 408 ''' 409 410 __example__ = "examples/reference/models/Ellipse.py" 411 412 _args = ('x', 'y', 'width', 'height', 'angle') 413 414 x = NumberSpec(default=field("x"), help=""" 415 The x-coordinates of the centers of the ellipses. 416 """) 417 418 y = NumberSpec(default=field("y"), help=""" 419 The y-coordinates of the centers of the ellipses. 420 """) 421 422 width = DistanceSpec(default=field("width"), help=""" 423 The widths of each ellipse. 424 """) 425 426 height = DistanceSpec(default=field("height"), help=""" 427 The heights of each ellipse. 428 """) 429 430 angle = AngleSpec(default=0.0, help=""" 431 The angle the ellipses are rotated from horizontal. [rad] 432 """) 433 434 line_props = Include(LineProps, use_prefix=False, help=""" 435 The %s values for the ellipses. 436 """) 437 438 fill_props = Include(FillProps, use_prefix=False, help=""" 439 The %s values for the ellipses. 440 """) 441 442 hatch_props = Include(HatchProps, use_prefix=False, help=""" 443 The %s values for the ellipses. 444 """) 445 446class HArea(LineGlyph, FillGlyph, HatchGlyph): 447 ''' Render a horizontally directed area between two equal length sequences 448 of x-coordinates with the same y-coordinates. 449 450 ''' 451 452 __example__ = "examples/reference/models/HArea.py" 453 454 _args = ('x1', 'x2', 'y') 455 456 x1 = NumberSpec(default=field("x1"), help=""" 457 The x-coordinates for the points of one side of the area. 458 """) 459 460 x2 = NumberSpec(default=field("x2"), help=""" 461 The x-coordinates for the points of the other side of the area. 462 """) 463 464 y = NumberSpec(default=field("y"), help=""" 465 The y-coordinates for the points of the area. 466 """) 467 468 fill_props = Include(ScalarFillProps, use_prefix=False, help=""" 469 The %s values for the horizontal directed area. 470 """) 471 472 hatch_props = Include(HatchProps, use_prefix=False, help=""" 473 The %s values for the horizontal directed area. 474 """) 475 476class HBar(LineGlyph, FillGlyph, HatchGlyph): 477 ''' Render horizontal bars, given a center coordinate, ``height`` and 478 (``left``, ``right``) coordinates. 479 480 ''' 481 482 __example__ = "examples/reference/models/HBar.py" 483 484 _args = ('y', 'height', 'right', 'left') 485 486 y = NumberSpec(default=field("y"), help=""" 487 The y-coordinates of the centers of the horizontal bars. 488 """) 489 490 height = NumberSpec(default=1, help=""" 491 The heights of the vertical bars. 492 """) 493 494 left = NumberSpec(default=0, help=""" 495 The x-coordinates of the left edges. 496 """) 497 498 right = NumberSpec(default=field("right"), help=""" 499 The x-coordinates of the right edges. 500 """) 501 502 line_props = Include(LineProps, use_prefix=False, help=""" 503 The %s values for the horizontal bars. 504 """) 505 506 fill_props = Include(FillProps, use_prefix=False, help=""" 507 The %s values for the horizontal bars. 508 """) 509 510 hatch_props = Include(HatchProps, use_prefix=False, help=""" 511 The %s values for the horizontal bars. 512 """) 513 514class HexTile(LineGlyph, FillGlyph, HatchGlyph): 515 ''' Render horizontal tiles on a regular hexagonal grid. 516 517 ''' 518 519 __example__ = "examples/reference/models/HexTile.py" 520 521 _args = ('q', 'r') 522 523 size = Float(1.0, help=""" 524 The radius (in data space units) of the hex tiling. 525 526 The radius is always measured along the cartesian y-axis for "pointy_top" 527 orientation, and along the cartesian x-axis for "flat_top" orientation. If 528 the aspect ratio of the underlying cartesian system is not 1-1, then the 529 tiles may be "squished" in one direction. To ensure that the tiles are 530 always regular hexagons, consider setting the ``match_aspect`` property of 531 the plot to True. 532 """) 533 534 aspect_scale = Float(1.0, help=""" 535 536 """) 537 538 r = NumberSpec(default=field("r"), help=""" 539 The "row" axial coordinates of the tile centers. 540 """) 541 542 q = NumberSpec(default=field("q"), help=""" 543 The "column" axial coordinates of the tile centers. 544 """) 545 546 scale = NumberSpec(1.0, help=""" 547 A scale factor for individual tiles. 548 """) 549 550 orientation = String("pointytop", help=""" 551 552 """) 553 554 line_props = Include(LineProps, use_prefix=False, help=""" 555 The %s values for the hex tiles. 556 """) 557 558 line_color = Override(default=None) 559 560 fill_props = Include(FillProps, use_prefix=False, help=""" 561 The %s values for the hex tiles. 562 """) 563 564 hatch_props = Include(HatchProps, use_prefix=False, help=""" 565 The %s values for the hex tiles. 566 """) 567 568class Image(XYGlyph): 569 ''' Render images given as scalar data together with a color mapper. 570 571 In addition to the defined model properties, ``Image`` also can accept 572 a keyword argument ``palette`` in place of an explicit ``color_mapper``. 573 The value should be a list of colors, or the name of one of the built-in 574 palettes in ``bokeh.palettes``. This palette will be used to automatically 575 construct a ``ColorMapper`` model for the ``color_mapper`` property. 576 577 If both ``palette`` and ``color_mapper`` are passed, a ``ValueError`` 578 exception will be raised. If neither is passed, then the ``Greys9`` 579 palette will be used as a default. 580 581 ''' 582 583 def __init__(self, **kwargs): 584 if 'palette' in kwargs and 'color_mapper' in kwargs: 585 raise ValueError("only one of 'palette' and 'color_mapper' may be specified") 586 elif 'color_mapper' not in kwargs: 587 # Use a palette (given or default) 588 palette = kwargs.pop('palette', 'Greys9') 589 mapper = LinearColorMapper(palette) 590 kwargs['color_mapper'] = mapper 591 592 super().__init__(**kwargs) 593 594 _args = ('image', 'x', 'y', 'dw', 'dh', 'dilate') 595 596 # a hook to specify any additional kwargs handled by an initializer 597 _extra_kws = { 598 'palette': ( 599 'str or list[color value]', 600 'a palette to construct a value for the color mapper property from' 601 ) 602 } 603 604 image = NumberSpec(default=field("image"), help=""" 605 The arrays of scalar data for the images to be colormapped. 606 """) 607 608 x = NumberSpec(default=field("x"), help=""" 609 The x-coordinates to locate the image anchors. 610 """) 611 612 y = NumberSpec(default=field("y"), help=""" 613 The y-coordinates to locate the image anchors. 614 """) 615 616 dw = DistanceSpec(default=field("dw"), help=""" 617 The widths of the plot regions that the images will occupy. 618 619 .. note:: 620 This is not the number of pixels that an image is wide. 621 That number is fixed by the image itself. 622 """) 623 624 dh = DistanceSpec(default=field("dh"), help=""" 625 The height of the plot region that the image will occupy. 626 627 .. note:: 628 This is not the number of pixels that an image is tall. 629 That number is fixed by the image itself. 630 """) 631 632 global_alpha = Float(1.0, help=""" 633 An overall opacity that each image is rendered with (in addition 634 to any alpha values applied explicitly in a color mapper). 635 """) 636 637 dilate = Bool(False, help=""" 638 Whether to always round fractional pixel locations in such a way 639 as to make the images bigger. 640 641 This setting may be useful if pixel rounding errors are causing 642 images to have a gap between them, when they should appear flush. 643 """) 644 645 color_mapper = Instance(ColorMapper, lambda: LinearColorMapper(palette="Greys9"), help=""" 646 A ``ColorMapper`` to use to map the scalar data from ``image`` 647 into RGBA values for display. 648 649 .. note:: 650 The color mapping step happens on the client. 651 """) 652 653 # TODO: (bev) support anchor property for Image 654 # ref: https://github.com/bokeh/bokeh/issues/1763 655 656class ImageRGBA(XYGlyph): 657 ''' Render images given as RGBA data. 658 659 ''' 660 661 _args = ('image', 'x', 'y', 'dw', 'dh', 'dilate') 662 663 image = NumberSpec(default=field("image"), help=""" 664 The arrays of RGBA data for the images. 665 """) 666 667 x = NumberSpec(default=field("x"), help=""" 668 The x-coordinates to locate the image anchors. 669 """) 670 671 y = NumberSpec(default=field("y"), help=""" 672 The y-coordinates to locate the image anchors. 673 """) 674 675 dw = DistanceSpec(default=field("dw"), help=""" 676 The widths of the plot regions that the images will occupy. 677 678 .. note:: 679 This is not the number of pixels that an image is wide. 680 That number is fixed by the image itself. 681 """) 682 683 dh = DistanceSpec(default=field("dh"), help=""" 684 The height of the plot region that the image will occupy. 685 686 .. note:: 687 This is not the number of pixels that an image is tall. 688 That number is fixed by the image itself. 689 """) 690 691 global_alpha = Float(1.0, help=""" 692 An overall opacity that each image is rendered with (in addition 693 to any inherent alpha values in the image itself). 694 """) 695 696 dilate = Bool(False, help=""" 697 Whether to always round fractional pixel locations in such a way 698 as to make the images bigger. 699 700 This setting may be useful if pixel rounding errors are causing 701 images to have a gap between them, when they should appear flush. 702 """) 703 704 # TODO: (bev) support anchor property for ImageRGBA 705 # ref: https://github.com/bokeh/bokeh/issues/1763 706 707class ImageURL(XYGlyph): 708 ''' Render images loaded from given URLs. 709 710 ''' 711 712 __example__ = "examples/reference/models/ImageURL.py" 713 714 _args = ('url', 'x', 'y', 'w', 'h', 'angle', 'dilate') 715 716 url = StringSpec(default=field("url"), help=""" 717 The URLs to retrieve images from. 718 719 .. note:: 720 The actual retrieving and loading of the images happens on 721 the client. 722 """) 723 724 x = NumberSpec(default=field("x"), help=""" 725 The x-coordinates to locate the image anchors. 726 """) 727 728 y = NumberSpec(default=field("y"), help=""" 729 The y-coordinates to locate the image anchors. 730 """) 731 732 w = NullDistanceSpec(help=""" 733 The width of the plot region that the image will occupy in data space. 734 735 The default value is ``None``, in which case the image will be displayed 736 at its actual image size (regardless of the units specified here). 737 """) 738 739 h = NullDistanceSpec(help=""" 740 The height of the plot region that the image will occupy in data space. 741 742 The default value is ``None``, in which case the image will be displayed 743 at its actual image size (regardless of the units specified here). 744 """) 745 746 angle = AngleSpec(default=0, help=""" 747 The angles to rotate the images, as measured from the horizontal. 748 """) 749 750 global_alpha = Float(1.0, help=""" 751 An overall opacity that each image is rendered with (in addition 752 to any inherent alpha values in the image itself). 753 """) 754 755 dilate = Bool(False, help=""" 756 Whether to always round fractional pixel locations in such a way 757 as to make the images bigger. 758 759 This setting may be useful if pixel rounding errors are causing 760 images to have a gap between them, when they should appear flush. 761 """) 762 763 anchor = Enum(Anchor, help=""" 764 What position of the image should be anchored at the `x`, `y` 765 coordinates. 766 """) 767 768 retry_attempts = Int(0, help=""" 769 Number of attempts to retry loading the images from the specified URL. 770 Default is zero. 771 """) 772 773 retry_timeout = Int(0, help=""" 774 Timeout (in ms) between retry attempts to load the image from the 775 specified URL. Default is zero ms. 776 """) 777 778class Line(ConnectedXYGlyph, LineGlyph): 779 ''' Render a single line. 780 781 The ``Line`` glyph is different from most other glyphs in that the vector 782 of values only produces one glyph on the Plot. 783 784 ''' 785 _args = ('x', 'y') 786 787 __example__ = "examples/reference/models/Line.py" 788 789 x = NumberSpec(default=field("x"), help=""" 790 The x-coordinates for the points of the line. 791 """) 792 793 y = NumberSpec(default=field("y"), help=""" 794 The y-coordinates for the points of the line. 795 """) 796 797 line_props = Include(ScalarLineProps, use_prefix=False, help=""" 798 The %s values for the line. 799 """) 800 801class MultiLine(LineGlyph): 802 ''' Render several lines. 803 804 The data for the ``MultiLine`` glyph is different in that the vector of 805 values is not a vector of scalars. Rather, it is a "list of lists". 806 807 ''' 808 809 __example__ = "examples/reference/models/MultiLine.py" 810 811 _args = ('xs', 'ys') 812 813 xs = NumberSpec(default=field("xs"), help=""" 814 The x-coordinates for all the lines, given as a "list of lists". 815 """) 816 817 ys = NumberSpec(default=field("ys"), help=""" 818 The y-coordinates for all the lines, given as a "list of lists". 819 """) 820 821 line_props = Include(LineProps, use_prefix=False, help=""" 822 The %s values for the lines. 823 """) 824 825class MultiPolygons(LineGlyph, FillGlyph, HatchGlyph): 826 ''' Render several MultiPolygon. 827 828 Modeled on geoJSON - the data for the ``MultiPolygons`` glyph is 829 different in that the vector of values is not a vector of scalars. 830 Rather, it is a "list of lists of lists of lists". 831 832 During box selection only multi-polygons entirely contained in the 833 selection box will be included. 834 835 ''' 836 837 __example__ = "examples/reference/models/MultiPolygons.py" 838 839 _args = ('xs', 'ys') 840 841 xs = NumberSpec(default=field("xs"), help=""" 842 The x-coordinates for all the patches, given as a nested list. 843 844 .. note:: 845 Each item in ``MultiPolygons`` represents one MultiPolygon and each 846 MultiPolygon is comprised of ``n`` Polygons. Each Polygon is made of 847 one exterior ring optionally followed by ``m`` interior rings (holes). 848 """) 849 850 ys = NumberSpec(default=field("ys"), help=""" 851 The y-coordinates for all the patches, given as a "list of lists". 852 853 .. note:: 854 Each item in ``MultiPolygons`` represents one MultiPolygon and each 855 MultiPolygon is comprised of ``n`` Polygons. Each Polygon is made of 856 one exterior ring optionally followed by ``m`` interior rings (holes). 857 """) 858 859 line_props = Include(LineProps, use_prefix=False, help=""" 860 The %s values for the multipolygons. 861 """) 862 863 fill_props = Include(FillProps, use_prefix=False, help=""" 864 The %s values for the multipolygons. 865 """) 866 867 hatch_props = Include(HatchProps, use_prefix=False, help=""" 868 The %s values for the multipolygons. 869 """) 870 871class Oval(XYGlyph, LineGlyph, FillGlyph, HatchGlyph): 872 ''' Render ovals. 873 874 This glyph renders ovals using Bezier curves, which are similar, 875 but not identical to ellipses. In particular, widths equal to heights 876 will not render circles. Use the ``Ellipse`` glyph for that. 877 878 ''' 879 880 def __init__(self, **kwargs): 881 deprecated("'Oval' is deprecated and will be removed in Bokeh 3.0, use the Ellipse glyph instead") 882 super().__init__(**kwargs) 883 884 __example__ = "examples/reference/models/Oval.py" 885 886 _args = ('x', 'y', 'width', 'height', 'angle') 887 888 x = NumberSpec(default=field("x"), help=""" 889 The x-coordinates of the centers of the ovals. 890 """) 891 892 y = NumberSpec(default=field("y"), help=""" 893 The y-coordinates of the centers of the ovals. 894 """) 895 896 width = DistanceSpec(default=field("width"), help=""" 897 The overall widths of each oval. 898 """) 899 900 height = DistanceSpec(default=field("height"), help=""" 901 The overall height of each oval. 902 """) 903 904 angle = AngleSpec(default=0.0, help=""" 905 The angle the ovals are rotated from horizontal. [rad] 906 """) 907 908 line_props = Include(LineProps, use_prefix=False, help=""" 909 The %s values for the ovals. 910 """) 911 912 fill_props = Include(FillProps, use_prefix=False, help=""" 913 The %s values for the ovals. 914 """) 915 916 hatch_props = Include(HatchProps, use_prefix=False, help=""" 917 The %s values for the ovals. 918 """) 919 920class Patch(ConnectedXYGlyph, LineGlyph, FillGlyph, HatchGlyph): 921 ''' Render a single patch. 922 923 The ``Patch`` glyph is different from most other glyphs in that the vector 924 of values only produces one glyph on the Plot. 925 926 ''' 927 928 __example__ = "examples/reference/models/Patch.py" 929 930 _args = ('x', 'y') 931 932 x = NumberSpec(default=field("x"), help=""" 933 The x-coordinates for the points of the patch. 934 935 .. note:: 936 A patch may comprise multiple polygons. In this case the 937 x-coordinates for each polygon should be separated by NaN 938 values in the sequence. 939 """) 940 941 y = NumberSpec(default=field("y"), help=""" 942 The y-coordinates for the points of the patch. 943 944 .. note:: 945 A patch may comprise multiple polygons. In this case the 946 y-coordinates for each polygon should be separated by NaN 947 values in the sequence. 948 """) 949 950 line_props = Include(ScalarLineProps, use_prefix=False, help=""" 951 The %s values for the patch. 952 """) 953 954 fill_props = Include(ScalarFillProps, use_prefix=False, help=""" 955 The %s values for the patch. 956 """) 957 958 hatch_props = Include(ScalarHatchProps, use_prefix=False, help=""" 959 The %s values for the patch. 960 """) 961 962class Patches(LineGlyph, FillGlyph, HatchGlyph): 963 ''' Render several patches. 964 965 The data for the ``Patches`` glyph is different in that the vector of 966 values is not a vector of scalars. Rather, it is a "list of lists". 967 968 During box selection only patches entirely contained in the 969 selection box will be included. 970 971 ''' 972 973 __example__ = "examples/reference/models/Patches.py" 974 975 _args = ('xs', 'ys') 976 977 xs = NumberSpec(default=field("xs"), help=""" 978 The x-coordinates for all the patches, given as a "list of lists". 979 980 .. note:: 981 Individual patches may comprise multiple polygons. In this case 982 the x-coordinates for each polygon should be separated by NaN 983 values in the sublists. 984 """) 985 986 ys = NumberSpec(default=field("ys"), help=""" 987 The y-coordinates for all the patches, given as a "list of lists". 988 989 .. note:: 990 Individual patches may comprise multiple polygons. In this case 991 the y-coordinates for each polygon should be separated by NaN 992 values in the sublists. 993 """) 994 995 line_props = Include(LineProps, use_prefix=False, help=""" 996 The %s values for the patches. 997 """) 998 999 fill_props = Include(FillProps, use_prefix=False, help=""" 1000 The %s values for the patches. 1001 """) 1002 1003 hatch_props = Include(HatchProps, use_prefix=False, help=""" 1004 The %s values for the patches. 1005 """) 1006 1007class Quad(LineGlyph, FillGlyph, HatchGlyph): 1008 ''' Render axis-aligned quads. 1009 1010 ''' 1011 1012 __example__ = "examples/reference/models/Quad.py" 1013 1014 _args = ('left', 'right', 'top', 'bottom') 1015 1016 left = NumberSpec(default=field("left"), help=""" 1017 The x-coordinates of the left edges. 1018 """) 1019 1020 right = NumberSpec(default=field("right"), help=""" 1021 The x-coordinates of the right edges. 1022 """) 1023 1024 bottom = NumberSpec(default=field("bottom"), help=""" 1025 The y-coordinates of the bottom edges. 1026 """) 1027 1028 top = NumberSpec(default=field("top"), help=""" 1029 The y-coordinates of the top edges. 1030 """) 1031 1032 line_props = Include(LineProps, use_prefix=False, help=""" 1033 The %s values for the quads. 1034 """) 1035 1036 fill_props = Include(FillProps, use_prefix=False, help=""" 1037 The %s values for the quads. 1038 """) 1039 1040 hatch_props = Include(HatchProps, use_prefix=False, help=""" 1041 The %s values for the quads. 1042 """) 1043 1044class Quadratic(LineGlyph): 1045 ''' Render parabolas. 1046 1047 ''' 1048 1049 __example__ = "examples/reference/models/Quadratic.py" 1050 1051 _args = ("x0", "y0", "x1", "y1", "cx", "cy") 1052 1053 x0 = NumberSpec(default=field("x0"), help=""" 1054 The x-coordinates of the starting points. 1055 """) 1056 1057 y0 = NumberSpec(default=field("y0"), help=""" 1058 The y-coordinates of the starting points. 1059 """) 1060 1061 x1 = NumberSpec(default=field("x1"), help=""" 1062 The x-coordinates of the ending points. 1063 """) 1064 1065 y1 = NumberSpec(default=field("y1"), help=""" 1066 The y-coordinates of the ending points. 1067 """) 1068 1069 cx = NumberSpec(default=field("cx"), help=""" 1070 The x-coordinates of the control points. 1071 """) 1072 1073 cy = NumberSpec(default=field("cy"), help=""" 1074 The y-coordinates of the control points. 1075 """) 1076 1077 line_props = Include(LineProps, use_prefix=False, help=""" 1078 The %s values for the parabolas. 1079 """) 1080 1081class Ray(XYGlyph, LineGlyph): 1082 ''' Render rays. 1083 1084 ''' 1085 1086 __example__ = "examples/reference/models/Ray.py" 1087 1088 _args = ('x', 'y', 'length', 'angle') 1089 1090 x = NumberSpec(default=field("x"), help=""" 1091 The x-coordinates to start the rays. 1092 """) 1093 1094 y = NumberSpec(default=field("y"), help=""" 1095 The y-coordinates to start the rays. 1096 """) 1097 1098 angle = AngleSpec(default=0, help=""" 1099 The angles in radians to extend the rays, as measured from the horizontal. 1100 """) 1101 1102 length = DistanceSpec(default=0, help=""" 1103 The length to extend the ray. Note that this ``length`` defaults 1104 to data units (measured in the x-direction). 1105 """) 1106 1107 line_props = Include(LineProps, use_prefix=False, help=""" 1108 The %s values for the rays. 1109 """) 1110 1111class Rect(XYGlyph, LineGlyph, FillGlyph, HatchGlyph): 1112 ''' Render rectangles. 1113 1114 ''' 1115 1116 __example__ = "examples/reference/models/Rect.py" 1117 1118 _args = ('x', 'y', 'width', 'height', 'angle', 'dilate') 1119 1120 x = NumberSpec(default=field("x"), help=""" 1121 The x-coordinates of the centers of the rectangles. 1122 """) 1123 1124 y = NumberSpec(default=field("y"), help=""" 1125 The y-coordinates of the centers of the rectangles. 1126 """) 1127 1128 width = DistanceSpec(default=field("width"), help=""" 1129 The overall widths of the rectangles. 1130 """) 1131 1132 height = DistanceSpec(default=field("height"), help=""" 1133 The overall heights of the rectangles. 1134 """) 1135 1136 angle = AngleSpec(default=0.0, help=""" 1137 The angles to rotate the rectangles, as measured from the horizontal. 1138 """) 1139 1140 dilate = Bool(False, help=""" 1141 Whether to always round fractional pixel locations in such a way 1142 as to make the rectangles bigger. 1143 1144 This setting may be useful if pixel rounding errors are causing 1145 rectangles to have a gap between them, when they should appear 1146 flush. 1147 """) 1148 1149 line_props = Include(LineProps, use_prefix=False, help=""" 1150 The %s values for the rectangles. 1151 """) 1152 1153 fill_props = Include(FillProps, use_prefix=False, help=""" 1154 The %s values for the rectangles. 1155 """) 1156 1157 hatch_props = Include(HatchProps, use_prefix=False, help=""" 1158 The %s values for the rectangles. 1159 """) 1160 1161class Scatter(Marker): 1162 ''' Render scatter markers selected from a predefined list of designs. 1163 1164 Use ``Scatter`` to draw any of Bokeh's built-in marker types: 1165 ``asterisk``, ``circle``, ``circle_cross``, ``circle_dot``, ``circle_x``, 1166 ``circle_y``, ``cross``, ``dash``, ``diamond``, ``diamond_cross``, 1167 ``diamond_dot``, ``dot``, ``hex``, ``hex_dot``, ``inverted_triangle``, 1168 ``plus``, ``square``, ``square_cross``, ``square_dot``, ``square_pin``, 1169 ``square_x``, ``star``, ``star_dot``, ``triangle``, ``triangle_dot``, 1170 ``triangle_pin``, ``x``, or ``y``. This collection is available in 1171 :class:`~bokeh.core.enums.MarkerType`. 1172 1173 Bokeh's built-in markers consist of a set of base markers, most of which can 1174 be combined with different kinds of additional visual features: 1175 1176 .. bokeh-plot:: docs/user_guide/examples/plotting_markertypes.py 1177 :source-position: none 1178 1179 You can select marker types in two ways: 1180 1181 * To draw the **same marker for all values**, use the ``marker`` attribute 1182 to specify the name of a specific marker. For example: 1183 1184 .. code-block:: python 1185 1186 glyph = Scatter(x="x", y="y", size="sizes", marker="square") 1187 plot.add_glyph(source, glyph) 1188 1189 This will render square markers for all points. 1190 1191 * Alternatively, to use **marker types specified in a data source column**, 1192 assign the column name to the ``marker`` attribute. For example: 1193 1194 .. code-block:: python 1195 1196 # source.data['markers'] = ["circle", "square", "circle", ... ] 1197 1198 glyph = Scatter(x="x", y="y", size="sizes", marker="markers") 1199 plot.add_glyph(source, glyph) 1200 1201 .. note:: 1202 When you draw ``circle`` markers with ``Scatter``, you can only assign a 1203 size in :ref:`screen units <userguide_styling_units>` (by passing a 1204 number of pixels to the ``size`` argument). In case you want to define 1205 the radius of circles in :ref:`data units <userguide_styling_units>`, 1206 use the :class:`~bokeh.models.glyphs.Circle` glyph instead of the 1207 ``Scatter`` glyph. 1208 1209 ''' 1210 1211 __example__ = "examples/reference/models/Scatter.py" 1212 1213 _args = ('x', 'y', 'size', 'angle', 'marker') 1214 1215 marker = MarkerSpec(default="circle", help=""" 1216 Which marker to render. This can be the name of any built in marker, 1217 e.g. "circle", or a reference to a data column containing such names. 1218 """) 1219 1220class Segment(LineGlyph): 1221 ''' Render segments. 1222 1223 ''' 1224 1225 __example__ = "examples/reference/models/Segment.py" 1226 1227 _args = ('x0', 'y0', 'x1', 'y1') 1228 1229 x0 = NumberSpec(default=field("x0"), help=""" 1230 The x-coordinates of the starting points. 1231 """) 1232 1233 y0 = NumberSpec(default=field("y0"), help=""" 1234 The y-coordinates of the starting points. 1235 """) 1236 1237 x1 = NumberSpec(default=field("x1"), help=""" 1238 The x-coordinates of the ending points. 1239 """) 1240 1241 y1 = NumberSpec(default=field("y1"), help=""" 1242 The y-coordinates of the ending points. 1243 """) 1244 1245 line_props = Include(LineProps, use_prefix=False, help=""" 1246 The %s values for the segments. 1247 """) 1248 1249class Step(XYGlyph, LineGlyph): 1250 ''' Render step lines. 1251 1252 Step levels can be draw before, after, or centered on each point, according 1253 to the value of the ``mode`` property. 1254 1255 The x-coordinates are assumed to be (and must be) sorted in ascending order 1256 for steps to be properly rendered. 1257 1258 ''' 1259 1260 __example__ = "examples/reference/models/Step.py" 1261 1262 _args = ('x', 'y') 1263 1264 x = NumberSpec(default=field("x"), help=""" 1265 The x-coordinates for the steps. 1266 """) 1267 1268 y = NumberSpec(default=field("y"), help=""" 1269 The y-coordinates for the steps. 1270 """) 1271 1272 line_props = Include(ScalarLineProps, use_prefix=False, help=""" 1273 The %s values for the steps. 1274 """) 1275 1276 mode = Enum(StepMode, default="before", help=""" 1277 Where the step "level" should be drawn in relation to the x and y 1278 coordinates. The parameter can assume one of three values: 1279 1280 * ``before``: (default) Draw step levels before each x-coordinate (no step before the first point) 1281 * ``after``: Draw step levels after each x-coordinate (no step after the last point) 1282 * ``center``: Draw step levels centered on each x-coordinate 1283 """) 1284 1285class Text(XYGlyph, TextGlyph): 1286 ''' Render text. 1287 1288 ''' 1289 1290 __example__ = "examples/reference/models/Text.py" 1291 1292 _args = ('x', 'y', 'text', 'angle', 'x_offset', 'y_offset') 1293 1294 x = NumberSpec(default=field("x"), help=""" 1295 The x-coordinates to locate the text anchors. 1296 """) 1297 1298 y = NumberSpec(default=field("y"), help=""" 1299 The y-coordinates to locate the text anchors. 1300 """) 1301 1302 text = StringSpec("text", help=""" 1303 The text values to render. 1304 """) 1305 1306 angle = AngleSpec(default=0, help=""" 1307 The angles to rotate the text, as measured from the horizontal. 1308 """) 1309 1310 x_offset = NumberSpec(default=0, help=""" 1311 Offset values to apply to the x-coordinates. 1312 1313 This is useful, for instance, if it is desired to "float" text a fixed 1314 distance in screen units from a given data position. 1315 """) 1316 1317 y_offset = NumberSpec(default=0, help=""" 1318 Offset values to apply to the y-coordinates. 1319 1320 This is useful, for instance, if it is desired to "float" text a fixed 1321 distance in screen units from a given data position. 1322 """) 1323 1324 text_props = Include(TextProps, use_prefix=False, help=""" 1325 The %s values for the text. 1326 """) 1327 1328class VArea(FillGlyph, HatchGlyph): 1329 ''' Render a vertically directed area between two equal length sequences 1330 of y-coordinates with the same x-coordinates. 1331 1332 ''' 1333 1334 __example__ = "examples/reference/models/VArea.py" 1335 1336 _args = ('x', 'y1', 'y2') 1337 1338 x = NumberSpec(default=field("x"), help=""" 1339 The x-coordinates for the points of the area. 1340 """) 1341 1342 y1 = NumberSpec(default=field("y1"), help=""" 1343 The y-coordinates for the points of one side of the area. 1344 """) 1345 1346 y2 = NumberSpec(default=field("y2"), help=""" 1347 The y-coordinates for the points of the other side of the area. 1348 """) 1349 1350 fill_props = Include(ScalarFillProps, use_prefix=False, help=""" 1351 The %s values for the vertical directed area. 1352 """) 1353 1354 hatch_props = Include(HatchProps, use_prefix=False, help=""" 1355 The %s values for the vertical directed area. 1356 """) 1357 1358class VBar(LineGlyph, FillGlyph, HatchGlyph): 1359 ''' Render vertical bars, given a center coordinate, width and (top, bottom) coordinates. 1360 1361 ''' 1362 1363 __example__ = "examples/reference/models/VBar.py" 1364 1365 _args = ('x', 'width', 'top', 'bottom') 1366 1367 x = NumberSpec(default=field("x"), help=""" 1368 The x-coordinates of the centers of the vertical bars. 1369 """) 1370 1371 width = NumberSpec(default=1, help=""" 1372 The widths of the vertical bars. 1373 """) 1374 1375 bottom = NumberSpec(default=0, help=""" 1376 The y-coordinates of the bottom edges. 1377 """) 1378 1379 top = NumberSpec(default=field("top"), help=""" 1380 The y-coordinates of the top edges. 1381 """) 1382 1383 line_props = Include(LineProps, use_prefix=False, help=""" 1384 The %s values for the vertical bars. 1385 """) 1386 1387 fill_props = Include(FillProps, use_prefix=False, help=""" 1388 The %s values for the vertical bars. 1389 """) 1390 1391 hatch_props = Include(HatchProps, use_prefix=False, help=""" 1392 The %s values for the vertical bars. 1393 """) 1394 1395class Wedge(XYGlyph, LineGlyph, FillGlyph, HatchGlyph): 1396 ''' Render wedges. 1397 1398 ''' 1399 1400 __example__ = "examples/reference/models/Wedge.py" 1401 1402 _args = ('x', 'y', 'radius', 'start_angle', 'end_angle', 'direction') 1403 1404 x = NumberSpec(default=field("x"), help=""" 1405 The x-coordinates of the points of the wedges. 1406 """) 1407 1408 y = NumberSpec(default=field("y"), help=""" 1409 The y-coordinates of the points of the wedges. 1410 """) 1411 1412 radius = DistanceSpec(default=field("radius"), help=""" 1413 Radii of the wedges. 1414 """) 1415 1416 start_angle = AngleSpec(default=field("start_angle"), help=""" 1417 The angles to start the wedges, as measured from the horizontal. 1418 """) 1419 1420 end_angle = AngleSpec(default=field("end_angle"), help=""" 1421 The angles to end the wedges, as measured from the horizontal. 1422 """) 1423 1424 direction = Enum(Direction, default='anticlock', help=""" 1425 Which direction to stroke between the start and end angles. 1426 """) 1427 1428 line_props = Include(LineProps, use_prefix=False, help=""" 1429 The %s values for the wedges. 1430 """) 1431 1432 fill_props = Include(FillProps, use_prefix=False, help=""" 1433 The %s values for the wedges. 1434 """) 1435 1436 hatch_props = Include(HatchProps, use_prefix=False, help=""" 1437 The %s values for the wedges. 1438 """) 1439 1440#----------------------------------------------------------------------------- 1441# Dev API 1442#----------------------------------------------------------------------------- 1443 1444#----------------------------------------------------------------------------- 1445# Private API 1446#----------------------------------------------------------------------------- 1447 1448#----------------------------------------------------------------------------- 1449# Code 1450#----------------------------------------------------------------------------- 1451