thorvg_python.animation¶

Submodules¶

Classes¶

Package Contents¶

class thorvg_python.animation.AnimationPointer¶

Bases: ctypes.c_void_p

A structure representing an animation controller object.

Note

You should use Animation class instead.

class thorvg_python.animation.PaintPointer¶

Bases: ctypes.c_void_p

A structure representing a graphical element.

Warning

The PaintPointer objects cannot be shared between Canvases.

Note

You should use Paint class instead.

class thorvg_python.animation.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.animation.Engine(thorvg_lib_path: str | None = None, threads: int = 0)¶

Engine API

A module enabling initialization and termination of the TVG engines.

threads = 0¶

init_result¶

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

__del__() → None¶

__enter__() → Engine¶

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

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

Initializes TVG engines.

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

Parameters:¶

threads : int¶

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

Return type:¶

thorvg_python.base.Result

Note

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

See also

Engine.term()

term() → thorvg_python.base.Result¶

Terminates TVG engines.

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

Returns:¶

Result.INSUFFICIENT_CONDITION Returned if there is nothing to terminate (e.g., Engine.init() was not called).

Return type:¶

thorvg_python.base.Result

See also

Engine.init()

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

Retrieves the version of the TVG engine.

Returns:¶

Result.SUCCESS

Return type:¶

thorvg_python.base.Result

Returns:¶

A major version number.

Return type:¶

int

Returns:¶

A minor version number.

Return type:¶

int

Returns:¶

A micro version number.

Return type:¶

int

Returns:¶

The version of the engine in the format major.minor.micro, or a None in case of an internal error.

Return type:¶

Optional[str]

Added in version 0.15.

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

Bases: thorvg_python.paint.Paint

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¶

_new() → thorvg_python.base.PaintPointer¶

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

thorvg_python.base.Result

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

thorvg_python.base.Result

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.

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

thorvg_python.base.Result

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

thorvg_python.base.Result

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

thorvg_python.base.Result

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

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

thorvg_python.base.PaintPointer

See also

Engine.accessor_generate_id()

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

Animation API

A module for manipulation of animatable images.

The module supports the display and control of animation frames.

engine¶

thorvg_lib¶

_new() → thorvg_python.base.AnimationPointer¶

Creates a new Animation object.

Returns:¶

AnimationPointer A new AnimationPointer object.

Return type:¶

thorvg_python.base.AnimationPointer

Note

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

Added in version 0.13.

set_frame(no: float) → thorvg_python.base.Result¶

Specifies the current frame in the animation.

Parameters:¶

no : float¶

The index of the animation frame to be displayed. The index should be less than the Animation.get_total_frame().

Returns:¶

• Result.INVALID_ARGUMENT An invalid AnimationPointer.

• Result.INSUFFICIENT_CONDITION if the given no is the same as the current frame value.

• Result.NOT_SUPPORTED The picture data does not support animations.

Return type:¶

thorvg_python.base.Result

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

thorvg_python.base.Result

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.