Imported from garbsam97/RAW_DEV (AGENTS.md). Install upstream with npx skills add garbsam97/RAW_DEV. Copyright stays with the author.

AGENTS.md

Scope and source of truth

• This repo is a C++20 RAW-processing playground centered on rawdev_core; most exercised behavior still lives in tests.
• The GUI direction is src/gui/, which is reserved for Qt6-based interface code.
• Treat tracked files under root, src/, and tests/ as source of truth; ignore cmake-build-debug/ for design decisions.
• Root main.cpp is not part of any target.

Build graph that is actually wired

• Root CMakeLists.txt adds only src/ and tests/; testing is globally enabled.
• src/core/ builds rawdev_core from image, pipeline, PNG writer, and stage sources (white balance, black level, color matrix, gamma correction, tone mapping, sRGB color transform).
• src/cli/ builds rawdev_cli from main.cpp, cli_options.*, and cli_runner.*; it links rawdev_core and now supports end-to-end process execution on real input/output paths through the core facade.
• src/gui/ builds rawdev_gui as a Qt6 executable (qt_add_executable) from main_gui.cpp, main_window.*, widgets/image_view_widget.*, and controllers/app_controller.*.
• src/modules/ links rawdev_core against libraw::libraw via src/modules/libraw-cmake; RAW ingestion is now implemented in src/core/src/coreapi/import.cpp.
• tests/ builds rawdev_tests (GoogleTest IO/pipeline/golden/coreapi/CLI/LLVM suite) and rawdev_benchmarks (lightweight performance harness).

Core architecture and data flow

• Public headers live in src/core/include/rawdev/...; implementations live in src/core/src/....
• rawdev::image::Image (src/core/include/rawdev/image/image.h) owns RGB data in std::vector<float> sized w * h * 3.
• Memory layout is interleaved RGB, not planar: Image::view() builds ImageView(data, w, h, 3, w * 3) and ImageView::at(x,y,c) indexes y*stride + x*channels + c.
• rawdev::pipeline::Pipeline (src/core/src/pipeline/pipeline.cpp) uses fast paths for empty pipelines and single in-place-capable stages, otherwise ping-pongs two ImageViews (original + scratch buffer) across ProcessingStages, then copies back if needed.
• Pipeline::supportsInPlace() is now used by execute() for the single-stage in-place fast path.
• Current stages: WhiteBalanceStage, BlackLevelStage, ColorMatrixStage, GammaCorrectionStage, ToneMappingStage, ColorTransformSrgbStage.
• ToneMappingStage now has a guarded OpenMP path on a safe pixel loop when RAWDEV_USE_OPENMP=1; serial fallback remains the default behavior when OpenMP is unavailable.
• ProcessingStage contract in src/core/include/rawdev/pipeline/pipeline.h now documents shape invariants and in-place expectations; contract tests are in tests/pipeline/test_stage_contracts.cpp.
• rawdev::coreapi::importRawImage (src/core/include/rawdev/coreapi/import.h) is the core-facing LibRaw import boundary that maps RAW decode failures to stable core-level errors.
• rawdev::coreapi::processImage (src/core/include/rawdev/coreapi/process.h) is the current high-level processing facade; it still supports in-memory input and can now also import RAW files via ProcessRequest::inputRawPath.
• Golden fixtures under tests/golden/fixtures/ now provide deterministic seed images for stage golden tests, and regression coverage includes interleaved layout plus pipeline copy-back checks.
• Additional regression coverage includes OpenMP tone-mapping parity (tests/pipeline/test_openmp_tone_mapping_parity.cpp) and RAW import success/failure (tests/io/test_raw_import.cpp).
• Benchmark baselines are tracked under tests/benchmark/ for reproducible median-based comparisons.

GUI boundary (Qt6)

• Keep GUI concerns in src/gui/; keep image processing and reusable logic in rawdev_core.
• Current GUI scaffolding splits responsibilities by layer:
  • main_gui.cpp: Qt app bootstrap
  • main_window.*: window composition and actions
  • controllers/app_controller.*: GUI-to-core orchestration
  • widgets/image_view_widget.*: preview widget surface
• Current phase-1 GUI wiring keeps minimal app state in AppController (hasImage_, currentPath_, lastStatus_) and updates UI via statusMessageChanged/imageAvailabilityChanged signals; Run Pipeline starts disabled until an image is marked as loaded.
• Current phase-2 GUI preview adds ImageViewWidget::setImage(...), clearImage(), hasImage(), and fit-centered rendering in paintEvent(...).
• Current phase-3 GUI adapter wiring converts core images through rawdev::gui::adapters::toQImage(...) in AppController::openRaw() and updates preview through previewImageChanged.
• Prefer calling rawdev_core from GUI adapters/controllers instead of embedding processing logic inside Qt widgets.
• Avoid introducing Qt types in public rawdev_core headers unless explicitly required by architecture changes.

CLI boundary

• Keep CLI-specific argument parsing and user-facing messages in src/cli/.
• Current CLI scaffolding splits responsibilities by file:
  • main.cpp: argv collection + command dispatch
  • cli_options.*: command-line parsing (ParsedCommand, ProcessOptions)
  • cli_runner.*: command execution flow and exit codes
• Treat cli_runner as the integration boundary toward rawdev_core; keep reusable processing logic in core.
• Current process path is integrated with rawdev::coreapi::processImage using real --input/--output paths (inputRawPath + PNG write). --white-balance is now parsed as a typed r,g,b triplet with strict validation.

External dependencies and toolchain gotchas

• Git submodules in .gitmodules: src/modules/libraw (0.22-stable), src/modules/libraw-cmake, src/modules/llvm (release/22.x).
• rawdev_core uses find_package(OpenMP) and defines RAWDEV_USE_OPENMP=1 only when OpenMP is found.
• On macOS/CLion, OpenMP may require -DOpenMP_ROOT=/opt/homebrew/opt/libomp.
• tests/CMakeLists.txt requires LLVM via find_package(LLVM REQUIRED CONFIG) and links Core, OrcJIT, ExecutionEngine, Support, native.
• If CLion cannot find LLVM, set LLVM_DIR to a folder containing LLVMConfig.cmake (commonly .../dist/lib/cmake/llvm).
• src/gui/CMakeLists.txt requires Qt6 components Core, Gui, Widgets.
• Keep strict warnings on first-party code; suppress third-party warning noise at integration points instead of weakening global flags.

Developer workflow in this workspace

• Default workflow is CLion-first: reload/update CMake from CLion, then build/run rawdev_tests, rawdev_benchmarks, rawdev_cli, or rawdev_gui.
• CLI fallback:

  cmake -S . -B build
  cmake --build build
  ctest --test-dir build --output-on-failure

• Benchmark fallback:

  cmake --build build --target rawdev_benchmarks
  ./build/tests/benchmark/rawdev_benchmarks --out tests/benchmark/baseline_0.3.0-alpha.csv --runs 20 --warmup 5 --max-size 4096 --tag m5-baseline-macos

• GoogleTest is fetched with FetchContent at tag v1.14.0; test discovery uses gtest_discover_tests(rawdev_tests).

Project conventions to preserve

• Keep established target names: rawdev_core, rawdev_cli, rawdev_gui, rawdev_tests, rawdev_benchmarks.
• Prefer adding reusable functionality to rawdev_core first, then covering it in tests before wiring CLI/GUI.
• Keep GUI scaffolding modular (main_window, controllers, widgets) and treat controllers as the boundary toward rawdev_core.
• Use public include paths like #include "rawdev/image/image.h"; avoid relative includes in new public headers.
• Mirror new features with focused tests under tests/io/, tests/pipeline/, tests/golden/, tests/coreapi/, tests/cli/, tests/llvm/, and benchmark additions under tests/benchmark/.
• When writing tests over Image::data, keep channel indexing consistent with interleaved RGB layout.
• Follow Semantic Versioning for project releases; current pre-release line is 0.4.2-alpha.

Existing instruction sources discovered

• AGENTS.md
• README.md
• tests/benchmark/README.md
• src/modules/libraw/README.md
• src/modules/libraw/RawSpeed3/README.md
• src/modules/libraw-cmake/README.md
• src/modules/llvm/README.md