ragraph.plot.svg

SVG shapes

This module contains two base classes, being the Line options for SVG shapes and an SVG mapping for the shapes themselves. You will also find several methods to obtain several basic shapes conveniently.

Line

Line(
    color: Optional[str] = None,
    width: Optional[int] = None,
    dash: Optional[str] = None,
)

Bases: Mapping

SVG line options mapping.

Parameters:

Name	Type	Description	Default
color	Optional[str]	Line color.	None
width	Optional[int]	Line width in pixels.	None
dash	Optional[str]	Dash style of the line.	None

Source code in ragraph/plot/svg.py

def __init__(
    self,
    color: Optional[str] = None,
    width: Optional[int] = None,
    dash: Optional[str] = None,
):
    super().__init__(color=color, width=width, dash=dash)

color

color() -> str

Line color.

Source code in ragraph/plot/svg.py

@field
def color(self) -> str:  # type: ignore
    """Line color."""

dash

dash() -> str

Dash style of the line.

Source code in ragraph/plot/svg.py

@field
def dash(self) -> str:  # type: ignore
    """Dash style of the line."""

width

width() -> int

Line width in pixels.

Source code in ragraph/plot/svg.py

@field
def width(self) -> int:  # type: ignore
    """Line width in pixels."""

SVG

SVG(
    visible: Optional[bool] = None,
    type: Optional[str] = None,
    layer: Optional[str] = None,
    xref: Optional[str] = None,
    xsizemode: Optional[str] = None,
    xanchor: Optional[str] = None,
    x0: Optional[float] = None,
    x1: Optional[float] = None,
    yref: Optional[str] = None,
    ysizemode: Optional[str] = None,
    yanchor: Optional[str] = None,
    y0: Optional[float] = None,
    y1: Optional[float] = None,
    path: Optional[str] = None,
    opacity: Optional[float] = None,
    line: Optional[Union[Dict[str, Any], Line]] = None,
    fillcolor: Optional[str] = None,
    fillrule: Optional[str] = None,
    editable: Optional[bool] = None,
    name: Optional[str] = None,
    templateitemname: Optional[str] = None,
)

Bases: Mapping

SVG shape mapping.

Parameters:

Name	Type	Description	Default
visible	Optional[bool]	Toggles shape visibility.	None
type	Optional[str]	One of 'circle', 'rect', 'path' or 'line'.	None
layer	Optional[str]	'above' draws shape above traces, 'below' under them.	None
xref	Optional[str]	x coordinate axis. 'paper' or 'x', 'x1', 'x2', etc.	None
xsizemode	Optional[str]	'scaled' or 'pixel'. Relative or absolute sizing w.r.t. axis.	None
xanchor	Optional[str]	If sizemode is set to 'pixel', reference on axis to anchor shape to.	None
x0	Optional[float]	Starting x position.	None
x1	Optional[float]	Ending x position.	None
yref	Optional[str]	y coordinate axis. 'paper' or 'y', 'y1', 'y2', etc.	None
ysizemode	Optional[str]	'scaled' or 'pixel'. Relative or absolute sizing w.r.t. axis.	None
yanchor	Optional[str]	If sizemode is set to 'pixel', reference on axis to anchor shape to.	None
y0	Optional[float]	Starting y position.	None
y1	Optional[float]	Ending y position.	None
path	Optional[str]	For shapetype 'path', a valid SVG path, with data values as coordinates when referencing axis and absolute pixels with respect to anchors when the 'pixel' sizemode is set.	None
opacity	Optional[float]	The opacity between 0.0 and 1.0.	None
line	Optional[Union[Dict[str, Any], Line]]	Line mapping options. See Line.	None
fillcolor	Optional[str]	Interior shape color.	None
fillrule	Optional[str]	Determines which regions of complex paths constitute the interior. One of "evenodd" or "nonzero".	None
editable	Optional[bool]	Whether the shape could be activated for edit or not.	None
name	Optional[str]	Only used with templates.	None
templateitemname	Optional[str]	Used to refer to a named item in this array in the template.	None

Source code in ragraph/plot/svg.py

def __init__(
    self,
    visible: Optional[bool] = None,
    type: Optional[str] = None,
    layer: Optional[str] = None,
    xref: Optional[str] = None,
    xsizemode: Optional[str] = None,
    xanchor: Optional[str] = None,
    x0: Optional[float] = None,
    x1: Optional[float] = None,
    yref: Optional[str] = None,
    ysizemode: Optional[str] = None,
    yanchor: Optional[str] = None,
    y0: Optional[float] = None,
    y1: Optional[float] = None,
    path: Optional[str] = None,
    opacity: Optional[float] = None,
    line: Optional[Union[Dict[str, Any], Line]] = None,
    fillcolor: Optional[str] = None,
    fillrule: Optional[str] = None,
    editable: Optional[bool] = None,
    name: Optional[str] = None,
    templateitemname: Optional[str] = None,
):
    super().__init__(
        visible=visible,
        type=type,
        layer=layer,
        xref=xref,
        xsizemode=xsizemode,
        xanchor=xanchor,
        x0=x0,
        x1=x1,
        yref=yref,
        ysizemode=ysizemode,
        yanchor=yanchor,
        y0=y0,
        y1=y1,
        path=path,
        opacity=opacity,
        line=line,
        fillcolor=fillcolor,
        fillrule=fillrule,
        editable=editable,
        name=name,
        templateitemname=templateitemname,
    )

editable

editable() -> bool

Whether the shape could be activated for edit or not.

Source code in ragraph/plot/svg.py

@field
def editable(self) -> bool:  # type: ignore
    """Whether the shape could be activated for edit or not."""

fillcolor

fillcolor() -> str

Interior shape color.

Source code in ragraph/plot/svg.py

@field
def fillcolor(self) -> str:  # type: ignore
    """Interior shape color."""

fillrule

fillrule() -> str

Determines which regions of complex paths constitute the interior. One of 'evenodd' or 'nonzero'.

Source code in ragraph/plot/svg.py

@field
def fillrule(self) -> str:  # type: ignore
    """Determines which regions of complex paths constitute the interior.
    One of 'evenodd' or 'nonzero'.
    """

layer

layer() -> str

'above' draws shape above traces, 'below' under them.

Source code in ragraph/plot/svg.py

@field
def layer(self) -> str:  # type: ignore
    """'above' draws shape above traces, 'below' under them."""

line

line() -> Line

Line mapping options. See Line.

Source code in ragraph/plot/svg.py

@field
def line(self) -> Line:  # type: ignore
    """Line mapping options. See [`Line`][ragraph.plot.svg.Line]."""

name

name() -> str

Only used with templates.

Source code in ragraph/plot/svg.py

@field
def name(self) -> str:  # type: ignore
    """Only used with templates."""

opacity

opacity() -> float

The opacity between 0.0 and 1.0.

Source code in ragraph/plot/svg.py

@field
def opacity(self) -> float:  # type: ignore
    """The opacity between 0.0 and 1.0."""

path

path() -> str

For shapetype 'path', a valid SVG path, with data values as coordinates when referencing axis and absolute pixels with respect to anchors when the 'pixel' sizemode is set.

Source code in ragraph/plot/svg.py

@field
def path(self) -> str:  # type: ignore
    """For shapetype 'path', a valid SVG path, with data values as coordinates when referencing
    axis and absolute pixels with respect to anchors when the 'pixel' sizemode is set.
    """

templateitemname

templateitemname() -> str

Used to refer to a named item in this array in the template.

Source code in ragraph/plot/svg.py

@field
def templateitemname(self) -> str:  # type: ignore
    """Used to refer to a named item in this array in the template."""

type

type() -> str

One of 'circle', 'rect', 'path' or 'line'.

Source code in ragraph/plot/svg.py

@field
def type(self) -> str:  # type: ignore
    """One of 'circle', 'rect', 'path' or 'line'."""

visible

visible() -> bool

Toggles shape visibility.

Source code in ragraph/plot/svg.py

@field
def visible(self) -> bool:  # type: ignore
    """Toggles shape visibility."""

x0

x0() -> float

Starting x position.

Source code in ragraph/plot/svg.py

@field
def x0(self) -> float:  # type: ignore
    """Starting x position."""

x1

x1() -> float

Ending x position.

Source code in ragraph/plot/svg.py

@field
def x1(self) -> float:  # type: ignore
    """Ending x position."""

xanchor

xanchor() -> str

If sizemode is set to 'pixel', reference on axis to anchor shape to.

Source code in ragraph/plot/svg.py

@field
def xanchor(self) -> str:  # type: ignore
    """If sizemode is set to 'pixel', reference on axis to anchor shape to."""

xref

xref() -> str

x coordinate axis. 'paper' or 'x', 'x1', 'x2', etc.

Source code in ragraph/plot/svg.py

@field
def xref(self) -> str:  # type: ignore
    """x coordinate axis. 'paper' or 'x', 'x1', 'x2', etc."""

xsizemode

xsizemode() -> str

'scaled' or 'pixel'. Relative or absolute sizing w.r.t. axis.

Source code in ragraph/plot/svg.py

@field
def xsizemode(self) -> str:  # type: ignore
    """'scaled' or 'pixel'. Relative or absolute sizing w.r.t. axis."""

y0

y0() -> float

Starting y position.

Source code in ragraph/plot/svg.py

@field
def y0(self) -> float:  # type: ignore
    """Starting y position."""

y1

y1() -> float

Ending y position.

Source code in ragraph/plot/svg.py

@field
def y1(self) -> float:  # type: ignore
    """Ending y position."""

yanchor

yanchor() -> str

If sizemode is set to 'pixel', reference on axis to anchor shape to.

Source code in ragraph/plot/svg.py

@field
def yanchor(self) -> str:  # type: ignore
    """If sizemode is set to 'pixel', reference on axis to anchor shape to."""

yref

yref() -> str

y coordinate axis. 'paper' or 'y', 'y1', 'y2', etc.

Source code in ragraph/plot/svg.py

@field
def yref(self) -> str:  # type: ignore
    """y coordinate axis. 'paper' or 'y', 'y1', 'y2', etc."""

ysizemode

ysizemode() -> str

'scaled' or 'pixel'. Relative or absolute sizing w.r.t. axis.

Source code in ragraph/plot/svg.py

@field
def ysizemode(self) -> str:  # type: ignore
    """'scaled' or 'pixel'. Relative or absolute sizing w.r.t. axis."""

get_curvedline

get_curvedline(
    x0: float,
    x1: float,
    x2: float,
    y0: float,
    y1: float,
    y2: float,
    **kwargs: Any
) -> SVG

Get curved line (quadratic Bezier) SVG mapping.

Parameters:

Name	Type	Description	Default
x0	float	Starting x position.	required
x1	float	Control point x position.	required
x2	float	Ending x position.	required
y0	float	Starting y position.	required
y1	float	Control point y position.	required
y2	float	Ending y position.	required
**kwargs	Any	Overrides for the SVG object.	{}

Returns:

Type	Description
SVG	Quadratic Bezier SVG shape mapping.

Source code in ragraph/plot/svg.py

def get_curvedline(
    x0: float,
    x1: float,
    x2: float,
    y0: float,
    y1: float,
    y2: float,
    **kwargs: Any,
) -> SVG:
    """Get curved line (quadratic Bezier) SVG mapping.

    Arguments:
        x0: Starting x position.
        x1: Control point x position.
        x2: Ending x position.
        y0: Starting y position.
        y1: Control point y position.
        y2: Ending y position.
        **kwargs: Overrides for the [`SVG`][ragraph.plot.svg.SVG] object.

    Returns:
        Quadratic Bezier SVG shape mapping.
    """
    path = f"M {x0} {y0} Q {x1} {y1} {x2} {y2}"
    return SVG(type="path", path=path, **kwargs)

get_line

get_line(
    x0: float,
    x1: float,
    y0: float,
    y1: float,
    **kwargs: Any
) -> SVG

Get straight line SVG mapping.

Parameters:

Name	Type	Description	Default
x0	float	Starting x position.	required
x1	float	Ending x position.	required
y0	float	Starting y position.	required
y1	float	Ending y position.	required
**kwargs	Any	Overrides for the SVG object.	{}

Returns:

Type	Description
SVG	SVG shape mapping.

Source code in ragraph/plot/svg.py

def get_line(
    x0: float,
    x1: float,
    y0: float,
    y1: float,
    **kwargs: Any,
) -> SVG:
    """Get straight line SVG mapping.

    Arguments:
        x0: Starting x position.
        x1: Ending x position.
        y0: Starting y position.
        y1: Ending y position.
        **kwargs: Overrides for the [`SVG`][ragraph.plot.svg.SVG] object.

    Returns:
        SVG shape mapping.
    """
    return SVG(type="line", x0=x0, x1=x1, y0=y0, y1=y1, **kwargs)

get_rectangle

get_rectangle(
    x0: float,
    x1: float,
    y0: float,
    y1: float,
    **kwargs: Any
) -> SVG

Get a rectangle SVG mapping.

Parameters:

Name	Type	Description	Default
x0	float	Starting x position.	required
x1	float	Ending x position.	required
y0	float	Starting y position.	required
y1	float	Ending y position.	required
**kwargs	Any	Overrides for the SVG object.	{}

Returns:

Type	Description
SVG	SVG shape mapping.

Source code in ragraph/plot/svg.py

def get_rectangle(
    x0: float,
    x1: float,
    y0: float,
    y1: float,
    **kwargs: Any,
) -> SVG:
    """Get a rectangle SVG mapping.

    Arguments:
        x0: Starting x position.
        x1: Ending x position.
        y0: Starting y position.
        y1: Ending y position.
        **kwargs: Overrides for the [`SVG`][ragraph.plot.svg.SVG] object.

    Returns:
        SVG shape mapping.
    """
    return SVG(type="rect", x0=x0, x1=x1, y0=y0, y1=y1, **kwargs)

get_wedge

get_wedge(
    x: float,
    y: float,
    r: float,
    start_angle: float,
    end_angle: float,
    **kwargs: Any
) -> SVG

Get a wedge SVG mapping.

Parameters:

Name	Type	Description	Default
x	float	x position of the wedge center.	required
y	float	y position of the wedge center.	required
r	float	radius of the wedge.	required
start_angle	float	Starting angle (radians) of the wedge.	required
end_angle	float	Ending angle (radians) of the wedge.	required
**kwargs	Any	Overrides for the SVG object.	{}

Returns:

Type	Description
SVG	SVG shape mapping.

Source code in ragraph/plot/svg.py

def get_wedge(
    x: float, y: float, r: float, start_angle: float, end_angle: float, **kwargs: Any
) -> SVG:
    """Get a wedge SVG mapping.

    Arguments:
        x: x position of the wedge center.
        y: y position of the wedge center.
        r: radius of the wedge.
        start_angle: Starting angle (radians) of the wedge.
        end_angle: Ending angle (radians) of the wedge.
        **kwargs: Overrides for the [`SVG`][ragraph.plot.svg.SVG] object.

    Returns:
        SVG shape mapping.
    """
    segments = ["M {} {}".format(x, y)]
    xa = x + round(r * cos(start_angle), 3)
    xb = y + round(r * sin(start_angle), 3)
    segments.append(" L {} {}".format(xa, xb))

    delta = end_angle - start_angle
    max_delta = 0.25 * pi
    while delta > 0:
        if delta >= max_delta:
            angle_step = max_delta
        else:
            angle_step = delta

        # Get curve control points
        xc = round(
            x + r / cos(angle_step / 2) * cos(start_angle + angle_step / 2),
            3,
        )
        yc = round(
            y + r / cos(angle_step / 2) * sin(start_angle + angle_step / 2),
            3,
        )
        xe = round(x + r * cos(start_angle + angle_step), 3)
        ye = round(y + r * sin(start_angle + angle_step), 3)

        # Add the segment.
        segments.append(" Q {} {} {} {}".format(xc, yc, xe, ye))
        delta -= angle_step
        start_angle += angle_step

    segments.append(" Z")

    path = "".join(segments)

    return SVG(type="path", path=path, **kwargs)