Images & Dimage Processing

Drawlib allows embedding external bitmap and vector images directly into your illustrations. You can combine raster graphics (company logos, cloud service icons, application screenshots) with vector shapes and annotations, or manipulate graphics programmatically using the immutable in-memory Dimage model:

from drawlib.canvas import save, setup
from drawlib.images import Dimage, image
from drawlib.shapes import rectangle
from drawlib.styles import Styles
from drawlib.text import text

setup(width=116, height=46)

# Card 1: Local image file
rectangle((33, 23), width=44, height=36, style=Styles.Neutral.patch(shape_r=3))
image((33, 26.5), width=18, image="../_assets/linux.png")
text((33, 10.5), "Linux Logo", style=Styles.DarkBold.patch(text_size=11.0))

# Card 2: Memory Dimage
rectangle((83, 23), width=44, height=36, style=Styles.SecondaryNeutral.patch(shape_r=3))
dimg = Dimage("../_assets/python.png")
image((83, 26.5), width=18, image=dimg)
text((83, 10.5), "Python Dimage", style=Styles.DarkBold.patch(text_size=11.0))

save()

1. Overview & Imports

Image placement and in-memory manipulation classes are imported from drawlib.images:

from drawlib.images import (
    Dimage,                # Immutable PIL Image wrapper with 20+ geometric & artistic transforms
    get_dimage_from_code,  # Render a Drawlib Python snippet in an isolated subprocess to a Dimage
    image,                 # Draw a file path, PIL Image, or Dimage onto the canvas
)

2. Placing & Styling Images (image)

The image() function places an image on the canvas at coordinate xy, automatically preserving its original aspect ratio.

image(
    xy: tuple[float, float],
    width: float,
    image: str | os.PathLike | Image.Image | Dimage,
    *,
    style: Style | None = None,
) -> None

2.1. Image & Transform Attributes on Style

When passing style= to image(), you can configure both image-specific image_* attributes and shared spatial transforms via .patch():

[!IMPORTANT] Rotation Requires Center Alignment (angle != 0): When style.angle is non-zero, image() requires center alignment (halign="center", valign="center"). If a non-center halign or valign is passed alongside angle != 0, Drawlib logs a warning and automatically resets alignment to "center".

2.2. Anchor Alignment & Rotation Example

By default, (x, y) anchors the geometric center of the image. You can shift the anchor to the bottom-left corner via style.patch(halign="left", valign="bottom"), or rotate a center-anchored image via style.patch(angle=...):

from drawlib.canvas import save, setup
from drawlib.images import image
from drawlib.shapes import circle, rectangle
from drawlib.styles import Colors, Styles
from drawlib.text import text

setup(width=128, height=48, grid=True)

img_path = "../_assets/python.png"
framed = Styles.Neutral.patch(image_border_width=1.0, image_border_color=Colors.Gray4)
lbl_st = Styles.DarkBold.patch(text_size=10.0)

# 1. Default center anchor at xy=(23, 25)
rectangle((23, 23), width=35, height=38, style=Styles.Neutral.patch(shape_r=2))
image((23, 25), width=17, image=img_path, style=framed)
circle((23, 25), radius=1.2, style=Styles.DangerFlat)
text((23, 8.0), "1. Center (23, 25)", style=lbl_st)

# 2. Bottom-left anchor at xy=(55.5, 16.5)
rectangle((64, 23), width=35, height=38, style=Styles.Neutral.patch(shape_r=2))
bl_style = framed.patch(halign="left", valign="bottom")
image((55.5, 16.5), width=17, image=img_path, style=bl_style)
circle((55.5, 16.5), radius=1.2, style=Styles.DangerFlat)
text((64, 8.0), "2. Bottom-Left", style=lbl_st)

# 3. Rotated center placement at xy=(105, 25)
rectangle((105, 23), width=35, height=38, style=Styles.SecondaryNeutral.patch(shape_r=2))
rot_style = Styles.Neutral.patch(angle=20)
image((105, 25), width=17, image=img_path, style=rot_style)
circle((105, 25), radius=1.2, style=Styles.DangerFlat)
text((105, 8.0), "3. Rotated (20°)", style=lbl_st)

save()

3. In-Memory Image Manipulation (Dimage)

Dimage wraps a PIL.Image.Image object in an immutable, chainable API. Every transformation method returns a new Dimage instance while keeping the original Dimage unchanged.

from drawlib.images import Dimage
from drawlib.styles import Colors

# 1. Load from file (or wrap an existing PIL Image / Dimage)
dimg = Dimage("../_assets/python.png")

# 2. Inspect pixel dimensions
width_px, height_px = dimg.get_image_size()

# 3. Fill transparent background pixels with a solid color (keeps opaque foreground intact)
filled_bg = dimg.fill(Colors.Primary1)

# 4. Chain geometric and artistic filters immutably
processed = dimg.mirror().grayscale().brightness(1.1)

[!NOTE] dimg.fill(color) Semantics: dimg.fill(color) fills transparent background pixels with color—compositing semi-transparent edge pixels over color while preserving all opaque foreground pixels as-is. To recolor the foreground tones of an image, use dimg.colorize(from_black_to=..., from_white_to=...).

3.1. I/O, Cloning & Inspection Methods

3.2. Geometry & Cropping Methods (5 Methods)

3.3. Transparency & Background Methods (3 Methods)

3.4. Color & Artistic Filter Methods (9 Methods)

3.5. Visual Showcase: Dimage Geometry, Filters & Border Styling

from drawlib.canvas import save, setup
from drawlib.images import Dimage, image
from drawlib.shapes import rectangle
from drawlib.styles import Colors, Styles
from drawlib.text import text

setup(width=132, height=66)

base = Dimage("../_assets/python.png")
w_px, h_px = base.get_image_size()

# Row 1: Geometry, Background Fill & Image Border Styling
row1 = [
    ("Original + Border", base, Styles.Primary.patch(image_border_width=1.8, image_border_color=Colors.Primary)),
    ("crop()", base.crop(w_px // 4, h_px // 4, w_px * 3 // 4, h_px * 3 // 4), None),
    ("mirror() + flip()", base.mirror().flip(), None),
    ("fill(Primary1)", base.fill(Colors.Primary1), Styles.Primary.patch(image_border_width=1.2, image_border_style="dashed", image_border_color=Colors.Primary4)),
]

for idx, (label, dimg_item, img_st) in enumerate(row1):
    cx = 19.5 + idx * 31
    rectangle((cx, 48), width=28.5, height=27, style=Styles.Neutral.patch(shape_r=2))
    image((cx, 51.5), width=13.5, image=dimg_item, style=img_st)
    text((cx, 38.5), label, style=Styles.DarkBold.patch(text_size=10.0))

# Row 2: Color & Artistic Filter Pipelines
row2 = [
    ("grayscale()", base.grayscale()),
    ("sepia()", base.sepia()),
    ("colorize()", base.colorize(Colors.Primary6, Colors.Primary1, Colors.Primary3)),
    ("mosaic() + blur()", base.mosaic(block_size=16).blur()),
]

for idx, (label, dimg_item) in enumerate(row2):
    cx = 19.5 + idx * 31
    rectangle((cx, 18), width=28.5, height=27, style=Styles.SecondaryNeutral.patch(shape_r=2))
    image((cx, 21.5), width=13.5, image=dimg_item)
    text((cx, 8.5), label, style=Styles.DarkBold.patch(text_size=10.0))

save()

4. Dynamic In-Memory Rendering (get_dimage_from_code)

Drawlib can execute a snippet of Drawlib Python code dynamically and return the rendered canvas directly as an in-memory Dimage. This enables recursive composition, zoomed inset callouts, and reusable sub-diagram templates.

get_dimage_from_code(
    code: str,
    timeout: float | None = None,
) -> Dimage

Subprocess Isolation Guarantees

• Clean Process Boundary: get_dimage_from_code() runs code inside an isolated multiprocessing.Process worker so the parent script's active canvas dimensions, artists, Styles, and Matplotlib global state remain completely untouched.
• Automatic save() Interception: Any save() calls inside code are automatically intercepted as no-ops in the worker process, preventing stray files from being written to disk before the rendered canvas is returned over an IPC pipe as a Dimage.

from drawlib.canvas import save, setup
from drawlib.images import get_dimage_from_code, image
from drawlib.shapes import rectangle
from drawlib.styles import Styles
from drawlib.text import text

# 1. Render a sub-component in an isolated subprocess with a 10s safety timeout
sub_code = """
from drawlib.canvas import save, setup
from drawlib.shapes import circle
from drawlib.styles import Styles

setup(width=40, height=40)
circle((20, 20), radius=15, style=Styles.PrimaryFlat, text="Pod", text_style=Styles.WhiteBold.patch(text_size=36))
save()
"""

sub_diagram = get_dimage_from_code(sub_code, timeout=10.0)

# 2. Embed the sub-diagram onto the primary canvas
setup(width=100, height=48)
rectangle((50, 24), width=74, height=38, style=Styles.MutedDashed)
image((50, 27), width=26, image=sub_diagram)
text((50, 10), "Host Canvas with Embedded Sub-Diagram", style=Styles.DarkBold.patch(text_size=11.0))

save()