GPU Image Filter (CPU and CUDA)

Interactive image filtering and benchmarking in C++/CUDA with simple 2D convolution kernels. Includes CPU and GPU implementations, plus micro-benchmarks.

---

Features

• CPU and CUDA implementations of 2D convolution-based filters
• Interactive CLI to choose filters and parameters
• Outputs filtered grayscale PNGs to the data directory
• Benchmarking utilities for CPU and GPU paths

---

Project structure

GPU_image_filter/
  benchmarking/                  # Standalone CPU/GPU benchmark programs
    00_cpu_conv2d_benchmark.cpp
    01_gpu_conv2d_benchmark.cu
    03_gpu_conv2d_pinnedConstMem_bench.cu
  bin/                           # Compiled binaries 
  build/                         # Optional build artifacts
  data/                          # Input images and generated outputs
  include/                       # Public headers
    00_cpu_conv2d.hpp
    01_gpu_conv2d.cuh
    02_gpu_conv2d_constMem.cuh
    utils.hpp
  lib/                           # Third-party single-header libs
    stb_image.h
    stb_image_write.h
  scripts/                       # CLI entry programs
    cpu_filter.cpp               # CPU interactive filter
    01_gpu_filter.cu             # CUDA interactive filter (const memory)
  src/                           # Library/implementation files
    cpu_conv2d.cpp
    gpu_conv2d_constMem.cu
    gpu_cov2d.cu                 # Alternate/experimental GPU kernel
    utils.cpp

---

Requirements

• For CPU build: a C++17 compiler (e.g., Clang or GCC)
• For GPU build: NVIDIA GPU and CUDA Toolkit (nvcc)
• stb_image.h and stb_image_write.h are bundled under lib/

---

Build

Create the bin directory if it doesn’t exist:

mkdir -p bin

CPU (Clang/GCC):

clang++ -std=c++17 -O2 \
  scripts/cpu_filter.cpp src/cpu_conv2d.cpp src/utils.cpp \
  -Iinclude -Ilib -o bin/cpu_filter

CUDA (nvcc):

nvcc -std=c++17 -O2 \
  scripts/01_gpu_filter.cu src/gpu_conv2d_constMem.cu src/utils.cpp \
  -Iinclude -Ilib -o bin/gpu_filter

Benchmarks (optional):

clang++ -std=c++17 -O2 benchmarking/00_cpu_conv2d_benchmark.cpp \
  src/cpu_conv2d.cpp src/utils.cpp -Iinclude -Ilib -o bin/cpu_bench

nvcc -std=c++17 -O2 benchmarking/01_gpu_conv2d_benchmark.cu \
  src/gpu_conv2d_constMem.cu src/utils.cpp -Iinclude -Ilib -o bin/gpu_bench

nvcc -std=c++17 -O2 benchmarking/03_gpu_conv2d_pinnedConstMem_bench.cu \
  src/gpu_conv2d_constMem.cu src/utils.cpp -Iinclude -Ilib -o bin/gpu_bench_pinned

---

Run

Make sure your input image exists (e.g., put one in data/sample.png). The apps are interactive: they will prompt for the image path and for a filter.

CPU:

./bin/cpu_filter
# Enter image location: data/lena.png
# Choose a filter when prompted. Output: data/filtered_img.png

CUDA:

./bin/gpu_filter
# Enter image location: data/lena.png
# Choose a filter when prompted. Output: data/filtered_image.png

Note: The CPU program writes data/filtered_img.png, while the CUDA program writes data/filtered_image.png.

---

Available filters

When prompted, enter one of:

• Sharpen (prompts for alpha in (0,1); default 0.8)
• High-pass
• Low-pass (prompts for alpha; default 9.0)
• Gaussian (prompts for alpha; default 16.0)
• d_Gaussian
• q to quit

All filters operate on a 3×3 kernel with radius 1 and run on a grayscale version of the input image. Internally the image is padded to a square of size max(width, height) for processing, then written at the original width × height.

---

Troubleshooting

• CUDA build errors on macOS/Apple Silicon: CUDA is not supported; build the CPU target instead.
• Missing stb_image symbols: ensure -Ilib is present and you compile the appropriate .cpp/.cu files that include stb headers.
• Permission denied when running binaries: chmod +x bin/* or re-create bin.

---

Acknowledgements

• Uses stb_image.h and stb_image_write.h by Sean Barrett (public domain / MIT-like).