✨ Image Crop Comparator

Image Crop Comparator (ICC): A research-oriented, interactive image crop comparator for pixel-level method analysis, designed for a fast and flexible interactive workflow with multi-ROI selection, auto layout, undo/redo, side-by-side ROI comparison, and more advanced options.

🌐 Languages: 👉 English | 简体中文

Image Crop Comparator Demo

Side-by-side Image Crops Preview

Fig. 1. Compare image crops across multiple methods. Select regions of interest (ROIs) interactively, and ICC will automatically align and display the corresponding crops from all methods side by side.

Overview 📌

Features ✨

• ROI-based multi-image comparison viewer for image restoration and more
• Fast and flexible multi-ROI selection via keyboard and mouse shortcut, with undo/redo support
• Automatic layout arrangement (left / right / top / bottom)
• Support for multiple workspace structures
• Highly customizable CLI for future research, and a user-friendly Web interface (gradio) for improved experience

News 🆕

• 2025.12.30 A quick demo of our tool is available on Hugging Face. 🤗
• 2025.12.30 Update Web version, a Gradio-based UI, providing better user experience for broader users. 🚀
• 2025.12.29 Update basic tutorial. 🧾
• 2025.12.28 Update ICC-CLI original-version, a runnable command-line (CLI) tool, including local/external sources, ROI selection, layout preview, and export. 🎈

Contents 📑

• Getting Started 🚀
  • Installation
  • Quick Start (CLI)
  • Quick Start (Gradio)
  • Workspace Layout
• User Guidance 🧭
  • Tutorials
  • Interaction
  • Usage
  • Output
• Reference ⚙️
  • CLI Options
  • Logs
  • Troubleshooting
• Community 🤝
  • Call to Action

Getting Started 🚀

Installation 🧰

• Python 3.8+
• requirements.txt pins opencv-python==4.7.* and numpy==1.26.*; install with pip install -r requirements.txt.
• Packages: opencv-python, numpy, natsort, Pillow

# Conda (recommended)
conda create -n crop-comparer python=3.10 -y  # python>=3.8 (e.g. 3.9) is also supported, and python<=3.12 is recommended
conda activate crop-comparer
pip install -r requirements.txt

venv alternative

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
pip install -r requirements.txt

Quick Start (CLI) 🚀

python compare.py

• Minimal two-step flow for local reviews:
  1. Copy your method results into examples/ (or another root that matches the structures below).
  2. Run python compare.py and start selecting ROIs; defaults work out of the box.
• If your layout differs, set Root/Structure in the UI or CLI to point to your folders.

Quick Start (Gradio) 🚀

python gradio_app.py

• Runs the Gradio UI locally on http://127.0.0.1:7860/ by default.
• Same two-step flow: drop images into your root (default: examples/), launch, and compare. Set Root/Structure if you use a custom layout.

Workspace Layout 🗂️

(for default local source) Methods live under the workspace root, and each holds datasets.

<root>/
  <method>/
    <dataset>/
      <images...>

Example

examples/         # <root>
  A-Net/          # <method>
    LOL-v2-real/  # <dataset>
      00698.png   # <images...>
      00775.png
    SDSD-indoor/
      00101.png
      00259.png
  B-Former/
    LOL-v2-real/
      00698.png
      00775.png
    SDSD-indoor/
      00101.png
      00259.png
  ...

Supported structures (use `--structure`)

• group-dataset-pair: <root>/<method>/<group>/<dataset>/<pair>/<img>.png
• group-dataset (default classic): <root>/<method>/<group>/<dataset>/<img>.png
• dataset-only: <root>/<method>/<dataset>/<img>.png
• flat: <root>/<method>/<img>.png
• shared: <root>/<image-id>/<method>.png
• auto (default): tries the above in order.

Structure examples

1. group-dataset-pair (deep): <root>/<method>/<group>/<dataset>/<pair>/<img>.png

<root>/
  <method1>/
    <group>/
      <dataset>/
        <pair>/
          <img1.png>
          <img2.png>
          ...
          <imgn.png>
  <method2>/
    <group>/
      <dataset>/
        <pair>/
          <img1.png>
          <img2.png>
          ...
          <imgn.png>

2. group-dataset (default classic): <root>/<method>/<group>/<dataset>/<img>.png

<root>/
  <method1>/
    <group>/
      <dataset>/
        <img1.png>
        <img2.png>
        ...
        <imgn.png>
  <method2>/
    <group>/
      <dataset>/
        <img1.png>
        <img2.png>
        ...
        <imgn.png>

3. dataset-only: <root>/<method>/<dataset>/<img>.png (example of current default for local source)

<root>/
  <method1>/
    <dataset>/
      <img1.png>
      <img2.png>
      ...
      <imgn.png>
  <method2>/
    <dataset>/
      <img1.png>
      <img2.png>
      ...
      <imgn.png>

4. flat (images directly under method): <root>/<method>/<img>.png

<root>/
  <method1>/
    <img1.png>
    <img2.png>
    ...
    <imgn.png>
  <method2>/
    <img1.png>
    <img2.png>
    ...
    <imgn.png>

5. shared (per-image folders contain per-method files): <root>/<image-id>/<methodA>.png, <methodB>.png, ...

<root>/
  <img1>/
    <method1.png>
    <method2.png>
    ...
    <methodn.png>
  <img2>/
    <method1.png>
    <method2.png>
    ...
    <methodn.png>

6. auto (default): tries the above in order until images are found.

User Guidance 🧭

Tutorials 🧪

Quick tutorial

Short walkthrough showing ROI selection.

Basic ROI operations

Select ROI	Move ROI	Add ROI

Reselect ROI	Delete ROI

Layout directions

Layout left	Layout right	Layout top	Layout bottom

Layout capacities

Single ROI (one)	Two ROIs	Three ROIs	More than three ROIs

Mouse-only quick tour

Optional mouse-only quick tour (all operations by mouse):

Interaction 🎮

Keyboard

Key	Action
a	Add new ROI
1–9	Add / select ROI by id; Tapping active id to reselect
Shift+1–9	Duplicate active ROI to target id or copy its size
d	Add ROI with active size
← ↑ → ↓	Change layout direction
z / y	Undo / redo
Enter	Switch dataset (group/dataset or dataset)
Space	Jump to image by name
n / p	Next / previous image
s	Save outputs
i	Toggle idle (hide/show grids)
r	Clear all ROIs
q / Esc	Quit

Note: Arrow keys (← ↑ → ↓) control the layout direction, not ROI movement. ROI movement is performed by mouse dragging in position mode.

Mouse

• Draw in selection mode; drag to reposition in position mode.
• Hold Shift while drawing a ROI: constrain to a square using the longer side.

Quick actions:

• Right-click on overlapping ROIs: cycle to the next higher id in that stack (wraps to smallest).
• Right-click outside any ROI: add the next ROI (same as a).
• Right-click down inside a ROI, release after the cursor leaves that ROI: delete it.
• Middle-button inside the active ROI: duplicate it to a new ROI, then drag the new ROI while holding.
• Middle-button inside a non-active ROI: copy the active ROI size to that ROI (Shift+digit).

Usage 🧭

Local images with auto-discovery:

python compare.py --source local --root <root> --group <group> --dataset <dataset> --layout right

External datasets

External (video-form) datasets require methods.txt:

python compare.py --source external --dataset SDSD-indoor --pair pair13 --layout left

CLI Options ⚙️

Core switches

• --source: local or external
• --root: workspace root (local)
• --group, --dataset, --pair: dataset selectors
• --structure: layout of files (see above)
• --output: output root directory

Display and layout

• --layout: left|top|right|bottom
• --columns: grid columns for per-ROI previews
• --magnify / --scale: display-only magnification (ignored for multi-ROI final)
• --layout-padding: padding between crops and base image
• --display-thickness-mult: overlay thickness multiplier for final layout

Interaction defaults

• --mode: selection|position|idle
• --preview: method key for final preview (GT/input if present)
• --thickness: ROI and crop border thickness

Logging

• --log-level: debug|info|warn|error
• --no-color: disable ANSI colors

Output 💾

On s, outputs are written to:

<output>/<timestamp>/<dataset>/<image-basename>/
  orig_<method>.png
  final_<method>.png
  crop_roi<id>_<method>.png

Each method writes its own originals, composed final previews, and all crops for active ROIs.

Reference ⚙️

Logs 🎨

• Linux terminals show colored status messages: info (cyan), success (green), warnings (yellow), errors (red), notes (bright cyan).
• Toggle with --no-color; set verbosity via --log-level.

Troubleshooting 🛠️

Issue:

cv2.error: OpenCV(4.7.0) /io/opencv/modules/highgui/src/window.cpp:1266: error: (-2:Unspecified error) The function is not implemented. Rebuild the library with Windows, GTK+ 2.x or Cocoa support. If you are on Ubuntu or Debian, install libgtk2.0-dev and pkg-config, then re-run cmake or configure script in function 'cvDestroyAllWindows'

Solution:

1. uninstall opencv-python-headless and reinstall opencv-python:

   pip uninstall opencv-python-headless
   pip install "opencv-python==4.7.*"

2. If operation system is Linux, ensure GTK is installed:

   sudo apt-get install libgtk2.0-dev pkg-config

Call to Action ⭐

• ⭐ If you like ICC, give it a star. It helps others discover the project and supports its growth.