Paths

A path allows you to create a shape by connecting a series of points by lines or curves. The usual way to use paths involves:

Creating a Path instance (which also specifies its initial location)

from scripton.canvas import Path, Canvas path = Path(x=30, y=20)
Invoking a series of methods on the Path instance (like path.line_to or path.arc_to)

path.line_to(x=270, y=180) path.move_to(x=30, y=180) path.line_to(x=270, y=20)
Drawing it on a Canvas instance using its draw_path method

canvas = Canvas(width=300, height=200) canvas.draw_path(path, stroke='#D38EE7')

As shown above, creating a Path instance and calling its various methods (like line_to or ellipse) doesn't result in any drawing. Instead, that occurs when the path is passed to a canvas instance's draw_path method. The same path can be drawn multiple times.

Current Position

Most methods described below implicitly start at the current position. This refers to the last set position of the path. It starts off as the point specified at construction (eg: Path(x=30, y=20)). Each subsequent path operation may alter this. For instance, path.line_to(x=270, y=20) leaves the current position at (270, 20). You can always explicitly set the current position using move_to.

API

`Path.line_to`

Adds a straight line from the current position to the newly specified one.

from scripton.canvas import Canvas, Path

path = Path(x=30, y=20)
path.line_to(x=270, y=180)

canvas = Canvas(width=300, height=200)
canvas.draw_path(path, stroke='#FFF', thickness=3)

`Path.move_to`

You can "lift up the pen" and move to a new location for a sub-path using the move_to method:

from scripton.canvas import Canvas, Path

path = Path(x=30, y=20)
path.line_to(x=270, y=180)
path.move_to(x=30, y=180)
path.line_to(x=270, y=20)

canvas = Canvas(width=300, height=200)
canvas.draw_path(path, stroke='#FFF', thickness=3)

`Path.arc_to`

Adds an arc specified by the two control points ((x1, y1) and (x2, y2)) and a radius.

from scripton.canvas import Canvas, Path

path = Path(x=80, y=30)
path.arc_to(
    x1=250,
    y1=128,
    x2=80,
    y2=256,
    radius=75
)

canvas = Canvas(width=200, height=200)
canvas.draw_path(path, stroke='#FFF', thickness=2)

Here's an annotated version of the same arc that provides some insights into how it's produced —

The precise details of how arc_to behaves matches the HTML Canvas specifications.

`Path.bezier_curve_to`

Adds a cubic Bézier curve specified by two control points ((cp1x, cp1y) and (cp2x, cp2y)) and an end point ((epx, epy)).

from scripton.canvas import Canvas, Path

path = Path(x=150, y=20)
path.bezier_curve_to(
    cp1x=50,
    cp1y=40,
    cp2x=200,
    cp2y=100,
    epx=100,
    epy=180
)

canvas = Canvas(width=300, height=200)
canvas.draw_path(path, stroke='#FFF', thickness=3)

The following figure visualizes the parameters of the Bézier curve above.

`Path.quadratic_curve_to`

Adds a quadratic Bézier curve specified by a single control point ((cpx, cpy)) and an end point ((epx, epy)).

from scripton.canvas import Canvas, Path

path = Path(x=25, y=150)
path.quadratic_curve_to(
    cpx=150,
    cpy=50,
    epx=275,
    epy=150
)

canvas = Canvas(width=300, height=200)
canvas.draw_path(path, stroke='#FFF', thickness=3)

The following figure visualizes the parameters of the quadratic Bézier curve above.

`Path.arc`

Adds an arc centered at (x, y) with a given radius, and starting and ending angles measured in radians. An optional counterclockwise keyword argument (False by default) controls the direction in which the path is rendered.

from scripton.canvas import Canvas, Path
from math import pi

path = Path(x=75, y=75)
path.arc(
    x=75,
    y=75,
    radius=70,
    start_angle=0.25 * pi,
    end_angle=1.75 * pi
)

canvas = Canvas(width=150, height=150)
canvas.draw_path(path, fill='#FAB526')

`Path.ellipse`

Adds an elliptical arc specified by its center ((x, y)), radii (radius_x, radius_y). Optional keyword-only arguments include:

rotation angle for the ellipse (measured in radians)
start_angle and end_angle for the arc (measured in radians)
counterclockwise (defaults to False) for controlling the direction of the arc.

from scripton.canvas import Canvas, Path
from math import pi

path = Path(x=75, y=75)
path.ellipse(
    x=75,
    y=75,
    radius_x=75,
    radius_y=50,
    rotation=pi / 4
)

canvas = Canvas(width=150, height=150)
canvas.draw_path(path, fill='#FAB526')

`Path.close`

Draws a straight-line from the current position to the start of the path. Calling close on an already closed path (or one with fewer than two points) is effectively a no-op.

from scripton.canvas import Canvas, Path

path = Path(x=75, y=25)
path.line_to(x=25, y=125)
path.line_to(x=125, y=125)
path.close()

canvas = Canvas(width=150, height=150)
canvas.draw_path(path, stroke='#FFF', thickness=3)

`Path.clone`

Returns a copy of the path. Updates to this copy leave the original path unaffected.