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.

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

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

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.

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.

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

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

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

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

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

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

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

Modifies the brightness of the image.

• 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

Modifies the contrast of the image.

• 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

Applies an emboss effect to the image.

• 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

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

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

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

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

Applies a gaussian blur to the image.

• 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

Create a negative of the image.

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

Applies motion blur to the image.

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

Highlights edges of the image.

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

Converts an RGB image to a grayscale image.

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

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

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

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

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

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

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

Modify the color saturation of the image.

• 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

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

• 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

Applies a sepia tone to an RGB image.

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

Modify the color saturation of the image.

• 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

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

• 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