Skip to content

Model Classes & Enums

These are the data classes and enumerations used for configuration.

pictex.SolidColor(r, g, b, a=255) dataclass

Represents a solid color with RGBA components.

This class provides a structured way to handle solid colors, with methods for creating instances from various string formats like hex codes or standard color names.

Attributes:

Name Type Description
r int

The red component of the color (0-255).
g int

The green component of the color (0-255).
b int

The blue component of the color (0-255).
a int

The alpha (opacity) component of the color (0-255), where 255 is fully opaque. Defaults to 255.

from_str(value) classmethod

Creates a SolidColor object from a general color string.

This method acts as a factory, supporting standard color names (e.g., 'red', 'blue') and hexadecimal codes.

Parameters:

Name Type Description Default
value str

The color string to parse.

 required

Returns:

Type Description
SolidColor

A new SolidColor instance.

Raises:

Type Description
ValueError

If the color name is unknown or the format is invalid.

pictex.LinearGradient(colors, stops=None, start_point=(0.0, 0.5), end_point=(1.0, 0.5)) dataclass

Represents a linear gradient fill, smoothly transitioning between colors along a straight line.

The gradient's direction and color distribution are controlled by its parameters.

Attributes:

Name Type Description
colors Sequence[Union[SolidColor, str]]

A sequence of two or more colors that define the key colors of the gradient.
stops Optional[Sequence[float]]

A sequence of numbers between 0.0 and 1.0 that specify the position of each color in the colors sequence. The length of stops must match the length of colors. If None, the colors are distributed evenly along the gradient line. For example, for colors with 3 colors, stops=[0.0, 0.5, 1.0] would place the second color exactly in the middle of the gradient.
start_point tuple[float, float]

A tuple (x, y) representing the starting point of the gradient line. Coordinates are relative to the object's bounding box, where (0.0, 0.0) is the top-left corner and (1.0, 1.0) is the bottom-right corner.
end_point tuple[float, float]

A tuple (x, y) representing the ending point of the gradient line. The gradient is drawn along the line connecting start_point to end_point.
Example

A simple horizontal gradient from red to blue 

horizontal_gradient = LinearGradient(
    colors=['#FF0000', 'blue']
)

A vertical gradient from top (yellow) to bottom (orange) 

vertical_gradient = LinearGradient(
    colors=['yellow', 'orange'],
    start_point=(0.5, 0.0),
    end_point=(0.5, 1.0)
)

A diagonal gradient with a custom color stop 

diagonal_gradient = LinearGradient(
    colors=[
        'magenta',
        'cyan',
        'yellow'
    ],
    stops=[0.0, 0.2, 1.0] # 'cyan' is positioned 20% along the gradient
)

pictex.RadialGradient(colors, stops=None, center=(0.5, 0.5), radius=0.5) dataclass

Represents a radial gradient fill, smoothly transitioning between colors from a center point outward in a circular pattern.

The gradient's center, radius, and color distribution are controlled by its parameters.

Attributes:

Name Type Description
colors Sequence[Union[SolidColor, str]]

A sequence of two or more colors that define the key colors of the gradient.
stops Optional[Sequence[float]]

A sequence of numbers between 0.0 and 1.0 that specify the position of each color in the colors sequence. The length of stops must match the length of colors. If None, the colors are distributed evenly from center to edge. For example, for colors with 3 colors, stops=[0.0, 0.5, 1.0] would place the second color exactly halfway between center and edge.
center tuple[float, float]

A tuple (x, y) representing the center point of the radial gradient. Coordinates are relative to the object's bounding box, where (0.0, 0.0) is the top-left corner and (1.0, 1.0) is the bottom-right corner. Defaults to (0.5, 0.5) which is the center of the object.
radius float

The radius of the gradient circle, relative to the object's dimensions. A value of 0.5 means the radius extends halfway across the bounding box. Must be positive. Defaults to 0.5.
Example

A simple radial gradient from red (center) to blue (edge)

radial_gradient = RadialGradient(
    colors=['#FF0000', 'blue']
)

A radial gradient centered at top-left corner

corner_gradient = RadialGradient(
    colors=['yellow', 'orange'],
    center=(0.0, 0.0),
    radius=0.7
)

A radial gradient with custom color stops

multi_stop_gradient = RadialGradient(
    colors=[
        'magenta',
        'cyan',
        'yellow'
    ],
    stops=[0.0, 0.3, 1.0]  # 'cyan' positioned 30% from center
)

pictex.SweepGradient(colors, stops=None, center=(0.5, 0.5)) dataclass

Represents a sweep (conical/angular) gradient fill, smoothly transitioning between colors in a circular sweep around a center point.

The gradient sweeps around the center point in a full 360-degree circle, creating a conical color distribution. This is useful for creating color wheels, radial UI elements, and angular effects.

Attributes:

Name Type Description
colors Sequence[Union[SolidColor, str]]

A sequence of two or more colors that define the key colors of the gradient.
stops Optional[Sequence[float]]

A sequence of numbers between 0.0 and 1.0 that specify the position of each color in the colors sequence. The length of stops must match the length of colors. If None, the colors are distributed evenly around the full circle. For example, for colors with 3 colors, stops=[0.0, 0.5, 1.0] would place the second color exactly halfway around the circle.
center tuple[float, float]

A tuple (x, y) representing the center point of the sweep gradient. Coordinates are relative to the object's bounding box, where (0.0, 0.0) is the top-left corner and (1.0, 1.0) is the bottom-right corner. Defaults to (0.5, 0.5) which is the center of the object.
Example

A simple full-circle sweep gradient

sweep_gradient = SweepGradient(
    colors=['#FF0000', '#00FF00', '#0000FF', '#FF0000']
)

A color wheel with custom stops

color_wheel = SweepGradient(
    colors=['red', 'yellow', 'green', 'cyan', 'blue', 'magenta', 'red'],
    stops=[0.0, 0.16, 0.33, 0.5, 0.66, 0.83, 1.0]
)

pictex.TwoPointConicalGradient(colors, stops=None, start=(0.5, 0.5), start_radius=0.0, end=(0.5, 0.5), end_radius=0.5) dataclass

Represents a two-point conical gradient fill, smoothly transitioning between colors from one circle to another circle.

This gradient creates a cone-like transition between two circles defined by their center points and radii. The gradient interpolates colors from the start circle to the end circle, creating sophisticated radial effects.

Attributes:

Name Type Description
colors Sequence[Color]

A sequence of two or more Color objects that define the key colors of the gradient.
stops Optional[Sequence[float]]

A sequence of numbers between 0.0 and 1.0 that specify the position of each color in the colors sequence. The length of stops must match the length of colors. If None, the colors are distributed evenly from start to end circle. For example, for colors with 3 colors, stops=[0.0, 0.5, 1.0] would place the second color exactly halfway between the circles.
start tuple[float, float]

A tuple (x, y) representing the center point of the start circle. Coordinates are relative to the object's bounding box, where (0.0, 0.0) is the top-left corner and (1.0, 1.0) is the bottom-right corner. Defaults to (0.5, 0.5).
start_radius float

The radius of the start circle, relative to the object's dimensions. Must be non-negative. Defaults to 0.0.
end tuple[float, float]

A tuple (x, y) representing the center point of the end circle. Coordinates are relative to the object's bounding box. Defaults to (0.5, 0.5).
end_radius float

The radius of the end circle, relative to the object's dimensions. Must be non-negative. Defaults to 0.5.
Example

A simple conical gradient from center to edge

conical_gradient = TwoPointConicalGradient(
    colors=['yellow', 'orange', 'red']
)

A spotlight effect with offset circles

spotlight = TwoPointConicalGradient(
    colors=['white', 'black'],
    start=(0.3, 0.3),
    start_radius=0.0,
    end=(0.5, 0.5),
    end_radius=0.7
)

A custom conical gradient with multiple stops

custom_conical = TwoPointConicalGradient(
    colors=['cyan', 'blue', 'purple', 'magenta'],
    stops=[0.0, 0.3, 0.7, 1.0],
    start=(0.5, 0.5),
    start_radius=0.1,
    end=(0.5, 0.5),
    end_radius=0.8
)
Note

For the gradient to render correctly, the start circle should be fully contained within the end circle. If they only partially overlap or do not overlap at all, the area outside the gradient region may appear transparent or unexpectedly dark - this behavior follows Skia's conical gradient implementation.

pictex.Shadow(offset=(2, 2), blur_radius=2.0, color=(lambda: SolidColor(0, 0, 0, a=128))()) dataclass

Represents a drop shadow effect for an element.

Attributes:

Name Type Description
offset tuple[float, float]

A tuple (dx, dy) specifying the horizontal and vertical offset of the shadow from the element. Positive dx values shift the shadow to the right, and positive dy values shift it downward. Defaults to (2, 2).
blur_radius float

The radius of the Gaussian blur applied to the shadow's shape. Larger values create a softer, more diffused shadow, while a value of 0 results in a sharp, un-blurred shadow. Defaults to 2.0.
color SolidColor | str

The color of the shadow, specified as a string or a SolidColor object. Defaults to a semi-transparent black, equivalent to rgba(0, 0, 0, 0.5).
Example 
from pictex import Text, Shadow

# A soft, standard drop shadow for a box
soft_shadow = Shadow(
    offset=(3, 3),
    blur_radius=5,
    color="black"
)

# Applying a single shadow to a box
element_with_shadow = Row().box_shadows(soft_shadow)

# Applying multiple shadows to text for a neon glow effect
neon_text = Text("Glow").text_shadows(
    Shadow(blur_radius=4, color="cyan"),
    Shadow(blur_radius=8, color="magenta"),
    Shadow(blur_radius=12, color="blue")
)

pictex.TextAlign

Text alignment options. Useful in multi-line text blocks.

pictex.FontWeight

pictex.FontStyle

Represents the builders of a font. Useful for variable fonts.

pictex.CropMode

Defines how the final image canvas should be cropped.

Render Tree Classes

These classes provide access to the hierarchical structure of rendered elements.

pictex.RenderNode(bounds, children, node_type) dataclass

Represents a rendered node in the composition tree.

This class provides a simple read-only view of the internal render tree, exposing the bounds and hierarchical structure of rendered elements.

Attributes:

Name Type Description
bounds Box

The bounding rectangle of this node (border bounds).
children List[RenderNode]

List of child nodes in the render tree.
node_type NodeType

The type of node (NodeType.TEXT, NodeType.ROW, etc.).

visit_children(visitor_func)

Recursively visits all children nodes.

Parameters:

Name Type Description Default
visitor_func

A function that takes a RenderNode as argument.

 required

find_nodes_by_type(node_type)

Finds all nodes in the tree with the specified type.

Parameters:

Name Type Description Default
node_type NodeType

The type of nodes to find.

 required

Returns:

Type Description
List[RenderNode]

A list of RenderNode instances matching the specified type.

pictex.NodeType

Enumeration of possible node types in the render tree.