Text-on-Images (Napisy na zdjęciach)

Uwaga: Plik wykonywalny (.exe) po zbudowaniu projektu znajduje się w katalogu: BIN/x64/Release

📝 Project Overview

Desktop application for browsing image folders, previewing thumbnails, reading EXIF/IPTC/GPS metadata and generating new images with a text overlay (single file or batch processing).
Built with C++20, wxWidgets (GUI) and Exiv2 (metadata).

Key features:

• Recursive directory scan for supported image formats
• Thumbnails list (128×128) with checkbox selection
• Live filtering (Search) + “Only checked” mode + counters (total/shown/checked)
• Metadata panel (basic info + EXIF/IPTC dump)
• Zoom view (double-click to toggle)
• CSV report generation for checked images (user-selected columns)
• Writing custom text or selected metadata fields onto images
• Batch processing for checked files
• Captions file support (filename;text) for batch text

Output images are saved next to the original file as: <name>_with_text.jpg (originals are not overwritten).

---

🏗 System Architecture

The application is divided into three main modules:

1. ImageInfo – represents a single image and its metadata (EXIF/IPTC/GPS), generates thumbnails and images with overlays.
2. ImageManager – manages a collection of images, selection state, reports and batch processing.
3. GUIMyFrame1 – wxWidgets GUI layer: list view, filtering, stats, metadata view, zoom and menu actions.

---

📚 Technical API Reference

1) Class: ImageInfo

Encapsulates all data and logic related to a single image file.

Public structures:

• BasicInfo
  • width, height – image dimensions
  • mimeType – file format (e.g. image/jpeg)
  • fileSize – bytes
  • filePath – full path (std::filesystem::path)
  • modificationTime – filesystem timestamp
• GpsData – latitude/longitude/altitude (stored via std::optional)
• ExposureInfo – aperture, shutter speed, ISO, focal length

Key methods:

• ImageInfo(path) – initializes basic file information
• getExifValue(key), getIptcValue(key) – fetch metadata values
• getExposureInfo(), getCameraInfo()
• hasGps(), formatGpsCoordinates()
• getThumbnail() – extracts embedded EXIF thumbnail (if available)
• generate_miniature() – creates a 128×128 wxImage preview
• generateImageWithText(...) – generates a new image with text overlay
• isSupportedImage(path) – checks allowed extensions

Important implementation notes:

• Uses lazy-loading (_metadataLoaded) to avoid reading metadata repeatedly.
• Thumbnail extraction uses Exiv2 DataBuf::data() and DataBuf::size() (compatible with newer Exiv2 versions).
• GUI displays filenames correctly even with Polish characters (Windows Unicode paths).

---

2) Class: ImageManager

Manages the lifecycle and batch operations for a collection of images.

Private members:

• _images – vector of std::shared_ptr<ImageInfo>
• _isactive – selection state (checkboxes)
• _dir_path – scanned directory

Key methods:

• loadDirectory() – recursive scan and collection build
• getImages(), getImageAt(index), getCount()
• GetThumbnail(index) – helper for GUI previews
• generateReportSelected(outputPath, fields) – CSV report for checked images
• saveProcessedImage(...) – saves image with overlay (_with_text.jpg)
• processAllActive(customText) – batch processing for checked
• processAllActiveWithSelectedParams(fields) – batch overlay built from selected metadata fields
• processAllActiveFromCaptions(map, fallback) – batch overlay from captions file
• generateDetailedReport(index) – TXT metadata dump (optional, can be attached to menu later)

---

🛠 Build / Run

Requirements

• Windows + Visual Studio 2022
• wxWidgets 3.2+
• Exiv2 (metadata)

Notes

• Ensure required DLLs are available in PATH or placed next to the executable.
• The project is delivered as a Visual Studio solution (.sln).

---

📁 Repository Layout

• SRC/ – source code (.cpp/.h, .vcxproj)
• test_data/ – test datasets used for validation (folder structures, captions, example images)
• README.md – this file

---

✅ Test data

test_data/ is included to make it easy to reproduce:

• recursive directory scan tests
• captions file parsing tests
• metadata presence/absence tests
• filenames with Polish characters tests

---

Created as part of the “Interfejsy użytkownika i biblioteki graficzne” course project.