An ImageJ/Fiji plugin for automated processing and analysis of Echo Revolutions microscope data. Handles multi-channel fluorescence imaging with tile stitching, Z-stack projection, background subtraction, ROI-based measurement, and particle analysis.
- Auto-detection: Parses
ScanInfo.xmlandXYZPositions.txtto auto-configure channels, colors, pixel calibration, and grid layout - Unified processing: Handles all four dataset types seamlessly — single images, tiled mosaics, Z-stacks, and tiled Z-stacks
- 5 analysis modules:
- Configure Channels — interactive or auto-detected channel setup with legacy preference import
- Visualisation — tile stitching, Z-projection, background subtraction, contrast enhancement, channel merging, multi-format export
- Draw ROIs — interactive freehand ROI drawing with area measurement
- Measure Intensities — IntDen, CTCF, %Area, thresholded measurement (measures on original values, not binary masks)
- Particle Analysis — object detection with size filtering, watershed separation, morphology metrics
- Thread-safe: All image processing uses direct Java APIs (no global state), enabling parallel execution
- Batch mode: Process multiple experiments unattended via CLI or BatchProcessor
- Quality reporting: Standalone HTML reports with inline QC thumbnails and processing parameters
- Provenance tracking: Auto-generates methods paragraphs for publications with full processing metadata
- Modern UI: Custom Swing dialogs with toggle switches, help text, and live preview support
cd "Echo Analysis Plugin"
mvn clean installCopy the resulting JAR from target/ to your Fiji plugins/ folder, or configure Maven to install directly.
- Fiji (ImageJ distribution with bundled plugins)
- Java 8+
- Fiji plugins (bundled): Grid/Collection Stitching, Bio-Formats
- Open Fiji
- Go to
Plugins > Echo Analysis Pipeline - Select a directory containing Echo microscope data (must have
ScanInfo.xml) - Toggle the analyses you want to run
- Configure channel settings (auto-populated from metadata)
- Run
From an ImageJ macro:
run("Echo Analysis Pipeline", "dir=[C:\\path\\to\\data] analyses=0,1,3 verbose quality_report");Analysis indices: 0=Configure, 1=Visualisation, 2=Draw ROIs, 3=Measure, 4=Particle Analysis
The plugin recursively discovers all datasets (directories with ScanInfo.xml) under a root folder. Use the BatchProcessor for overnight processing of entire cohorts.
The plugin expects standard Echo Revolutions microscope output:
ExperimentName_N0000000/
├── ScanInfo.xml # Acquisition metadata
├── XYZPositions.txt # Tile coordinates and channel info
├── Tile000001.tif # Individual image tiles
├── Tile000002.tif
├── ...
└── preview.bmp # Scan preview
Supported configurations:
- Single images: 1 tile per channel (IMAGE)
- Tiled mosaics: NxM grid of tiles (TILE)
- Z-stacks: Multiple Z-planes per position (IMAGE_STACK)
- Tiled Z-stacks: NxM grid with Z-planes (TILE_STACK)
Dataset/
├── .echo/config.json # Processing configuration (JSON)
├── Images/ or Tiles/ # Processed channel images and merges
│ ├── 0_DAPI.png
│ ├── 1_FITC.png
│ ├── 2_TRITC.png
│ ├── 3_CY5.png
│ ├── Merge.png
│ └── Merge_2-4.png # Custom partial merge
├── ROIs/
│ └── ROI Set 1.zip # Saved ROI sets
├── Data Analysis/
│ ├── ROI Intensities/ # Per-channel measurement CSVs
│ ├── Particles/ # Particle analysis results
│ └── Attributes/ # ROI properties
├── Quality_Report/
│ └── QC_Report.html # Standalone QC report
└── provenance.json # Full processing provenance
The plugin uses a JSON configuration file that can be:
- Auto-generated from
ScanInfo.xmlmetadata - Imported from legacy
Echo_*_Preferences.txtfiles - Manually edited
- Shared as reusable recipes between experiments
Existing Echo_Image_Preferences.txt, Echo_Tile_Preferences.txt, and Echo_ImageStack_Preferences.txt files are automatically detected and can be imported into the new JSON format.
echo.pipeline/
├── EchoPipeline.java # Main plugin entry point
├── DebugLauncher.java # IDE debug launcher
├── analyses/
│ ├── Analysis.java # Common interface
│ ├── CreateConfigAnalysis.java # Channel configuration
│ ├── VisualisationAnalysis.java # Processing pipeline
│ ├── DrawROIsAnalysis.java # ROI drawing
│ ├── MeasureAnalysis.java # Intensity measurement
│ ├── ParticleAnalysis.java # Object detection
│ └── BatchProcessor.java # Multi-experiment batch
├── echo/
│ ├── ScanInfoParser.java # DOM+XPath XML parser
│ ├── ScanInfo.java # Parsed metadata model
│ ├── PositionParser.java # XYZPositions.txt reader
│ ├── PositionData.java # Position/grid model
│ ├── EchoDataset.java # Dataset discovery + classification
│ ├── DatasetType.java # IMAGE/TILE/STACK enum
│ ├── EchoConfig.java # Gson-serializable config
│ └── EchoConfigIO.java # Config I/O + legacy import
├── image/
│ ├── ZProjection.java # Thread-safe max projection
│ ├── TileStitcher.java # Grid/Collection stitching wrapper
│ ├── BackgroundCorrector.java # Channel/rolling ball subtraction
│ ├── ContrastProcessor.java # Auto/manual/custom contrast
│ ├── ChannelMerger.java # Composite + partial merges
│ ├── ImageCalcOps.java # Thread-safe pixel arithmetic
│ ├── ThreadSafeMeasure.java # IntDen, CTCF, thresholded
│ └── AdaptiveParallelism.java # Memory-aware threading
├── io/
│ ├── TileLoader.java # Sequential + parallel tile loading
│ ├── ImageExporter.java # PNG/TIFF/8-bit export
│ ├── OmeTiffIO.java # OME-TIFF with Bio-Formats
│ └── CsvExporter.java # CSV read/write/append
├── ui/
│ ├── PipelineDialog.java # Modern Swing dialog
│ ├── ToggleSwitch.java # iOS-style toggle component
│ └── PreviewPanel.java # Live image preview
├── roi/
│ ├── RoiIO.java # ROI zip I/O (no global manager)
│ └── RoiOps.java # Thread-safe ROI operations
├── report/
│ ├── QualityReport.java # HTML QC report generator
│ └── ProvenanceTracker.java # Methods paragraph + JSON provenance
└── cli/
├── CLIArgumentParser.java # Macro option string parser
└── CLIConfig.java # CLI configuration model
| Feature | Original Macro | Java Plugin |
|---|---|---|
| Metadata parsing | String indexOf/substring | DOM + XPath |
| Configuration | Custom XML-like text files | JSON (Gson) with auto-detection |
| Thread safety | None (global state everywhere) | Thread-safe APIs throughout |
| Parallelism | Not possible | Parallel tile loading, adaptive threading |
| Memory management | Load everything at once | Bounded loading, adaptive parallelism |
| Measurement | IntDen only, binary mask bug | IntDen + CTCF + %Area, measures on originals |
| Tile overlap | Hardcoded 3% | Computed from stage coordinates |
| Error handling | Macro crashes | Graceful recovery, batch error collection |
| Batch mode | None | CLI + BatchProcessor for multi-experiment |
| QC reporting | None | Standalone HTML with thumbnails |
| Reproducibility | Manual notes | Auto-generated methods paragraphs + provenance JSON |
| UI | GenericDialog | Custom Swing with toggles, help text, preview |
mvn test59 unit tests covering:
- Metadata parsing (ScanInfo.xml, XYZPositions.txt, dataset classification)
- Configuration (JSON round-trip, legacy import, hex color mapping)
- Image processing (Z-projection, background subtraction, contrast, merge specs)
- I/O (CSV read/write/quoting, directory creation, tile listing)
- Measurement (IntDen, CTCF, thresholded, ROI save/load)
- CLI (option parsing, paths with spaces, edge cases)
- Reporting (provenance, QC report HTML generation)
Jamie Malcolm — UK Dementia Research Institute, Brancaccio Lab