thorvg_python.paint¶

class thorvg_python.paint.Paint(engine: Engine, paint: PaintStruct)¶

Bases: object

Paint API

A module for managing graphical elements. It enables duplication, transformation and composition.

This is base Paint class. Please instantiate with Shape, Picture, Scene or Text instead.

duplicate() → PaintStruct | None¶

Duplicates the given PaintStruct object.

Creates a new object and sets its all properties as in the original object.

Returns:¶: A copied PaintStruct object if succeed, nullptr otherwise.
Return type:¶: Optional[PaintStruct]

get_bounds(transformed: bool = False) → tuple[Result, float, float, float, float]¶

Gets the axis-aligned bounding box of the PaintStruct object.

Parameters:¶

transformed : bool¶: If true, the paint’s transformations are taken into account in the scene it belongs to. Otherwise they aren’t.

Returns:¶

INVALID_ARGUMENT An invalid PaintStruct pointer.

Return type:¶

Result

Returns:¶

The x-coordinate of the upper-left corner of the object.

Return type:¶

float

Returns:¶

The y-coordinate of the upper-left corner of the object.

Return type:¶

float

Returns:¶

The width of the object.

Return type:¶

float

Returns:¶

The height of the object.

Return type:¶

float

Note

This is useful when you need to figure out the bounding box of the paint in the canvas space.

Note

The bounding box doesn’t indicate the actual drawing region. It’s the smallest rectangle that encloses the object.

Note

If transformed is true, the paint needs to be pushed into a canvas and updated before this api is called.

See also

Canvas.update_paint()

get_composite_method() → tuple[Result, PaintStruct, CompositeMethod]¶

Gets the composition target object and the composition method.

Returns:¶: INVALID_ARGUMENT A nullptr is passed as the argument.
Return type:¶: Result
Returns:¶: The target object of the composition.
Return type:¶: PaintStruct
Returns:¶: The method used to composite the source object with the target.
Return type:¶: CompositeMethod

get_identifier() → tuple[Result, Identifier]¶: Deprecated since version 0.15.

See also

Paint.get_type()

get_opacity() → tuple[Result, int]¶

Gets the opacity of the given PaintStruct.

Returns:¶: INVALID_ARGUMENT In case a nullptr is passed as the argument.
Return type:¶: Result
Returns:¶: The opacity value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque.
Return type:¶: int

get_transform() → tuple[Result, Matrix]¶

Gets the matrix of the affine transformation of the given PaintStruct object.

In case no transformation was applied, the identity matrix is returned.

Returns:¶: INVALID_ARGUMENT A nullptr is passed as the argument.
Return type:¶: Result
Returns:¶: The 3x3 augmented matrix.
Return type:¶: Matrix

get_type() → tuple[Result, TvgType]¶

Gets the unique value of the paint instance indicating the instance type.

Returns:¶: INVALID_ARGUMENT In case a nullptr is passed as the argument.
Return type:¶: Result
Returns:¶: The unique type of the paint instance type.
Return type:¶: TvgType

Note

Experimental API

rotate(degree: float) → Result¶

Rotates the given PaintStruct by the given angle.

The angle in measured clockwise from the horizontal axis. The rotational axis passes through the point on the object with zero coordinates.

Parameters:¶

degree : float¶: The value of the rotation angle in degrees.

Returns:¶

INVALID_ARGUMENT An invalid PaintStruct pointer.
INSUFFICIENT_CONDITION in case a custom transform is applied.

Return type:¶

Result

See also

Paint.set_transform()

scale(factor: float) → Result¶

Scales the given PaintStruct object by the given factor.

Parameters:¶

factor : float¶: The value of the scaling factor. The default value is 1.

Returns:¶

INVALID_ARGUMENT An invalid PaintStruct pointer.
INSUFFICIENT_CONDITION in case a custom transform is applied.

Return type:¶

Result

See also

Paint.set_transform()

set_blend_method(method: BlendMethod) → Result¶

Sets the blending method for the paint object.

The blending feature allows you to combine colors to create visually appealing effects, including transparency, lighting, shading, and color mixing, among others. its process involves the combination of colors or images from the source paint object with the destination (the lower layer image) using blending operations. The blending operation is determined by the chosen BlendMethod, which specifies how the colors or images are combined.

Parameters:¶

method : BlendMethod¶: The blending method to be set.

Returns:¶

INVALID_ARGUMENT In case a nullptr is passed as the argument.

Return type:¶

Result

Added in version 0.15.

set_clip(clipper: Paint) → Result¶

Clip the drawing region of the paint object.

This function restricts the drawing area of the paint object to the specified shape’s paths.

Parameters:¶

clipper : Paint¶: The shape object as the clipper.

Returns:¶

INVALID_ARGUMENT In case a nullptr is passed as the argument.
NOT_SUPPORTED If the clipper type is not Shape.

Return type:¶

Result

Note

Experimental API

set_composite_method(target: Paint, method: CompositeMethod) → Result¶

Sets the composition target object and the composition method.

Parameters:¶

target : Paint¶: The target object of the composition.
method : CompositeMethod¶: The method used to composite the source object with the target.

Returns:¶

INVALID_ARGUMENT An invalid paint or target object or the method equal to NONE.

Return type:¶

Result

set_opacity(opacity: int) → Result¶

Sets the opacity of the given PaintStruct.

Parameters:¶

opacity : int¶: The opacity value in the range [0 ~ 255], where 0 is completely transparent and 255 is opaque.

Returns:¶

INVALID_ARGUMENT An invalid PaintStruct pointer.

Return type:¶

Result

Note

Setting the opacity with this API may require multiple renderings using a composition. It is recommended to avoid changing the opacity if possible.

set_transform(m: Matrix) → Result¶

Transforms the given PaintStruct using the augmented transformation matrix.

The augmented matrix of the transformation is expected to be given.

Parameters:¶

m : Matrix¶: The 3x3 augmented matrix.

Returns:¶

INVALID_ARGUMENT A nullptr is passed as the argument.

Return type:¶

Result

translate(x: float, y: float) → Result¶

Moves the given PaintStruct in a two-dimensional space.

The origin of the coordinate system is in the upper-left corner of the canvas. The horizontal and vertical axes point to the right and down, respectively.

Parameters:¶

x : float¶: The value of the horizontal shift.
y : float¶: The value of the vertical shift.

Returns:¶

INVALID_ARGUMENT An invalid PaintStruct pointer.
INSUFFICIENT_CONDITION in case a custom transform is applied.

Return type:¶

Result

See also

Paint.set_transform()