thorvg_python¶

Note

For efficiency, ThorVG ignores updates to the new frame value if the difference from the current frame value is less than 0.001. In such cases, it returns Result.InsufficientCondition. Values less than 0.001 may be disregarded and may not be accurately retained by the Animation.

See also

Animation.get_total_frame()

Added in version 0.13.

get_picture() → thorvg_python.paint.picture.Picture¶

Retrieves a picture instance associated with this animation instance.

This function provides access to the picture instance that can be used to load animation formats, such as Lottie(json). After setting up the picture, it can be pushed to the designated canvas, enabling control over animation frames with this Animation instance.

Returns:¶: A picture instance that is tied to this animation.
Return type:¶: Picture

Warning

The picture instance is owned by Animation. It should not be deleted manually.

Added in version 0.13.

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

Retrieves the current frame number of the animation.

Returns:¶: Result.INVALID_ARGUMENT An invalid AnimationPointer or no
Return type:¶: thorvg_python.base.Result
Returns:¶: The current frame number of the animation, between 0 and totalFrame() - 1.
Return type:¶: float

See also

Animation.get_total_frame()

See also

Animation.set_frame()

Added in version 0.13.

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

Retrieves the total number of frames in the animation.

Returns:¶: Result.INVALID_ARGUMENT An invalid AnimationPointer or cnt.
Return type:¶: thorvg_python.base.Result
Returns:¶: The total number of frames in the animation.
Return type:¶: float

Note

Frame numbering starts from 0.

Note

If the Picture is not properly configured, this function will return 0.

Added in version 0.13.

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

Retrieves the duration of the animation in seconds.

Returns:¶: Result.INVALID_ARGUMENT An invalid AnimationPointer or duration.
Return type:¶: thorvg_python.base.Result
Returns:¶: The duration of the animation in seconds.
Return type:¶: float

Note

If the Picture is not properly configured, this function will return 0.

Added in version 0.13.

set_segment(begin: float, end: float) → thorvg_python.base.Result¶

Specifies the playback segment of the animation.

The set segment is designated as the play area of the animation. This is useful for playing a specific segment within the entire animation. After setting, the number of animation frames and the playback time are calculated by mapping the playback segment as the entire range.

Parameters:¶

begin: float¶: segment begin frame.
end: float¶: segment end frame.

Returns:¶

Result.INSUFFICIENT_CONDITION In case the animation is not loaded.
Result.INVALID_ARGUMENT If the begin is higher than end.

Note

Animation allows a range from 0.0 to the total frame. end should not be higher than begin.

Note

If a marker has been specified, its range will be disregarded.

See also

Animation.set_marker()

See also

Animation.get_total_frame()

Added in version 1.0.

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

Gets the current segment.

Returns:¶

Result.INSUFFICIENT_CONDITION In case the animation is not loaded.
Result.INVALID_ARGUMENT An invalid AnimationPointer.

Return type:¶

Returns:¶

segment begin frame.

Return type:¶

float

Returns:¶

segment end frame.

Return type:¶

float

Added in version 1.0.

_del() → thorvg_python.base.Result¶

Deletes the given AnimationPointer object.

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

Added in version 0.13.

class thorvg_python.LottieAnimation(engine: thorvg_python.engine.Engine, animation: thorvg_python.base.AnimationPointer | None = None)¶

Bases: thorvg_python.animation.Animation

LottieAnimation Extension API

A module for manipulation of the scene tree

This module helps to control the scene tree.

engine¶

thorvg_lib¶

new() → thorvg_python.base.AnimationPointer¶

Creates a new LottieAnimation object.

Returns:¶: AnimationPointer A new Lottie AnimationPointer object.
Return type:¶: thorvg_python.base.AnimationPointer

Added in version 0.15.

gen_slot(slot: str) → int¶

Generates a new slot from the given slot data.

Parameters:¶

slot : str¶: The Lottie slot data in JSON format.

Returns:¶

The generated slot ID when successful, 0 otherwise.

Return type:¶

int

Added in version 1.0.

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

Applies a previously generated slot to the animation.

Parameters:¶

_id : int¶: The ID of the slot to apply, or 0 to reset all slots.

Returns:¶

Result.INSUFFICIENT_CONDITION In case the animation is not loaded.
Result.INVALID_ARGUMENT When the given _id is invalid
Result.NOT_SUPPORTED The Lottie Animation is not supported.

Return type:¶

Added in version 1.0.

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

Deletes a previously generated slot.

Parameters:¶

_id: int¶: The ID of the slot to delete.

Returns:¶

Result.INSUFFICIENT_CONDITION In case the animation is not loaded or the slot ID is invalid.
Result.NOT_SUPPORTED The Lottie Animation is not supported.

Return type:¶

Note

This function should be paired with gen.

See also

LottieAnimation.gen_slot()

Added in version 1.0.

set_marker(marker: str) → thorvg_python.base.Result¶

Specifies a segment by marker.

Parameters:¶

marker : str¶: The name of the segment marker.

Returns:¶

Result.INSUFFICIENT_CONDITION In case the animation is not loaded.
Result.INVALID_ARGUMENT When the given marker is invalid.
Result.NOT_SUPPORTED The Lottie Animation is not supported.

Return type:¶

Note

Experimental API

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

Gets the marker count of the animation.

Returns:¶: Result.INVALID_ARGUMENT In case a None is passed as the argument.
Return type:¶: thorvg_python.base.Result
Returns:¶: The count value of the markers.
Return type:¶: int

Note

Experimental API

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

Gets the marker name by a given index.

Parameters:¶

idx : int¶: The index of the animation marker, starts from 0.

Returns:¶

Result.INVALID_ARGUMENT In case None is passed as the argument or idx is out of range.

Rtyle:¶

Result

Returns:¶

The name of marker when succeed.

Return type:¶

Optional[str]

Note

Experimental API

tween(_from: float, to: float, progress: float) → thorvg_python.base.Result¶

Interpolates between two frames over a specified duration.

This method performs tweening, a process of generating intermediate frame between _from and to based on the given progress.

Parameters:¶

_from: float¶: The start frame number of the interpolation.
to: float¶: The end frame number of the interpolation.
progress: float¶: The current progress of the interpolation (range: 0.0 to 1.0).

Returns:¶

TVG_RESULT_INSUFFICIENT_CONDITION In case the animation is not loaded.

Return type:¶

Added in version 1.0.

assign(layer: str, ix: int, var: str, val: float) → thorvg_python.base.Result¶

Updates the value of an expression variable for a specific layer.

Parameters:¶

layer : str¶: The name of the layer containing the variable to be updated.
ix : int¶: The property index of the variable within the layer.
var : str¶: The name of the variable to be updated.
val : float¶: The new value to assign to the variable.

Returns:¶

Result.INSUFFICIENT_CONDITION If the animation is not loaded.
Result.INVALID_ARGUMENT When the given parameter is invalid.
Result.NOT_SUPPORTED When neither the layer nor the property is found in the current animation.

Return type:¶

Note

Experimental API

set_quality(value: int) → thorvg_python.base.Result¶

Sets the quality level for Lottie effects.

This function controls the rendering quality of effects like blur, shadows, etc. Lower values prioritize performance while higher values prioritize quality.

Parameters:¶

value : int¶: The quality level (0-100). 0 represents lowest quality/best performance, 100 represents highest quality/lowest performance, default is 50.

Returns:¶

Result.INSUFFICIENT_CONDITION If the animation is not loaded.
Result.INVALID_ARGUMENT An invalid AnimationPointer.

Return type:¶

Note

This option is used as a hint; its behavior heavily depends on the render backend.

Added in version 1.0.

class thorvg_python.BlendMethod¶

Bases: enum.IntEnum

Enumeration indicates the method used for blending paint. Please refer to the respective formulas for each method.

NORMAL = 0¶

MULTIPLY = 1¶

SCREEN = 2¶

OVERLAY = 3¶

DARKEN = 4¶

LIGHTEN = 5¶

COLORDODGE = 6¶

COLORBURN = 7¶

HARDLIGHT = 8¶

SOFTLIGHT = 9¶

DIFFERENCE = 10¶

EXCLUSION = 11¶

HUE = 12¶

SATURATION = 13¶

COLOR = 14¶

LUMINOSITY = 15¶

ADD = 16¶

COMPOSITION = 255¶

classmethod from_param(obj: int) → int¶

class thorvg_python.Colorspace¶

Bases: enum.IntEnum

Enumeration specifying the methods of combining the 8-bit color channels into 32-bit color.

Changed in version 0.13: Added ABGR8888S and ARGB8888S

Changed in version 1.0: Added UNKNOWN

ABGR8888 = 0¶

ARGB8888 = 1¶

ABGR8888S = 2¶

ARGB8888S = 3¶

UNKNOWN = 255¶

classmethod from_param(obj: int) → int¶

class thorvg_python.ColorStop¶

Bases: ctypes.Structure

A data structure storing the information about the color and its relative position inside the gradient bounds.

_fields_¶

class thorvg_python.EngineOption¶

Bases: enum.IntEnum

Enumeration to specify rendering engine behavior.

Note

The availability or behavior of EngineMethod.SMART_RENDER may vary depending on platform or backend support. It attempts to optimize rendering performance by updating only the regions of the canvas that have changed between frames (partial redraw). This can be highly effective in scenarios where most of the canvas remains static and only small portions are updated—such as simple animations or GUI interactions. However, in complex scenes where a large portion of the canvas changes frequently (e.g., full-screen animations or heavy object movements), the overhead of tracking changes and managing update regions may outweigh the benefits, resulting in decreased performance compared to the default rendering mode. Thus, it is recommended to benchmark both modes in your specific use case to determine the optimal setting.

Added in version 1.0.

NONE = 0¶

DEFAULT = 1¶

SMART_RENDER = 2¶

class thorvg_python.FillRule¶

Bases: enum.IntEnum

Enumeration specifying the algorithm used to establish which parts of the shape are treated as the inside of the shape.

NON_ZERO = 0¶

EVEN_ODD = 1¶

classmethod from_param(obj: int) → int¶

class thorvg_python.MaskMethod¶

Bases: enum.IntEnum

Enumeration indicating the method used in the masking of two objects - the target and the source.

NONE = 0¶

ALPHA = 1¶

INVERSE_ALPHA = 2¶

LUMA = 3¶

INVERSE_LUMA = 4¶

ADD = 5¶

SUBTRACT = 6¶

INTERSECT = 7¶

DIFFERENCE = 8¶

LIGHTEN = 9¶

DARKEN = 10¶

classmethod from_param(obj: int) → int¶

class thorvg_python.Matrix¶

Bases: ctypes.Structure

A data structure representing a three-dimensional matrix.

The elements e11, e12, e21 and e22 represent the rotation matrix, including the scaling factor.

The elements e13 and e23 determine the translation of the object along the x and y-axis, respectively.

The elements e31 and e32 are set to 0, e33 is set to 1.

_fields_¶

class thorvg_python.PathCommand¶

Bases: enum.IntEnum

Enumeration specifying the values of the path commands accepted by ThorVG.

CLOSE = 0¶

MOVE_TO = 1¶

LINE_TO = 2¶

CUBIC_TO = 3¶

classmethod from_param(obj: int) → int¶

thorvg_python.PictureAssetResolverType¶

class thorvg_python.PointStruct¶

Bases: ctypes.Structure

A data structure representing a point in two-dimensional space.

_fields_¶

class thorvg_python.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.StrokeCap¶

Bases: enum.IntEnum

Enumeration determining the ending type of a stroke in the open sub-paths.

BUTT = 0¶

ROUND = 1¶

SQUARE = 2¶

classmethod from_param(obj: int) → int¶

class thorvg_python.StrokeFill¶

Bases: enum.IntEnum

Enumeration specifying how to fill the area outside the gradient bounds.

PAD = 0¶

REFLECT = 1¶

REPEAT = 2¶

classmethod from_param(obj: int) → int¶

class thorvg_python.StrokeJoin¶

Bases: enum.IntEnum

Enumeration specifying how to fill the area outside the gradient bounds.

MITER = 0¶

ROUND = 1¶

BEVEL = 2¶

classmethod from_param(obj: int) → int¶

class thorvg_python.TextMetrics¶

Bases: ctypes.Structure

Describes the font metrics of a text object.

Provides the basic vertical layout metrics used for text rendering, such as ascent, descent, and line spacing (linegap).

See also

Text.get_metrics()

Note

Experimental API

_fields_¶

ascent : float¶

descent : float¶

linegap : float¶

advance : float¶

class thorvg_python.TextWrap¶

Bases: enum.IntEnum

A data structure storing the information about the color and its relative position inside the gradient bounds.

NONE = 0¶

CHARACTER = 1¶

WORD = 2¶

SMART = 3¶

ELLIPSIS = 4¶

HYPHENATION = 5¶

classmethod from_param(obj: int) → int¶

class thorvg_python.TvgType¶

Bases: enum.IntEnum

Enumeration indicating the ThorVG object type value.

ThorVG’s drawing objects can return object type values, allowing you to identify the specific type of each object.

UNDEF = 0¶

SHAPE = 1¶

SCENE = 2¶

PICTURE = 3¶

TEXT = 4¶

LINEAR_GRAD = 10¶

RADIAL_GRAD = 11¶

classmethod from_param(obj: int) → int¶

class thorvg_python.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:¶

..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:¶

..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:¶

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:¶

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:¶

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.CanvasPointer

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.

class thorvg_python.SwCanvas(engine: thorvg_python.engine.Engine, op: thorvg_python.base.EngineOption = EngineOption.DEFAULT, canvas: thorvg_python.base.CanvasPointer | None = None)¶

Bases: thorvg_python.canvas.Canvas

SwCanvas API

A module for rendering the graphical elements using the software engine.

engine¶

thorvg_lib¶

buffer_arr : ctypes.Array[ctypes.c_uint32] | None = None¶

w : int | None = None¶

h : int | None = None¶

stride : int | None = None¶

cs : thorvg_python.base.Colorspace | None = None¶

_create(op: thorvg_python.base.EngineOption = EngineOption.DEFAULT) → thorvg_python.base.CanvasPointer¶

Creates a new Software Canvas object with optional rendering engine settings.

This method generates a software canvas instance that can be used for drawing vector graphics. It accepts an optional parameter op to choose between different rendering engine behaviors.

Parameters:¶

op : thorvg_python.engine.EngineOption¶: The rendering engine option.

Returns:¶

A new CanvasPointer object.

Return type:¶

Note

You need not call this method as it is auto called when initializing SwCanvas().

See also

EngineOption

set_target(w: int, h: int, stride: int | None = None, cs: thorvg_python.base.Colorspace = Colorspace.ABGR8888) → tuple[thorvg_python.base.Result, ctypes.Array[ctypes.c_uint32]]¶

Sets the buffer used in the rasterization process and defines the used colorspace.

For optimisation reasons TVG does not allocate memory for the output buffer on its own. The buffer of a desirable size should be allocated and owned by the caller.

w, h, stride, cs and buffer_arr will be stored in instance when calling this method.

Parameters:¶

w : int¶: The width of the raster image.
h : int¶: The height of the raster image.
stride : Optional[int]¶: The stride of the raster image - default is same value as w.
cs : thorvg.base.Colorspace¶: The colorspace value defining the way the 32-bits colors should be read/written.

Returns:¶

Result.INVALID_ARGUMENTS An invalid canvas or buffer pointer passed or one of the stride, w or h being zero.
Result.INSUFFICIENT_CONDITION if the canvas is performing rendering. Please ensure the canvas is synced.
Result.NOT_SUPPORTED The software engine is not supported.

Return type:¶

Returns:¶

A pointer to the allocated memory block of the size stride x h.

Return type:¶

ctypes.Array[ctypes.c_uint32]

Warning

Do not access buffer during Canvas_draw() - Canvas_sync(). It should not be accessed while the engine is writing on it.

See also

Colorspace

get_pillow(pil_mode: str = 'RGBA') → PIL.Image.Image¶

Gets Pillow Image from buffer of canvas

Parameters:¶

pil_mode : str¶: Color mode of Pillow Image. Defaults to RGBA

Returns:¶

Pillow image

Return type:¶

PIL.Image.Image

class thorvg_python.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:¶

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.Gradient(engine: thorvg_python.engine.Engine, grad: thorvg_python.base.GradientPointer)¶

Common Gradient API

A module managing the gradient fill of objects.

The module enables to set and to get the gradient colors and their arrangement inside the gradient bounds, to specify the gradient bounds and the gradient behavior in case the area defined by the gradient bounds is smaller than the area to be filled.

This is base Gradient class. Please use LinearGradient or RadialGradient for creating

engine¶

thorvg_lib¶

_grad¶

set_color_stops(color_stop: collections.abc.Sequence[thorvg_python.base.ColorStop]) → thorvg_python.base.Result¶

Sets the parameters of the colors of the gradient and their position.

Parameters:¶

color_stop : Sequence[thorvg_python.base.ColorStop]¶: An array of ColorStop data structure.

Returns:¶

Result.INVALID_ARGUMENT An invalid GradientPointer.

Return type:¶

get_color_stops() → tuple[thorvg_python.base.Result, collections.abc.Sequence[thorvg_python.base.ColorStop]]¶

Gets the parameters of the colors of the gradient, their position and number

The function does not allocate any memory.

Returns:¶: Result.INVALID_ARGUMENT A None passed as the argument.
Return type:¶: thorvg_python.base.Result
Returns:¶: An array of ColorStop data structure.
Return type:¶: Sequence[ColorStop]

set_spread(spread: thorvg_python.base.StrokeFill) → thorvg_python.base.Result¶

Sets the StrokeFill value, which specifies how to fill the area outside the gradient bounds.

Parameters:¶

spread : StrokeFill¶: The FillSpread value.

Returns:¶

Result.INVALID_ARGUMENT An invalid GradientPointer.

Return type:¶

get_spread() → tuple[thorvg_python.base.Result, thorvg_python.base.StrokeFill]¶

Gets the FillSpread value of the gradient object.

Returns:¶: Result.INVALID_ARGUMENT A None passed as the argument.
Return type:¶: thorvg_python.base.Result
Returns:¶: The FillSpread value.
Return type:¶: StrokeFill

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

Sets the matrix of the affine transformation for the gradient object.

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

:param Matrix m 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 gradient object.

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

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

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

Gets the unique value of the gradient 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 gradient instance type.
Return type:¶: thorvg_python.base.TvgType

Note

Experimental API

duplicate() → Gradient | None¶

Duplicates the given GradientPointer object.

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

Returns:¶: A copied GradientPointer object if succeed, None otherwise.
Return type:¶: thorvg_python.base.GradientPointer

_del() → thorvg_python.base.Result¶

Deletes the given gradient object.

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

class thorvg_python.LinearGradient(engine: thorvg_python.engine.Engine, grad: thorvg_python.base.GradientPointer | None = None)¶

Bases: thorvg_python.gradient.Gradient

Linear Gradient API

engine¶

thorvg_lib¶

_new() → thorvg_python.base.GradientPointer¶

Creates a new linear gradient object.

Returns:¶: A new linear gradient object.
Return type:¶: thorvg_python.base.GradientPointer

Note

You need not call this method as it is auto called when initializing LinearGradient().

set(x1: float, y1: float, x2: float, y2: float) → thorvg_python.base.Result¶

Sets the linear gradient bounds.

The bounds of the linear gradient are defined as a surface constrained by two parallel lines crossing the given points (x1, y1) and (x2, y2), respectively. Both lines are perpendicular to the line linking (x1, y1) and (x2, y2).

Parameters:¶

x1 : float¶: The horizontal coordinate of the first point used to determine the gradient bounds.
y1 : float¶: The vertical coordinate of the first point used to determine the gradient bounds.
x2 : float¶: The horizontal coordinate of the second point used to determine the gradient bounds.
y2 : float¶: The vertical coordinate of the second point used to determine the gradient bounds.

Returns:¶

Result.INVALID_ARGUMENT An invalid GradientPointer.

Return type:¶

Note

In case the first and the second points are equal, an object is filled with a single color using the last color specified in the Gradient.set_color_stops().

See also

Gradient.set_color_stops()

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

Gets the linear gradient bounds.

Returns:¶: Result.INVALID_ARGUMENT An invalid GradientPointer.
Return type:¶: thorvg_python.base.Result
Returns:¶: The horizontal coordinate of the first point used to determine the gradient bounds.
Return type:¶: float
Returns:¶: The vertical coordinate of the first point used to determine the gradient bounds.
Return type:¶: float
Returns:¶: The horizontal coordinate of the second point used to determine the gradient bounds.
Return type:¶: float
Returns:¶: The vertical coordinate of the second point used to determine the gradient bounds.
Return type:¶: float

class thorvg_python.RadialGradient(engine: thorvg_python.engine.Engine, grad: thorvg_python.base.GradientPointer | None = None)¶

Bases: thorvg_python.gradient.Gradient

Radial Gradient API

engine¶

thorvg_lib¶

_new() → thorvg_python.base.GradientPointer¶

Creates a new radial gradient object.

Returns:¶: A new radial gradient object.
Return type:¶: thorvg_python.base.GradientPointer

Note

You need not call this method as it is auto called when initializing LinearGradient().

set(cx: float, cy: float, r: float, fx: float, fy: float, fr: float) → thorvg_python.base.Result¶

Sets the radial gradient attributes.

The radial gradient is defined by the end circle with a center (cx, cy) and a radius r and the start circle with a center/focal point (fx, fy) and a radius fr. The gradient will be rendered such that the gradient stop at an offset of 100% aligns with the edge of the end circle and the stop at an offset of 0% aligns with the edge of the start circle.

Parameters:¶

cx : float¶

The horizontal coordinate of the center of the end circle.

cy : float¶

The vertical coordinate of the center of the end circle.

r : float¶

The radius of the end circle.

fx : float¶

The horizontal coordinate of the center of the start circle.

fy : float¶

The vertical coordinate of the center of the start circle.

fr : float¶

The radius of the start circle.

TVG_RESULT_INVALID_ARGUMENT An invalid GradientPointer or the radius r or fr value is negative.

Note

In case the radius r is zero, an object is filled with a single color using the last color specified in the specified in the Gradient.set_color_stops().

Note

In case the focal point (fx` and ``fy) lies outside the end circle, it is projected onto the edge of the end circle.

Note

If the start circle doesn’t fully fit inside the end circle (after possible repositioning), the fr is reduced accordingly.

Note

By manipulating the position and size of the focal point, a wide range of visual effects can be achieved, such as directing the gradient focus towards a specific edge or enhancing the depth and complexity of shading patterns. If a focal effect is not desired, simply align the focal point (fx and fy) with the center of the end circle (cx and cy) and set the radius (fr) to zero. This will result in a uniform gradient without any focal variations.

See also

Gradient.set_color_stops()

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

The function gets radial gradient attributes.

Returns:¶: Result.INVALID_ARGUMENT An invalid GradientPointer.
Return type:¶: thorvg_python.base.Result
Returns:¶: The horizontal coordinate of the center of the bounding circle.
Return type:¶: float
Returns:¶: The vertical coordinate of the center of the bounding circle.
Return type:¶: float
Returns:¶: The radius of the bounding circle.
Return type:¶: float
Returns:¶: The horizontal coordinate of the center of the start circle.
Return type:¶: float
Returns:¶: The vertical coordinate of the center of the start circle.
Return type:¶: float
Returns:¶: The radius of the start circle.
Return type:¶: float

class thorvg_python.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.

deref(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(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

See also

Paint.get_visible()

See also

Canvas.remove()

Added in version 1.0.

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:¶

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:¶

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:¶

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:¶

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:¶

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:¶

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.PointStruct

Returns:¶

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

Return type:¶

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:¶

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:¶

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:¶

Added in version 0.15.

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

Picture API

A module enabling to create and to load an image in one of the supported formats: svg, png, jpg, lottie and raw.

engine¶

thorvg_lib¶

Creates a new picture object.

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

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

load(path: str) → thorvg_python.base.Result¶

Loads a picture data directly from a file.

ThorVG efficiently caches the loaded data using the specified path as a key. This means that loading the same file again will not result in duplicate operations; instead, ThorVG will reuse the previously loaded picture data.

Parameters:¶

path : str¶: The absolute path to the image file.

Returns:¶

Result.INVALID_ARGUMENT An invalid PaintPointer or an empty path.
Result.NOT_SUPPORTED A file with an unknown extension.

Return type:¶

load_raw(data: bytes, w: int, h: int, cs: thorvg_python.base.Colorspace, copy: bool) → thorvg_python.base.Result¶

Loads a picture data from a memory block of a given size.

ThorVG efficiently caches the loaded data using the specified data address as a key when the copy has false. This means that loading the same data again will not result in duplicate operations for the sharable data. Instead, ThorVG will reuse the previously loaded picture data.

Parameters:¶

data : bytes¶: A pointer to a memory location where the content of the picture raw data is stored.
w : int¶: The width of the image data in pixels.
h : int¶: The height of the image data in pixels.
cs : thorvg.base.Colorspace¶: Specifies how the 32-bit color values should be interpreted (read/write).
copy : bool¶: If true the data are copied into the engine local buffer, otherwise they are not.

Returns:¶

Result.INVALID_ARGUMENT An invalid PaintPointer or no data are provided or the w or h value is zero or less.

Return type:¶

Added in version 0.9.

load_data(data: bytes, mimetype: str, rpath: str | None, copy: bool) → thorvg_python.base.Result¶

Loads a picture data from a memory block of a given size.

Parameters:¶

data : bytes¶: A pointer to a memory location where the content of the picture file is stored. A null-terminated string is expected for non-binary data if copy is false
mimetype : str¶: Mimetype or extension of data such as “jpg”, “jpeg”, “svg”, “svg+xml”, “lottie”, “png”, etc. In case an empty string or an unknown type is provided, the loaders will be tried one by one.
rpath : Optional[str]¶: A resource directory path, if the data needs to access any external resources.
copy : bool¶: If true the data are copied into the engine local buffer, otherwise they are not.

Returns:¶

Result.INVALID_ARGUMENT In case a None is passed as the argument or the size is zero or less.
Result.NOT_SUPPORTED A file with an unknown extension.

Return type:¶

Warning

: It’s the user responsibility to release the data memory if the copy is true.

set_asset_resolver(resolver: collections.abc.Callable[[thorvg_python.base.PaintPointer, ctypes.c_char_p, ctypes.c_void_p], bool], data: bytes) → thorvg_python.base.Result¶

Sets the asset resolver callback for handling external resources (e.g., images and fonts).

This callback is invoked when an external asset reference (such as an image source or file path) is encountered in a Picture object. It allows the user to provide a custom mechanism for loading or substituting assets, such as loading from an external source or a virtual filesystem.

Parameters:¶

resolver : Callable[[thorvg_python.base.PaintPointer, ctypes.c_char_p, ctypes.c_void_p], bool]¶: A user-defined function that handles the resolution of asset paths. The function should return true if the asset was successfully resolved by the user, or false if it was not.
data : bytes¶: A pointer to user-defined data that will be passed to the callback each time it is invoked. This can be used to maintain context or access external resources.

Returns:¶

Result.INVALID_ARGUMENT A None passed as the picture argument.
Result.INSUFFICIENT_CONDITION If the picture is already loaded.

Return type:¶

Note

This function must be called before Picture.load() Setting the resolver after loading will have no effect on asset resolution for that asset.

Note

If false is returned by resolver, ThorVG will attempt to resolve the resource using its internal resolution mechanism as a fallback.

Note

To unset the resolver, pass None as the resolver parameter.

Note

Experimental API

See also

PictureAssetResolverType

set_size(w: float, h: float) → thorvg_python.base.Result¶

Resizes the picture content to the given width and height.

The picture content is resized while keeping the default size aspect ratio. The scaling factor is established for each of dimensions and the smaller value is applied to both of them.

Parameters:¶

w : float¶: A new width of the image in pixels.
h : float¶: A new height of the image in pixels.

Returns:¶

Result.INVALID_ARGUMENT An invalid PaintPointer.

Return type:¶

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

Gets the size of the loaded picture.

Returns:¶: Result.INVALID_ARGUMENT An invalid PaintPointer.
Return type:¶: thorvg_python.base.Result
Returns:¶: A width of the image in pixels.
Return type:¶: float
Returns:¶: A height of the image in pixels.
Return type:¶: float

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

Sets the normalized origin point of the Picture object.

This method defines the origin point of the Picture using normalized coordinates. Unlike a typical pivot point used only for transformations, this origin affects both the transformation behavior and the actual rendering position of the Picture.

The specified origin becomes the reference point for positioning the Picture on the canvas. For example, setting the origin to (0.5f, 0.5f) moves the visual center of the picture to the position specified by Paint.translate().

The coordinates are given in a normalized range relative to the picture’s bounds: - (0.0f, 0.0f): top-left corner - (0.5f, 0.5f): center - (1.0f, 1.0f): bottom-right corner

Parameters:¶

x: float¶: The normalized x-coordinate of the origin point (range: 0.0f to 1.0f).
y: float¶: The normalized y-coordinate of the origin point (range: 0.0f to 1.0f).

Returns:¶

Result.INVALID_ARGUMENT An invalid PaintPointer.

Return type:¶

thorvg_python.base.PaintPointer

Note

This origin directly affects how the Picture is placed on the canvas when using transformations such as translate(), rotate(), or scale().

See also

Paint.translate()

See also

Paint.rotate()

See also

Paint.scale()

See also

Paint.set_transform()

See also

Picture.get_origin()

Added in version 1.0.

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

Gets the normalized origin point of the Picture object.

This method retrieves the current origin point of the Picture, expressed in normalized coordinates relative to the picture’s bounds.

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

See also

Picture.set_origin()

Added in version 1.0.

get_paint(_id: int) → thorvg_python.paint.Paint | None¶

Retrieve a paint object from the Picture scene by its Unique ID.

This function searches for a paint object within the Picture scene that matches the provided id.

Parameters:¶

_id : int¶: The Unique ID of the paint object.

Returns:¶

A pointer to the paint object that matches the given identifier, or None if no matching paint object is found.

Return type:¶

See also

Engine.accessor_generate_id()

class thorvg_python.Scene(engine: thorvg_python.engine.Engine, scene: thorvg_python.base.PaintPointer | None = None)¶

Scene API

A module managing the multiple paints as one group paint.

As a group, scene can be transformed, translucent, maskd with other target paints, its children will be affected by the scene world.

engine¶

thorvg_lib¶

Creates a new Scene object.

This function allocates and returns a new Scene instance. To properly destroy the Scene object, use Paint.rel().

Returns:¶: A pointer to the newly created Scene object.
Return type:¶: thorvg_python.base.PaintPointer

See also

Paint.rel()

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

Adds a paint object to the scene.

Appends the specified paint object to the given scene. Only paint objects added to the scene are considered rendering targets.

Parameters:¶

paint : thorvg_python.paint.Paint¶: A handle to the paint object to be added to the scene. This parameter must not be None.

Return type:¶

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 scene.

Note

The rendering order of paint objects follows their order in the root scene. If layering is required, ensure the paints are added in the desired order.

See also

Scene.insert()

See also

Scene.remove()

Added in version 1.0.

insert(at: thorvg_python.paint.Paint) → thorvg_python.base.Result¶

Inserts a paint object into the scene.

Inserts the specified paint object into the scene immediately before the given paint object at. The at parameter must reference an existing paint object already added to the scene.

Parameters:¶

at : thorvg_python.paint.Paint¶: A handle to an existing paint object in the scene before which target will be inserted. This parameter must not be None.

Return type:¶

Note

Ownership of the target object is transferred to the scene upon successful addition. To retain ownership, call Paint.ref() before adding it to the scene.

Note

The rendering order of paint objects follows their order in the root scene. If layering is required, ensure the paints are added in the desired order.

See also

Scene.add()

See also

Scene.remove()

Added in version 1.0.

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

Removes a paint object from the scene.

This function removes a specified paint object from the 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: thorvg_python.paint.Paint | None¶: A pointer to the Paint object to be removed from the scene. If None, remove all the paints from the scene.

Return type:¶

See also

Scene.add()

Added in version 1.0.

clear_effects() → thorvg_python.base.Result¶

Clears all previously applied scene effects.

This function clears all effects that have been applied to the scene, restoring it to its original state without any post-processing.

Return type:¶: thorvg_python.base.Result

Added in version 1.0.

add_effect_gaussian_blur(sigma: float, direction: int, border: int, quality: int) → thorvg_python.base.Result¶

Adds a Gaussian blur effect to the scene.

This function adds a Gaussian blur filter to the scene as a post-processing effect. The blur can be applied in different directions with configurable border handling and quality settings.

Parameters:¶

sigma : float¶: The blur radius (sigma) value. Must be greater than 0.
direction : int¶: Blur direction: 0 = both directions, 1 = horizontal only, 2 = vertical only.
border : int¶: Border handling method: 0 = duplicate, 1 = wrap.
quality : int¶: Blur quality level [0 - 100].

Return type:¶

Added in version 1.0.

add_effect_drop_shadow(r: int, g: int, b: int, a: int, angle: float, distance: float, sigma: float, quality: int) → thorvg_python.base.Result¶

Adds a drop shadow effect to the scene.

This function adds a drop shadow with a Gaussian blur to the scene. The shadow can be customized using color, opacity, angle, distance, blur radius (sigma), and quality parameters.

:param int r Red channel value of the shadow color [0 - 255]. :param int g: Green channel value of the shadow color [0 - 255]. :param int b: Blue channel value of the shadow color [0 - 255]. :param int a Alpha (opacity) channel value of the shadow [0 - 255]. :param float angle: Shadow direction in degrees [0 - 360]. :param float distance: Distance of the shadow from the original object. :param float sigma: Gaussian blur sigma value for the shadow. Must be > 0. :param int quality: Blur quality level [0 - 100].

Return type:¶: thorvg_python.base.Result

Added in version 1.0.

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

Adds a fill color effect to the scene.

This function overrides the scene’s content colors with the specified fill color.

:param int r Red color channel value [0 - 255]. :param int g: Green color channel value [0 - 255]. :param int b: Blue color channel value [0 - 255]. :param int a Alpha (opacity) channel value [0 - 255].

Return type:¶: thorvg_python.base.Result

Added in version 1.0.

add_effect_tint(black_r: int, black_g: int, black_b: int, white_r: int, white_g: int, white_b: int, intensity: float) → thorvg_python.base.Result¶

Adds a tint effect to the scene.

This function tints the current scene using specified black and white color values, modulated by a given intensity.

Parameters:¶

black_r : int¶: Red component of the black color [0 - 255].
black_g : int¶: Green component of the black color [0 - 255].
black_b : int¶: Blue component of the black color [0 - 255].
white_r : int¶: Red component of the white color [0 - 255].
white_g : int¶: Green component of the white color [0 - 255].
white_b : int¶: Blue component of the white color [0 - 255].
intensity : float¶: Tint intensity value [0 - 100].

Added in version 1.0.

add_effect_effect_tritone(shadow_r: int, shadow_g: int, shadow_b: int, midtone_r: int, midtone_g: int, midtone_b: int, highlight_r: int, highlight_g: int, highlight_b: int, blend: int) → thorvg_python.base.Result¶

Adds a tritone color effect to the scene.

This function adds a tritone color effect to the given scene using three sets of RGB values representing shadow, midtone, and highlight colors.

Parameters:¶

shadow_r : int¶: Red component of the shadow color [0 - 255].
shadow_g : int¶: Green component of the shadow color [0 - 255].
shadow_b : int¶: Blue component of the shadow color [0 - 255].
midtone_r : int¶: Red component of the midtone color [0 - 255].
midtone_g : int¶: Green component of the midtone color [0 - 255].
midtone_b : int¶: Blue component of the midtone color [0 - 255].
highlight_r : int¶: Red component of the highlight color [0 - 255].
highlight_g : int¶: Green component of the highlight color [0 - 255].
highlight_b : int¶: Blue component of the highlight color [0 - 255].
blend : int¶: A blending factor that determines the mix between the original color and the tritone colors [0 - 255].

Added in version 1.0.

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

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¶

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:¶

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:¶

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:¶

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:¶

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:¶

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:¶

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:¶

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:¶

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:¶

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:¶

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:¶

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:¶

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:¶

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:¶

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:¶

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:¶

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:¶

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:¶

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

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

Text API

A class to represent text objects in a graphical context, allowing for rendering and manipulation of unicode text.

engine¶

thorvg_lib¶

Creates a new text object.

This function allocates and returns a new Text instance. To properly destroy the Text object, use Paint.rel()

Returns:¶: A pointer to the newly created Text object.
Return type:¶: thorvg_python.base.PaintPointer

Added in version 0.15.

Note

You need not call this method as it is auto called when initializing Text().

set_font(name: str | None = None) → thorvg_python.base.Result¶

Sets the font family for the text.

This function specifies the name of the font to be used when rendering text.

Parameters:¶

name: str | None = None¶: The name of the font. This should match a font available through the canvas backend. If set to None, ThorVG will attempt to select a fallback font available on the engine.

Returns:¶

Result.INVALID_ARGUMENT A None passed as the paint argument.
Result.INSUFFICIENT_CONDITION The specified name cannot be found.

Note

This function only sets the font family name. Use size() to define the font size.

Note

If the name is not specified, ThorVG will select an available fallback font.

See also

Text.set_size()

See also

Engine.font_load()

Added in version 1.0.

set_size(size: float) → thorvg_python.base.Result¶

Sets the font size for the text.

This function sets the font size used during text rendering. The size is specified in point units, and supports floating-point precision for smooth scaling and animation effects.

Parameters:¶

size : float¶: The font size in points. Must be greater than 0.0.

Returns:¶

Result.INVALID_ARGUMENT A None passed as the paint argument.
Result.INVALID_ARGUMENT if the size is less than or equal to 0.

Return type:¶

Note

Use this function in combination with font() to fully define text appearance.

Note

Fractional sizes (e.g., 12.5) are supported for sub-pixel rendering and animations.

See also

Text.set_font()

Added in version 1.0.

set_text(utf8: str) → thorvg_python.base.Result¶

Assigns the given unicode text to be rendered.

This function sets the unicode text that will be displayed by the rendering system. The text is set according to the specified UTF encoding method, which defaults to UTF-8.

Parameters:¶

utf8 : str¶: The multi-byte text encoded with utf8 string to be rendered.

Rtyle:¶

Result

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

Sets text alignment or anchor per axis.

If layout width/height is set on an axis, align within the layout box. Otherwise, treat it as an anchor within the text bounds which point of the text box is pinned to the paint position.

Parameters:¶

x : float¶: Horizontal alignment/anchor in [0..1]: 0=left/start, 0.5=center, 1=right/end. (Default is 0)
y : float¶: Vertical alignment/anchor in [0..1]: 0=top, 0.5=middle, 1=bottom. (Default is 0)

Added in version 1.0.

See also

Text.layout()

layout(w: float, h: float) → thorvg_python.base.Result¶

Sets the virtual layout box (constraints) for the text.

If width/height is set on an axis, that axis is constrained by a virtual layout box and the text may wrap/align inside it. If width/height == 0, the axis is unconstrained and Text.align() acts as an anchor on that axis.

Parameters:¶

w : float¶: Layout width in user space. Use 0 for no horizontal constraint. (Default is 0)
h : float¶: Layout height in user space. Use 0 for no vertical constraint. (Default is 0)

Note

This defines constraints only; alignment/anchoring is controlled by align().

Added in version 1.0.

See also

Text.align()

See also

Text.spacing()

wrap_mode(mode: thorvg_python.base.TextWrap) → thorvg_python.base.Result¶

Sets the text wrapping mode for this text object.

This method controls how the text is laid out when it exceeds the available space. The wrapping mode determines whether text is truncated, wrapped by character or word, or adjusted automatically. An ellipsis mode is also available for truncation with “…”.

Parameters:¶

mode : thorvg_python.base.TextWrap¶: The wrapping strategy to apply. Default is NONE.

See also

TextWrap

Added in version 1.0.

spacing(letter: float, line: float) → thorvg_python.base.Result¶

Set the spacing scale factors for text layout.

This function adjusts the letter spacing (horizontal space between glyphs) and line spacing (vertical space between lines of text) using scale factors.

Both values are relative to the font’s default metrics: - The letter spacing is applied as a scale factor to the glyph’s advance width. - The line spacing is applied as a scale factor to the glyph’s advance height.

Parameters:¶

letter : float¶: The scale factor for letter spacing. Values > 1.0 increase spacing, values < 1.0 decrease it. Must be greater than or equal to 0.0. (default: 1.0)
line: float¶: The scale factor for line spacing. Values > 1.0 increase line spacing, values < 1.0 decrease it. Must be greater than or equal to 0.0. (default: 1.0)

Added in version 1.0.

set_italic(shear: float) → thorvg_python.base.Result¶

Apply an italic (slant) transformation to the text.

This function applies a shear transformation to simulate an italic (oblique) style for the current text object. The shear factor determines the degree of slant applied along the X-axis.

Parameters:¶

shear : float¶: The shear factor to apply. A value of 0.0 applies no slant, while values around 0.5 result in a strong slant. Must be in the range [0.0, 0.5]. Recommended value is 0.18.

Returns:¶

Result.INVALID_ARGUMENT A None passed as the paint argument.

Return type:¶

Note

The shear factor will be clamped to the valid range if it exceeds the limits.

Note

This does not require the font itself to be italic. It visually simulates the effect by applying a transformation matrix.

Warning

Excessive slanting may cause visual distortion depending on the font and size.

See also

Text.set_font()

Added in version 1.0.

set_outline(width: float, r: int, g: int, b: int) → thorvg_python.base.Result¶

Sets an outline (stroke) around the text object.

This function adds an outline to the text with the specified width and RGB color. The outline enhances the visibility of the text by rendering a stroke around its glyphs.

Parameters:¶

width : width¶: The width of the outline. Must be positive value. (The default is 0)
r : int¶: Red component of the outline color (0–255).
g : int¶: Green component of the outline color (0–255).
b : int¶: Blue component of the outline color (0–255).

Note

To disable the outline, set width to 0.

See also

Text.set_fill_color() to set the main text fill color.

Added in version 1.0.

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

Sets the text solid color.

Returns:¶: Result.INVALID_ARGUMENT A None passed as the paint argument.
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

Text.set_font()

See also

Text.set_outline()

Added in version 0.15.

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

Sets the gradient fill for the text.

Parameters:¶

gradient : thorvg.base.GradientPointer¶: The linear or radial gradient fill

Returns:¶

Result.INVALID_ARGUMENT A None passed as the paint argument.
Result.MEMORY_CORRUPTION An invalid GradientPointer.

Return type:¶

Note

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

See also

Text.set_font()

Added in version 0.15.

get_metrics() → tuple[thorvg_python.base.Result, thorvg_python.base.TextMetrics]¶

Retrieves the layout metrics of the text object.

Fills the provided TextMetrics structure with the font layout values of this text object, such as ascent, descent, linegap, and line advance.

The returned values reflect the font size applied to the text object, but do not include any transformations (e.g., scale, rotation, or translation).

Returns:¶: A TextMetrics structure filled with the resulting values.
Return type:¶: thorvg_python.base.TextMetrics
Returns:¶: TVG_RESULT_INSUFFICIENT_CONDITION if no font or size has been set yet.
Return type:¶: thorvg_python.base.Result

See also

TextMetrics

Note

Experimental API

font_load(path: str) → thorvg_python.base.Result¶

Loads a scalable font data from a file.

Parameters:¶

path : str¶: The path to the font file.

Returns:¶

Result.INVALID_ARGUMENT An invalid path passed as an argument.
Result.NOT_SUPPORTED When trying to load a file with an unknown extension.

Return type:¶

See also

Engine.font_unload()

Added in version 0.15.

font_load_data(name: str, data: bytes, mimetype: str | None, copy: bool) → thorvg_python.base.Result¶

Loads a scalable font data from a memory block of a given size.

ThorVG efficiently caches the loaded font data using the specified name as a key. This means that loading the same fonts again will not result in duplicate operations. Instead, ThorVG will reuse the previously loaded font data.

Parameters:¶

name : str¶: The name under which the font will be stored and accessible (e.x. in a Text.set_font API).
data : bytes¶: A pointer to a memory location where the content of the font data is stored.
mimetype : str¶: Mimetype or extension of font data. In case a None or an empty “” value is provided the loader will be determined automatically.
copy : bool¶: If true the data are copied into the engine local buffer, otherwise they are not (default).

Returns:¶

Result.INVALID_ARGUMENT If no name is provided or if size is zero while data points to a valid memory location.
Result.NOT_SUPPORTED When trying to load a file with an unknown extension.
Result.INSUFFICIENT_CONDITION When trying to unload the font data that has not been previously loaded.

Return type:¶

Warning

: It’s the user responsibility to release the data memory.

Note

To unload the font data loaded using this API, pass the proper name and None as data.

Added in version 0.15.

font_unload(path: str) → thorvg_python.base.Result¶

Unloads the specified scalable font data that was previously loaded.

This function is used to release resources associated with a font file that has been loaded into memory.

Parameters:¶

path : str¶: The path to the loaded font file.

Returns:¶

Result.INSUFFICIENT_CONDITION The loader is not initialized.

Return type:¶

Note

If the font data is currently in use, it will not be immediately unloaded.

See also

Engine.font_load()

Added in version 0.15.

class thorvg_python.Saver(engine: thorvg_python.engine.Engine, saver: thorvg_python.base.SaverPointer | None = None)¶

Saver API

A module for exporting a paint object into a specified file.

The module enables to save the composed scene and/or image from a paint object. Once it’s successfully exported to a file, it can be recreated using the Picture module.

engine¶

thorvg_lib¶

_new() → thorvg_python.base.SaverPointer¶

Creates a new SaverPointer object.

Returns:¶: A new SaverPointer object.
Return type:¶: SaverPointer

Note

You need not call this method as it is auto called when initializing Saver().

save_paint(paint: thorvg_python.paint.Paint, path: str, quality: int) → thorvg_python.base.Result¶

Exports the given paint data to the given path

If the saver module supports any compression mechanism, it will optimize the data size. This might affect the encoding/decoding time in some cases. You can turn off the compression if you wish to optimize for speed.

Parameters:¶

paint : thorvg_python.paint.Paint¶: The paint to be saved with all its associated properties.
path : str¶: A path to the file, in which the paint data is to be saved.
quality : bool¶: If true then compress data if possible.

Returns:¶

Result.INVALID_ARGUMENT A None passed as the argument.
Result.INSUFFICIENT_CONDITION Currently saving other resources.
Result.NOT_SUPPORTED Trying to save a file with an unknown extension or in an unsupported format.
Result.UNKNOWN An empty paint is to be saved.

Return type:¶

Note

Saving can be asynchronous if the assigned thread number is greater than zero. To guarantee the saving is done, call Saver.sync() afterwards.

See also

Saver.sync()

save_animation(animation: thorvg_python.animation.Animation, path: str, quality: int, fps: int) → thorvg_python.base.Result¶

Exports the given animation data to the given path

Parameters:¶

animation : thorvg_python.animation.Animation¶: The animation to be saved with all its associated properties.
path : str¶: A path to the file, in which the animation data is to be saved.
quality : int¶: The encoded quality level. 0 is the minimum, 100 is the maximum value(recommended).
fps : int¶: The frames per second for the animation. If 0, the default fps is used.

Returns:¶

Result.INVALID_ARGUMENT A None passed as the argument.
Result.INSUFFICIENT_CONDITION Currently saving other resources or animation has no frames.
Result.NOT_SUPPORTED Trying to save a file with an unknown extension or in an unsupported format.
Result.UNKNOWN Unknown if attempting to save an empty paint.

Return type:¶

Note

A higher frames per second (FPS) would result in a larger file size. It is recommended to use the default value.

Note

Saving can be asynchronous if the assigned thread number is greater than zero. To guarantee the saving is done, call Saver.sync() afterwards.

See also

Saver.sync()

Added in version 1.0.

sync() → thorvg_python.base.Result¶

Guarantees that the saving task is finished.

The behavior of the Saver module works on a sync/async basis, depending on the threading setting of the Initializer. Thus, if you wish to have a benefit of it, you must call Saver.sync() after the Saver.save() in the proper delayed time. Otherwise, you can call Saver.sync() immediately.

Returns:¶

Result.INVALID_ARGUMENT A None passed as the argument.
Result.INSUFFICIENT_CONDITION No saving task is running.

Return type:¶