Image Histogram Tool

Project roadmap

1. 01

   Set up the project and sample images

   ~1h

   Create a CMake project in C11 with warnings enabled and a histo program that takes an image path and options. Create a few test images in the binary PPM format (P6), for example by converting photos with ImageMagick (convert photo.jpg photo.ppm) or GIMP, and save them in samples/. Done when: the project builds, and the sample images are in the repo.

2. 02

   Read PPM images

   ~2.5h

   Write read_ppm(path) that opens the file in binary mode, reads the header (the magic number P6, width, height and a maximum value of 255, skipping comment lines that start with #), then reads width × height × 3 bytes of pixel data. Check for overflow before multiplying the dimensions, and reject files that are truncated or have unsupported values, with clear error messages. Done when: the sample images load, and a truncated or invalid file gives a clear error.

3. 03

   Calculate histograms

   ~1.5h

   Compute four arrays of 256 counters: red, green, blue, and grayscale using the luminance formula 0.299 R + 0.587 G + 0.114 B, rounded. Put this in its own function that takes the image and fills a Histograms struct. Done when: for a small test image you create by hand, the counts match what you expect.

4. 04

   Print statistics

   ~1.5h

   For each channel, compute the mean, minimum, maximum, the most common value and the median (found by walking the histogram until half the pixels are counted). Print them in an aligned table, and add an estimate of whether the image is dark, balanced or bright based on the grayscale mean. Done when: the statistics are correct for a solid-color test image and plausible for photos.

5. 05

   Draw the histograms

   ~2h

   Add --text to print each histogram as horizontal bars in the terminal, grouping the 256 values into 32 bins and scaling the bars to 60 characters. Add --out file.ppm to draw the histograms into a new 512×400 PPM image, with one colored graph per channel. Done when: the text chart prints correctly, and the output image opens in an image viewer.

6. 06

   Test it

   ~1.5h

   Write tests run by ctest: create small images in code (a solid color, a two-color image, a gradient), compute their histograms and statistics, and check the exact values. Include invalid files: a wrong magic number, a truncated file and huge dimensions. Run the tests under valgrind to check for leaks. Done when: ctest passes and valgrind reports no leaks.

Resources

• DocsPPM format specification (Netpbm)
• ArticleImage histogram (Wikipedia)
• DocsC reference (cppreference)
• DocsCMake tutorial