melage 2.1.2

MELAGE: An open-source Python toolkit for medical imaging (3D MRI & 3D ultrasound, 3D CT, etc.).

🧠🩻 MELAGE: Medical Imaging Software

Machine learning & analysis for next-generation neuroimaging and medical imaging research

Table of Contents

• Features
• Plugins & Dynamic Extensions
• Installation
• Usage
• Dependencies
• Manual (collapsible)
• License
• Citation & Acknowledgements
• Releases

---

MELAGE is an open-source neuroimaging software designed for analysis, segmentation, and visualization of multimodal datasets.
It combines classical medical image processing with state-of-the-art deep learning support, making it useful for both researchers and practitioners.

🚀 New in v2.x: Real-Time Video Segmentation MELAGE now supports full medical video loading and processing. Apply segmentation algorithms to video streams (e.g., Ultrasound loops) with the same speed and accuracy as static images. Analyze, segment, and save results frame-by-frame in real-time.

🎥 Key Features

• ⚡ Real-Time Video Processing: Seamlessly load medical videos (e.g., Ultrasound, Cine-MRI) and perform segmentation with the same high speed and accuracy as static images.
• 🖼️ Multi-Modality Support: Comprehensive support for MRI, CT, X-Ray, and Ultrasound data in standard formats (DICOM, NIfTI, AVI, MP4).
• 🧠 Deep Learning Integration: Built-in support for PyTorch models, allowing you to deploy state-of-the-art AI for automated segmentation and classification.
• 🛠️ Advanced Preprocessing: Powerful tools for denoising, filtering, resampling, and harmonizing image data before analysis.
• 🎨 Interactive Visualization: 2D and 3D rendering capabilities for exploring anatomical structures and segmentation results in detail.
• 🔌 Dynamic Plugin System: easily extend functionality by dropping Python scripts into the plugins/ folder—MELAGE automatically generates the GUI for you.
• 💾 Flexible Export: Save your results, including video segmentation masks, into standard research-ready formats.

🧩 Plugins & Dynamic Extensions

MELAGE now features a powerful Dynamic Plugin System that allows you to integrate custom Deep Learning models or image processing algorithms without modifying the core source code.

How it works:

1. Create: Write your algorithm or model wrapper as a Python class inheriting from the MELAGE Plugin base class.
2. Drop-in: Place your script in the plugins/ directory.
3. Auto-Load: MELAGE automatically detects, loads, and generates a GUI widget for your tool upon launch.

This modular architecture supports:

• Deep Learning inference: Drag-and-drop integration for .pth or .onnx models.
• Custom Analysis: Add proprietary segmentation or quantification logic.
• Workflow Automation: Create macros for repetitive tasks.

🚀 How to Add a Plugin

1. Folder Structure: Organize your plugin in its own directory under the plugins/ folder. MELAGE recursively scans these folders to find valid plugins.

   plugins/
   ├── warpseg/
   │   ├── __init__.py
   │   ├── WarpSeg.py       <-- Contains the Plugin Class
   │   └── WarpSeg_schema.py <-- Contains the Plugin Scheme for GUI
   └── my_new_tool/
       └── ...
   

🚀 Installation

🐧 LINUX:

🐍 STEP 0: INSTALL CONDA (PREREQUISITE)

If you don't have Conda, install Miniconda (lightweight version).

1. Download installer

   wget [https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh](https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh)
   

2. Run installer (Type 'yes' to license and init)

   bash Miniconda3-latest-Linux-x86_64.sh
   

3. Refresh shell

   source ~/.bashrc
   

🛠️ STEP 1: CREATE ENVIRONMENT (RECOMMENDED)

# Create env (Python 3.10 is most stable with PyQt5)
conda create -n melage-gui python=3.10 -c conda-forge -y

# Activate the environment
conda activate melage-gui

# Install PyQt5 (includes Qt frameworks)
conda install -c conda-forge pyqt=5 -y

# Install melage inside the environment
pip install melage

# Verify which melage is being used (should point to this env)
which melage

# Run
melage

📦 STEP 2: INSTALL MELAGE (STANDALONE)

If skipping Conda (Not recommended for GUI apps):

From PyPI:

pip install melage

🚀 STEP 3: CREATE ONE-CLICK LAUNCHERS

Create a script file to automatically activate the environment and run the app.

1. Create a file named 'launch_melage.sh' with the following content: (Note: Adjust the 'source' path if your conda is installed elsewhere)

   #!/bin/bash
   # Initialize Conda (Adjust path based on 'conda info --base')
   source ~/miniconda3/etc/profile.d/conda.sh
   conda activate melage-gui
   melage
   

2. Make it executable:

   chmod +x launch_melage.sh
   

3. Run it:

   ./launch_melage.sh
   

4. (Optional) Create a Desktop Shortcut file named 'Melage.desktop': (Create this file in ~/.local/share/applications/ for Start Menu access OR on your ~/Desktop/ for a desktop icon).

   [Desktop Entry]
   Version=1.0
   Type=Application
   Name=Melage
   Comment=Melage GUI
   # IMPORTANT: Use absolute paths below (e.g., /home/user/...)
   Exec=/home/user/path/to/launch_melage.sh
   Icon=/home/user/path/to/your_icon.png
   Terminal=false
   Categories=Utility;
   

5. (Optional) If put on Desktop, right-click file -> "Allow Launching".

---

🍎 macOS:

🐍 STEP 0: INSTALL CONDA (PREREQUISITE)

1. Download installer (Intel)

   curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh
   

   ... OR ...

   Download installer (Apple M1/M2 Silicon)

   curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh
   

2. Run installer

   bash Miniconda3-latest-MacOSX-x86_64.sh
   # or
   bash Miniconda3-latest-MacOSX-arm64.sh
   

3. Refresh shell

   source ~/.zshrc
   

🛠️ STEP 1: CREATE ENVIRONMENT (RECOMMENDED)

# Create env (Python 3.10 is most stable with PyQt5)
conda create -n melage-gui python=3.10 -c conda-forge -y

# Activate the environment
conda activate melage-gui

# Install PyQt5 (includes Qt frameworks)
conda install -c conda-forge pyqt=5 -y

# Install melage inside the environment
pip install melage

# Verify which melage is being used (should point to this env)
which melage

# Run
melage

📦 STEP 2: INSTALL MELAGE (STANDALONE)

If skipping Conda (Not recommended for GUI apps):

From PyPI:

pip install melage

🚀 STEP 3: CREATE ONE-CLICK LAUNCHERS

Create a script file to automatically activate the environment and run the app.

1. Create a file named 'launch_melage.sh' with the following content: (Note: Adjust the 'source' path if your conda is installed elsewhere)

   #!/bin/bash
   # Initialize Conda (Adjust path based on 'conda info --base')
   source ~/miniconda3/etc/profile.d/conda.sh
   conda activate melage-gui
   melage
   

2. Make it executable:

   chmod +x launch_melage.sh
   

3. Run it:

   ./launch_melage.sh
   

Alternatively

1. Open "Automator" (Cmd + Space -> Type Automator).
2. Select "Application" -> Click "Choose".
3. Search for "Run Shell Script" and double-click it.
4. Paste the code below (Update the path using 'conda info --base'!):

source /Users/yourname/miniconda3/etc/profile.d/conda.sh
conda activate melage-gui
melage

5. Press Cmd+S to save. Name it "Melage" and save to Applications.

--- HOW TO CHANGE THE APP ICON ---

1. Copy your logo image (Open image -> Cmd + C).
2. Right-click your new "Melage.app" -> "Get Info".
3. Click the small icon in the top-left corner of the Info window.
4. Paste (Cmd + V).

---

🖥️ WINDOWS:

🐍 STEP 0: INSTALL CONDA (PREREQUISITE)

1. Download .exe from https://docs.conda.io/en/latest/miniconda.html
2. Run installer.
3. Open "Anaconda Prompt" from Start Menu for the steps below.

🛠️ STEP 1: CREATE ENVIRONMENT (RECOMMENDED)

# Create env
conda create -n melage-gui python=3.10 -c conda-forge -y


# Activate
conda activate melage-gui

# Install PyQt5
conda install -c conda-forge pyqt=5 -y
# Install antspyx (Optioanl) to avoid pip install melage failed for any reason)
conda install -c conda-forge antspyx

# Install melage
pip install melage

# Run
melage

📦 STEP 2: INSTALL MELAGE (STANDALONE)

If skipping Conda (Not recommended for GUI apps):

From PyPI:

pip install melage

🚀 STEP 3: CREATE ONE-CLICK LAUNCHERS

1. Create a file named 'launch_melage.bat' with the following content:

   call conda activate melage-gui
   melage
   pause
   

2. Double-click 'launch_melage.bat' to run the app.
3. (Optional) Right-click the .bat file -> "Send to" -> "Desktop (create shortcut)" to give it a custom icon.

---

🖥️✨ Usage

After installation and activating your virtual environment, you can launch MELAGE directly from the terminal:

conda activate melage-gui
melage

MELAGE graphical user interface in action.

---

📦 Dependencies

MELAGE relies on the following core libraries:

- NumPy, SciPy – numerical computing & scientific operations  
- scikit-image, Pillow, OpenCV – image processing & visualization  
- scikit-learn, numba, einops – machine learning & acceleration  
- nibabel, pydicom, pynrrd, SimpleITK – medical imaging formats (NIfTI, DICOM, NRRD)  
- PyQt5, QtPy, qtwidgets – GUI support  
- matplotlib, vtk, PyOpenGL – visualization & rendering  
- shapely, trimesh, rdp – geometry & 3D mesh processing  
- pyfftw – fast Fourier transforms  
- cryptography – security utilities  
- dominate – HTML generation  

Optional Extras

• Deep Learning: torch>=1.12 (pip install melage[dl])

📖 Manual

🏠 Main Page

The Main Page is the first window that appears after launching MELAGE.

👉 From here, you can:

• ➕ Create a new project
• 📂 Load a previously saved project (default format: .bn)

The MELAGE Main Window

🛠️ Toolbars

1️⃣ Project Toolbar

Located at the top-left of the main window, the Project Toolbar provides quick access to essential project actions:

• 🆕 Create New Project – Start a new project and open a new image file.
• 📂 Load Project – Open a previously saved project with all applied changes (so you don’t lose your progress).
• 💾 Save Project – Save the current project. This will overwrite the existing file if one is already open.

🔗 These options are also available through the File menu:

• File → New Project
• File → Load Project
• File → Save

Project toolbar: (from left to right) Create New Project, Load Project, Save

2️⃣ Image Toolbar

To the right of the Project Toolbar, you’ll find the Image Toolbar, which allows you to load up to two images simultaneously:

• 🖼 Open First Image – Default button for loading First image (often referred to as the top image).
• 🧲 Open Second Image – Default button for loading Second image.

Image toolbar: Left – No project loaded. Right – Project loaded.

3️⃣ Tools Toolbar

At the top-left of MELAGE, you’ll find the Tools Toolbar, which contains seven buttons grouped into three sections:

• ✏️ Build Lines – Draw multiple lines in the same slice and create a segmentation by connecting their endpoints (explained in detail later).
• 🎯 Point Selection – Mark and locate selected points within a slice.
• 🔍 Zoom In – Zoom into all windows (3/6 view) simultaneously.
• 🔎 Zoom Out – Zoom out of all windows simultaneously.
• 📏 Measurement – Ruler tool to measure distances and lengths.
• 🔗 Linking – Synchronize sagittal, coronal, and axial slices. This makes it easy to locate the same point across all views.
• 🧊 3D Toggle – Show or hide 3D widgets in the view.

Tools toolbar with essential navigation and annotation functions

4️⃣ Panning Toolbar

Just below the Project Toolbar, you’ll find the Panning Toolbar with two options:

• 🖱 Arrow – Standard selection arrow.
• ✋ Panning – Drag to move around within a slice (useful after zooming).

Panning toolbar for navigating slices

5️⃣ Segmentation Toolbar

On the right side of the Panning Toolbar, you’ll find the Segmentation Toolbar. From left to right:

• 🩹 Eraser – Remove segmentation from the image.
• 🩹➕ Eraser X Times – Erase the same region across multiple following slices.
• 🖊 Pen – Freehand segmentation with arbitrary closed shapes.
• 🌀 Contour – Draw a contour to segment everything inside it.
• 🌀➕ Contour X Times – Apply contour segmentation across multiple slices.
• ⭕ Circle – Segment a region using a circle with an adjustable radius.
• 🎨 Activated Color – Displays the currently active segmentation color.
• 🏷 Color Name – Shows the name of the active segmentation color.

Segmentation toolbar for drawing and editing regions

6️⃣ Exit Toolbar

Finally, at the far right, you’ll find the Exit Toolbar, which includes:

• 🧩 Logo – Displays the MELAGE / MELAGE+ logo.
• ❌ Exit – Closes the application.

Exit toolbar with logo and close button

Widgets

🎨 Color widget

Color

Right click

Choose, activate, and search label colors (LUTs) for different structures. You can switch styles, import your own, and customize labels.

You can freely change styles—or add your own.
Currently default styles come from these human brain atlases:

• 🍼 Albert Neonatal brain atlas
• 🍼 M-CRIB 2.0 neonatal brain atlas
• 🧠 Adult brain (generic)

There are also two tissue-based styles and one simple scheme.
You can import a new style via Import.
Label names are editable, and you can create a new label by clicking a color in the Segmentation Toolbar.

Add a color

Pick a new color here. Then you’ll see a second window:

Add index and name

Set the index and name for the new color.
If the index already exists, the new color will replace the previous one.

🧰 Image enhancement widget

Image enhancement

Image enhancement (continued)

Enhance images with:

• 🔆 Brightness & contrast
• 🧱 Band-pass & Hamming filters
• 🧭 Sobel edge operator
• 🔄 Rotation by anatomical planes (sagittal, axial, coronal) or combinations

There’s also a “sagittal ↔ coronal” swap for datasets that need plane reorientation (handy for certain top/bottom image workflows).

📋 Table widget

Table widget

This table includes:

• 📝 Description – additional notes
• 🖼 Image type – top (first image) or bottom (second image)
• 📏 Measure 1 – surface or length (ruler)
• 📐 Measure 2 – perimeter or angle (ruler)
• 🧾 Slice – slice number
• 🪟 Window name – sagittal, coronal, or axial
• 🎯 CenterXY – center position
• 🗂 FileName – file name

Table widget (context menu)

Right-click options:

• ➕ Add – insert a new row
• ✏️ Edit – edit the current cell
• 📤 Export – save table as CSV
• 🗑 Remove – delete the current row

🖼️ Batch Images widget

Images widget

Manage a set of images (e.g., different modalities or sessions) and their corresponding segmentations.

• Toggle the eye icon to show/hide an image.
• A segmentation file requires its image to be loaded first.

Images widget (context menu)

Right-click options:

• 📥 Import
  • Images – import one or more images
  • Segmentation – import a segmentation associated with a loaded image
• 🗑 Remove Selected – remove the highlighted item
• 🧹 Clear All – clear all non-active images

When importing, you’ll see:

Import dialog

Choose the image/segmentation type from the dialog.
Use Preview to inspect an image before opening it. 👀

🌈 Segmentation intensity widget

Segmentation intensity

Adjust the visual intensity of the segmentation overlay.

• 0 ➜ hide segmentation
• Higher values ➜ stronger overlay

🖍️ Marker size widget

Marker size

Controls (top ➜ bottom):

• ⭕ Circle radius for region selection
• ✏️ Pen thickness for contour drawing

Tabs

MELAGE includes three tabs:

Tabs overview

1) 🤝 Mutual view

• Process two images at once.
• Each image shows three planes in the order: coronal, sagittal, axial.
• The number above each plane is the slice index.
• Side letters indicate orientation: S (sagittal), A (axial), C (coronal).
• You can segment and process either image directly in this view.
• The top panel shows the first (top) image; the bottom panel shows the second (bottom) image.
• If one image is closed, the tab displays the three planes of the remaining image:

2) 🧩 Top image (first image) workspace

Designed to focus on one plane at larger size while tracking the instant 3D view of the segmentation.

• 📜 Horizontal slider: scroll through slices
• 🔘 Plane selection: choose sagittal, axial, or coronal
• 👁 Show seg: toggle segmentation overlay
• 🧊 3D visualization: real-time 3D feedback

3) 🧩 Bottom image (second image) workspace

Same layout and controls, dedicated to the second (bottom) image.

• 📜 Horizontal slider: scroll through slices
• 🔘 Plane selection: sagittal, axial, or coronal
• 👁 Show seg: toggle segmentation overlay
• 🧊 3D visualization: real-time 3D feedback

🧊 3D Visualization

Right-click on the 3D region to access various options:

🔎 GoTo

• Activating GoTo lets you jump to the corresponding location in the image.
• The approximate mouse position in 3D space appears at the bottom-right of the window.
• The selected point will also appear in the closest sagittal, coronal, or axial plane.

🧩 Segmentation

• Toggle segmentation overlay within the 3D view.
• ⚠️ Tip: If it doesn’t activate immediately, switch to another tab and return.

🧩 Transparent 3D Overlay

MELAGE allows users to seamlessly overlay segmentation masks on top of anatomical images within the 3D visualization module. This feature enables clear comparison between raw data and segmented structures, while maintaining anatomical context.

• Transparency Control: Adjust the opacity of the segmentation layer for balanced visualization.
• Interactive Toggle: Enable or disable overlays dynamically without reloading the view.
• Integrated Navigation: Selected points remain synchronized across sagittal, coronal, and axial planes.
• ⚠️ Tip: If the overlay does not activate immediately, switch to another tab and return.

Transparent 3D overlay.

Transparent 3D overlay of segmentation mask and anatomical image in MELAGE.

🎨 BG color

• Change the background color of the 3D visualization.
• Choose between different themes to improve contrast.

🖌️ Painting

✏️ Draw

• Cut parts of the 3D image interactively by drawing.

🌈 Image render

• Render the 3D image using different color maps.
• The Segmentation Intensity widget can enhance visualization.

Rainbow	Gray	Jet
Gnuplot	Gnuplot2	Original

🧭 Axis

• Display axes alongside the 3D visualization for orientation.

🗺️ Grid

• Show a reference grid within the 3D window.

🛠️ Tools

✏️ Segmentation options with contour

Right-click on a segmented contour to access these options:

• 🎯 Center – show center of the region
• 📐 Surface area – compute region surface
• 📏 Perimeter – measure perimeter length
• 📤 Send to table – export all measurements to the table widget
• ➕ Add to interpolation – add the current slice to slice-to-slice interpolation
• ▶️ Apply interpolation – apply interpolation using current and previous slices

🔀 Interpolation between slices

To interpolate across slices:

1. ✅ Activate the colors you want to interpolate
2. 🖼 Select a segmented region in one plane (sagittal, axial, or coronal)
3. ➕ Add more regions from other slices (as many as needed)
4. 🖱 Right-click → Apply interpolation
5. ⏳ Wait for interpolation results

📏 Ruler

The ruler measures distances between two points in an image.
Right-click on a ruler gives access to:

• 🎯 Center position
• 📏 Length
• 📐 Line angle
• 🗑 Remove – delete the current ruler
• 📤 Send to table – export ruler data

🔄 You can add unlimited rulers.

🧰 Tools menu

Options available under the Tools menu:

• ↩️ Undo – revert up to 10 segmentations
• ↪️ Redo – redo up to 10 actions
• 🧪 Preprocessing – N4 Bias Field Correction, Image Masking, BET, DeepBET, Thresholding, Masking Ops, Change CS
• ℹ️ Basic Info – Histogram, Resize, Image Info

🧮 N4 Bias Field Correction

Uses SimpleITK. Parameters include:

• Otsu thresholding for mask creation
• Fitting level
• Shrinking factor
• Max iterations
• Image selection (top = first image, bottom = second image)

After running, you can restore the Original image if needed.

🎭 Image Masking

Keep or remove image parts using segmentation masks:

• Image selection (top or bottom)
• Action: Keep / Remove
• Mask color
• Apply button

Reset by using mask color 9876_Combined.

🧠 Brain Extraction Tool (BET)

Implements Smith 2002.
Parameters:

• Advanced mode
• Iterations
• Adaptive thresholding
• Fractional threshold
• Search distance
• Radius of curvature

🤖 Deep Learning Brain Extraction

DL-based brain extraction with configurable options:

• Advanced mode (editable)
• Image selection
• Model selection
• CUDA acceleration (optional)
• Threshold (-4 to 4)
• Network weights path
• Apply button

💡 Tip: Adjust threshold without rerunning the model.

⚖️ Image Thresholding

Multi-Otsu based thresholding:

• Image selection
• Number of classes
• Apply

➕➖ Masking Operations

Combine masks using summation or subtraction:

• Masking color(s)
• Operation
• Image selection
• Apply

🧭 Change CS (Coordinate System)

• Image selection
• From (current system)
• To (desired system)
• Apply

📊 Basic Info

Tools for inspecting and resizing images.

• 📈 Histogram – view image histogram
• 📐 Resize – isotropic resize

• ℹ️ Image info – metadata with search

📂 File Menu

Options include:

• 🆕 New project – start fresh
• 📂 Load project – open saved project
• 💾 Save – overwrite project
• 💾 Save as – save under new name
• 📥 Import – import segmentation

• 📤 Export – save modified image/segmentation with suffix

• 📸 Screenshot – capture a plane or whole scene

• ❌ Close top image – close first (top) image
• ❌ Close bottom image – close second (bottom) image
• ⚙️ Settings – change application defaults

• 🚪 Exit – close app (confirmation window will ask to save project)

📜 License

For licensing inquiries, please contact:

• [e-mail]
• [e-mail]

Protection & Registration

MELAGE is registered in the Electronic Register of Intellectual Property as software, under file FCAD-22002, by the Technology Transfer Office of the Andalusian Public Health System (OTT-SSPA).

• Identifier: 2211222681375
• View registration details on SafeCreative
  This legal protection ensures intellectual property rights are formally secured.

📖 Citation & Acknowledgements

If you use MELAGE in your research, please cite the following work:

Jafrasteh, B., Lubián-López, S. P., & Benavente-Fernández, I. (2023).
MELAGE: A purely Python-based Neuroimaging Software (Neonatal).
arXiv preprint arXiv:2309.07175

We would like to acknowledge all contributors and collaborators who have supported the development and testing of MELAGE.

🚀 Releases

Stable releases and updates of MELAGE are available on the GitHub Releases page.

• 🟢 Stable releases: Fully tested, recommended for production and research use.
• 🧪 Pre-releases / beta versions: For testing new features and providing feedback.

Stay updated by watching the repository for new release notifications.