Dimage

The image() function draws an image from a file. If you want to specify a file path and show it as is, providing a relative path is acceptable.

Dimage is an image data class in Drawlib. It is useful in the following situations:

• Applying effects to images

• Caching (loading data in one place and using it in many places)

The image() function can take a Dimage object and draw the image.

Image Cache Feature

Each illustration code can refer to image files for drawing the image. If the image is used only in the code, this is fine.

However, if many of your illustration codes refer to the same image file, pointing to the same file is not ideal. In such cases, changing the file name and location becomes difficult. Dimage’s cache feature is useful in this situation. You can cache the image in the style code, and all illustration codes can access it through the cache name.

Dimage possesses a class attribute cache. This means you can access it like Dimage.cache. It is an image cache management object with the following methods:

• has(name:str): Checks if the cache exists

• set(name:str, image:str|Dimage|PIL.Image): Caches image data with the specified name

• list(): Gets all cache names

• get(name:str): Retrieves cache data by name

• delete(name:str): Deletes cache data

Here is an example:

image_cache.py

from drawlib.apis import *

config(width=100, height=50)
Dimage.cache.set("linux", "linux.png")
im = Dimage.cache.get("linux")
image((50, 25), 25, im)
save()

In this example, we first cache an image using the set() function. The function has an image argument, which can handle a string (file name), Dimage object, or PIL.Image object. When you cache an image with a name, the object is automatically copied or converted to a Dimage internally.

You can retrieve the image using the get() function. It will return the copied image data that matches the key name.

Here is the output:

Not only can you cache images loaded from files, but you can also cache images you have modified. If you repeatedly use some images, we recommend using this feature as well.

Things Controlled by image()

Dimage is a helper for the image() function. Therefore, Dimage does not include features that are implemented in image(). These features are not included:

• Rotate: Controlled by the angle option

• Add Border: Controlled by the lwidth and lcolor attributes of ImageStyle

Save Dimage to File

Dimage can save its data to a file without using Drawlib’s canvas. The save() method performs this function. It requires a mandatory argument, file. While the file argument in Canvas’s save() is optional, it is required for Dimage’s save().

If you provide a relative path, the image file will be saved relative to the script’s path. An absolute path will also work.

Get Image Pixel Size

You can get the original image size using the get_image_size() method. It returns a tuple of width and height.

This method is helpful for determining the dimensions of the image before performing operations like resize() or trim()

Resizing and Changing Aspect

The resize() method in Dimage takes two arguments: width and height. These dimensions refer to the original pixel size of the image data, not the size on Drawlib’s canvas.

Before resizing, you can check the original width and height using the get_image_size() method. If you want to maintain the aspect ratio of the original image, you should calculate either the new width or the new height while keeping the ratio between them. If you want to change the aspect ratio, you need to calculate both the new width and height accordingly.

Here’s an example of changing the aspect ratio where we halve the image height:

image_getsize_resize.py

from drawlib.apis import *

config(width=100, height=50, dpi=200)

# original
original_image = Dimage("linux.png")
image((25, 30), 20, original_image)
text((25, 15), "original")
width, height = original_image.get_image_size()
text((25, 10), f"width={width}, height={height}")

# resize
new_height = int(height / 2)
resized_image = original_image.resize(width, new_height)
image((75, 30), 20, resized_image)
text((75, 15), "resize()")
text((75, 10), f"width={width}, height={new_height}")

save()

In this example, we retrieve the original image dimensions using get_image_size(). And then resize the image using resize(). We keep original width, but new height is half of original. Finally, the resized image is drawn with image() function.

Here is the output:

resize

Crop

If an image contains unnecessary parts, you can trim or crop it using the crop() method. This method accepts the following arguments:

• x: Specifies the starting point from the left (0 to x pixels will be cropped).

• y: Specifies the starting point from the bottom (0 to y pixels will be cropped).

• width: Specifies the width of the cropped area starting from x.

• height: Specifies the height of the cropped area starting from y.

Here’s an example that keeps the center 50% of the image:

image_crop.py

from drawlib.apis import *

config(width=100, height=50, dpi=200)

# original
original_image = Dimage("linux.png")
image((25, 25), 20, original_image, style=ImageStyle(lwidth=1))
text((25, 10), "original")
width, height = original_image.get_image_size()

# trimming
x_start = int(width / 4)
crop_width = int(width / 2)
y_start = int(height / 4)
crop_height = int(height / 2)
cropped_image = original_image.crop(x_start, y_start, crop_width, crop_height)
image((75, 25), 20, cropped_image, style=ImageStyle(lwidth=1))
text((75, 10), "crop()")

save()

In this example, we calculate the cropping parameters to keep the center 50% of the image. We then use the crop() method to apply the cropping operation to the Dimage object. Finally, the cropped image can be used in drawing operations with image().

Here is the output:

crop()

Flip Horizontally and Vertically

You can easily flip an image using Dimage:

• Horizontal Flip: Use the mirror() method.

• Vertical Flip: Use the flip() method.

Here’s an example:

image_mirror_flip.py

from drawlib.apis import *

config(width=100, height=50, dpi=200)

# original
original_image = Dimage("linux.png")
image((20, 25), 20, original_image)
text((20, 10), "original")

# mirror
image((50, 25), 20, original_image.mirror())
text((50, 10), "mirror()")

# flip
image((80, 25), 20, original_image.flip())
text((80, 10), "flip()")

save()

Here is the output:

Change color

Drawlib provides several functions to modify the color of images:

• grayscale(): Converts the image to grayscale

• sepia(): Applies a sepia tone effect to the image

Here’s an example:

image_grayscale_sepia.py

from drawlib.apis import *

config(width=100, height=50, dpi=200)

# original
original_image = Dimage("linux.png")
image((20, 25), 20, original_image)
text((20, 10), "original")

# grayscale
image((50, 25), 20, Dimage("linux.png").grayscale())
text((50, 10), "grayscale()")

# sepia
image((80, 25), 20, original_image.sepia())
text((80, 10), "sepia()")

save()

Here is the output.

• brightness(): Adjusts the brightness of the image

A value of 0.0 makes the image completely dark, 1.0 keeps the original brightness, and values greater than 1.0 increase the brightness.

Here’s an example:

image_brightness.py

from drawlib.apis import *

config(width=100, height=50, dpi=200)

image((20, 25), 20, Dimage("linux.png").brightness(0.5))
text((20, 10), "brightness(0.5)")

image((50, 25), 20, Dimage("linux.png").brightness(1.0))
text((50, 10), "brightness(1.0): Original")

image((80, 25), 20, Dimage("linux.png").brightness(2.0))
text((80, 10), "brightness(2.0)")

save()

Here is an output.

• invert(): Reverses the RGB values of the image

• colorize(): Applies colors to a grayscale image. If the image is not grayscaled, it will be automatically grayscaled before colorize.

image_invert_colorize.py

from drawlib.apis import *

config(width=100, height=50, dpi=200, background_color=Colors.Gray)
tstyle = TextStyle(color=Colors.White)

# invert
image((20, 25), 20, Dimage("linux.png").invert())
text((20, 10), "invert()", style=tstyle)

# brightness
image(
    (50, 25),
    20,
    Dimage("linux.png").colorize(
        from_black_to=Colors.Blue,
        from_white_to=Colors.Red,
    ),
)
text((50, 10), "colorize()", style=tstyle)

# invert (rectangle is just background)
image(
    (80, 25),
    20,
    Dimage("linux.png").colorize(
        from_black_to=Colors.Blue,
        from_white_to=Colors.Red,
        from_mid_to=Colors.Green,
    ),
)
text((80, 10), "colorize()", style=tstyle)

save()

Here is the output.

Apply Effects

You can apply various effects to images using Drawlib:

• mosaic(): Applies a mosaic effect to the image. You can specify the size of mosaic blocks with the optional block_size argument. Default is 8.

• blur(): Applies a blur effect to the image

Here’s an example:

image_mosaic_blur.py

from drawlib.apis import *

config(width=100, height=50, dpi=200)

image((20, 25), 20, Dimage("linux.png").mosaic(8))
text((20, 10), "mosaic(8)")

image((50, 25), 20, Dimage("linux.png").mosaic(16))
text((50, 10), "mosaic(16)")

image((80, 25), 20, Dimage("linux.png").blur())
text((80, 10), "blur()")

save()

Here is the output.