scistag.imagestag.canvas.Canvas¶

class Canvas(size=None, target_image=None, default_color=Color(r=0.0, g=0.0, b=0.0, a=1.0, _rgba=(0.0, 0.0, 0.0, 1.0), _int_rgba=(0, 0, 0, 255)), image_format='RGB')[source]¶

Bases: object

The Canvas class provides functions for drawing graphical elements such as lines, circles or text into an Image’s pixel buffer.

Parameters

size (Union[tuple[float, float], Size2D, None]) – The size in pixels (if a new image shall be created)
target_image (Optional[Image]) – An image into which the canvas shall paint
default_color (Union[Color, tuple[int, int, int], tuple[int, int, int, int], tuple[float, float, float], tuple[float, float, float, float], str]) – The background fill color
image_format (PixelFormat) – The image format, currently only RGB, RGBA and G

Methods

`add_offset_shift`	Shifts the painting offset by given x, y distance in pixels
`clear`	Clears the canvas
`clip`	Clips the current painting region, relative to the current one
`draw_image`	Draws given image onto the canvas
`get_default_font`	Returns the default font configured for this canvas
`get_font`	Tries to create a font handle for given font and returns it.
`load_image`	Loads an image and returns it
`pattern`	Repeats an image within the specified area as often as possible
`pop_state`	Restores the previous state
`push_state`	Backups the current state
`rect`	Draws a rectangle onto the canvas
`rectangle_list`	Optimized rectangle drawing function for drawing a large amount of filled rectangles or frames in a single or multiple colors.
`shift_position_by_offset`	Shifts given coordinates by this canvas' current drawing offset
`text`	Renders a simple text using given parameters into the target image.
`to_image`	Returns an image representation of this canvas.

Attributes

`__dict__`
`__doc__`
`__module__`
`__weakref__`	list of weak references to the object (if defined)
`size`	The canvas' size in pixels
`width`	The image's width in pixels
`height`	The image's height in pixels
`offset`	The current painting offset in pixels
`clip_region`	The min and max x y position valid for painting.
`framework`	The rendering framework being used
`stat_stack`	Buffer to backup and restore the current painting state such as offset and clipping bounding
`target_image`	The image into which the canvas will paint

__setattr__(key, value)[source]¶: Implement setattr(self, name, value).

add_offset_shift(offset)[source]¶

Shifts the painting offset by given x, y distance in pixels

Parameters: offset – The distance of movement in pixels
Returns: Self

clear(color=Color(r=0.0, g=0.0, b=0.0, a=1.0, _rgba=(0.0, 0.0, 0.0, 1.0), _int_rgba=(0, 0, 0, 255)))[source]¶

Clears the canvas

Parameters: color (Union[Color, tuple[int, int, int], tuple[int, int, int, int], tuple[float, float, float], tuple[float, float, float, float], str]) – The color with which the canvas shall be cleared
Return type: Canvas
Returns: Self

clip(offset, size)[source]¶

Clips the current painting region, relative to the current one

Parameters

offset – The distance of movement in pixels
size – The width and height of the painting region

draw_image(image, pos, auto_blend=True)[source]¶

Draws given image onto the canvas

Parameters

image (Image) – The source image to draw
pos (Union[Pos2D, tuple[float, float]]) – The target position in pixels
auto_blend – Defines if the image shall automatically alpha blend if it contains an alpha channel

Return type

Canvas

Returns

Self

get_default_font(size_factor=1.0, size=None, flags=None)[source]¶

Returns the default font configured for this canvas

Parameters

size_factor – Factor by which the font shall be scaled
size (float | None) – The effective size in pixels. Overrides size_factor.
flags (set[str] | None) – The font flags. See get_font().

Return type

Font

Returns

The default font

get_font(font_face, size, flags=None)[source]¶

Tries to create a font handle for given font and returns it.

Parameters

font_face (str) – The font’s face
size (int) – The font’s size in pt
flags (set[str] | None) – The flags such as {‘Bold’} or {‘Bold’, ‘Italic’}

Return type

Font | None

Returns

On success the handle of the font

load_image(source)[source]¶

Loads an image and returns it

Parameters

source (Union[str, ndarray, bytes, Image, type]) –

The image source, e.g. a filename, an URL or a bytes object.

See ImageSourceTypes for supported types.

Return type

Image

Returns

The image handle

pattern(image, bounding, only_full_fit=False, **params)[source]¶

Repeats an image within the specified area as often as possible

Parameters

image (Image) – The image to repeat
bounding (Union[Bounding2D, tuple[int, int, int, int], tuple[float, float, float, float], tuple[Union[Pos2D, tuple[float, float]], Union[Pos2D, tuple[float, float]]], tuple[Union[Pos2D, tuple[float, float]], Union[tuple[float, float], Size2D]]]) – The bounding in which the image shall be repeated
only_full_fit (bool) – Defines if the pattern may only be repeated as long as the image fully fits into the area
params – See draw_image() for additional parameters

Return type

Canvas

Returns

Self

pop_state()[source]¶

Restores the previous state

Return type: Canvas
Returns: Self

push_state()[source]¶

Backups the current state

Return type: Canvas
Returns: Self

rect(pos=None, size=None, bounding=None, color=None, outline_color=None, outline_width=1)[source]¶

Draws a rectangle onto the canvas

Parameters

pos (Pos2DTypes | None) – The position of the upper left edge
size (Size2DTypes | None) – The rectangle’s size in pixels
bounding (Bounding2DTypes | None) – The bounding of the rectangle (alternative to pos and size).
color (ColorTypes | None) – The inner color
outline_color (ColorTypes | None) – The outline color
outline_width (int) – The outline’s width

Return type

Canvas

Returns

Self

rectangle_list(rectangles, colors=None, single_color=None, outline_width=0)[source]¶

Optimized rectangle drawing function for drawing a large amount of filled rectangles or frames in a single or multiple colors.

Assumes raw-types for fast processing and can optimize the transformation process. This function is not (reasonable) faster if you just draw a single rectangle but should be preferred if you draw many ones.

Parameters

rectangles (list[RawBoundingType]) – The list of rectangles ((x,y),(x2,y2))
colors (list[RawColorType] | None) – The list of colors (has to match the length of rectangles)
single_color (RawColorType | None) – The rectangle color (if all rectangles have the same color)
outline_width (int) – If defined a non-filled rectangles with given frame width will be painted

Return type

Canvas

Returns

Self

shift_position_by_offset(position)[source]¶

Shifts given coordinates by this canvas’ current drawing offset

Parameters: position (tuple | Pos2D) – The position
Return type: tuple[float, float]
Returns: The new position as tuple

text(pos, text, color=Color(r=0.0, g=0.0, b=0.0, a=1.0, _rgba=(0.0, 0.0, 0.0, 1.0), _int_rgba=(0, 0, 0, 255)), font=None, h_align=HTextAlignment.LEFT, v_align=VTextAlignment.TOP, center=None, line_spacing=0, stroke_width=0, stroke_color=None, anchor=Anchor2D.TOP_LEFT, _show_formatting=False)[source]¶

Renders a simple text using given parameters into the target image.

Parameters

pos (Pos2DTypes) – The text’s position in x, y coordinates
text (str) – The text to be drawn
color (ColorTypes) – The text’s color
font (Font) – The font to be used.
line_spacing (int) – The spacing between each line in pixels
h_align (HTextAlignmentTypes) –
The text’s horizontal alignment.

Note that the text will be horizontally aligned to the right of pos. If you want to center a text to the left and right of pos you can either pass the argument center=true or set h_align to HTextAlignment.CENTER and anchor to Anchor2D.CENTER.
v_align (VTextAlignmentTypes) – The text’s vertical alignment. (line-wise) Can NOT be used to center a multi-line text.
stroke_width (int) – The stroke width in pixels. Only has effect if stroke_color is not None
center (bool | None) – If set to true the text will be horizontally and vertically centered around pos.
stroke_color (ColorTypes | None) – The stroke color
anchor (Anchor2DTypes) – The positioning anchor relative to which the text shall be positioned. Can be used to center a multiline vertically.
_show_formatting (bool) – Defines if the formatting such as ascend and descent shall be visualized

Return type

Canvas

Returns

Self

to_image()[source]¶

Returns an image representation of this canvas.

If the canvas draws directly to a PIL image handle the returned image will not be a copy and point ot the current PIL image handle as well.

Return type: Image
Returns: The image handle

clip_region: tuple[float, float, float, float]¶: The min and max x y position valid for painting. Note that this is not respected by many paint commands but shall just help skipping irrelevant geometries completely.

framework¶: The rendering framework being used

height¶: The image’s height in pixels

offset¶: The current painting offset in pixels

size¶: The canvas’ size in pixels

stat_stack: list[scistag.imagestag.canvas.CanvasState]¶: Buffer to backup and restore the current painting state such as offset and clipping bounding

target_image: Image¶: The image into which the canvas will paint

width¶: The image’s width in pixels