API Reference

perfect_freehand – Draw perfect pressure-sensitive freehand lines

Draw perfect pressure-sensitive freehand lines.

For most use cases, the get_stroke() function is the only thing you will need. It transforms the input points from the device to a polygon representing the stroke which can be drawn.

perfect_freehand.get_stroke(points, *, size=16.0, streamline=0.5, last=False, thinning=0.5, smoothing=0.5, easing=<function default_easing>, simulate_pressure=True, cap_start=True, taper_start=False, taper_start_ease=<function default_taper_start_ease>, cap_end=True, taper_end=False, taper_end_ease=<function default_taper_end_ease>)

Get an array of points describing a polygon that surrounds the input points.

Internally, this calls get_stroke_points() to pre-process the points (normalizing, smoothing, adding extra metadata) then get_stroke_outline_points() to transform the points to an outline of the drawn stroke.

Parameters:

  • points (Sequence[Union[Sequence[float], InputPoint]]) –

    An array of points, as a iterable (x, y, pressure) or a dict {"x": x, "y": y, "pressure": p}.

    Pressure is optional in both cases.

  • size (float) – The base size (diameter) of the stroke.

  • streamline (float) – Adjust the interpolation level between points.

  • last (bool) – Whether to handle the points as a completed stroke.

  • thinning (float) – The effect of pressure on the stroke’s size.

  • smoothing (float) – How much to soften the stroke’s edges.

  • easing (Callable[[float], float]) – An easing function to apply to each point’s pressure.

  • simulate_pressure (bool) – Whether to simulate pressure based on velocity.

  • cap_start (bool) – Whether to draw a round cap at the start of the line. This parameter has no effect if taper_start is non-zero.

  • taper_start (Union[bool, float]) – The distance to apply the start taper. If set to True, the taper will be the total length of the stroke.

  • taper_start_ease (Callable[[float], float]) – An easing function for the start taper. Default is based on a quadratic curve.

  • cap_end (bool) – Whether to draw a round cap at the end of the line. This parameter has no effect if taper_end is non-zero.

  • taper_end (Union[bool, float]) – The distance to apply the end taper. If set to True, the taper will be the total length of the stroke.

  • taper_end_ease (Callable[[float], float]) – An easing function for the end taper. Default is based on a cubic curve.

Return type:

List[Tuple[float, float]]

Returns:

A sequence of points (each represented by a tuple of (x, y)) that represent an outline of the drawn stroke.

Returns:

A sequence of points (each represented by a tuple of (x, y)) that represent an outline of the drawn stroke.

perfect_freehand.get_stroke_points(points, *, size=16.0, streamline=0.5, last=False)

Returns a sequence of stroke points with an adjusted point, pressure, vector, distance, and running length.

Parameters:

  • points (Sequence[Union[Sequence[float], InputPoint]]) –

    An array of points, as a iterable (x, y, pressure) or a dict {"x": x, "y": y, "pressure": p}.

    Pressure is optional in both cases.

  • size (float) – The base size (diameter) of the stroke.

  • streamline (float) – Adjust the interpolation level between points.

  • last (bool) – Whether to handle the points as a completed stroke.

Return type:

List[StrokePoint]

Returns:

A sequence of types.StrokePoint objects.

Note

When the last property is True, the line’s end will be drawn at the last input point, rather than slightly behind it.

perfect_freehand.get_stroke_outline_points(points, *, size=16.0, thinning=0.5, smoothing=0.5, easing=<function default_easing>, simulate_pressure=True, last=False, cap_start=True, taper_start=False, taper_start_ease=<function default_taper_start_ease>, cap_end=True, taper_end=False, taper_end_ease=<function default_taper_end_ease>)

Get an array of points (as (x, y)) representing the outline of a stroke.

Parameters:

  • points (Sequence[StrokePoint]) – An array of types.StrokePoint as returned from get_stroke_points().

  • size (float) – The base size (diameter) of the stroke.

  • thinning (float) – The effect of pressure on the stroke’s size.

  • smoothing (float) – How much to soften the stroke’s edges.

  • easing (Callable[[float], float]) – An easing function to apply to each point’s pressure.

  • simulate_pressure (bool) – Whether to simulate pressure based on velocity.

  • last (bool) – Whether to handle the points as a completed stroke.

  • cap_start (bool) – Whether to draw a round cap at the start of the line. This parameter has no effect if taper_start is non-zero.

  • taper_start (Union[bool, float]) – The distance to apply the start taper. If set to True, the taper will be the total length of the stroke.

  • taper_start_ease (Callable[[float], float]) – An easing function for the start taper. Default is based on a quadratic curve.

  • cap_end (bool) – Whether to draw a round cap at the end of the line. This parameter has no effect if taper_end is non-zero.

  • taper_end (Union[bool, float]) – The distance to apply the end taper. If set to True, the taper will be the total length of the stroke.

  • taper_end_ease (Callable[[float], float]) – An easing function for the end taper. Default is based on a cubic curve.

Return type:

List[Tuple[float, float]]

Returns:

A sequence of points (each represented by a tuple of (x, y)) that represent an outline of the drawn stroke.

perfect_freehand.types – Support for Python type hints

Support types for Python type hints.

class perfect_freehand.types.InputPoint

The structure of a point dict that can be used as input to get_stroke_points()

This TypedDict class is only used for typechecking; you can use an ordinary dict with the keys described here.

pressure: float

The stylus pressure associated with the point. Optional.

x: float

The x coordinate of the point.

y: float

The y coordinate of the point.

class perfect_freehand.types.StrokePoint

The structure of a point dict that is the output from get_stroke_points()

This TypedDict class is only used for typechecking; the returned points are accessed in the same way as a normal dict.

distance: float

The linear distance from the previous point to this point.

point: Tuple[float, float]

The x/y position of the point.

pressure: float

The stylus pressure associated with the point, or synthesized.

running_length: float

The sum of all distances up to this point.

vector: Tuple[float, float]

The motion vector from the previous point to this point.