ccolors/AGENTS.md

AGENTS.md

Project summary

ccolors is a command-line utility that extracts dominant color palettes from images and outputs both terminal-colored swatches and a JSON file containing the extracted colors. It features a single-file design where all functionality is contained in main.cpp with no subdirectories, utilizing standard C++17 and the stb_image.h header-only library.

Build/test/lint commands

• Build requirements:
  • Compiler: C++17 compliant (g++/clang++)
  • CMake: Version 3.10+
  • CMake configuration:

    cmake_minimum_required(VERSION 3.10)
    project(ccolors)
    set(CMAKE_CXX_STANDARD 17)
    add_executable(ccolors main.cpp)
    

• Test: The single-file architecture makes unit testing difficult.
• Lint / Code style rules:
  • 4-space indentation
  • No complex macros

Code style rules

• Variables: snake_case (imagefile), CamelCase (Pixel)
• Constants: UPPER_SNAKE_CASE (argv, STB_IMAGE_IMPLEMENTATION)
• Functions: snake_case (is_jpeg, is_png)
• Namespaces: Alias-based (fs for std::filesystem)
• Code Structure Patterns:
  • Early returns for error handling
  • Forward declarations before use
  • Type aliases for commonly used types
  • Defensive programming with comprehensive error checking
  • 4-space indentation, no complex macros

Directory structure and where things are located

• Single-file design: All functionality is contained in main.cpp in the root directory. There are no subdirectories.
• Dependencies: stb_image.h header-only library.

Constraints agents must adhere to

• Single-file design: All core logic, data structures, algorithms, and I/O must remain in main.cpp with no separation of concerns.
• Standard Compatibility: Must be C++17 compliant.
• Dependencies: Keep external dependencies limited to standard library and the included header-only stb_image.h.
• Downsampling & Filtering: Color extraction must downsample pixels (step = 10) and filter out pixels with brightness < 60 and saturation < 10.
• Fixed-size Output: Output must be limited to the top 5 colors.
• Quantization: Colors must be quantized into 16×16×16 buckets (4096 keys).
• Statelessness: Operation must remain stateless with no persistent storage or global state between runs.