FSC Replacer

FSC Replacer is a professional-grade desktop utility designed to automate the detection and replacement of FSC (Forest Stewardship Council) logos within PDF documents. Utilizing advanced computer vision (OpenCV) and low-level PDF manipulation libraries, it ensures branding consistency across large volumes of documents with pixel-perfect precision.

🚀 Key Features

• Computer Vision Powered: High-accuracy detection via multi-stage template matching.
• Iterative Batch Processing: Intelligent workflow that allows targeting "missed" files with alternative templates.
• Side-by-Side Validation: Built-in split-view preview to compare original and modified documents.
• Modern Dark UI: A responsive interface built with PySide6 for optimal user experience.
• Structural Integrity: Replaces visual assets while preserving the underlying PDF vector data and metadata.

🏗 Program Structure

The project architecturally adheres to Clean Architecture principles, separating business logic from infrastructure concerns:

├── application/          # Orchestration layer (Job management & Service logic)
├── domain/               # Core entities, Enums, and Business Models
├── infrastructure/       # External integrations
│   ├── detection/        # OpenCV implementation for logo identification
│   ├── pdf/              # PDF I/O, Redaction, and Overlay logic (fitz & pikepdf)
│   ├── persistence/      # Local session management via SQLite
│   └── logging/          # Enterprise-standard application logging
├── ui/                   # Desktop presentation layer (Components & Dialogs)
├── output/               # Default destination for processed documents
├── assets/               # Application assets and static templates
└── app.py                # System entry point

🧠 Core Methodology & Workflow

1. The Iterative Pattern Matching Concept

In real-world scenarios, FSC logos may vary slightly due to compression artifacts, different print standards, or specific page backgrounds. A single template might not catch 100% of the logos.

FSC Replacer solves this through an iterative workflow:

• You select an initial template and run the batch.
• The system identifies "Success", "Not Found", or "Ambiguous" results.
• For files marked as Not Found, you can select a new pattern (e.g., a logo with slightly different proportions or sharpness from a different document) and re-run the process.
• The application automatically skips already modified files, focusing only on the remaining "unsolved" ones.

2. High-Precision Replacement

Unlike simple "image overlays", the program:

1. Rasterizes the page for detection.
2. Maps image-space coordinates back to PDF-space points.
3. Redacts the original area to ensure no ghosting of the old logo.
4. Overlays the new high-resolution replacement asset at the exact vector coordinates.

🖥 Installation

1. Clone the repository:

   git clone https://github.com/KonradJam/FSC_replacer.git
   cd FSC_replacer

2. Environment Setup:

   python -m venv venv
   source venv/bin/activate  # Windows: venv\Scripts\activate

3. Install Dependencies:

   pip install -r requirements.txt

📖 How to Use (Step-by-Step)

Step 1: Loading Files

Drag and drop your PDF files into the "PDF Files" tab. The sidebar will list all loaded documents and their current processing status.

Step 2: Defining the Search Pattern (Template)

• Go to the "Template" tab or click the template icon in the toolbar.
• Select a PDF from the list that contains a clear example of the logo you want to replace.
• A dialog will open; use your mouse to draw a rectangle precisely around the FSC logo. This becomes your search pattern.

Step 3: Selecting the Replacement

In the "Replacement" tab, load the new logo file (PNG or JPG). This is the asset that will be injected into the documents.

Step 4: Execution & Refinement

• Click "Start Processing". The system will scan the loaded PDFs.
• Review Results: Files successfully processed will show a ✓ and can be previewed in the split-view pane.
• Handle Misses: If some files are "Not Found", select one of them, define a new template from its specific layout, and click start again. Only the "Not Found" files will be re-scanned.

📂 Output & Results

All successfully processed documents are saved in the output/ directory located in the project root.

• Naming Convention: replaced_[original_filename].pdf
• Quality: The output maintains text searchability and vector quality (where applicable), with the new logo seamlessly integrated.

📄 License & Author

• Author: Konrad Jam
• License: Licensed under the MIT License.

---

FSC Replacer — Precision Computer Vision for Professional Document Management.