Image Transformation Troubleshooting: Errors and Fixes

Error: Missing Arguments (too few or too many args)

Cause: You provided fewer or more than three arguments after main.py. The dispatcher requires exactly three: a command, a source path, and a destination directory. The exact error printed to the console is:

Missing Arguments. Run 'python main.py --help'

Fix: Make sure your command matches the expected shape exactly:

python main.py <command> <src> <dest>

Common mistakes that trigger this error:

# ✗ Missing dest argument
python main.py grayscale Input_Image/mountains.jpg

# ✗ Extra argument
python main.py grayscale Input_Image/mountains.jpg Output_Image/ --verbose

# ✓ Correct
python main.py grayscale Input_Image/mountains.jpg Output_Image/

Run python main.py --help to see the full list of commands and the expected syntax.

Error: Invalid arguments (unrecognised command)

Cause: The command name you provided is not one of the ten recognised commands. This is usually a typo or a capitalisation mismatch — all command names are lowercase and hyphenated. The exact error printed to the console is:

Invalid arguments. Run 'python main.py --help'

Fix: Check your spelling against the list of valid commands:

python main.py --help

Valid commands are: detect-edges, grayscale, upscale, downscale, flip, rotate, invert-color, contrast, rgb-channels, transparency.Common mistakes:

# ✗ Wrong separator
python main.py detect_edges Input_Image/mountains.jpg Output_Image/

# ✗ Wrong capitalisation
python main.py Grayscale Input_Image/mountains.jpg Output_Image/

# ✓ Correct
python main.py detect-edges Input_Image/mountains.jpg Output_Image/

FileNotFoundError when loading the image

Cause: The src path you provided does not point to an existing file. matplotlib.image.imread() raises a FileNotFoundError if the file cannot be found at the resolved absolute path.Fix: Verify that the file exists and that the path is correct relative to the directory you are running the command from (the project root). Use an absolute path if you are unsure:

# Check the file exists
ls Input_Image/mountains.jpg

# Run from the project root (where main.py lives)
python main.py grayscale Input_Image/mountains.jpg Output_Image/

# Or use an absolute path
python main.py grayscale /home/user/Image-Transformation/Input_Image/mountains.jpg /home/user/Image-Transformation/Output_Image/

Also confirm that the filename — including extension and capitalisation — matches exactly. On Linux and macOS, mountains.jpg and Mountains.jpg are different files.

Output directory does not exist / FileNotFoundError on save

Cause: The dest directory path you specified does not exist. Image Transformation calls matplotlib.image.imsave() with the fully constructed output path, but it does not create intermediate directories. If any part of the destination path is missing, the save will fail.Fix: Create the output directory before running the command:

# Linux / macOS
mkdir -p Output_Image/

# Windows (Command Prompt)
mkdir Output_Image

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path Output_Image

Then run your command as normal:

python main.py grayscale Input_Image/mountains.jpg Output_Image/

ModuleNotFoundError: No module named 'numpy' (or 'matplotlib')

Cause: The virtual environment is either not activated or the dependencies have not been installed into it yet. When you run python main.py outside the virtual environment, Python uses the system interpreter, which may not have numpy or matplotlib installed.Fix: Activate the virtual environment and install dependencies:

# Linux / macOS — activate the venv created by setup.sh
source .venv/bin/activate

# Windows — activate the venv created by setup.ps1
.\.venv\Scripts\Activate.ps1
# or use the convenience script generated by setup.ps1:
.\activate.ps1

# Install dependencies if not already installed
pip install -r requirements.txt

If you have not run the setup script yet, run it first:

# Linux / macOS
bash setup.sh

# Windows (PowerShell, run as Administrator if needed)
.\setup.ps1

Confirm the environment is active — your terminal prompt should show (.venv) before the path. Then retry your command.

Transparency output looks fully opaque (no transparency visible)

Cause: The source image is a JPEG (.jpg or .jpeg). The transparency command writes a 4-channel RGBA array into self.outp, but when Matplotlib saves the file it detects a JPEG extension and discards the alpha channel. The result is an opaque image regardless of the percentage you entered.

JPEG does not support an alpha channel. Any transparency applied to a JPEG source will be silently dropped when the file is saved. This is a fundamental limitation of the JPEG format, not a bug in Image Transformation.

Fix: Use a PNG source image so that the output file (which inherits the source extension) is also saved as PNG, preserving the alpha channel:

# ✗ JPEG — alpha will be discarded
python main.py transparency Input_Image/peslogo.jpg Output_Image/

# ✓ PNG — alpha is preserved
python main.py transparency Input_Image/peslogo.png Output_Image/
# Output: Output_Image/peslogo_transparency40.0.png

If your only available source is a JPEG, convert it to PNG first using any image editor or a tool like ImageMagick before running the transparency command.

rgb-channels keeps re-prompting 'Invalid input composition'

Cause: The value you entered does not match the regular expression ^r?g?b?$. The tool requires the channels to be specified as a combination of the lowercase letters r, g, and b in exactly that order. Uppercase letters, spaces, repeated letters, or any other character will all be rejected.Fix: Enter one of the seven valid compositions:

Input	Channels kept	Effect
`r`	Red only	Red tint
`g`	Green only	Green tint
`b`	Blue only	Blue tint
`rg`	Red + Green	Yellow tint (no blue)
`rb`	Red + Blue	Magenta tint (no green)
`gb`	Green + Blue	Cyan tint (no red)
`rgb`	All channels	Original colours

Common invalid inputs:

# ✗ Uppercase
Enter channel composition: RG

# ✗ Wrong order
Enter channel composition: gr

# ✗ Contains space
Enter channel composition: r g b

# ✓ Correct
Enter channel composition: rg

Rotation output has black borders or gaps around the image

Cause: This is expected behaviour. When the tool rotates an image by an arbitrary angle, it first calculates the new canvas dimensions needed to contain the entire rotated image without cropping, then fills that canvas with zeros (black pixels) before mapping the original pixels into their new positions. Any area of the new canvas that does not correspond to a pixel in the original image remains black.Fix: There is no built-in crop option. If you need a clean result without black borders, you have two options:

Rotate by a multiple of 90° — 90, 180, or 270 degrees produce no empty canvas regions because the bounding box does not grow.
Crop the output manually after rotating, using an external image editor or a Python script:

from src.imageEdit import imageEdit
import numpy as np
import matplotlib.image as mpimg

obj = imageEdit("Input_Image/building.jpg", "Output_Image/")
obj.loadImg()
obj.rotate()         # prompts for angle
obj.writeImg("rotated_" + str(obj.ang))

# Load the saved rotated image and crop manually
rotated = mpimg.imread(str(obj.dest))
# Example: crop 50px from each edge
cropped = rotated[50:-50, 50:-50]
mpimg.imsave("Output_Image/building_rotated_cropped.jpg", cropped)

os.system('start ...') does nothing on Linux or macOS

Cause: After saving the output file, main.py calls os.system(f"start {sys.argv[3]}") to open the destination folder. start is a Windows Command Prompt built-in; it has no equivalent under the same name on Linux or macOS, so the call exits silently without opening anything.Fix: This only affects the auto-open behaviour — the image is saved correctly regardless. To view the output, open it manually:

# Linux (GNOME)
xdg-open Output_Image/

# macOS
open Output_Image/

# Or open a specific file
xdg-open Output_Image/mountains_grayscale.jpg   # Linux
open Output_Image/mountains_grayscale.jpg        # macOS

This is a cosmetic limitation and does not affect image quality or correctness.

Get Started

Command Reference

API Reference

Guides

Image Transformation Troubleshooting: Errors and Fixes

Getting Help

Build docs developers (and LLMs) love

Get Started

Command Reference

API Reference

Guides

Documentation Index

​Getting Help

Build docs developers (and LLMs) love

Getting Help