MAGICAL

Macro Automated General Image CALibration

A small suite of ImageJ/Fiji macros (.ijm) for batch preprocessing of fluorescence microscopy images before automated single cell segmentation and morphology analysis (e.g. CellProfiler, Ilastik, custom pipelines).

Every macro is a batch macro: you point it at an input folder and an output folder, set the parameters once in a dialog, and it processes every TIFF in the folder and writes a suffixed copy. Originals are never overwritten.

---

Contents

Macro	Purpose	Output suffix
zSqueese.ijm (zSqueeze)	Per slice background subtraction and Z projection of stacks	_zSqueeze.tif
EdgiCut.ijm	Detects the tissue/section boundary and clears everything outside it	_EdgiCut.tif
BagSubV2.ijm	Contrast, rolling ball background, unsharp mask, CLAHE, global normalisation (16 bit)	_BagSub_V2.tif
MagicVJ.ijm	Same idea as BagSubV2 but with a selectable background model and 8 bit output	_MagicVJ.tif
FilterSub.ijm	Generic "original minus filtered" background removal (Gaussian / median / mean / maximum)	_FilteredSubtracted.tif
ClusCrop.ijm	Crops cells by coordinate and cluster label from a CSV, then builds per cluster stacks and montages	folder per cluster

---

Requirements

• Fiji (ImageJ 1.53 or newer recommended)
• No extra installation needed. Enhance Local Contrast (CLAHE) ships with Fiji.
• Input images must be TIFF (.tif / .tiff, case insensitive). ClusCrop also accepts .png.

Installation

Option A, run directly (quickest)

1. Drag the .ijm file onto the Fiji main window, or open it with File > New > Script... and File > Open....
2. Press Run.

Option B, install into the menu

1. Copy the .ijm files into Fiji.app/scripts/Plugins/MAGICAL/ (create the folder).
2. Help > Refresh Menus.
3. The macros appear under Plugins > MAGICAL.

---

Typical workflow

raw z-stacks
    |
    v  zSqueeze          project stacks to 2D
    |
    v  EdgiCut           remove out-of-tissue background and edge artefacts
    |
    v  BagSubV2 / MagicVJ / FilterSub    flatten background, enhance ramifications
    |
    v  segmentation (CellProfiler, etc.) -> per-cell features + coordinates
    |
    v  clustering (R, Python) -> CSV with cluster labels
    |
    v  ClusCrop           visual gallery of each morphological cluster

Not every dataset needs every step. Single plane images skip zSqueeze; whole-slide images with clean edges skip EdgiCut. Choose one background/contrast macro per dataset, and keep that choice fixed across all images of an experiment so that downstream segmentation parameters remain comparable.

---

Macro reference

1. zSqueeze (zSqueese.ijm)

Converts Z stacks into a single 2D image. Background subtraction is applied slice by slice before projection, which preserves thin processes better than subtracting after projection.

Prompts: input folder, output folder, then one dialog.

Parameter	Default	Notes
Apply background subtraction	on	rolling ball, sliding mode, applied to each slice
Rolling ball radius	50	in pixels; set larger than the largest structure of interest
Apply Unsharp Mask	on	applied to the projection, not to slices
Unsharp Mask radius	2
Unsharp Mask amount	0.80	0 to 1
Z Projection Method	Sum Slices	Average / Max / Min / Sum / Standard Deviation / Median

Use Sum Slices or Average Intensity when you want to keep faint distal processes; Max Intensity is brighter but exaggerates single noisy voxels.

2. EdgiCut

Builds a smooth mask of the tissue, shrinks it inward, and clears everything outside it on a duplicate of the original. Useful for removing section edges, folds and bright rim artefacts that otherwise dominate intensity normalisation.

Prompts: input folder, output folder, then three numbers.

Parameter	Default	Notes
Maximum filter radius	10	closes gaps in sparse labelling before masking
Gaussian Blur sigma	50	large sigma gives a smooth tissue outline
Shrink mask inward (pixels)	100	number of erode iterations; increase to cut deeper into the tissue

Output is 8 bit. Check one image before running the whole folder: if the mask eats real tissue, lower the shrink value; if edges survive, raise it.

3. BagSubV2

The main preprocessing macro. Order of operations: 16 bit conversion, contrast enhancement, rolling ball background subtraction, unsharp mask, CLAHE, then global rescaling to the full 16 bit range. The final global normalisation step reduces the tile boundary artefacts CLAHE can introduce.

Parameter	Default	Notes
Saturated pixels (%)	0.35	contrast stretch with normalisation
Rolling Ball radius	50
Unsharp Mask radius	1.0
Unsharp Mask weight	0.7	0 to 0.9 typical; higher values ring
CLAHE histogram bins	512
CLAHE maximum slope	2.0	1 for low noise images, up to 4 for noisy ones
Fast CLAHE	off	faster, slightly less accurate

CLAHE block size is set automatically to 50% of the image width, clamped to 64 to 256 pixels and forced odd. It is printed to the Log for every image.

4. MagicVJ

An alternative to BagSubV2 when the background is not well described by a rolling ball. Lets you choose the background model and returns an 8 bit image.

Parameter	Default	Notes
Saturated pixels (%)	0.1
Background filter type	Gaussian Blur	Gaussian Blur / Rolling Ball / Median Filter
Gaussian sigma	10	used only for Gaussian Blur
Rolling Ball radius	50	used only for Rolling Ball (runs with the light option)
Median filter radius	2	used only for Median Filter
CLAHE maximum slope	2
CLAHE histogram bins	256
Fast CLAHE	off

Gaussian and Median modes subtract a blurred copy of the image from itself, which handles smoothly varying illumination gradients. Rolling Ball mode is better for a flat background with discrete bright objects.

5. FilterSub

A minimal, transparent "unsharp style" background removal: duplicate, filter, subtract. No contrast manipulation, so it is the safest option when absolute intensities must stay interpretable.

Prompts: input folder, output folder, filter name (typed as text: gaussian, median, mean or maximum), and the filter radius (default 2.0).

6. ClusCrop

Takes segmentation coordinates plus a cluster label and produces one folder per cluster containing the cropped cells, a stack, and a montage. Intended for visual inspection of clustering results.

Prompts, in order:

1. Folder of images to crop from (PNG or TIFF)
2. Coordinate CSV
3. Output base folder
4. Crop width (default 50 px), crop height (default 50 px), montage columns (default 10)

CSV format. No header assumptions beyond the first row being a header, which is skipped. Columns are read by position:

Column	Content
1	Image / animal identifier
2	Cluster label
3	X centroid (pixels)
4	Y centroid (pixels)

ImageNumber,Cluster,X,Y
154,3,1024.5,880.2
154,1,512.0,301.7

Important: an image is matched to a CSV row by comparing the first three characters of the image filename with column 1. Name your files accordingly (154_MCAo_slice2.tif matches identifier 154). Montage rows are set automatically to the number of images in the folder.

Output per cluster: Cluster_<label>/ containing <ID>_Cluster_<label>_crop<N>.png, Cluster_<label>_stack.tif and Cluster_<label>_montage.png.

---

Practical notes

• All macros print progress to the Fiji Log window. Keep it open, and copy it into your lab book or methods file: it is a complete record of the parameters used.
• Parameters are asked once and applied to the whole folder. Run each experiment (or each imaging session) as its own batch so that acquisition settings and preprocessing settings stay coupled.
• Always validate on two or three representative images before batching: one bright, one dim, one with visible background structure.
• Bit depth matters downstream. BagSubV2 and FilterSub write 16 bit, MagicVJ and EdgiCut write 8 bit. Keep one bit depth across a dataset.
• zSqueeze closes all images and waits between files; large folders take time. Do not interact with Fiji while it runs.

Troubleshooting

Symptom	Likely cause
"No input folder selected" and the macro exits	the folder chooser was cancelled
Nothing is processed	the folder has no .tif/.tiff files, or images are in subfolders (the macros do not recurse)
Visible square tiles in the output	CLAHE slope too high or block size too small for the structures; lower the slope
Processes disappear	rolling ball radius too small, or unsharp weight too high
EdgiCut returns a nearly empty image	shrink value too large, or the auto threshold failed on a very dim image
ClusCrop produces empty cluster folders	image filename prefix does not match column 1 of the CSV

Citation

If you use MAGICAL in a publication, please cite this repository.

MAGICAL: Macro Automated General Image CALibration.
ImageJ macro suite for batch preprocessing of fluorescence microscopy images.
https://github.com/<user>/<repo>

License

MIT (see LICENSE).