thorvg_python.paint.picture¶

Classes¶

`Picture`	Picture API

Module Contents¶

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

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

Note

Setting Picture.set_accessible() to True enables more efficient access.

See also

Engine.accessor_generate_id()

set_accessible(accessible: bool) → thorvg_python.base.Result¶

Enable or disable accessible mode for a Picture.

When accessible mode is enabled, the Picture maintains an internal mapping of ID-accessible vector assets nodes (such as SVG), allowing efficient access to Paint objects and their associated identifier information via Accessor APIs.

When disabled, no additional mapping is maintained and all nodes are treated as general traversal targets.

Parameters:¶

accessible : bool¶: Set to True to enable accessible mode, or False to disable it.

See also

Accessor.generate_id()

See also

Accessor.get_name()

See also

Picture.get_paint()

set_filter(method: thorvg_python.base.FilterMethod) → thorvg_python.base.Result¶

Sets the image filtering method for rendering this picture.

Specifies how the image data should be filtered when it is scaled or transformed during rendering. This affects the visual quality and performance of the output.

Parameters:¶

method : thorvg_python.base.FilterMethod¶: The filtering method to apply. Default is thorvg_python.base.FilterMethod.BILINEAR

Returns:¶

Result

Return type:¶

thorvg_python.base.Result

See also

FilterMethod

Note

Experimental API