thorvg_python.canvas¶

Submodules¶

Classes¶

`CanvasPointer`	A structure responsible for managing and drawing graphical elements.
`PaintPointer`	A structure representing a graphical element.
`Result`	Enumeration specifying the result from the APIs.
`Engine`	Engine API
`Paint`	Paint API
`Canvas`	Common Canvas API

Package Contents¶

class thorvg_python.canvas.CanvasPointer¶

Bases: ctypes.c_void_p

A structure responsible for managing and drawing graphical elements.

It sets up the target buffer, which can be drawn on the screen. It stores the PaintPointer objects (Shape, Scene, Picture).

Note

You should use Canvas class instead.

class thorvg_python.canvas.PaintPointer¶

Bases: ctypes.c_void_p

A structure representing a graphical element.

Warning

The PaintPointer objects cannot be shared between Canvases.

Note

You should use Paint class instead.

class thorvg_python.canvas.Result¶

Bases: enum.IntEnum

Enumeration specifying the result from the APIs.

All ThorVG APIs could potentially return one of the values in the list. Please note that some APIs may additionally specify the reasons that trigger their return values.

SUCCESS = 0¶

INVALID_ARGUMENT = 1¶

INSUFFICIENT_CONDITION = 2¶

FAILED_ALLOCATION = 3¶

MEMORY_CORRUPTION = 4¶

NOT_SUPPORTED = 5¶

UNKNOWN = 255¶

classmethod from_param(obj: int) → int¶

class thorvg_python.canvas.Engine(thorvg_lib_path: str | None = None, threads: int = 0)¶

Engine API

A module enabling initialization and termination of the TVG engines.

threads = 0¶

init_result¶

_load_lib(thorvg_lib_path: str | None = None) → None¶

__del__() → None¶

__enter__() → Engine¶

__exit__(exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: types.TracebackType | None) → None¶

init(threads: int) → thorvg_python.base.Result¶

Initializes TVG engines.

ThorVG requires an active runtime environment to operate. Internally, it utilizes a task scheduler to efficiently parallelize rendering operations. You can specify the number of worker threads using the threads parameter. During initialization, ThorVG will spawn the specified number of threads.

Parameters:¶

threads : int¶: The number of additional threads used to perform rendering. Zero indicates only the main thread is to be used.

Return type:¶

thorvg_python.base.Result

Note

The initializer uses internal reference counting to track multiple calls. The number of threads is fixed on the first call to Engine.init() and cannot be changed in subsequent calls.

See also

Engine.term()

term() → thorvg_python.base.Result¶

Terminates TVG engines.

Cleans up resources and stops any internal threads initialized by Engine.init().

Returns:¶: Result.INSUFFICIENT_CONDITION Returned if there is nothing to terminate (e.g., Engine.init() was not called).
Return type:¶: thorvg_python.base.Result

See also

Engine.init()

version() → tuple[thorvg_python.base.Result, int, int, int, str | None]¶

Retrieves the version of the TVG engine.

Returns:¶: Result.SUCCESS
Return type:¶: thorvg_python.base.Result
Returns:¶: A major version number.
Return type:¶: int
Returns:¶: A minor version number.
Return type:¶: int
Returns:¶: A micro version number.
Return type:¶: int
Returns:¶: The version of the engine in the format major.minor.micro, or a None in case of an internal error.
Return type:¶: Optional[str]

Added in version 0.15.

class thorvg_python.canvas.Paint(engine: thorvg_python.engine.Engine, paint: thorvg_python.base.PaintPointer)¶

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.

engine¶

thorvg_lib¶

_paint¶

_rel() → thorvg_python.base.Result¶

Safely releases a Tv_Paint object.

This is the counterpart to the new() API, and releases the given Paint object safely, handling None and managing ownership properly.

ref() → int¶

Increment the reference count for the PaintPointer object.

This method increases the reference count of PaintPointer object, allowing shared ownership and control over its lifetime.

Returns:¶: The updated reference count after the increment by 1.
Return type:¶: int

Warning

Please ensure that each call to Paint.ref() is paired with a corresponding call to Paint.unref() to prevent a dangling instance.

See also

Paint.unref()

See also

Paint.get_ref()

Added in version 1.0.

unref(free: bool) → int¶

Decrement the reference count for the PaintPointer object.

This method decreases the reference count of the PaintPointer object by 1. If the reference count reaches zero and the free flag is set to true, the instance is automatically deleted.

Parameters:¶

free : bool¶: Flag indicating whether to delete the Paint instance when the reference count reaches zero.

Returns:¶

The updated reference count after the decrement.

Return type:¶

int

See also

Paint.ref()

See also

Paint.get_ref()

Added in version 1.0.

get_ref() → int¶

Retrieve the current reference count of the PaintPointer object.

This method provides the current reference count, allowing the user to check the shared ownership state of the PaintPointer object.

Returns:¶: The current reference count of the PaintPointer object.
Return type:¶: int

See also

Paint.ref()

See also

Paint.unref()

Added in version 1.0.

set_visible(visible: bool) → thorvg_python.base.Result¶

Sets the visibility of the Paint object.

This is useful for selectively excluding paint objects during rendering.

Parameters:¶

visible : bool¶: A boolean flag indicating visibility. The default is true. - true: the object will be rendered by the engine. - false: the object will be excluded from the drawing process.

Note

An invisible object is not considered inactive—it may still participate in internal update processing if its properties are updated, but it will not be taken into account for the final drawing output. To completely deactivate a paint object, remove it from the canvas.

See also

Paint.get_visible()

See also

Canvas.remove()

Added in version 1.0.

get_visible() → thorvg_python.base.Result¶

Gets the current visibility status of the Paint object..

Returns:¶: True if the object is visible and will be rendered. False if the object is hidden and will not be rendered.
Return type:¶: bool

See also

Paint.set_visible()

Added in version 1.0.

get_id() → int¶

Gets the ID of the Paint object.

Returns:¶: The ID of the paint object, or 0 if the ID is not set.
Return type:¶: int

See also

Picture.get_paint()

See also

Accessor.generate_id()

See also

Paint.set_id()

Note

Experimental API

set_id(_id: int) → thorvg_python.base.Result¶

Sets the ID of the Paint object.

Parameters:¶

_id : int¶: The ID to assign to the paint object.

See also

Picture.get_paint()

See also

Accessor.generate_id()

See also

Paint.get_id()

Note

Experimental API

scale(factor: float) → thorvg_python.base.Result¶

Scales the given PaintPointer object by the given factor.

Parameters:¶

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

Returns:¶

Result.INVALID_ARGUMENT An invalid PaintPointer.
Result.INSUFFICIENT_CONDITION in case a custom transform is applied.

Return type:¶

thorvg_python.base.Result

See also

Paint.set_transform()

rotate(degree: float) → thorvg_python.base.Result¶

Rotates the given PaintPointer 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:¶

Result.INVALID_ARGUMENT An invalid PaintPointer.
Result.INSUFFICIENT_CONDITION in case a custom transform is applied.

Return type:¶

thorvg_python.base.Result

See also

Paint.set_transform()

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

Moves the given PaintPointer 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:¶

Result.INVALID_ARGUMENT An invalid PaintPointer.
Result.INSUFFICIENT_CONDITION in case a custom transform is applied.

Return type:¶

thorvg_python.base.Result

See also

Paint.set_transform()

set_transform(m: thorvg_python.base.Matrix) → thorvg_python.base.Result¶

Transforms the given PaintPointer using the augmented transformation matrix.

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

Parameters:¶

m : thorvg_python.base.Matrix¶: The 3x3 augmented matrix.

Returns:¶

Result.INVALID_ARGUMENT A None is passed as the argument.

Return type:¶

thorvg_python.base.Result

get_transform() → tuple[thorvg_python.base.Result, thorvg_python.base.Matrix]¶

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

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

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

set_opacity(opacity: int) → thorvg_python.base.Result¶

Sets the opacity of the given PaintPointer.

Parameters:¶

opacity : int¶: The opacity 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

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

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

Gets the opacity of the given PaintPointer.

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

duplicate() → thorvg_python.base.PaintPointer | None¶

Duplicates the given PaintPointer object.

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

Returns:¶: A copied PaintPointer object if succeed, None otherwise.
Return type:¶: Optional[thorvg_python.base.PaintPointer]

intersects(x: int, y: int, w: int, h: int) → bool¶

Checks whether a given region intersects the filled area of the paint.

This function determines whether the specified rectangular region—defined by (x, y, w, h)— intersects the geometric fill region of the paint object.

This is useful for hit-testing purposes, such as detecting whether a user interaction (e.g., touch or click) occurs within a painted region.

The paint must be updated in a Canvas beforehand—typically after the Canvas has been drawn and synchronized.

Parameters:¶

x : int¶: The x-coordinate of the top-left corner of the test region.
y : int¶: The y-coordinate of the top-left corner of the test region.
w : int¶: The width of the region to test. Must be greater than 0; defaults to 1.
h : int¶: The height of the region to test. Must be greater than 0; defaults to 1.

Returns:¶

true if any part of the region intersects the filled area; otherwise, false.

Note

To test a single point, set the region size to w = 1, h = 1.

Note

For efficiency, an AABB (axis-aligned bounding box) test is performed internally before precise hit detection.

Note

This test does not take into account the results of blending or masking.

Note

This test does take into account the the hidden paints as well. See Paint.set_visible().

Added in version 1.0.

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

Retrieves the axis-aligned bounding box (AABB) of the paint object in canvas space.

Returns the bounding box of the paint as an axis-aligned bounding box (AABB), with all relevant transformations applied. The returned values x, y, w, h, may have invalid if the operation fails. Thus, please check the retval.

This bounding box can be used to determine the actual rendered area of the object on the canvas, for purposes such as hit-testing, culling, or layout calculations.

Returns:¶

Result.INVALID_ARGUMENT An invalid paint.
Result.INSUFFICIENT_CONDITION If it failed to compute the bounding box (mostly due to invalid path information).

Return type:¶

thorvg_python.base.Result

Returns:¶

The x-coordinate of the upper-left corner of the bounding box.

Return type:¶

float

Returns:¶

The y-coordinate of the upper-left corner of the bounding box.

Return type:¶

float

Returns:¶

The width of the bounding box.

Return type:¶

float

Returns:¶

The height of the bounding box.

Return type:¶

float

See also

Paint.get_obb()

See also

Canvas.update()

get_obb() → tuple[thorvg_python.base.Result, thorvg_python.base.PointStruct]¶

Retrieves the object-oriented bounding box (OBB) of the paint object in canvas space.

This function returns the bounding box of the paint, as an oriented bounding box (OBB) after transformations are applied. The returned values pt4 may have invalid if the operation fails. Thus, please check the retval.

This bounding box can be used to obtain the transformed bounding region in canvas space by taking the geometry’s axis-aligned bounding box (AABB) in the object’s local coordinate space and applying the object’s transformations.

Returns:¶

Result.INVALID_ARGUMENT paint or pt4 is invalid.
Result.INSUFFICIENT_CONDITION If it failed to compute the bounding box (mostly due to invalid path information).

Return type:¶

thorvg_python.base.Result

Returns:¶

An array of four points representing the bounding box. The array size must be 4.

Return type:¶

thorvg_python.base.PointStruct

See also

Paint.get_aabb()

See also

Canvas.update()

Added in version 1.0.

set_mask_method(target: Paint, method: thorvg_python.base.MaskMethod) → thorvg_python.base.Result¶

Sets the masking target object and the masking method.

Parameters:¶

target : thorvg_python.paint.Paint¶: The target object of the masking.
method : thorvg_python.base.MaskMethod¶: The method used to mask the source object with the target.

Returns:¶

Result.INSUFFICIENT_CONDITION if the target has already belonged to another paint.

Return type:¶

thorvg_python.base.Result

get_mask_method(target: Paint) → tuple[thorvg_python.base.Result, thorvg_python.base.MaskMethod]¶

Gets the masking target object and the masking method.

Returns:¶: Result.INVALID_ARGUMENT A None is passed as the argument.
Return type:¶: thorvg_python.base.Result
Returns:¶: The method used to mask the source object with the target.
Return type:¶: thorvg_python.base.MaskMethod

set_clip(clipper: Paint) → thorvg_python.base.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 : thorvg_python.paint.Paint¶: The shape object as the clipper.

Returns:¶

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

Return type:¶

thorvg_python.base.Result

get_clip() → Paint | None¶

Get the clipper shape of the paint object.

This function returns the clipper that has been previously set to this paint object.

Returns:¶: The shape object used as the clipper, or None if no clipper is set.
Return type:¶: Optional[Paint]

See also

Paint.set_clip()

Added in version 1.0.

get_parent() → Paint | None¶

Retrieves the parent paint object.

This function returns a pointer to the parent object if the current paint belongs to one. Otherwise, it returns None.

Returns:¶: The parent object if available, otherwise None.
Return type:¶: Optional[Paint]

See also

Scene.add()

See also

Canvas.add()

Added in version 1.0.

get_type() → tuple[thorvg_python.base.Result, thorvg_python.base.TvgType]¶

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

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

set_blend_method(method: thorvg_python.base.BlendMethod) → thorvg_python.base.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 : thorvg_python.base.BlendMethod¶: The blending method to be set.

Returns:¶

Result.INVALID_ARGUMENT In case a None is passed as the argument.

Return type:¶

thorvg_python.base.Result

Added in version 0.15.

class thorvg_python.canvas.Canvas(engine: thorvg_python.engine.Engine, canvas: thorvg_python.base.CanvasPointer)¶

Common Canvas API

A module for managing and drawing graphical elements.

A canvas is an entity responsible for drawing the target. It sets up the drawing engine and the buffer, which can be drawn on the screen. It also manages given Paint objects.

Note

A Canvas behavior depends on the raster engine though the final content of the buffer is expected to be identical.

Warning

The Paint objects belonging to one Canvas can’t be shared among multiple Canvases.

This is base Canvas class. Please instantiate SwCanvas, GlCanvas or WgCanvas instead

engine¶

thorvg_lib¶

_canvas¶

destroy() → thorvg_python.base.Result¶

Clears the canvas internal data, releases all paints stored by the canvas and destroys the canvas object itself.

Return type:¶: thorvg_python.base.Result

add(paint: thorvg_python.paint.Paint) → thorvg_python.base.Result¶

Adds a paint object to the canvas for rendering.

Adds the specified paint into the canvas root scene. Only paints added to the canvas are considered rendering targets. The canvas retains the paint object until it is explicitly removed via Canvas.remove().

Parameters:¶

paint : thorvg_python.paint.Paint¶: A handle to the paint object to be rendered.

Returns:¶

TVG_RESULT_INSUFFICIENT_CONDITION If the canvas is not in a valid state to accept new paints.

Return type:¶

thorvg_python.base.Result

..note:: Ownership of the paint object is transferred to the canvas upon: successful addition. To retain ownership, call Paint.ref() before adding it to the canvas.
..note:: The rendering order of paint objects follows the order in which they are: added to the canvas. If layering is required, ensure paints are added in the desired order.

See also

Canvas.insert()

See also

Canvas.remove()

insert(target: thorvg_python.paint.Paint, at: thorvg_python.paint.Paint | None) → thorvg_python.base.Result¶

Inserts a paint object into the canvas root scene.

Inserts a paint object into the root scene of the specified canvas. If the at parameter is provided, the paint object is inserted immediately before the specified paint in the root scene. If at is None, the paint object is appended to the end of the root scene.

Parameters:¶

target : thorvg_python.paint.Paint¶: A handle to the paint object to be inserted into the root scene. This parameter must not be None.
at : Optional[Paint]¶: A handle to an existing paint object in the root scene before which target will be inserted. If None, target is appended to the end of the root scene.

Returns:¶

TVG_RESULT_INSUFFICIENT_CONDITION If the canvas is not in a valid state to accept new paints.

Return type:¶

thorvg_python.base.Result

..note:: Ownership of the paint object is transferred to the canvas upon: successful addition. To retain ownership, call Paint.ref() before adding it to the canvas.
..note:: The rendering order of paint objects follows the order in which they are: added to the canvas. If layering is required, ensure paints are added in the desired order.

See also

Canvas.insert()

See also

Canvas.remove()

remove(paint: thorvg_python.paint.Paint | None = None) → thorvg_python.base.Result¶

Removes a paint object from the root scene.

This function removes a specified paint object from the root scene. If no paint object is specified (i.e., the default None is used), the function performs to clear all paints from the scene.

Parameters:¶

paint : Optional[thorvg_python.paint.Paint]¶: Paint object to be removed from the root scene. If None, remove all the paints from the root scene.

Returns:¶

Result.INVALID_ARGUMENT An invalid CanvasPointer.

Return type:¶

thorvg_python.base.Result

See also

Canvas.add()

See also

Canvas.insert()

Added in version 1.0.

update() → thorvg_python.base.Result¶

Requests the canvas to update modified paint objects in preparation for rendering.

This function triggers an internal update for all paint instances that have been modified since the last update. It ensures that the canvas state is ready for accurate rendering.

Returns:¶

TVG_RESULT_INVALID_ARGUMENT An invalid CanvasPointer.
TVG_RESULT_INSUFFICIENT_CONDITION The canvas is not properly prepared. This may occur if the canvas target has not been set or if the update is called during drawing. Call Canvas.sync() before trying.

Return type:¶

thorvg_python.base.Result

Note

Only paint objects that have been changed will be processed.

Note

If the canvas is configured with multiple threads, the update may be performed asynchronously.

See also

Canvas.sync()

draw(clear: bool) → thorvg_python.base.Result¶

Requests the canvas to render the Paint objects.

Parameters:¶

clear: bool¶: If true, clears the target buffer to zero before drawing.

Returns:¶

TVG_RESULT_INVALID_ARGUMENT An invalid CanvasPointer.
TVG_RESULT_INSUFFICIENT_CONDITION The canvas is not properly prepared. This may occur if the canvas target has not been set or if the update is called during drawing. without calling Canvas.sync() in between.

Return type:¶

thorvg_python.base.Result

Note

Clearing the buffer is unnecessary if the canvas will be fully covered with opaque content. Skipping the clear can improve performance.

Note

Drawing may be performed asynchronously if the thread count is greater than zero. To ensure the drawing process is complete, call sync() afterwards.

Note

If the canvas has not been updated prior to Canvas.draw(), it may implicitly perform Canvas.update()

See also

Canvas.sync()

See also

Canvas.update()

sync() → thorvg_python.base.Result¶

Guarantees that drawing task is finished.

The Canvas rendering can be performed asynchronously. To make sure that rendering is finished, the Canvas.sync() must be called after the Canvas.draw() regardless of threading.

Returns:¶: TVG_RESULT_INVALID_ARGUMENT An invalid CanvasPointer.
Return type:¶: thorvg_python.base.Result

See also

Canvas.draw()

set_viewport(x: int, y: int, w: int, h: int) → thorvg_python.base.Result¶

Sets the drawing region of the canvas.

This function defines a rectangular area of the canvas to be used for drawing operations. The specified viewport clips rendering output to the boundaries of that rectangle.

Please note that changing the viewport is only allowed at the beginning of the rendering sequence—that is, after calling Canvas.sync().

Parameters:¶

x: int¶: The x-coordinate of the upper-left corner of the rectangle.
y: int¶: The y-coordinate of the upper-left corner of the rectangle.
w: int¶: The width of the rectangle.
h: int¶: The height of the rectangle.

Returns:¶

Result.INVALID_ARGUMENT An invalid CanvasPointer.
Result.INSUFFICIENT_CONDITION If the canvas is not in a synced state.

Return type:¶

thorvg_python.base.Result

See also

Canvas.sync()

See also

SwCanvas.set_target()

See also

GlCanvas.set_target()

See also

WgCanvas.set_target()

Warning

Changing the viewport is not allowed after calling Canvas.add(), Canvas.remove(), Canvas.update(), or Canvas.draw().

Note

When the target is reset, the viewport will also be reset to match the target size.

Added in version 0.15.