Skip to content

thorvg-python documentation

thorvg_python.paint.shape

thorvg_python.paint.shape¶

Classes¶

`Shape`	Shape API

Module Contents¶

class thorvg_python.paint.shape.Shape(engine: thorvg_python.engine.Engine, paint: thorvg_python.base.PaintPointer | None = None)¶

Bases: thorvg_python.paint.Paint

Shape API

A module for managing two-dimensional figures and their properties.

A shape has three major properties: shape outline, stroking, filling. The outline in the shape is retained as the path. Path can be composed by accumulating primitive commands such as Shape.move_to(), Shape.line_to(), Shape.cubic_to() or complete shape interfaces such as Shape.append_rect(), Shape.append_circle(), etc. Path can consists of sub-paths. One sub-path is determined by a close command.

The stroke of a shape is an optional property in case the shape needs to be represented with/without the outline borders. It’s efficient since the shape path and the stroking path can be shared with each other. It’s also convenient when controlling both in one context.

engine¶

thorvg_lib¶

_new() → thorvg_python.base.PaintPointer¶

Creates a new shape object.

Note that you need not call this method as it is auto called when initializing Shape().

Returns:¶: A new shape object.
Return type:¶: thorvg_python.base.PaintPointer

reset() → thorvg_python.base.Result¶

Resets the shape path properties.

The color, the fill and the stroke properties are retained.

Returns:¶: Result.INVALID_ARGUMENT An invalid PaintPointer.
Return type:¶: thorvg_python.base.Result

Note

The memory, where the path data is stored, is not deallocated at this stage for caching effect.

move_to(x: float, y: float) → thorvg_python.base.Result¶

Sets the initial point of the sub-path.

The value of the current point is set to the given point.

Parameters:¶

x : float¶: The horizontal coordinate of the initial point of the sub-path.
y : float¶: The vertical coordinate of the initial point of the sub-path.

Returns:¶

Result.INVALID_ARGUMENT An invalid PaintPointer.

Return type:¶

thorvg_python.base.Result

line_to(x: float, y: float) → thorvg_python.base.Result¶

Adds a new point to the sub-path, which results in drawing a line from the current point to the given end-point.

The value of the current point is set to the given end-point.

Parameters:¶

x : float¶: The horizontal coordinate of the end-point of the line.
y : float¶: The vertical coordinate of the end-point of the line.

Returns:¶

Result.INVALID_ARGUMENT An invalid PaintPointer.

Return type:¶

thorvg_python.base.Result

Note

In case this is the first command in the path, it corresponds to the Shape.move_to() call.

cubic_to(cx1: float, cy1: float, cx2: float, cy2: float, x: float, y: float) → thorvg_python.base.Result¶

Adds new points to the sub-path, which results in drawing a cubic Bezier curve.

The Bezier curve starts at the current point and ends at the given end-point (x, y). Two control points (cx1, cy1) and (cx2, cy2) are used to determine the shape of the curve. The value of the current point is set to the given end-point.

Parameters:¶

cx1 : float¶: The horizontal coordinate of the 1st control point.
cy1 : float¶: The vertical coordinate of the 1st control point.
cx2 : float¶: The horizontal coordinate of the 2nd control point.
cy2 : float¶: The vertical coordinate of the 2nd control point.
x : float¶: The horizontal coordinate of the endpoint of the curve.
y : float¶: The vertical coordinate of the endpoint of the curve.

Returns:¶

Result.INVALID_ARGUMENT An invalid PaintPointer.

Return type:¶

thorvg_python.base.Result

Note

In case this is the first command in the path, no data from the path are rendered.

close() → thorvg_python.base.Result¶

Closes the current sub-path by drawing a line from the current point to the initial point of the sub-path.

The value of the current point is set to the initial point of the closed sub-path.

Returns:¶: Result.INVALID_ARGUMENT An invalid PaintPointer.
Return type:¶: thorvg_python.base.Result

Note

In case the sub-path does not contain any points, this function has no effect.

append_rect(x: float, y: float, w: float, h: float, rx: float, ry: float, cw: bool) → thorvg_python.base.Result¶

Appends a rectangle to the path.

The rectangle with rounded corners can be achieved by setting non-zero values to rx and ry arguments. The rx and ry values specify the radii of the ellipse defining the rounding of the corners.

The position of the rectangle is specified by the coordinates of its upper-left corner - x and y arguments.

The rectangle is treated as a new sub-path - it is not connected with the previous sub-path.

The value of the current point is set to (x + rx, y) - in case rx is greater than w/2 the current point is set to (x + w/2, y)

Parameters:¶

x : float¶: The horizontal coordinate of the upper-left corner of the rectangle.
y : float¶: The vertical coordinate of the upper-left corner of the rectangle.
w : float¶: The width of the rectangle.
h : float¶: The height of the rectangle.
rx : float¶: The x-axis radius of the ellipse defining the rounded corners of the rectangle.
ry : float¶: The y-axis radius of the ellipse defining the rounded corners of the rectangle.
cw : bool¶: Specifies the path direction: true for clockwise, false for counterclockwise.

Returns:¶

Result.INVALID_ARGUMENT An invalid PaintPointer.

Return type:¶

thorvg_python.base.Result

Note

For rx and ry greater than or equal to the half of w and the half of h, respectively, the shape become an ellipse.

append_circle(cx: float, cy: float, rx: float, ry: float, cw: bool) → thorvg_python.base.Result¶

Appends an ellipse to the path.

The position of the ellipse is specified by the coordinates of its center - cx and cy arguments.

The ellipse is treated as a new sub-path - it is not connected with the previous sub-path.

The value of the current point is set to (cx, cy - ry).

Parameters:¶

cx : float¶: The horizontal coordinate of the center of the ellipse.
cy : float¶: The vertical coordinate of the center of the ellipse.
rx : float¶: The x-axis radius of the ellipse.
ry : float¶: The y-axis radius of the ellipse.
cw : bool¶: Specifies the path direction: true for clockwise, false for counterclockwise.

Returns:¶

Result.INVALID_ARGUMENT An invalid PaintPointer.

Return type:¶

thorvg_python.base.Result

append_path(cmds: collections.abc.Sequence[thorvg_python.base.PathCommand], pts: collections.abc.Sequence[thorvg_python.base.PointStruct]) → thorvg_python.base.Result¶

Appends a given sub-path to the path.

The current point value is set to the last point from the sub-path. For each command from the cmds array, an appropriate number of points in pts array should be specified. If the number of points in the pts array is different than the number required by the cmds array, the shape with this sub-path will not be displayed on the screen.

Parameters:¶

cmds : Sequence[thorvg_python.base.PathCommand]¶: The array of the commands in the sub-path.
pts : Sequence[thorvg_python.base.PointStruct]¶: The array of the two-dimensional points.

Returns:¶

Result.INVALID_ARGUMENT A None passed as the argument or cmdCnt or ptsCnt equal to zero.

Return type:¶

thorvg_python.base.Result

get_path() → tuple[thorvg_python.base.Result, collections.abc.Sequence[thorvg_python.base.PathCommand], collections.abc.Sequence[thorvg_python.base.PointStruct]]¶

Gets the points values of the path.

The function does not allocate any data, it operates on internal memory. There is no need to free the pts sequence.

Returns:¶: Result.INVALID_ARGUMENT A None passed as the argument.
Return type:¶: thorvg_python.base.Result
Returns:¶: A sequence of the commands from the path.
Return type:¶: Sequence[thorvg_python.base.PathCommand]
Returns:¶: A sequence of the two-dimensional points from the path.
Return type:¶: Sequence[thorvg_python.base.PointStruct]

set_stroke_width(width: float) → thorvg_python.base.Result¶

Sets the stroke width for the path.

This function defines the thickness of the stroke applied to all figures in the path object. A stroke is the outline drawn along the edges of the path’s geometry.

Parameters:¶

width: float¶: The width of the stroke in pixels. Must be positive value. (The default is 0)

Returns:¶

TVG_RESULT_INVALID_ARGUMENT An invalid PaintPointer.

Return type:¶

thorvg_python.base.Result

Note

A value of width 0 disables the stroke.

See also

Shape.set_stroke_color()

get_stroke_width() → tuple[thorvg_python.base.Result, float]¶

Gets the shape’s stroke width.

Returns:¶: Result.INVALID_ARGUMENT An invalid pointer passed as an argument.
Return type:¶: thorvg_python.base.Result
Returns:¶: The stroke width.
Return type:¶: float

set_stroke_color(r: int, g: int, b: int, a: int) → thorvg_python.base.Result¶

Sets the shape’s stroke color.

Parameters:¶

r : int¶: The red color channel value in the range [0 ~ 255]. The default value is 0.
g : int¶: The green color channel value in the range [0 ~ 255]. The default value is 0.
b : int¶: The blue color channel value in the range [0 ~ 255]. The default value is 0.
a : int¶: The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque.

Returns:¶

Result.INVALID_ARGUMENT An invalid PaintPointer.

Return type:¶

thorvg_python.base.Result

Note

If the stroke width is 0 (default), the stroke will not be visible regardless of the color.

Note

Either a solid color or a gradient fill is applied, depending on what was set as last.

See also

Shape.set_stroke_width()

See also

Shape.set_stroke_gradient()

get_stroke_color() → tuple[thorvg_python.base.Result, int, int, int, int]¶

Gets the shape’s stroke color.

Returns:¶

Result.INVALID_ARGUMENT An invalid PaintPointer.
Result.INSUFFICIENT_CONDITION No stroke was set.

Return type:¶

thorvg_python.base.Result

Returns:¶

The red color channel value in the range [0 ~ 255]. The default value is 0.

Return type:¶

int

Returns:¶

The green color channel value in the range [0 ~ 255]. The default value is 0.

Return type:¶

int

Returns:¶

The blue color channel value in the range [0 ~ 255]. The default value is 0.

Return type:¶

int

Returns:¶

The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque.

Return type:¶

int

set_stroke_gradient(grad: thorvg_python.gradient.Gradient) → thorvg_python.base.Result¶

Sets the gradient fill of the stroke for all of the figures from the path.

Parameters:¶

grad : thorvg_python.gradient.Gradient¶: The gradient fill.

Returns:¶

Result.INVALID_ARGUMENT An invalid PaintPointer.
Result.MEMORY_CORRUPTION An invalid GradientPointer or an error with accessing it.

Return type:¶

thorvg_python.base.Result

Note

Either a solid color or a gradient fill is applied, depending on what was set as last.

See also

Shape.set_stroke_color()

get_stroke_gradient() → tuple[thorvg_python.base.Result, thorvg_python.gradient.Gradient | None]¶

Gets the gradient fill of the shape’s stroke.

The function does not allocate any memory.

Returns:¶: Result.INVALID_ARGUMENT An invalid pointer passed as an argument.
Return type:¶: thorvg_python.base.Result
Returns:¶: The gradient fill.
Return type:¶: Optional[thorvg_python.Gradient]

set_stroke_dash(dash_pattern: collections.abc.Sequence[float] | None, offset: float) → thorvg_python.base.Result¶

Sets the shape’s stroke dash pattern.

Parameters:¶

dash_pattern : Optional[Sequence[float]]¶: An array of alternating dash and gap lengths.
offset : float¶: The shift of the starting point within the repeating dash pattern, from which the pattern begins to be applied.

Returns:¶

Result.INVALID_ARGUMENT In case dash_pattern is None and cnt > 0 or dash_pattern is not None and cnt is zero.

Return type:¶

thorvg_python.base.Result

Note

To reset the stroke dash pattern, pass None to dash_pattern and zero to cnt.

Note

Values of dash_pattern less than zero are treated as zero.

Note

If all values in the dash_pattern are equal to or less than 0, the dash is ignored.

Note

If the dash_pattern contains an odd number of elements, the sequence is repeated in the same order to form an even-length pattern, preserving the alternation of dashes and gaps.

Added in version 1.0.

get_stroke_dash() → tuple[thorvg_python.base.Result, collections.abc.Sequence[float], float]¶

Gets the dash pattern of the stroke.

The function does not allocate any memory.

Returns:¶: Result.INVALID_ARGUMENT An invalid pointer passed as an argument.
Return type:¶: thorvg_python.base.Result
Returns:¶: The array of consecutive pair values of the dash length and the gap length.
Return type:¶: Sequence[float]
Returns:¶: The shift of the starting point within the repeating dash pattern.
Return type:¶: float

Added in version 1.0.

set_stroke_cap(cap: thorvg_python.base.StrokeCap) → thorvg_python.base.Result¶

Sets the cap style used for stroking the path.

The cap style specifies the shape to be used at the end of the open stroked sub-paths.

Parameters:¶

cap : thorvg_python.base.StrokeCap¶: The cap style value. The default value is StrokeCap.SQUARE.

Returns:¶

Result.INVALID_ARGUMENT An invalid PaintPointer.

Return type:¶

thorvg_python.base.Result

get_stroke_cap() → tuple[thorvg_python.base.Result, thorvg_python.base.StrokeCap]¶

Gets the stroke cap style used for stroking the path.

Returns:¶: Result.INVALID_ARGUMENT An invalid pointer passed as an argument.
Return type:¶: thorvg_python.base.Result
Returns:¶: The cap style value.
Return type:¶: thorvg_python.base.StrokeCap

set_stroke_join(join: thorvg_python.base.StrokeJoin) → thorvg_python.base.Result¶

Sets the join style for stroked path segments.

Parameters:¶

join : thorvg_python.base.StrokeJoin¶: The join style value. The default value is StrokeJoin.BEVEL.

Returns:¶

Result.INVALID_ARGUMENT An invalid PaintPointer.

Return type:¶

thorvg_python.base.Result

get_stroke_join() → tuple[thorvg_python.base.Result, thorvg_python.base.StrokeJoin]¶

The function gets the stroke join method

Returns:¶: Result.INVALID_ARGUMENT An invalid pointer passed as an argument.
Return type:¶: thorvg_python.base.Result
Returns:¶: The join style value.
Return type:¶: thorvg_python.base.StrokeJoin

set_stroke_miterlimit(miterlimit: float) → thorvg_python.base.Result¶

Sets the stroke miterlimit.

Parameters:¶

miterlimit : float¶: The miterlimit imposes a limit on the extent of the stroke join when the MITER join style is set. The default value is 4.

Returns:¶

Result enumeration INVALID_ARGUMENT An invalid PaintPointer or Unsupported miterlimit values (less than zero).

Return type:¶

thorvg_python.base.Result

Added in version 0.11.

get_stroke_miterlimit() → tuple[thorvg_python.base.Result, float]¶

The function gets the stroke miterlimit.

Returns:¶: Result.INVALID_ARGUMENT An invalid pointer passed as an argument.
Return type:¶: thorvg_python.base.Result
Returns:¶: The stroke miterlimit.
Return type:¶: float

Added in version 0.11.

set_trimpath(begin: float, end: float, simultaneous: bool) → thorvg_python.base.Result¶

Sets the trim of the shape along the defined path segment, allowing control over which part of the shape is visible.

If the values of the arguments begin and end exceed the 0-1 range, they are wrapped around in a manner similar to angle wrapping, effectively treating the range as circular.

Parameters:¶

begin : float¶: Specifies the start of the segment to display along the path.
end : float¶: Specifies the end of the segment to display along the path.
simultaneous : bool¶: Determines how to trim multiple paths within a single shape. If set to true (default), trimming is applied simultaneously to all paths; Otherwise, all paths are treated as a single entity with a combined length equal to the sum of their individual lengths and are trimmed as such.

Returns:¶

TVG_RESULT_INVALID_ARGUMENT An invalid PaintPointer.

Return type:¶

thorvg_python.base.Result

Added in version 1.0.

set_fill_color(r: int, g: int, b: int, a: int) → thorvg_python.base.Result¶

Sets the shape’s solid color.

The parts of the shape defined as inner are colored.

:param int r The red color channel value in the range [0 ~ 255]. The default value is 0. :param int g: The green color channel value in the range [0 ~ 255]. The default value is 0. :param int b: The blue color channel value in the range [0 ~ 255]. The default value is 0. :param int a The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque. The default value is 0.

Returns:¶: Result.INVALID_ARGUMENT An invalid PaintPointer.
Return type:¶: thorvg_python.base.Result

Note

Either a solid color or a gradient fill is applied, depending on what was set as last.

See also

Shape.set_fill_rule()

get_fill_color() → tuple[thorvg_python.base.Result, int, int, int, int]¶

Gets the shape’s solid color.

Returns:¶: The red color channel value in the range [0 ~ 255]. The default value is 0.
Return type:¶: int
Returns:¶: The green color channel value in the range [0 ~ 255]. The default value is 0.
Return type:¶: int
Returns:¶: The blue color channel value in the range [0 ~ 255]. The default value is 0.
Return type:¶: int
Returns:¶: The alpha channel value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque. The default value is 0.
Return type:¶: int
Returns:¶: Result.INVALID_ARGUMENT An invalid PaintPointer.
Return type:¶: thorvg_python.base.Result

set_fill_rule(rule: thorvg_python.base.FillRule) → thorvg_python.base.Result¶

Sets the fill rule for the shape.

Specifies how the interior of the shape is determined when its path intersects itself. The default fill rule is FillRule.NON_ZERO.

Parameters:¶

rule : thorvg_python.base.FillRule¶: The fill rule to apply to the shape.

Returns:¶

TVG_RESULT_INVALID_ARGUMENT An invalid PaintPointer.

Return type:¶

thorvg_python.base.Result

get_fill_rule() → tuple[thorvg_python.base.Result, thorvg_python.base.FillRule]¶

Retrieves the current fill rule used by the shape.

This function returns the fill rule, which determines how the interior regions of the shape are calculated when it overlaps itself.

Returns:¶: The current FillRule value of the shape.
Return type:¶: thorvg_python.base.FillRule
Returns:¶: TVG_RESULT_INVALID_ARGUMENT An invalid pointer passed as an argument.
Return type:¶: thorvg_python.base.Result

set_paint_order(stroke_first: bool) → thorvg_python.base.Result¶

Sets the rendering order of the stroke and the fill.

Parameters:¶

stroke_first : bool¶: If true the stroke is rendered before the fill, otherwise the stroke is rendered as the second one (the default option).

Returns:¶

Result.INVALID_ARGUMENT An invalid PaintPointer.

Return type:¶

thorvg_python.base.Result

Added in version 0.10.

set_gradient(grad: thorvg_python.gradient.Gradient) → thorvg_python.base.Result¶

Sets the gradient fill for all of the figures from the path.

The parts of the shape defined as inner are filled.

Parameters:¶

grad : thorvg_python.gradient.Gradient¶: The gradient fill.

Returns:¶

TVG_RESULT_INVALID_ARGUMENT An invalid PaintPointer.
TVG_RESULT_MEMORY_CORRUPTION An invalid GradientPointer.

Return type:¶

thorvg_python.base.Result

Note

Either a solid color or a gradient fill is applied, depending on what was set as last.

See also

Shape.set_fill_rule()

get_gradient() → tuple[thorvg_python.base.Result, thorvg_python.gradient.linear.LinearGradient | thorvg_python.gradient.radial.RadialGradient]¶

Gets the gradient fill of the shape.

The function does not allocate any data.

Returns:¶: Result.INVALID_ARGUMENT An invalid pointer passed as an argument.
Return type:¶: thorvg_python.base.Result
Returns:¶: The gradient fill.
Return type:¶: thorvg_python.base.GradientPointer