Output Classes

These classes represent the final rendered product of a composition.

pictex.BitmapImage(skia_image, content_box, render_tree=None)

A wrapper around a rendered raster image.

This class holds the pixel data from a rendered image and provides convenient methods to save it to a file or convert it to other common formats like NumPy arrays or Pillow (PIL) Images.

Objects of this class are typically created by calling Canvas.render().

Example

# Assuming 'canvas' is a pre-configured Canvas object
image = canvas.render("Hello World")

# Save the image to a file
image.save("output.png")

# Get a NumPy array for use with OpenCV or other libraries
import cv2
cv2_image = image.to_numpy()
cv2.imshow("Render", cv2_image)
cv2.waitKey(0)

Attributes:

Name	Type	Description
content_box	Box	The bounding box of the content (text + padding), relative to the image's top-left corner.
width	int	The total width of the image in pixels.
height	int	The total height of the image in pixels.
skia_image	Image	The underlying raw skia.Image object for advanced use cases.
render_tree	RenderNode	The hierarchical structure of rendered nodes with their bounds information.

Initializes the Image wrapper.

Note

This constructor is intended for internal use by the library, typically called from Canvas.render().

Parameters:

Name	Type	Description	Default
skia_image	Image	The underlying skia.Image object.	required
content_box	Box	The calculated bounding box of the content area.	required
render_tree	Optional[RenderNode]	The hierarchical structure of rendered nodes with bounds.	None

content_box property

Gets the bounding box of the content area.

width property

Gets the width of the image in pixels.

height property

Gets the height of the image in pixels.

skia_image property

Gets the raw, underlying skia.Image object.

render_tree property

Gets the hierarchical structure of rendered nodes with bounds.

to_bytes()

Returns the raw pixel data as a byte string.

The format of the byte string is 32-bit BGRA, with 8 bits per component.

Returns:

Type	Description
bytes	A byte string containing the raw pixel data.

to_numpy(mode='RGBA')

Converts the image to a NumPy array in the specified channel order.

Parameters:

Name	Type	Description	Default
mode	Literal['RGBA', 'BGRA', 'RGB', 'Grayscale']	The desired channel order or format for the output array. Defaults to 'RGBA', the most common format for image processing. - 'RGBA': Red, Green, Blue, Alpha. - 'BGRA': Blue, Green, Red, Alpha. Compatible with OpenCV. - 'RGB': Red, Green, Blue. Alpha channel is discarded. - 'Grayscale': Converts the image to a single-channel grayscale.	'RGBA'

Returns:

Type	Description
ndarray	A NumPy array representing the image. The shape will be
ndarray	(height, width, 4) for RGBA/BGRA, (height, width, 3) for RGB,
ndarray	and (height, width) for Grayscale.

to_pillow()

Converts the image to a Pillow (PIL) Image object.

The returned Pillow Image will be in 'RGBA' mode.

Returns:

Type	Description
Image	A PIL.Image.Image object.

Raises:

Type	Description
ImportError	If the Pillow library is not installed.

save(output_path, quality=100)

Saves the image to a file.

The output format is inferred from the file extension. Supported formats are PNG, JPEG, and WebP. Defaults to PNG if the extension is unknown.

Parameters:

Name	Type	Description	Default
output_path	str	The path to save the output image (e.g., 'image.png').	required
quality	int	An integer from 0 to 100 indicating image quality. This is only used for lossy formats like JPEG and WebP. It is ignored for PNG.	100

Raises:

Type	Description
RuntimeError	If Skia fails to encode the image to the specified format.
IOError	If there is an error writing the file to disk.

show()

Displays the image using the default Pillow viewer.

This method is useful for debugging in scripts and interactive environments like Jupyter notebooks.

Raises:

Type	Description
ImportError	If the Pillow library is not installed.

pictex.VectorImage(svg_content, render_tree=None, font_files=None)

Represents a rendered vector image in SVG format.

This class holds the SVG data generated by a rendering operation and provides convenient methods for saving it to a file or displaying it in rich environments like Jupyter Notebooks.

Objects of this class are typically created by calling Canvas.render_as_svg().

Example

# Assuming 'canvas' is a pre-configured Canvas object
vector_image = canvas.render_as_svg("Vector Text")

# Save the image to a .svg file
vector_image.save("output.svg")

Attributes:

Name	Type	Description
svg	str	The raw SVG content as a string.
render_tree	RenderNode	The hierarchical structure of rendered nodes with their bounds information.

Initializes the VectorImage.

Note

This constructor is intended for internal use by the library, typically called from Canvas.render_as_svg().

Parameters:

Name	Type	Description	Default
svg_content	str	The full SVG content as a string.	required
render_tree	Optional[RenderNode]	The hierarchical structure of rendered nodes with bounds.	None
font_files	Optional[list[str]]	List of absolute paths to font files used in the SVG. Only populated when embed_fonts=False.	None

svg property

Gets the raw SVG content as a string.

render_tree property

Gets the hierarchical structure of rendered nodes with bounds.

save(output_path, copy_fonts=True, fonts_subdir='fonts')

Saves the SVG image to a file.

When the SVG was rendered with embed_fonts=False and copy_fonts=True, this method will automatically copy all used font files to a subdirectory relative to the SVG output path and update font references accordingly.

The file is saved with UTF-8 encoding.

Parameters:

Name	Type	Description	Default
output_path	str	The path where the output file will be saved (e.g., 'image.svg').	required
copy_fonts	bool	If True (default), copies font files to fonts_subdir and updates references. Set to False to skip copying.	True
fonts_subdir	str	Name of the subdirectory for fonts (default: "fonts"). Only used if copy_fonts=True.	'fonts'

Raises:

Type	Description
IOError	If there is an error writing the file to disk.