Huehistogram

A python script to create "hue" histogram of a colored image.

TLDR

Use python >=3.8. This project uses astral-sh/uv as its project manager (and you should try it). Install Huehistogram by cloning this repo and uv sync to install dependencies.

You have a following image on docs/images/pexels-nietjuh-1883385.jpg (A photo by Ylanite Koppens on Pexels: https://www.pexels.com/ja-jp/photo/1883385)

Run the following command to generate a hue histogram of this image:

python src/huehistogram_cli.py -i docs/images/pexels-nietjuh-1883385.jpg -o docs/images/out/pexels-nietjuh-histogram.png

Now open docs/images/out/pexels-nietjuh-histogram.png to see the hue histogram:

Usage

Note

Run src/huehistogram_cli.py without arguments to see all available options.

Generate a histogram of an image

Use -i option with path to image, then use -o option with path to output directory or path with a filename and extension that you want your histogram to have. The following is an example of specifying filename as output:

python src/huehistogram_cli.py -i path/to/input_image.png -o path/to/output_histogram.png

If you use -o option with a path to existing directory, the output filename will be same as the input filename. Let's run the following command:

python src/huehistogram_cli.py -i path/to/input_image.png -o path/to/output_dir/

... and you will get path/to/output_dir/input_image.png as output.

Important

If you do not specify output filename, the filename and the extension of the output file(s) will be same as input file(s). If you want PNG or something make sure to specify output filename.

Note

In default behavior, the script will NOT overwrite existing files. If you need to overwrite existing files, use -f ( --force-overwrite) option to recklessly overwrite existing files.

Generate histograms of multiple images

Tip

Huehistogram processes multiple files concurrently. It will simply execute multiple instances of itself so overall RAM usage will be around 1.5 GB with 8 JPEG images in 4K resolution. If you want to adjust the number of instances, modify the following in src/Huehistogram/huehistogram.py:

with ProcessPoolExecutor(max_workers=8) as executor:

and change the number after max_workers=.

-i option accepts multiple paths to images. Use -o option with output path to directory:

python src/huehistogram_cli.py -i path/to/im1.png path/to/im2.png -o path/to/output_dir/

Important

You cannot use -o option with filename when you input multiple images.

If you want to bulk-process all images in a directory, use -dir --directory-input option:

python src/huehistogram_cli.py -dir path/to/directory -o path/to/output_dir/

Important

You cannot use -o option with filename in this case.

Additional options

• -v --verbose: Show many progress messages.
• -f --force-overwrite: Overwrite existing files even when output file already exists.
• --dpi: Specify DPI for your histogram. Default to default DPI of matplotlib.