Walnut Annotation

Tools for preparing walnut images and manually annotating walnut centers for training or evaluation.

Overview

Script	Purpose
crop_image_quadrants.py	Split every image in a folder into four equal quadrants each (useful for tiling large photos).
walnut_annotator.py	Interactive GUI to click walnut centers and save coordinates to text files.

Typical workflow

1. (Optional) Crop large images into quadrants with crop_image_quadrants.py.
2. Annotate walnut centers with walnut_annotator.py.
3. Use the generated .txt annotation files downstream (training, validation, etc.).

Documentation in the scripts

Both scripts are documented in two places:

1. Module docstrings (top of each file) — usage, options, and behavior at a glance.
2. Inline comments — explain non-obvious logic (coordinate transforms, zoom/pan, save format, quadrant naming).

Read the file headers before running; they mirror what --help shows and add context (e.g. quadrant naming q00–q11, annotation file format).

Requirements

• Python 3.9+
• Dependencies: opencv-python, numpy (see requirements.txt)

OpenCV needs a display for walnut_annotator.py (not ideal over headless SSH). Use opencv-python (not opencv-python-headless) if the GUI window does not open.

Setup

1. Create a virtual environment

python3 -m venv .venv

On Windows (Command Prompt):

python -m venv .venv

2. Activate the virtual environment

macOS / Linux (bash/zsh):

source .venv/bin/activate

Windows — PowerShell:

.\.venv\Scripts\Activate.ps1

Windows — Command Prompt:

.venv\Scripts\activate.bat

Windows: “running scripts is disabled on this system”

If PowerShell refuses to run Activate.ps1 with an execution-policy error, allow scripts for your user (one-time):

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Then activate again:

.\.venv\Scripts\Activate.ps1

• RemoteSigned lets local scripts run; downloaded scripts still need signing.
• You can revert later with Set-ExecutionPolicy -ExecutionPolicy Restricted -Scope CurrentUser if you prefer.
• Alternative: use Command Prompt and activate.bat above (no PowerShell script policy).

3. Install dependencies

pip install --upgrade pip
pip install -r requirements.txt

4. Sanity check

python -c "import cv2, numpy; print('opencv', cv2.__version__, 'numpy', numpy.__version__)"
python crop_image_quadrants.py --help
python walnut_annotator.py --help

Usage

crop_image_quadrants.py

Split every image in a directory into four equal tiles each (.jpg, .jpeg, .png, case-insensitive).

python crop_image_quadrants.py /path/to/images -o /path/to/output

Argument / option	Description
input_dir	Folder containing images to crop
-o, --output	Output directory (default: same folder as input_dir)

Odd dimensions are padded automatically (one black pixel on the bottom and/or right) so each quadrant is equal size.

Output names: <stem>_q00, _q01, _q10, _q11 + original extension

Suffix	Region
q00	top-left
q01	top-right
q10	bottom-left
q11	bottom-right

Example:

python crop_image_quadrants.py image -o image/quadrants

walnut_annotator.py

Interactive annotation over all images in a folder.

python walnut_annotator.py /path/to/images -o /path/to/annotations

Option	Description
image_folder	Folder of .jpg / .jpeg / .png images
-o, --output	Where .txt annotations are saved (default: image_folder/annotations)
-r, --radius	Circle radius for markers (default: 8)

Controls

Action	Effect
Left click	Add walnut center
Right click	Remove nearest annotation
Ctrl + left click + drag	Pan
Mouse wheel or + / -	Zoom in/out (+/- work when the wheel does not, e.g. on macOS)
s	Save current image
n / p	Next / previous image (saves first)
r	Reset zoom and pan
z	Clear annotations on current image
q or Esc	Quit (saves before exit)

Annotation files: one <image_stem>.txt per image in the output folder. Header lines start with #; data lines are x y in image pixel coordinates.

Project layout

Walnut_annotation/
├── crop_image_quadrants.py
├── walnut_annotator.py
├── requirements.txt
├── Readme.md
└── image/                 # example images (optional)

Troubleshooting

Issue	What to try
PowerShell won’t activate venv	Set-ExecutionPolicy RemoteSigned -Scope CurrentUser, or use activate.bat in cmd
import cv2 fails	Activate venv, run pip install -r requirements.txt
Annotator window doesn’t appear	Use opencv-python, run locally with a display
Zoom doesn’t work with mouse wheel	Click the window to focus it, or use + / - on the keyboard (common on macOS)
Uneven split on odd-sized images	Padding is automatic (black pixel on bottom/right)