Editor¶

Editor class. It does all the editing operations.

Parameters:: source (Image | str | bytes | BytesIO | Editor | Canvas | Path) – Image or Canvas to edit.

add_border(width: int = 1, color: int | str | tuple[int, int, int] | tuple[int, int, int, int] = 'black') → Editor¶

Add a border around the image.

Parameters:

width (int, optional) – Border width in pixels, by default 1
color (Color, optional) – Border color, by default “black”

Draw arc.

Parameters:

position (Tuple[float, float]) – Position to draw arc
width (float) – Width or arc
height (float) – Height of arch
start (float) – Start position of arch
rotation (float) – Rotation in degree
fill (Color or Gradient, optional) – Fill color or gradient, by default None
color (Color or Gradient, optional) – Alias of fill, by default None
stroke_width (float, optional) – Stroke width, by default 1

Draw a progress bar.

Parameters:

position (Tuple[int, int]) – Position to draw bar
max_width (Union[int, float]) – Max width of the bar
height (Union[int, float]) – Height of the bar
percentage (int, optional) – Percentage to fill of the bar, by default 1
fill (Color or Gradient, optional) – Fill color or gradient, by default None
color (Color or Gradient, optional) – Alias of fill, by default None
outline (Color, optional) – Outline color, by default None
stroke_width (float, optional) – Stroke width, by default 1
radius (int, optional) – Radius of the bar, by default 0

blend(image: Image | Editor | Canvas, alpha: float = 0.0, *, on_top: bool = False) → Editor¶

Blend image into editor image.

Parameters:

image (Union[Image, Editor, Canvas]) – Image to blend
alpha (float, optional) – Alpha amount, by default 0.0
on_top (bool, optional) – Places image on top, by default False

blur(mode: Literal['box', 'gaussian'] = 'gaussian', amount: float = 1) → Editor¶

Blur image.

Parameters:

mode (Literal["box", "gaussian"], optional) – Blur mode, by default “gaussian”
amount (float, optional) – Amount of blur, by default 1

brightness(factor: float = 1.0) → Editor¶

Adjust image brightness.

Parameters:: factor (float, optional) – Brightness factor. 1.0 = original, >1 = brighter, <1 = darker.

Draw text centered horizontally on the image.

Parameters:

text (str) – Text to draw
font (ImageFont.FreeTypeFont | Font, optional) – Font for text
color (Color, optional) – Text color, by default “black”
y_offset (float, optional) – Vertical offset from center, by default 0

circle_image() → Editor¶: Make image circle.

close() → None¶: Close the image.

compose(editors: list[Editor], direction: Literal['horizontal', 'vertical'] = 'vertical', align: Literal['start', 'center', 'end'] = 'center', spacing: int = 0) → Editor¶

Combine multiple editors into one image.

Parameters:

editors (list[Editor]) – Editors to combine
direction (Literal["horizontal", "vertical"], optional) – Layout direction, by default “vertical”
align (Literal["start", "center", "end"], optional) – Alignment of items in the opposite axis, by default “center”
spacing (int, optional) – Spacing between items in pixels, by default 0

contrast(factor: float = 1.0) → Editor¶

Adjust image contrast.

Parameters:: factor (float, optional) – Contrast factor. 1.0 = original, >1 = more contrast, <1 = less.

crop(box: tuple[int, int, int, int]) → Editor¶

Crop image to bounding box.

Parameters:: box (tuple[int, int, int, int]) – (left, upper, right, lower) pixel coordinates

Draw a donut (ring) shape.

Parameters:

position (tuple[float, float]) – Center coordinates (x, y)
inner_radius (float) – Inner radius of ring
outer_radius (float) – Outer radius of ring
fill (Color or Gradient, optional) – Fill color or gradient, by default “black”
outline (Color | None, optional) – Outline color, by default None
stroke_width (int, optional) – Outline stroke width, by default 0

effect(effect: Effect) → Editor¶: Apply effect to image. Accepts any Effect subclass instance.

Draw an ellipse.

Parameters:

position (Tuple[float, float]) – Position to draw ellipse
width (float) – Width of ellipse
height (float) – Height of ellipse
fill (Color or Gradient, optional) – Fill color or gradient, by default None
color (Color or Gradient, optional) – Alias of fill, by default None
outline (Color, optional) – Outline color, by default None
stroke_width (float, optional) – Stroke width, by default 1

fit_text(text: str, max_width: float, font: FreeTypeFont | Font | str, *, max_size: int = 100, min_size: int = 1) → FreeTypeFont¶

Find the largest font size that fits text within max_width.

Parameters:

text (str) – Text to measure
max_width (float) – Maximum allowed width in pixels
font (ImageFont.FreeTypeFont | Font | str) – Font object or path to font file
max_size (int, optional) – Maximum font size to try, by default 100
min_size (int, optional) – Minimum font size to try, by default 1

Returns:

Font at the fitted size

Return type:

ImageFont.FreeTypeFont

flip(*, horizontal: bool = False) → Editor¶

Flip image.

Parameters:: horizontal (bool, optional) – Flip horizontally (mirror), by default False (vertical flip)

property image_bytes: BytesIO¶

Return image bytes.

Returns:: Bytes from the image of Editor
Return type:: BytesIO

invert() → Editor¶: Invert image colors.

line(start: tuple[float, float], end: tuple[float, float], width: int = 1, fill: int | str | tuple[int, int, int] | tuple[int, int, int, int] = 'black') → Editor¶

Draw a line.

Parameters:

start (tuple[float, float]) – Start coordinates (x, y)
end (tuple[float, float]) – End coordinates (x, y)
width (int, optional) – Line width, by default 1
fill (Color, optional) – Line color, by default “black”

mask(mask_image: Image | Editor, invert: bool = False) → Editor¶

Apply external mask for transparency.

Parameters:

mask_image (Union[Image, Editor]) – Grayscale mask where white=opaque, black=transparent.
invert (bool, optional) – Invert mask (white=transparent, black=opaque), by default False

multi_text(position: tuple[float, float], texts: list[Text], *, space_separated: bool = True, align: Literal['left', 'center', 'right'] = 'left', anchor: str | None = None) → Editor¶: Backward-compatible alias for rich_text().

classmethod open(fp: str | Path | BytesIO) → Editor¶

Open image file as Editor.

Parameters:: fp (str | Path | BytesIO) – File path or buffer

paste(image: Image | Editor | Canvas, position: tuple[int, int]) → Editor¶

Paste image into editor.

Parameters:

image (Union[Image, Editor, Canvas]) – Image to paste
position (Tuple[int, int]) – Position to paste

Draw a polygon.

Parameters:

coordinates (list) – Coordinates to draw
fill (Color or Gradient, optional) – Fill color or gradient, by default None
color (Color or Gradient, optional) – Alias of fill, by default None
outline (Color, optional) – Outline color, by default None

Draw rectangle into image.

Parameters:

position (Tuple[float, float]) – Position to draw rectangle
width (float) – Width of rectangle
height (float) – Height of rectangle
fill (Color or Gradient, optional) – Fill color or gradient, by default None
color (Color or Gradient, optional) – Alias of fill, by default None
outline (Color, optional) – Outline color, by default None
stroke_width (float, optional) – Stroke width, by default 1
radius (int, optional) – Radius of rectangle, by default 0

resize(size: tuple[int, int], *, crop: bool = False) → Editor¶

Resize image.

Parameters:

size (Tuple[int, int]) – New Size of image
crop (bool, optional) – Crop the image to bypass distortion, by default False

rich_text(position: tuple[float, float], texts: list[Text], *, space_separated: bool = True, align: Literal['left', 'center', 'right'] = 'left', anchor: str | None = None) → Editor¶

Draw rich text with mixed colors and fonts inline.

Parameters:

position (Tuple[float, float]) – Position to draw text
texts (List[Text]) – List of texts
space_separated (bool, optional) – Separate texts with space, by default True
align (Literal["left", "center", "right"], optional) – Align texts, by default “left”
anchor (str, optional) – Pillow text anchor (e.g. “mm” for middle-middle). Defaults to align-based anchor (“lt”/”mt”/”rt”).

rotate(deg: float = 0, *, expand: bool = False) → Editor¶

Rotate image.

Parameters:

deg (float, optional) – Degrees to rotate, by default 0
expand (bool, optional) – Expand while rotating, by default False

Draw a rounded bar.

Parameters:

position (Tuple[float, float]) – Position to draw rounded bar
width (Union[int, float]) – Width of the bar
height (Union[int, float]) – Height of the bar
percentage (float) – Percentage to fill.
fill (Color or Gradient, optional) – Fill color or gradient, by default None
color (Color or Gradient, optional) – Alias of color, by default None
stroke_width (float, optional) – Stroke width, by default 1
radius (int, optional) – Corner radius. Defaults to height//2 (fully rounded).

rounded_corners(radius: int = 10, offset: int = 2) → Editor¶

Make image rounded corners.

Parameters:

radius (int, optional) – Radius of roundness, by default 10
offset (int, optional) – Offset pixel while making rounded, by default 2

saturation(factor: float = 1.0) → Editor¶

Adjust image color saturation.

Parameters:: factor (float, optional) – Saturation factor. 1.0 = original, >1 = more saturated, <1 = less.

save(fp: str | Path | BytesIO, file_format: str | None = None, **params: Any) → None¶

Save the image.

Parameters:

fp (str | Path | BytesIO) – File path or buffer
file_format (str, optional) – File format, by default None
**params (Any) – Additional parameters for PIL Image.save

show() → None¶: Show the image.

Draw text into image.

Parameters:

position (Tuple[float, float]) – Position to draw text.
text (str) – Text to draw
font (Union[ImageFont.FreeTypeFont, Font], optional) – Font used for text, by default None
color (Color, optional) – Color of the font, by default “black”
align (Literal["left", "center", "right"], optional) – Align text, by default “left”
anchor (str, optional) – Pillow text anchor (e.g. “mm” for middle-middle). Overrides align if set.
stroke_width (int, optional) – Whether there should be any stroke. Defaults to None. It represents the width of the said stroke.
stroke_fill (Color, optional) – Color of the stroke, if any stroke is applied to the text. Defaults to “black”

Draw text wrapped to fit inside a bounding box.

Parameters:

position (Tuple[float, float]) – Position to draw text (top-left).
text (str) – Text to draw.
font (Union[ImageFont.FreeTypeFont, Font]) – Font used for text.
color (Color, optional) – Color of the font, by default “black”
align (Literal["left", "center", "right"], optional) – Align text, by default “left”
max_width (float, optional) – Max width before wrapping. Defaults to image width.
line_spacing (int, optional) – Extra spacing between lines, by default 4
stroke_width (int, optional) – Stroke width, by default None
stroke_fill (Color, optional) – Stroke color, by default “black”

Draw text with a drop shadow.

Parameters:

position (Tuple[float, float]) – Position to draw text.
text (str) – Text to draw.
font (Union[ImageFont.FreeTypeFont, Font], optional) – Font used for text, by default None
color (Color, optional) – Text color, by default “white”
shadow_color (Color, optional) – Shadow color, by default “black”
shadow_offset (Tuple[int, int], optional) – Shadow offset (x, y), by default (2, 2)
align (Literal["left", "center", "right"], optional) – Align text, by default “left”
stroke_width (int, optional) – Stroke width, by default None
stroke_fill (Color, optional) – Stroke color, by default “black”

thumbnail(size: tuple[int, int]) → Editor¶

Resize image to fit within size, maintaining aspect ratio.

Parameters:: size (tuple[int, int]) – Maximum (width, height)

to_bytes(fmt: str = 'PNG') → bytes¶

Return image as bytes.

Parameters:: fmt (str, optional) – Image format, by default “PNG”