Source code for flatsurf.graphical.hyperbolic

r"""
Plotting primitives for subsets of the hyperbolic plane

EXAMPLES:

Usually, the primitives defined here should not be used directly. Instead the
:meth:`flatsurf.geometry.hyperbolic.HyperbolicConvexSet.plot` method of
hyperbolic sets internally uses these primitives::

    sage: from flatsurf import HyperbolicPlane

    sage: H = HyperbolicPlane()

    sage: geodesic = H.vertical(0)

    sage: plot = geodesic.plot()

    sage: list(plot)
    [CartesianPathPlot([CartesianPathPlotCommand(code='MOVETO', args=(0.000000000000000, 0.000000000000000)), CartesianPathPlotCommand(code='RAYTO', args=(0, 1))])]

.. NOTE::

    The need for these primitives arises because SageMath has no good
    facilities to plot infinite objects such as lines and rays. However, these are
    needed to plot subsets of the hyperbolic plane in the upper half plane model.

.. jupyter-execute::
    :hide-code:

    # Allow jupyter-execute blocks in this module to contain doctests
    import jupyter_doctest_tweaks

"""
# ****************************************************************************
#  This file is part of sage-flatsurf.
#
#        Copyright (C) 2022-2023 Julian Rüth
#
#  sage-flatsurf 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.
#
#  sage-flatsurf is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
#
#  You should have received a copy of the GNU General Public License
#  along with sage-flatsurf. If not, see <https://www.gnu.org/licenses/>.
# ****************************************************************************

from dataclasses import dataclass

from sage.plot.primitive import GraphicPrimitive
from sage.misc.cachefunc import cached_method
from sage.misc.decorators import options, rename_keyword

from flatsurf.geometry.hyperbolic import HyperbolicPoint, HyperbolicPlane


[docs] class CartesianPathPlot(GraphicPrimitive): r""" A plotted path in the hyperbolic plane, i.e., a sequence of commands and associated control points in the hyperbolic plane. The ``plot`` methods of most hyperbolic convex sets rely on such a path. Usually, such a path should not be produced directly. This can be considered a more generic version of ``sage.plot.line.Line`` and ``sage.plot.polygon.Polygon`` since this is not limited to finite line segments. At the same time this generalizes matplotlib's ``Path`` somewhat, again by allowing infinite rays and lines. INPUT: - ``commands`` -- a sequence of :class:`HyperbolicPathPlotCommand` describing the path. - ``options`` -- a dict or ``None`` (the default), options to affect the plotting of the path; the options accepted are the same that ``Polygon`` of :mod:`sage.plot.polygon` accepts. EXAMPLES: A geodesic plot as a single such path (wrapped in a SageMath graphics object):: sage: from flatsurf import HyperbolicPlane sage: from flatsurf.graphical.hyperbolic import CartesianPathPlot, CartesianPathPlotCommand sage: H = HyperbolicPlane() sage: P = H.vertical(0).plot() sage: isinstance(P[0], CartesianPathPlot) True The sequence of commands should always start with a move command to establish the starting point of the plot; note that coordinates are always given in the Cartesian two dimension plot coordinate system:: sage: P = CartesianPathPlot([ ....: CartesianPathPlotCommand("MOVETO", (0, 0)) ....: ]) After the initial move, a sequence of arcs can be drawn to represent objects in the upper half plane model; the parameters is the center and the end point of the arc:: sage: P = CartesianPathPlot([ ....: CartesianPathPlotCommand("MOVETO", (-1, 0)), ....: CartesianPathPlotCommand("ARCTO", ((0, 0), (0, 1))), ....: ]) We can also draw segments to represent objects in the Klein disk model:: sage: P = CartesianPathPlot([ ....: CartesianPathPlotCommand("MOVETO", (-1, 0)), ....: CartesianPathPlotCommand("LINETO", (0, 0)), ....: ]) Additionally, we can draw rays to represent verticals in the upper half plane model; the parameter is the direction of the ray, i.e., (0, 1) for a vertical:: sage: P = CartesianPathPlot([ ....: CartesianPathPlotCommand("MOVETO", (0, 0)), ....: CartesianPathPlotCommand("RAYTO", (0, 1)), ....: ]) Similarly, we can also move the cursor to an infinitely far point in a certain direction. This can be used to plot a half plane, e.g., the point with non-negative real part:: sage: P = CartesianPathPlot([ ....: CartesianPathPlotCommand("MOVETO", (0, 0)), ....: CartesianPathPlotCommand("MOVETOINFINITY", (1, 0)), ....: CartesianPathPlotCommand("MOVETOINFINITY", (0, 1)), ....: CartesianPathPlotCommand("LINETO", (0, 0)), ....: ]) In a similar way, we can also draw an actual line, here the real axis:: sage: P = CartesianPathPlot([ ....: CartesianPathPlotCommand("MOVETOINFINITY", (-1, 0)), ....: CartesianPathPlotCommand("RAYTO", (1, 0)), ....: ]) Finally, we can draw an arc in clockwise direction; here we plot the point in the upper half plane of norm between 1 and 2:: sage: P = CartesianPathPlot([ ....: CartesianPathPlotCommand("MOVETO", (-1, 0)), ....: CartesianPathPlotCommand("ARCTO", ((0, 0), (1, 0))), ....: CartesianPathPlotCommand("MOVETO", (2, 0)), ....: CartesianPathPlotCommand("RARCTO", ((0, 0), (-2, 0))), ....: CartesianPathPlotCommand("MOVETO", (-1, 0)), ....: ]) .. SEEALSO:: :func:`hyperbolic_path` to create a ``Graphics`` containing a :class:`CartesianPathPlot`, most likely you want to use that function if you want to use this functionality in plots of your own. """ def __init__(self, commands, options=None): options = options or {} valid_options = self._allowed_options() for option in options: if option not in valid_options: raise RuntimeError(f"option {option} not valid") # We don't validate the commands here. The consumers below are going to # do that implicitly. self._commands = commands super().__init__(options) def _allowed_options(self): r""" Return the options that are supported by a path. We support all the options that are understood by a SageMath polygon. EXAMPLES:: sage: from flatsurf.graphical.hyperbolic import CartesianPathPlot sage: P = CartesianPathPlot([]) sage: P._allowed_options() # random output depending on the version of SageMath {'alpha': 'How transparent the figure is.', 'edgecolor': 'The color for the border of filled polygons.', 'fill': 'Whether or not to fill the polygon.', 'hue': 'The color given as a hue.', 'legend_color': 'The color of the legend text.', 'legend_label': 'The label for this item in the legend.', 'linestyle': 'The style of the enclosing line.', 'rgbcolor': 'The color as an RGB tuple.', 'thickness': 'How thick the border line is.', 'zorder': 'The layer level in which to draw'} sage: P = CartesianPathPlot([], options={"alpha": .1}) sage: P = CartesianPathPlot([], options={"beta": .1}) Traceback (most recent call last): ... RuntimeError: option beta not valid """ from sage.plot.polygon import Polygon return Polygon([], [], {})._allowed_options() def __repr__(self): r""" Return a printable representation of this plot for debugging purposes. EXAMPLES:: sage: from flatsurf.graphical.hyperbolic import CartesianPathPlot, CartesianPathPlotCommand sage: P = CartesianPathPlot([ ....: CartesianPathPlotCommand("MOVETO", (-1, 0)), ....: CartesianPathPlotCommand("LINETO", (0, 0)), ....: ]) sage: P CartesianPathPlot([CartesianPathPlotCommand(code='MOVETO', args=(-1, 0)), CartesianPathPlotCommand(code='LINETO', args=(0, 0))]) """ return f"CartesianPathPlot({self._commands})" def _render_on_subplot(self, subplot): r""" Render this path on ``subplot``. Matplotlib was not really made to draw things that extend to infinity. The trick here is to register a callback that redraws whenever the viewbox of the plot changes, e.g., as more objects are added to the plot or as the plot is dragged around. This implements the interface required by SageMath's ``GraphicPrimitive``. INPUT: - ``subplot`` -- the axes of a subplot EXAMPLES:: sage: from flatsurf.graphical.hyperbolic import CartesianPathPlot, CartesianPathPlotCommand sage: P = CartesianPathPlot([ ....: CartesianPathPlotCommand("MOVETO", (-1, 0)), ....: CartesianPathPlotCommand("LINETO", (0, 0)), ....: ]) sage: from matplotlib.figure import Figure sage: figure = Figure() sage: subplot = figure.add_subplot(111) sage: P._render_on_subplot(subplot) sage: subplot.patches <Axes.ArtistList of 1 patches> """ matplotlib_options = { key: value for (key, value) in self.options().items() if key not in { "alpha", "legend_color", "legend_label", "linestyle", "rgbcolor", "thickness", } } from matplotlib.path import Path path = Path([(0, 0)]) from matplotlib.patches import PathPatch patch = PathPatch(path, **matplotlib_options) subplot.axes.add_patch(patch) options = self.options() fill = options.pop("fill", None) if fill: patch.set_fill(True) # Translate SageMath options to matplotlib style. if "thickness" in options: patch.set_linewidth(float(options.pop("thickness"))) if "linestyle" in options: patch.set_linestyle(options.pop("linestyle")) if "alpha" in options: patch.set_alpha(float(options["alpha"])) from sage.plot.colors import to_mpl_color color = None if "rgbcolor" in options: color = to_mpl_color(options.pop("rgbcolor")) edge_color = options.pop("edgecolor", None) if edge_color is not None: edge_color = to_mpl_color(edge_color) if edge_color is None: if color is None: pass else: patch.set_color(color) else: patch.set_edgecolor(edge_color) if color is None: pass else: patch.set_facecolor(color) if "legend_label" in options: patch.set_label(options.pop("legend_label")) def redraw(_=None): r""" Redraw after the viewport has been rescaled to make sure that infinite rays reach the end of the viewport. """ # We use ._path directly since .set_path is not available in old # versions of matplotlib patch._path = self._create_path( subplot.axes.get_xlim(), subplot.axes.get_ylim(), fill=fill ) subplot.axes.callbacks.connect("ylim_changed", redraw) subplot.axes.callbacks.connect("xlim_changed", redraw) redraw() def _create_path(self, xlim, ylim, fill): r""" Create a matplotlib path for this primitive in the bounding box given by ``xlim`` and ``ylim``. This is a helper method for :meth:`_rendor_on_subplot`. INPUT: - ``xlim`` -- a pair of floats, the lower and upper horizontal bound of the view box - ``ylim`` -- a pair of floats, the lower and upper vertical bound of the view box - ``fill`` -- a boolean; whether the area enclosed by this path should be filled EXAMPLES:: sage: from flatsurf.graphical.hyperbolic import CartesianPathPlot, CartesianPathPlotCommand sage: P = CartesianPathPlot([ ....: CartesianPathPlotCommand("MOVETO", (-1, 0)), ....: CartesianPathPlotCommand("LINETO", (0, 0)), ....: ]) sage: P._create_path([-1, 1], [-1, 1], fill=False) Path(array([[-1., 0.], [ 0., 0.]]), array([1, 2], dtype=uint8)) """ # Handle the first command. This controls how the path starts. command = self._commands[0] if command.code == "MOVETO": pos = command.args direction = None vertices = [pos] elif command.code == "MOVETOINFINITY": # We cannot draw lines yet. We don't seem to need them for hyperbolic plots at the moment. raise NotImplementedError( "cannot draw a path that starts at an infinite point yet" ) else: raise RuntimeError(f"path must not start with a {command.code} command") from matplotlib.path import Path codes = [Path.MOVETO] for command in self._commands[1:]: pos, direction = self._extend_path( vertices, codes, pos, direction, command, fill, xlim, ylim ) return Path(vertices, codes) @staticmethod def _infinity(pos, direction, xlim, ylim): r""" Return the finite coordinates of a point that ressembles infinity starting from ``pos`` and going in ``direction``. This is a helper method for :meth:`_create_path`. INPUT: - ``pos`` -- a coordinate in the plane as a tuple - ``direction`` -- a direction in the plane as a tuple - ``xlim`` -- a pair of floats, the lower and upper horizontal bound of the view box - ``ylim`` -- a pair of floats, the lower and upper vertical bound of the view box EXAMPLES:: sage: from flatsurf.graphical.hyperbolic import CartesianPathPlot sage: CartesianPathPlot._infinity((0., 0.), (0., 1.), (-1024., 1024.), (-1024., 1024.)) (0.000000000000000, 5120.00000000000) sage: CartesianPathPlot._infinity((0., 0.), (1., 1.), (-1024., 1024.), (-1024., 1024.)) (3920.30937574010, 3920.30937574010) sage: CartesianPathPlot._infinity((1., 0.), (1., 1.), (-1024., 1024.), (-1024., 1024.)) (3920.30937574010, 3919.30937574010) """ from sage.all import vector direction = vector(direction) pos = vector(pos) from sage.all import infinity if direction[0]: λx = max( (xlim[0] - pos[0]) / direction[0], (xlim[1] - pos[0]) / direction[0] ) else: λx = infinity if direction[1]: λy = max( (ylim[0] - pos[1]) / direction[1], (ylim[1] - pos[1]) / direction[1] ) else: λy = infinity λ = min(λx, λy) # Additionally, we now move out a full plot size so we are sure # that no artifacts coming from any sweeps (see below) show up in # the final plot. plot_size = (xlim[1] - xlim[0]) + (ylim[1] - ylim[0]) λ += plot_size / direction.norm() return pos + λ * direction @staticmethod def _extend_path(vertices, codes, pos, direction, command, fill, xlim, ylim): r""" Extend the matplotlib Path ``vertices`` and ``codes`` by realizing ``command``. INPUT: - ``vertices`` -- a list of control points - ``codes`` -- a list of matplotlib Path plot command - ``pos`` -- the current location of the plotted path before executing ``command`` - ``direction`` -- ``None`` or the direction if the current position is infinite - ``command`` -- a :class:`CartesianPathPlotCommand` - ``fill`` -- a boolean, whether the interior of the plotted path should be filled - ``xlim`` -- a pair of floats, the lower and upper horizontal bound of the view box - ``ylim`` -- a pair of floats, the lower and upper vertical bound of the view box OUTPUT: The new ``pos`` and ``direction`` after executing the ``command``. EXAMPLES:: sage: from flatsurf.graphical.hyperbolic import CartesianPathPlot, CartesianPathPlotCommand sage: from matplotlib.path import Path sage: vertices = [(0., 0.)] sage: codes = [Path.MOVETO] sage: pos = (0., 0.) sage: direction = None sage: command = CartesianPathPlotCommand("LINETO", (1., 1.)) sage: CartesianPathPlot._extend_path(vertices, codes, pos, direction, command, False, (-1024., 1024.), (-1024., 1024.)) ((1.00000000000000, 1.00000000000000), None) sage: vertices [(0.000000000000000, 0.000000000000000), (1.00000000000000, 1.00000000000000)] sage: codes [1, 2] """ from matplotlib.path import Path def extend(path): vertices.extend(path.vertices[1:]) codes.extend(path.codes[1:]) if command.code == "LINETO": target = command.args if direction is not None: vertices.append( CartesianPathPlot._infinity(target, direction, xlim, ylim) ) codes.append(Path.LINETO) direction = None pos = target vertices.append(pos) codes.append(Path.LINETO) elif command.code == "RAYTO": if direction is None: direction = command.args vertices.append(CartesianPathPlot._infinity(pos, direction, xlim, ylim)) codes.append(Path.LINETO) else: start = CartesianPathPlot._infinity(pos, direction, xlim, ylim) direction = command.args end = CartesianPathPlot._infinity(pos, direction, xlim, ylim) # Sweep the bounding box counterclockwise from start to end from sage.all import vector center = vector(((start[0] + end[0]) / 2, (start[1] + end[1]) / 2)) extend(CartesianPathPlot._arc_path(center, start, end)) vertices.append(end) codes.append(Path.LINETO if fill else Path.MOVETO) elif command.code == "ARCTO": target, center = command.args assert direction is None extend(CartesianPathPlot._arc_path(center, pos, target)) pos = target elif command.code == "RARCTO": target, center = command.args assert direction is None extend(CartesianPathPlot._arc_path(center, target, pos, reverse=True)) pos = target elif command.code == "MOVETO": target = command.args pos = target direction = None vertices.append(pos) codes.append(Path.MOVETO) else: raise RuntimeError(f"cannot draw {command.code} yet") return pos, direction
[docs] @cached_method def get_minmax_data(self): r""" Return a bounding box for this plot. This implements the required interface of SageMath's GraphicPrimitive. EXAMPLES:: sage: from flatsurf.graphical.hyperbolic import CartesianPathPlot, CartesianPathPlotCommand sage: P = CartesianPathPlot([ ....: CartesianPathPlotCommand("MOVETO", (-1, 0)), ....: CartesianPathPlotCommand("LINETO", (0, 0)), ....: ]) sage: P.get_minmax_data() {'xmax': 0.0, 'xmin': -1.0, 'ymax': 0.0, 'ymin': 0.0} :: sage: P = CartesianPathPlot([ ....: CartesianPathPlotCommand("MOVETO", (0, 0)), ....: CartesianPathPlotCommand("RAYTO", (0, 1)), ....: ]) sage: P.get_minmax_data()['ymax'] 1.0 """ try: from matplotlib.transforms import Bbox bbox = Bbox.null() for command in self._commands: if command.code in ["MOVETO", "LINETO"]: pos = command.args bbox.update_from_data_xy([pos], ignore=False) elif command.code in ["ARCTO", "RARCTO"]: target, center = command.args # We simplify the computation of the bounding box here to # speed things up. Since these are hyperbolic arcs, their # center must be at y=0 and the endpoints at y≥0. # If we want to use this for non-hyperbolic objects, we'd # have to use this instead: # bbox = bbox.union( # [ # bbox, # self._arc_path( # center, target, pos, reverse=command.code == "RARCTO" # ).get_extents(), # ] # ) bbox = bbox.union( [ bbox, Bbox.from_bounds(*pos, 0, 0), Bbox.from_bounds(*target, 0, 0), ] ) from sage.all import sgn if sgn(pos[0] - center[0]) != sgn(target[0] - center[0]): # The bounding box includes a point that is higher # than the endpoints of the arc. from math import sqrt bbox = bbox.union( [ bbox, Bbox.from_bounds( center[0], sqrt((pos[0] - center[0]) ** 2 + pos[1] ** 2), 0, 0, ), ] ) pos = target elif command.code in ["RAYTO", "MOVETOINFINITY"]: # We just move "1" in the direction of the ray so that # infinite rays are visible at all. If everything plotted # is extremely small, then this is not ideal. Maybe we # should make this relative to the entire plot size. from sage.all import vector direction = vector(command.args) moved = vector(pos) + direction bbox = bbox.union( [bbox, Bbox.from_bounds(pos[0], moved[0], pos[1], moved[1])] ) else: raise NotImplementedError( f"cannot determine bounding box for {command.code} command" ) from sage.plot.plot import minmax_data return minmax_data(bbox.intervalx, bbox.intervaly, dict=True) except Exception as e: raise RuntimeError(e)
@staticmethod def _arc_path(center, start, end, reverse=False): r""" Return a matplotlib path approximating an circular arc. This is a helper method for :meth:`_extend_path`. INPUT: - ``center`` -- the center point of the circle completing the arc - ``start`` -- the coordinates of the starting point of the arc - ``end`` -- the coordinates of the end point of the arc - ``reverse`` -- a boolean (default: ``False``); whether the arc should go clockwise from ``end`` to ``start`` instead of going counterclockwise from ``start`` to ``end``. EXAMPLES:: sage: from flatsurf.graphical.hyperbolic import CartesianPathPlot sage: CartesianPathPlot._arc_path((0, 0), (1, 0), (0, 1)) Path(array([[1.00000000e+00, 0.00000000e+00], ... .. NOTE:: Currently, we are using 32 Bezier segments to approximate an arc. This is probably too many for small arcs and not enough for very big arcs and should be optimized. """ from matplotlib.path import Path from math import atan2, pi from sage.all import vector unit_arc = Path.arc( atan2(start[1] - center[1], start[0] - center[0]) / pi * 180, atan2(end[1] - center[1], end[0] - center[0]) / pi * 180, n=32, ) # Scale and translate the arc arc_vertices = ( unit_arc.vertices * vector((start[0] - center[0], start[1] - center[1])).norm() + center ) if reverse: arc_vertices = arc_vertices[::-1] return Path(arc_vertices, unit_arc.codes)
[docs] @dataclass class HyperbolicPathPlotCommand: r""" A step in a hyperbolic plot. Such a step is independent of the model chosen for the plot. It merely draws a segment (``LINETO``) in the hyperbolic plan or performs a movement without drawing a segment (``MOVETO``). Each command has a parameter, the point to which the command moves. A sequence of such commands cannot be plotted directly. It is first converted into a sequence of :class:`CartesianPathPlotCommand` which realizes the commands in a specific hyperbolic model. EXAMPLES:: sage: from flatsurf import HyperbolicPlane sage: from flatsurf.graphical.hyperbolic import HyperbolicPathPlotCommand sage: H = HyperbolicPlane() sage: HyperbolicPathPlotCommand("MOVETO", H(0)) HyperbolicPathPlotCommand(code='MOVETO', target=0) """ code: str # Literal["MOVETO", "LINETO"] requires Python 3.8 target: HyperbolicPoint
[docs] def cartesian(self, model, cursor=None, fill=True, stroke=True): r""" Return the sequence of commands that realizes this plot in the Cartesian plot coordinate system. INPUT: - ``model`` -- one of ``"half_plane"`` or ``"klein"`` - ``cursor`` -- a point in the hyperbolic plane or ``None`` (the default); assume that the cursor has been positioned at ``cursor`` before this command. - ``fill`` -- a boolean; whether to return commands that produce the correct polygon to represent the area of the polygon. - ``stroke`` -- a boolean; whether to return commands that produce the correct polygon to represent the lines of the polygon. EXAMPLES:: sage: from flatsurf import HyperbolicPlane sage: from flatsurf.graphical.hyperbolic import HyperbolicPathPlotCommand sage: H = HyperbolicPlane() sage: command = HyperbolicPathPlotCommand("MOVETO", H(0)) sage: command.cartesian("half_plane") [CartesianPathPlotCommand(code='MOVETO', args=(0.000000000000000, 0.000000000000000))] sage: command.cartesian("klein") [CartesianPathPlotCommand(code='MOVETO', args=(0.000000000000000, -1.00000000000000))] sage: command = HyperbolicPathPlotCommand("LINETO", H(1)) sage: command.cartesian("half_plane", cursor=H(0)) [CartesianPathPlotCommand(code='RARCTO', args=((1.00000000000000, 0.000000000000000), (0.500000000000000, 0)))] sage: command.cartesian("klein", cursor=H(0)) [CartesianPathPlotCommand(code='LINETO', args=(1.00000000000000, 0.000000000000000))] sage: command = HyperbolicPathPlotCommand("LINETO", H(oo)) sage: command.cartesian("half_plane", cursor=H(1)) [CartesianPathPlotCommand(code='RAYTO', args=(0, 1))] sage: command.cartesian("klein", cursor=H(1)) [CartesianPathPlotCommand(code='LINETO', args=(0.000000000000000, 1.00000000000000))] """ if cursor is None: if self.code != "MOVETO": raise ValueError( "when no previous cursor position is specified, command must be MOVETO" ) if model == "half_plane" and self.target == self.target.parent().infinity(): return [CartesianPathPlotCommand("MOVETOINFINITY", (0, 1))] from sage.all import RR return [ CartesianPathPlotCommand( "MOVETO", self.target.change_ring(RR).coordinates(model=model) ) ] if self.code == "LINETO": return HyperbolicPathPlotCommand.create_segment_cartesian( cursor, self.target, model=model ) if self.code == "MOVETO": return HyperbolicPathPlotCommand.create_move_cartesian( cursor, self.target, model=model, fill=fill, stroke=stroke ) raise NotImplementedError( "cannot convert this command to a Cartesian plot command yet" )
[docs] @staticmethod def make_cartesian(commands, model, fill=True, stroke=True): r""" Return the sequence of :class:`CartesianPathPlotCommand` that realizes the hyperbolic ``commands`` in the ``model``. INPUT: - ``commands`` -- a sequence of :class:`HyperbolicPathPlotCommand`. - ``model`` -- one of ``"half_plane"`` or ``"klein"`` - ``fill`` -- a boolean; whether to return commands that produce the correct polygon to represent the area of the polygon. - ``stroke`` -- a boolean; whether to return commands that produce the correct polygon to represent the lines of the polygon. EXAMPLES:: sage: from flatsurf import HyperbolicPlane sage: from flatsurf.graphical.hyperbolic import HyperbolicPathPlotCommand sage: H = HyperbolicPlane() A finite closed triangle in the hyperbolic plane:: sage: commands = [ ....: HyperbolicPathPlotCommand("MOVETO", H(I)), ....: HyperbolicPathPlotCommand("LINETO", H(I + 1)), ....: HyperbolicPathPlotCommand("LINETO", H(2 * I)), ....: HyperbolicPathPlotCommand("LINETO", H(I)), ....: ] And its corresponding plot in different models:: sage: HyperbolicPathPlotCommand.make_cartesian(commands, model="half_plane") [CartesianPathPlotCommand(code='MOVETO', args=(0.000000000000000, 1.00000000000000)), CartesianPathPlotCommand(code='RARCTO', args=((1.00000000000000, 1.00000000000000), (0.500000000000000, 0))), CartesianPathPlotCommand(code='ARCTO', args=((0.000000000000000, 2.00000000000000), (-1.00000000000000, 0))), CartesianPathPlotCommand(code='LINETO', args=(0.000000000000000, 1.00000000000000))] sage: HyperbolicPathPlotCommand.make_cartesian(commands, model="klein") [CartesianPathPlotCommand(code='MOVETO', args=(0.000000000000000, 0.000000000000000)), CartesianPathPlotCommand(code='LINETO', args=(0.666666666666667, 0.333333333333333)), CartesianPathPlotCommand(code='LINETO', args=(0.000000000000000, 0.600000000000000)), CartesianPathPlotCommand(code='LINETO', args=(0.000000000000000, 0.000000000000000))] Asking for a polygon that works for both fill and stroke is not always possible:: sage: commands = [ ....: HyperbolicPathPlotCommand("MOVETO", H(0)), ....: HyperbolicPathPlotCommand("MOVETO", H(1)), ....: HyperbolicPathPlotCommand("LINETO", H(oo)), ....: HyperbolicPathPlotCommand("LINETO", H(0)), ....: ] sage: HyperbolicPathPlotCommand.make_cartesian(commands, model="half_plane") Traceback (most recent call last): ... ValueError: exactly one of fill & stroke must be set sage: HyperbolicPathPlotCommand.make_cartesian(commands, model="half_plane", fill=False, stroke=True) [CartesianPathPlotCommand(code='MOVETO', args=(0.000000000000000, 0.000000000000000)), CartesianPathPlotCommand(code='MOVETO', args=(1.00000000000000, 0.000000000000000)), CartesianPathPlotCommand(code='RAYTO', args=(0, 1)), CartesianPathPlotCommand(code='LINETO', args=(0.000000000000000, 0.000000000000000))] sage: HyperbolicPathPlotCommand.make_cartesian(commands, model="half_plane", fill=True, stroke=False) [CartesianPathPlotCommand(code='MOVETO', args=(0.000000000000000, 0.000000000000000)), CartesianPathPlotCommand(code='LINETO', args=(1.00000000000000, 0.000000000000000)), CartesianPathPlotCommand(code='RAYTO', args=(0, 1)), CartesianPathPlotCommand(code='LINETO', args=(0.000000000000000, 0.000000000000000))] """ cartesian_commands = [] cursor = None for command in commands: cartesian_commands.extend( command.cartesian(model=model, cursor=cursor, stroke=stroke, fill=fill) ) cursor = command.target while cartesian_commands and cartesian_commands[-1].code.startswith("MOVE"): cartesian_commands.pop() return cartesian_commands
[docs] @staticmethod def create_segment_cartesian(start, end, model): r""" Return a sequence of :class:`CartesianPathPlotCommand` that represent the closed boundary of a :class:`~flatsurf.geometry.hyperbolic.HyperbolicConvexPolygon`, namely the segment to ``end`` (from the previous position ``start``.) This is a helper function for :meth:`cartesian`. INPUT: - ``start`` -- a :class:`~flatsurf.geometry.hyperbolic.HyperbolicPoint` - ``end`` -- a :class:`~flatsurf.geometry.hyperbolic.HyperbolicPoint` - ``model`` -- one of ``"half_plane"`` or ``"klein"`` in which model to realize this segment EXAMPLES:: sage: from flatsurf import HyperbolicPlane sage: from flatsurf.graphical.hyperbolic import HyperbolicPathPlotCommand sage: H = HyperbolicPlane() A finite segment in the hyperbolic plane; note that we assume that "cursor" is at ``start``, so only the command that goes to ``end`` is returned:: sage: HyperbolicPathPlotCommand.create_segment_cartesian(H(I), H(2*I), model="half_plane") [CartesianPathPlotCommand(code='LINETO', args=(0.000000000000000, 2.00000000000000))] An infinite segment:: sage: HyperbolicPathPlotCommand.create_segment_cartesian(H(I), H(oo), model="half_plane") [CartesianPathPlotCommand(code='RAYTO', args=(0, 1))] A segment that is infinite on both ends; it looks the same because the starting point is not rendered here:: sage: HyperbolicPathPlotCommand.create_segment_cartesian(H(0), H(oo), model="half_plane") [CartesianPathPlotCommand(code='RAYTO', args=(0, 1))] Note that this is a "closed" boundary of the polygon that is left of that segment unlike the "open" version produced by :meth:`create_move_cartesian` which contains the entire positive real axis:: sage: HyperbolicPathPlotCommand.create_move_cartesian(H(0), H(oo), model="half_plane", stroke=True, fill=False) [CartesianPathPlotCommand(code='MOVETOINFINITY', args=(0, 1))] sage: HyperbolicPathPlotCommand.create_move_cartesian(H(0), H(oo), model="half_plane", stroke=False, fill=True) [CartesianPathPlotCommand(code='RAYTO', args=(1, 0)), CartesianPathPlotCommand(code='RAYTO', args=(0, 1))] The corresponding difference in the Klein model:: sage: HyperbolicPathPlotCommand.create_segment_cartesian(H(0), H(oo), model="klein") [CartesianPathPlotCommand(code='LINETO', args=(0.000000000000000, 1.00000000000000))] sage: HyperbolicPathPlotCommand.create_move_cartesian(H(0), H(oo), model="klein", stroke=True, fill=False) [CartesianPathPlotCommand(code='MOVETO', args=(0.000000000000000, 1.00000000000000))] sage: HyperbolicPathPlotCommand.create_move_cartesian(H(0), H(oo), model="klein", stroke=False, fill=True) [CartesianPathPlotCommand(code='ARCTO', args=((0.000000000000000, 1.00000000000000), (0, 0)))] .. NOTE:: Sometimes there are problems on a very small scale due to our usage of RR internally. We should probably use ball arithmetic to make things more robust. """ if start == end: raise ValueError( f"cannot draw segment from point {start} to itself ({end})" ) if model == "half_plane": from sage.all import RR if start != start.parent().infinity(): start_x, start_y = start.change_ring(RR).coordinates(model="half_plane") if end != end.parent().infinity(): end_x, end_y = end.change_ring(RR).coordinates(model="half_plane") if start == start.parent().infinity(): return [ CartesianPathPlotCommand("LINETO", (end_x, end_y)), ] if end == end.parent().infinity(): return [ CartesianPathPlotCommand( "RAYTO", (0, 1), ) ] # We should probably be more careful here and not just use a random # epsilon. if (start_x - end_x).abs() < (start_y - end_y).abs() * 1e-6: # This segment is (almost) vertical. We plot it as if it were # vertical to avoid numeric issues. return [CartesianPathPlotCommand("LINETO", (end_x, end_y))] real_hyperbolic_plane = HyperbolicPlane(RR) geodesic = real_hyperbolic_plane.geodesic( real_hyperbolic_plane.point(start_x, start_y, model="half_plane"), real_hyperbolic_plane.point(end_x, end_y, model="half_plane"), ) center = ( (geodesic.start().coordinates()[0] + geodesic.end().coordinates()[0]) / 2, 0, ) return [ CartesianPathPlotCommand( "RARCTO" if start_x < end_x else "ARCTO", ((end_x, end_y), center) ) ] elif model == "klein": from sage.all import RR return [ CartesianPathPlotCommand( "LINETO", end.change_ring(RR).coordinates(model="klein") ) ] else: raise NotImplementedError("cannot draw segment in this model")
[docs] @staticmethod def create_move_cartesian(start, end, model, stroke=True, fill=True): r""" Return a list of :class:`CartesianPathPlotCommand` that represent the open "segment" on the boundary of a polygon connecting ``start`` and ``end``. This is a helper function for :meth:`make_cartesian`. INPUT: - ``start`` -- a :class:`~flatsurf.geometry.hyperbolic.HyperbolicPoint` - ``end`` -- a :class:`~flatsurf.geometry.hyperbolic.HyperbolicPoint` - ``model`` -- one of ``"half_plane"`` or ``"klein"`` in which model to realize this segment - ``stroke`` -- a boolean (default: ``True``); whether this is part of a stroke path that is not filled - ``fill`` -- a boolean (default: ``True``); whether this is part of a filled path that is not stroked EXAMPLES:: sage: from flatsurf import HyperbolicPlane sage: from flatsurf.graphical.hyperbolic import HyperbolicPathPlotCommand sage: H = HyperbolicPlane() sage: HyperbolicPathPlotCommand.create_move_cartesian(H(0), H(1), "half_plane", stroke=True, fill=False) [CartesianPathPlotCommand(code='MOVETO', args=(1.00000000000000, 0.000000000000000))] """ if start == end: raise ValueError("cannot move from point to itself") if start.is_finite(): raise ValueError(f"starting point of move must be ideal but was {start}") if end.is_finite(): raise ValueError(f"end of move must be ideal but was {end}") if fill == stroke: raise ValueError("exactly one of fill & stroke must be set") if model == "half_plane": from sage.all import RR if not fill: if end == end.parent().infinity(): return [CartesianPathPlotCommand("MOVETOINFINITY", (0, 1))] return [ CartesianPathPlotCommand( "MOVETO", end.change_ring(RR).coordinates() ) ] if start == start.parent().infinity(): return [ CartesianPathPlotCommand("RAYTO", (-1, 0)), CartesianPathPlotCommand( "LINETO", end.change_ring(RR).coordinates() ), ] if end == end.parent().infinity(): return [ CartesianPathPlotCommand("RAYTO", (1, 0)), CartesianPathPlotCommand("RAYTO", (0, 1)), ] if ( start.change_ring(RR).coordinates()[0] < end.change_ring(RR).coordinates()[0] ): return [ CartesianPathPlotCommand( "LINETO", end.change_ring(RR).coordinates() ) ] else: return [ CartesianPathPlotCommand("RAYTO", (1, 0)), CartesianPathPlotCommand("RAYTO", (0, 1)), CartesianPathPlotCommand("RAYTO", (-1, 0)), CartesianPathPlotCommand( "LINETO", end.change_ring(RR).coordinates() ), ] elif model == "klein": from sage.all import RR if fill: return [ CartesianPathPlotCommand( "ARCTO", (end.change_ring(RR).coordinates(model="klein"), (0, 0)), ) ] else: return [ CartesianPathPlotCommand( "MOVETO", end.change_ring(RR).coordinates(model="klein") ) ] else: raise NotImplementedError("cannot move in this model")
[docs] @dataclass class CartesianPathPlotCommand: r""" A plot command in the plot coordinate system. EXAMPLES: Move the cursor to the origin of the coordinate system:: sage: from flatsurf.graphical.hyperbolic import CartesianPathPlotCommand sage: P = CartesianPathPlotCommand("MOVETO", (0, 0)) Draw a line segment to another point:: sage: P = CartesianPathPlotCommand("LINETO", (1, 1)) Draw a ray from the current position in a specific direction:: sage: P = CartesianPathPlotCommand("RAYTO", (1, 1)) Move the cursor to a point at infinity in a specific direction:: sage: P = CartesianPathPlotCommand("MOVETOINFINITY", (0, 1)) When already at a point at infinity, then this draws a line:: sage: P = CartesianPathPlotCommand("RAYTO", (0, -1)) When at a point at infinity, we can also draw a ray to a finite point:: sage: P = CartesianPathPlotCommand("LINETO", (0, 0)) Finally, we can draw counterclockwise and clockwise sectors of the circle, i.e., arcs by specifying the other endpoint and the center of the circle:: sage: P = CartesianPathPlotCommand("ARCTO", ((2, 0), (1, 0))) sage: P = CartesianPathPlotCommand("RARCTO", ((0, 0), (1, 0))) .. SEEALSO:: :class:`CartesianPathPlot` which draws a sequence of such commands with matplotlib. :meth:`HyperbolicPathPlotCommand.make_cartesian` to generate a sequence of such commands from a sequence of plot commands in the hyperbolic plane. """ code: str # Literal["MOVETO", "MOVETOINFINITY", "LINETO", "RAYTO", "ARCTO", "RARCTO"] requires Python 3.8 args: tuple
[docs] @rename_keyword(color="rgbcolor") @options( alpha=1, rgbcolor=(0, 0, 1), edgecolor=None, thickness=1, legend_label=None, legend_color=None, aspect_ratio=1.0, fill=True, ) def hyperbolic_path(commands, model="half_plane", **options): r""" Return a SageMath ``Graphics`` object that represents the hyperbolic path encoded by ``commands``. INPUT: - ``commands`` -- a sequence of :class:`HyperbolicPathPlotCommand` - ``model`` -- one of ``"half_plane"`` or ``"klein"`` Many additional keyword arguments are understood, see :class:`CartesianPathPlot` for details. EXAMPLES: .. jupyter-execute:: sage: from flatsurf.graphical.hyperbolic import HyperbolicPathPlotCommand, hyperbolic_path sage: from flatsurf import HyperbolicPlane sage: H = HyperbolicPlane() sage: hyperbolic_path([ ....: HyperbolicPathPlotCommand("MOVETO", H(0)), ....: HyperbolicPathPlotCommand("LINETO", H(I + 1)), ....: HyperbolicPathPlotCommand("LINETO", H(oo)), ....: HyperbolicPathPlotCommand("LINETO", H(I - 1)), ....: HyperbolicPathPlotCommand("LINETO", H(0)), ....: ]) ...Graphics object consisting of 2 graphics primitives .. SEEALSO:: :meth:`flatsurf.geometry.hyperbolic.HyperbolicConvexSet.plot` """ if options["thickness"] is None: if options["fill"] and options["edgecolor"] is None: options["thickness"] = 0 else: options["thickness"] = 1 from sage.plot.all import Graphics g = Graphics() g._set_extra_kwds(Graphics._extract_kwds_for_show(options)) try: if options.get("fill", None): g.add_primitive( CartesianPathPlot( HyperbolicPathPlotCommand.make_cartesian( commands, model=model, fill=True, stroke=False ), {**options, "thickness": 0}, ) ) g.add_primitive( CartesianPathPlot( HyperbolicPathPlotCommand.make_cartesian( commands, model=model, fill=False, stroke=True ), {**options, "fill": False}, ) ) except Exception as e: raise RuntimeError(f"Failed to render hyperbolic path {commands}", e) if options["legend_label"]: g.legend(True) g._legend_colors = [options["legend_color"]] return g