✨ 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, automatic layout arrangement, and rich customization options.

Image Crop Comparator Demo

Overview 📌

Features ✨

ROI-based multi-image previewer for image restoration (or other else) tasks
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 🚀
User Guidance 🧭
- Tutorials
- Interaction
- Usage
- Output
Reference ⚙️
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

Local mode (default) expects the example datasets under examples/; adjust Root/Structure in the UI if using your own layout.

Quick Start (Gradio) 🚀

python gradio_app.py

Runs the Gradio UI locally on http://127.0.0.1:7860/ by default.
Local mode (default) expects the example datasets under examples/; adjust Root/Structure in the UI if using your own 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

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>

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>

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>

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

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

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>

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:

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

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

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.

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
examples		examples
figures		figures
utils		utils
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
compare.py		compare.py
gradio_app.py		gradio_app.py
requirements.txt		requirements.txt

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

✨ Image Crop Comparator

Overview 📌

Features ✨

News 🆕

Contents 📑

Getting Started 🚀

Installation 🧰

Quick Start (CLI) 🚀

Quick Start (Gradio) 🚀

Workspace Layout 🗂️

User Guidance 🧭

Tutorials 🧪

Interaction 🎮

Usage 🧭

CLI Options ⚙️

Output 💾

Reference ⚙️

Logs 🎨

Troubleshooting 🛠️

Call to Action ⭐

About

Uh oh!

Releases

Packages

Languages

License

Yangzhichen763/ImageCropComparator

Folders and files

Latest commit

History

Repository files navigation

✨ Image Crop Comparator

Overview 📌

Features ✨

News 🆕

Contents 📑

Getting Started 🚀

Installation 🧰

Quick Start (CLI) 🚀

Quick Start (Gradio) 🚀

Workspace Layout 🗂️

User Guidance 🧭

Tutorials 🧪

Interaction 🎮

Usage 🧭

CLI Options ⚙️

Output 💾

Reference ⚙️

Logs 🎨

Troubleshooting 🛠️

Call to Action ⭐

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages