Regional IF Analyzer

A GUI tool for analyzing immunofluorescence images with atlas region mapping and automated cell counting.

v8.03.000 Highlights (current major release)

• Atlas Manager Ribbon (new central, discoverable UI for atlas region work; toggleable via View > "Show Atlas Manager Ribbon"):
  • Expandable header + content; always shows selected region.
  • Global Crop and Move now checkboxes (visible active state; enables whole-atlas click-drag modes).
  • "Move Selected Region" checkbox + interior drag: translates only the orange selected zone's mask (artwork/other regions fixed).
  • "Border drag resize enabled" checkbox: enables edge grab.
  • Global Quick Adjust (new): Rot +/-5°, Scale +/-5% for entire atlas page (base + masks) + Dialogs access.
  • Selectable list of labeled regions (click to select for editing).
  • Selected Region Quick Adjust (Rot +/-5°, Scale +/-5%, Dialogs) — only affects chosen zone.
• Per-region atlas editing:
  • Select via canvas click (now autoselects named regions, no re-name prompt), list, or Atlas > Select Region.
  • Edge grab: click near border → red local segment (persistent). Re-click to reposition; drag to locally deform boundary (falloff, live preview). Commit on release.
  • Move-selected + quick per-region transforms.
• Mutual exclusion & clarity: Enabling edge/border auto-deselects global Move (and Crop); vice versa. Checkboxes + orange tint + list make context obvious.
• Menu update: Import Atlas (plus all global/per-region tools) moved to dedicated top-level Atlas menu.
• Robustness fixes:
  • Atlas crop: proper model coords via _canvas_to_atlas, rebase img_x/img_y, prune orphans, full state clear (no more "disappearing" atlas).
  • Load order: image after atlas no longer breaks global Move/edge (stale selection/edge state now fully cleared in import_tiff + _load_tiff_file paths).
  • Edge hit-testing forgiving (boundary pixels still trigger grab when near selected).
  • Drag delegation: per-region features work even under global edit bindings.
  • Hygiene: clears on page switch, deselect, imports, crop, etc.
• Updated manual (regenerated with new What's New 8.03.000 + expanded Atlas chapter documenting ribbon, quick adjust, edge features, checkboxes, etc.).
• Version in code/settings JSON: "8.03.000".

See release-notes-v8.03.000.md for full details. Previous v8.02.x Paint reliability and count fixes remain intact.

v8.02.002 Highlights (previous patch)

v8.02.001 Highlights (previous)

• Final Paint tool reliability fixes so the primary workflow ("draw region, right-click name immediately, click Count Cells") succeeds on the very first attempt after loading any image:
  • Fixed a case where the first named painted region would be lost ("No Regions Defined" error) while a second region drawn afterward would appear in the spreadsheet.
  • Root cause was an unconditional reset of zone_names / mask_images / zone_counters inside load_page_image the first time atlas_filetype='img' (baked paint) was activated during stop_paint's show_page. Guarded so only PDF atlas pages perform per-page zone resets; paint zones now survive the internal bake-to-img path.
  • Additional hardening in the named conversion, stop, and count paths (broader durable data collection, conditional dtag, pre-clear re-tries, ultimate force before the error guard) to guarantee paint_group_data model points always produce registered zones.
• Brightness Settings dialog (the live slider) X button (titlebar close) now works and closes the window. Same fix applied for consistency to Brush Size, Scale, and Rotate settings dialogs. (Progress dialogs remain intentionally hardened against early close.)
• All v8.02.000 Paint guarantees (immediate naming, auto-stop on Count, durable geometry, interior binary_fill_holes fill, no dups, full cross-image wipe, auto Save Paint Layer to File Browser dir, etc.) now apply even to the first painted region.
• Version recorded in exported settings JSON is now "8.02.001".

v8.02.000 Highlights (previous)

• Major reliability overhaul of the Paint tool for custom regions:
  • Zones named immediately after drawing now correctly register for counting.
  • Count Cells auto-stops paint mode and converts all strokes (named + auto-default).
  • Full state wipe on every new image load (prevents cross-image leakage).
  • Durable model-coordinate storage so drawings survive zoom/pan.
  • Proper interior filling (binary_fill_holes) + neighborhood zone lookup → accurate counts inside hand-drawn structures.
  • No more duplicate zones in the spreadsheet.
• Paint menu improvements:
  • "Save Paint" moved from File menu to Paint menu and renamed Save Paint Layer.
  • New Load Paint command added to the Paint menu.
  • Save Paint Layer now auto-saves directly into the folder currently open in the left File Browser (smart unique naming, no dialog). The file list refreshes automatically.
  • Load Paint and Import Paint default to the current left File Browser directory.
• Critical stability fix: Closing the "Counting Cells" or "Detecting Cells" progress dialog early (X button) can no longer crash the application. All progress UI calls are now defensive.
• Continuing from v8.01: Modern Blob Detection (default), Smart Suggest (Offline), left File Browser with counted status, automatic dual export (.xlsx + _masked.tif), and portable settings.

v8.01.000 Highlights (previous major release)

• New modern Blob Detection engine (Laplacian of Gaussian) — significantly better results on most immunofluorescence images.
• "Smart Suggest (Offline)" — a fully local, privacy-preserving tool that analyzes your image and recommends better detection parameters (with checkbox selection).
• Live switching between Blob and legacy Watershed detection methods directly in Mask Settings.
• Left-side File Browser pane: Select a folder to see all TIFFs, double-click to load, and see which images have already been counted (✓ indicator).
• Automatic export on Count Cells: {image}.xlsx (with Cell Counts + full Detection Parameters metadata sheet) and {image}_masked.tif (original + red mask overlay).
• Export/Import full detection settings as portable .json files from Mask Settings.
• Improved Autotune buttons that adapt intelligently based on the active detection method.
• Brush Settings dialog now opens automatically when using Add/Remove Cell.

Description

The Regional IF Analyzer is designed to help researchers analyze immunofluorescence images by:

• Overlaying atlas sections onto TIFF images
• Highlighting and naming specific regions of interest
• Detecting and counting cells within defined regions
• Automatic Excel + masked image export on Count Cells (with full parameter metadata)
• Saving annotated images

Installation

Prerequisites

• Python 3.8 or higher
• pip (Python package installer)
• tkinter (usually comes with Python, but may need separate installation on Linux)

On Ubuntu/Debian Linux, you might need to install tkinter separately:

sudo apt-get install python3-tk

Setting Up

1. Clone the repository:

git clone https://github.com/LaingLab/BARCC.git
cd BARCC

2. Install required packages:

pip install -r requirements.txt

Note on Excel exports (recommended): Starting with v8.01 (refined in 8.02), clicking Count Cells automatically saves:

• YourImage.xlsx — Contains two sheets:
  • "Cell Counts" (per region)
  • "Detection Parameters" (complete record of every setting used — excellent for methods/reproducibility)
• YourImage_masked.tif — Original image with the final cell mask (including manual edits) as a semi-transparent red overlay.

For full .xlsx support, install the Excel engines:

pip install openpyxl xlsxwriter

Without them, BARCC falls back to a plain .csv.

Running the Program

1. Navigate to the program directory:

cd Application

2. Run the program:

python Application/barcc.py

Basic Usage

1. Import TIFF Image:

   • Click "File > Import TIFF"
   • Select your TIFF image file

2. Determine Regions

   a. Draw Region of Interest:

   • Click "Paint > Start Paint"
   • Draw a circle around the ROI
   • Once done, click "Paint > Stop Paint"
   • Use "Paint > Save Paint Layer" to auto-save the paint into your current left File Browser folder (or "Load Paint" to reload one).

   b. Import Atlas:

   • Click "Atlas > Import Atlas"
   • Select your PDF atlas file

3. Align Atlas:

   • Use "Move Atlas" button to position the atlas over your image
   • Use rotation and scaling controls if needed
   • For fine per-region adjustments (after naming zones): Atlas > Select Region (then click a yellow region), then use Rotate Selected Region / Scale Selected Region to tweak individual shapes larger/smaller or rotate them. The underlying atlas lines stay fixed as reference while the counting zones (yellow) adjust.

4. Define Regions:

   • Click on regions to highlight them
   • Name each region when prompted

5. Verify Mask:

   • Click "Mask > Show Mask"
   • Adjust detection with "Mask > Show Mask Settings"
   • Manually add and remove cells under "Mask > Add/Remove Cells"

6. Count Cells:

   • Click "Count Cells" to analyze
   • Save results to Excel when prompted

Common Issues

• If tkinter is missing: Install python3-tk package via your system's package manager
• If images don't load: Ensure your TIFF files are in a compatible format
• For PDF loading issues: Ensure PyMuPDF is properly installed

Support

For issues and feature requests, please open an issue in the GitHub repository.

License