bpimage

bpimage is a simple image editing library which can be used from the command line. Basic image transformations, color editing, and convolution filters are implemented.

Created mainly so I could explore numpy, image processing, cli development, and extending python with c.

Commands

• preview
• dest
• boxblur
• brightness
• contrast
• emboss
• fliph
• flipv
• gaussian
• invert
• motionblur
• outline
• rgb2gray
• rotate
• rotate90
• saturation
• scale
• sepia
• sharpen
• shear

Dependencies

• python (>= 3.10)
• numpy (>= 1.22)
• Pillow (>= 9.1.1)
  • used only for io tasks such as loading, saving and previewing images

Installation

From Source

bpimage depends on functions written in multiple c files. These files must be compiled into a shared library so they can be invoked from python.

Prerequisites

You will need:

• A c compiler, such as gcc.

Linux

# checkout project if you have not already.
git clone https://github.com/beakerandjake/bpimage.git
# change your pwd to the root of the project.
cd bpimage
# compile all source c files into a shared library.
gcc -fPIC -shared -O3 bpimage/*.c -o bpimage.so

This will create a bpimage.so file. This file will be loaded in python and used by the library to perform image manipulation.

CLI Usage

First ensure that you have compiled the c files and that your pwd is the root of the project.

cd bpimage

You can print help by running the command without arguments, or with the --help option.

python3 bpimage/main.py --help

The first argument expected is the source image file. Then you can specify zero one or more edits to apply to the image. Finally you need to specify an output. The output could either be saved to a new file or previewed.

Here is an example which rotates an image 90 degrees, inverts the colors, then saves it to a new file.

python3 bpimage/main.py ~/Pictures/example.png --rotate90 --invert -d ~/Pictures/output.png

Commands

preview (-p)

Creates a temporary file and opens the image with the systems default image viewer. Useful for testing commands and immediately seeing the result. Cannot be used with dest (-d).

python3 bpimage/main.py ~/Pictures/example.png --invert -p

dest (-d)

Saves the image to the specified location. Cannot be used with preview (-p).

python3 bpimage/main.py ~/Pictures/example.png -d ~/Pictures/output.png

boxblur

Blurs each pixel by averaging all surrounding pixels extending radius pixels in each direction.

Arguments:

• radius (int): Number of pixels to take in each direction.

python3 bpimage/main.py ~/Pictures/example.png --boxblur 2 -d ~/Pictures/output.png

brightness

Modifies the brightness of the image.

Arguments:

• strength (float): The amount to brighten or darken the image. A value of 0.0 will result in a black image, 1.0 gives the original image.

python3 bpimage/main.py ~/Pictures/example.png --brightness 1.5 -d ~/Pictures/output.png

contrast

Modifies the contrast of the image.

Arguments:

• strength (float): The amount to brighten or darken the image. A value of 0.0 will result in a gray image, 1.0 gives the original image.

python3 bpimage/main.py ~/Pictures/example.png --contrast 1.8 -d ~/Pictures/output.png

emboss

Applies an emboss effect to the image.

Arguments:

• direction (str): One of the following supported values.
  • 'u' Emboss from top to bottom
  • 'd' Emboss from bottom to top
  • 'l' Emboss from left to right
  • 'r' Emboss from right to left
• strength (float): The number of surrounding pixels to take in each direction.

python3 bpimage/main.py ~/Pictures/example.png --emboss r 1 -d ~/Pictures/output.png

fliph

Flips the image across the horizontal, from bottom to top.

python3 bpimage/main.py ~/Pictures/example.png --fliph -d ~/Pictures/output.png

flipv

Flips the image across the vertical, from left to right.

python3 bpimage/main.py ~/Pictures/example.png --flipv -d ~/Pictures/output.png

gaussian

Applies a gaussian blur to the image.

Arguments:

• radius (int): The number of pixels to take in each direction.
• sig (float): The sigma of the gaussian function. Higher values result in more blurring.

python3 bpimage/main.py ~/Pictures/example.png --gaussian 2 6.0 -d ~/Pictures/output.png

invert

Create a negative of the image.

python3 bpimage/main.py ~/Pictures/example.png --invert -d ~/Pictures/output.png

motionblur

Applies motion blur to the image.

python3 bpimage/main.py ~/Pictures/example.png --motionblur -d ~/Pictures/output.png

outline

Highlights edges of the image.

python3 bpimage/main.py ~/Pictures/example.png --outline -d ~/Pictures/output.png

rgb2gray

Converts an RGB image to a grayscale image.

python3 bpimage/main.py ~/Pictures/example.png --rgb2gray -d ~/Pictures/output.png

rotate

Rotates the image counter-clockwise by a specified angle around the center. Optionally expands the canvas size to hold the rotated image.

Arguments:

• angle (float): The amount of degrees to rotate the image.
• expand (boolean): Should the canvas be expanded to hold the rotated image?

Example:

python3 bpimage/main.py ~/Pictures/example.png --rotate 45 true -d ~/Pictures/output.png

rotate90

Rotates the image counter-clockwise 90 degrees around the center n times.

Arguments:

• times (integer): Number of times to rotate the image.

Example:

python3 bpimage/main.py ~/Pictures/example.png --rotate90 3 -d ~/Pictures/output.png

saturation

Modify the color saturation of the image.

Arguments:

• strength (float): The amount to modify the saturation. A value of 0.0 will result in a black and white image, 1.0 gives the original image.

python3 bpimage/main.py ~/Pictures/example.png --saturation 1.8 -d ~/Pictures/output.png

scale

Re-sizes the image uniformly based on a scale factor.

Arguments:

• scale (float): Non-zero positive number multiplied by the width and height of the image to determine the dimensions of the resulting image.

python3 bpimage/main.py ~/Pictures/example.png --scale .5 -d ~/Pictures/output.png

sepia

Applies a sepia tone to an RGB image.

python3 bpimage/main.py ~/Pictures/example.png --sepia -d ~/Pictures/output.png

sharpen

Modify the color saturation of the image.

Arguments:

• strength (float): The amount to modify the saturation. A value of 0.0 will result in a black and white image, 1.0 gives the original image.

python3 bpimage/main.py ~/Pictures/example.png --shear .25 0 true -d ~/Pictures/output.png

shear

Shears the image in the specified dimension(s). Optionally expands the canvas size to hold the rotated image.

Arguments:

• shear_x (float): The amount to shear the image in the x axis (0.0 does nothing)
• shear_y (float): The amount to shear the image in the y axis (0.0 does nothing)
• expand (bool): If true, expands the dimensions of resulting image so it's large enough to hold the entire skewed image.

python3 bpimage/main.py ~/Pictures/example.png --shear .25 0 true -d ~/Pictures/output.png