melage 0.0.70__py3-none-any.whl → 0.0.72__py3-none-any.whl

melage-0.0.72.dist-info/METADATA

@@ -0,0 +1,914 @@
+Metadata-Version: 2.4
+Name: melage
+Version: 0.0.72
+Summary: MELAGE: An open-source Python toolkit for neonatal and adult neuroimaging (MRI & 3D ultrasound).
+Author-email: Bahram Jafrasteh <jafrasteh.bahram@inibica.es>
+Project-URL: Homepage, https://github.com/BahramJafrasteh/MELAGE
+Project-URL: Repository, https://github.com/BahramJafrasteh/MELAGE
+Project-URL: Issues, https://github.com/BahramJafrasteh/MELAGE/issues
+Project-URL: Documentation, https://github.com/BahramJafrasteh/MELAGE#readme
+Keywords: neuroimaging,MRI,ultrasound,segmentation,visualization,neonatal,medical-imaging
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: scikit-image
+Requires-Dist: scikit-learn
+Requires-Dist: matplotlib
+Requires-Dist: Pillow
+Requires-Dist: nibabel
+Requires-Dist: pydicom
+Requires-Dist: pynrrd
+Requires-Dist: qtwidgets
+Requires-Dist: SimpleITK
+Requires-Dist: opencv-python-headless
+Requires-Dist: PyQt5
+Requires-Dist: PyOpenGL
+Requires-Dist: vtk
+Requires-Dist: pyfftw
+Requires-Dist: shapely
+Requires-Dist: cryptography
+Requires-Dist: trimesh
+Requires-Dist: numba
+Requires-Dist: einops
+Requires-Dist: dominate
+Requires-Dist: rdp
+Requires-Dist: QtPy
+Provides-Extra: dl
+Requires-Dist: torch>=1.12; extra == "dl"
+Provides-Extra: bids
+Requires-Dist: pybids>=0.16; extra == "bids"
+Requires-Dist: bids-validator>=1.14; python_version < "3.12" and extra == "bids"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+
+<style>
+td, th {
+   border: none!important;
+}
+</style>
+
+
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/additional_resources/demo.gif" alt="MELAGE Demo" width="400"/><br>
+  <h1 align="center">🧠🩻 MELAGE: Medical Imaging Software</h1>
+  <p align="center">
+    <em>Machine learning & analysis for next-generation neuroimaging and medical imaging research</em>  
+  </p>
+</p>
+
+
+MELAGE is an open-source **medical imaging 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.
+
+## ✨ Features
+
+- 🧠 **Medical Image Preprocessing**: resampling, denoising, and filtering for various modalities (MRI, CT, Ultrasound, etc.).
+- 🎯 **Segmentation and Labeling**: Region-based segmentation and anatomical labeling with support for standard medical formats.
+- 🖼️ **Visualization**: Interactive 2D/3D visualization of images, segmentations, and anatomical structures.
+- 🔗 **Deep Learning Integration (Optional)**: Seamless use of PyTorch for model-based tasks when installed.
+- 💡 **Extensible Design**: Modular framework that can be adapted for different medical imaging research workflows.
+
+## 🚀 Installation
+
+### 🛠️ 1. Create a Virtual Environment (Recommended)
+
+For **Linux / macOS**:
+```bash
+python3 -m venv melage
+source melage/bin/activate
+```
+
+For **Windows (PowerShell)**:
+```bash
+python -m venv melage
+melage\Scripts\activate
+```
+
+### 📦 2. Install MELAGE
+
+From **PyPI**:
+```bash
+pip install melage
+```
+
+
+### 🤖 3. (Optional) Install Deep Learning Support
+```bash
+pip install mealge[dl] 
+```
+
+---
+
+## 🖥️✨ Usage
+
+After installation and activating your virtual environment, you can launch **MELAGE** directly from the terminal:
+
+```bash
+melage
+```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/additional_resources/MELAGE_main-1536x615.png" 
+       alt="MELAGE GUI Screenshot" 
+       style="max-width:800px; height:auto; border:1px solid #ccc; border-radius:10px;">
+  <br>
+  <em> MELAGE graphical user interface in action.</em>
+</p>
+
+---
+# Table of contents
+- [Dependencies](#dependencies)
+- [Installation](#installation)
+- [How to use](#manual)
+- [Toolbars](#toolbars)
+- [Widgets](#widgets)
+- [Tabs](#tabs)
+- [Tools](#tools)
+- [License](#license)
+- [Releases](#releases)
+- [Citation and acknowledgements](#citation-and-acknowledgements)
+
+## 📦 Dependencies
+
+MELAGE relies on the following core libraries:
+```bash
+- 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`)  
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/main_page.png" 
+       alt="MELAGE Main Window" 
+       width="800" 
+       style="border:1px solid #ccc; border-radius:8px; object-fit:contain;">
+</p>
+
+<p align="center"><em>The MELAGE Main Window</em></p>
+
+
+# 🛠️ 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`  
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/open_save_load.png" 
+       alt="MELAGE Project Toolbar" 
+       width="250" 
+       style="border:1px solid #ccc; border-radius:6px; object-fit:contain;">
+</p>
+
+<p align="center"><em>Project toolbar: (from left to right) Create New Project, Load Project, Save</em></p>
+
+
+## 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**.  
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/load_image_file.png" 
+       alt="MELAGE Image Toolbar (no project)" 
+       width="250" 
+       style="border:1px solid #ccc; border-radius:6px; object-fit:contain; margin-right:10px;">
+  <img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/load_image_file_openp.png" 
+       alt="MELAGE Image Toolbar (project loaded)" 
+       width="250" 
+       style="border:1px solid #ccc; border-radius:6px; object-fit:contain;">
+</p>
+
+<p align="center"><em>Image toolbar: Left – No project loaded. Right – Project loaded.</em></p>
+
+
+
+## 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.  
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/toolbar_tools.png" 
+       alt="MELAGE Tools Toolbar" 
+       width="500" 
+       style="border:1px solid #ccc; border-radius:6px; object-fit:contain;">
+</p>  
+
+<p align="center"><em>Tools toolbar with essential navigation and annotation functions</em></p>
+
+
+## 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).  
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/panning_toolbar.png" 
+       alt="MELAGE Panning Toolbar" 
+       width="220" 
+       style="border:1px solid #ccc; border-radius:6px; object-fit:contain;">
+</p>  
+
+<p align="center"><em>Panning toolbar for navigating slices</em></p>
+
+
+
+## 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.  
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/segmentation_toolbar.png" 
+       alt="MELAGE Segmentation Toolbar" 
+       width="600" 
+       style="border:1px solid #ccc; border-radius:6px; object-fit:contain;">
+</p>  
+
+<p align="center"><em>Segmentation toolbar for drawing and editing regions</em></p>
+
+
+
+## 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.  
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/exit_toolbar.png" 
+       alt="MELAGE Exit Toolbar" 
+       width="300" 
+       style="border:1px solid #ccc; border-radius:6px; object-fit:contain;">
+</p>  
+
+<p align="center"><em> Exit toolbar with logo and close button</em></p>
+
+# Widgets
+
+## 🎨 Color widget
+
+<table>
+<tr>
+<td>
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/widget_color.png" alt="MELAGE" width="750" style="border:1px solid black" object-fit="contain"/><br>
+<font size="2"> Color </font> 
+</p>
+</td>
+<td>
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/widget_color_additional.png" alt="MELAGE" width="1000" style="border:1px solid black" object-fit="contain"/><br>
+<font size="2"> Right click</font> 
+</p>
+</td>
+<td>
+<font size="5">
+Choose, activate, and search label colors (LUTs) for different structures. You can switch styles, import your own, and customize labels. 
+</font>
+</td>
+</tr>
+</table>
+
+You can freely change styles—or add your own.  
+Currently default styles come from these human brain atlases:
+
+- 🍼 [Albert Neonatal brain atlas](https://brain-development.org/brain-atlases/neonatal-brain-atlases/neonatal-brain-atlas-gousias/)
+- 🍼 [M-CRIB 2.0 neonatal brain atlas](https://osf.io/4vthr/)
+- 🧠 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**.
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/widget_color_add.png" alt="MELAGE" width="300" style="border:1px solid black" object-fit="contain"/><br>
+<font size="2"> Add a color</font> 
+</p>
+
+Pick a new color here. Then you’ll see a second window:
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/widget_color_add2.png" alt="MELAGE" width="300" style="border:1px solid black" object-fit="contain"/><br>
+<font size="2"> Add index and name</font> 
+</p>
+
+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
+
+<table>
+<tr>
+<td>
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/widget_mri.png" alt="MELAGE" width="400" style="border:1px solid black" object-fit="contain"/><br>
+<font size="2">Image enhancement</font> 
+</p>
+</td>
+<td>
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/widget_mri2.png" alt="MELAGE" width="400" style="border:1px solid black" object-fit="contain"/><br>
+<font size="2">Image enhancement (continued)</font> 
+</p>
+</td>
+</tr>
+</table>
+
+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
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/widget_table.png" alt="MELAGE" width="700" style="border:1px solid black" object-fit="contain"/><br>
+<font size="2">Table widget</font> 
+</p>
+
+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  
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/widget_table2.png" alt="MELAGE" width="300" style="border:1px solid black" object-fit="contain"/><br>
+<font size="2">Table widget (context menu)</font> 
+</p>
+
+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
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/widget_images.png" alt="MELAGE" width="400" style="border:1px solid black" object-fit="contain"/><br>
+<font size="2">Images widget</font> 
+</p>
+
+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.  
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/widget_images2.png" alt="MELAGE" width="400" style="border:1px solid black" object-fit="contain"/><br>
+<font size="2">Images widget (context menu)</font> 
+</p>
+
+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:
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/widget_images3.png" alt="MELAGE" width="800" style="border:1px solid black" object-fit="contain"/><br>
+<font size="2">Import dialog</font> 
+</p>
+
+Choose the **image/segmentation type** from the dialog.  
+Use **Preview** to inspect an image before opening it. 👀
+
+
+
+## 🌈 Segmentation intensity widget
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/widget_segintensity.png" alt="MELAGE" width="300" style="border:1px solid black" object-fit="contain"/><br>
+<font size="2">Segmentation intensity</font> 
+</p>
+
+Adjust the **visual intensity** of the segmentation overlay.  
+- **0** ➜ hide segmentation  
+- Higher values ➜ stronger overlay
+
+
+
+## 🖍️ Marker size widget
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/widget_marker.png" alt="MELAGE" width="300" style="border:1px solid black" object-fit="contain"/><br>
+<font size="2">Marker size</font> 
+</p>
+
+Controls (top ➜ bottom):
+- ⭕ **Circle radius** for region selection  
+- ✏️ **Pen thickness** for contour drawing  
+
+
+# Tabs
+
+MELAGE includes three tabs:
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/tabs.png" alt="MELAGE" width="800" style="border:1px solid black" object-fit="contain"/><br>
+<font size="2">Tabs overview</font> 
+</p>
+
+### 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:
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/additional_resources/widget_tab_mutualview.png" alt="MELAGE" width="800" style="border:1px solid black" object-fit="contain"/><br>
+</p>
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/additional_resources/widget_tab_mutualview2.png" alt="MELAGE" width="800" style="border:1px solid black" object-fit="contain"/><br>
+</p>
+
+### 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
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/additional_resources/tab1.png" alt="MELAGE" width="800" style="border:1px solid black" object-fit="contain"/><br>
+</p>
+
+### 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
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/additional_resources/tab2.png" alt="MELAGE" width="800" style="border:1px solid black" object-fit="contain"/><br>
+</p>
+
+# 🧊 3D Visualization
+
+Right-click on the 3D region to access various options:
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/additional_resources/3D_rightc.png" alt="MELAGE" width="400" style="border:1px solid black" object-fit="contain"/><br>
+</p>
+
+## 🔎 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.
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/additional_resources/3D_rightc_goto.png" alt="MELAGE" width="700" style="border:1px solid black" object-fit="contain"/><br>
+</p>
+
+
+
+## 🧩 Segmentation
+- Toggle segmentation overlay within the 3D view.  
+- ⚠️ Tip: If it doesn’t activate immediately, switch to another tab and return.
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/additional_resources/3D_rightc_seg.png" alt="MELAGE" width="700" style="border:1px solid black" object-fit="contain"/><br>
+</p>
+
+
+## 🧩 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.  
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/additional_resources/transparent_3D_overlay_0.png" 
+     alt="MELAGE Transparent 3D Overlay" width="700" 
+     style="border:1px solid black; object-fit:contain"/><br>
+<em>Transparent 3D overlay.</em>
+</p>
+
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/additional_resources/transparent_3D_overlay.png" 
+     alt="MELAGE Transparent 3D Overlay" width="700" 
+     style="border:1px solid black; object-fit:contain"/><br>
+<em>Transparent 3D overlay of segmentation mask and anatomical image in MELAGE.</em>
+</p>
+
+
+## 🎨 BG color
+- Change the background color of the 3D visualization.  
+- Choose between different themes to improve contrast.
+
+
+
+## 🖌️ Painting
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/additional_resources/3D_rightc_paint.png" alt="MELAGE" width="700" style="border:1px solid black" object-fit="contain"/><br>
+</p>
+
+### ✏️ Draw
+- Cut parts of the 3D image interactively by drawing.
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/additional_resources/cut_3D.png" alt="MELAGE" width="700" style="border:1px solid black" object-fit="contain"/>
+</p>
+
+
+
+### 🌈 Image render
+- Render the 3D image using different color maps.  
+- The **Segmentation Intensity widget** can enhance visualization.
+
+<table>
+<tr>
+<td>
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/3D_rightc_paint_render.png" alt="MELAGE" width="400" style="border:1px solid black" object-fit="contain"/>
+<font size="2">Rainbow</font> 
+</p>
+</td>
+<td>
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/3D_rightc_paint_render2.png" alt="MELAGE" width="400" style="border:1px solid black" object-fit="contain"/>
+<font size="2">Gray</font> 
+</p>
+</td>
+<td>
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/3D_rightc_paint_render3.png" alt="MELAGE" width="400" style="border:1px solid black" object-fit="contain"/>
+<font size="2">Jet</font> 
+</p>
+</td>
+</tr>
+<tr>
+<td>
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/3D_rightc_paint_render4.png" alt="MELAGE" width="400" style="border:1px solid black" object-fit="contain"/>
+<font size="2">Gnuplot</font> 
+</p>
+</td>
+<td>
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/3D_rightc_paint_render5.png" alt="MELAGE" width="400" style="border:1px solid black" object-fit="contain"/>
+<font size="2">Gnuplot2</font> 
+</p>
+</td>
+<td>
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/3D_rightc_paint_render6.png" alt="MELAGE" width="400" style="border:1px solid black" object-fit="contain"/>
+<font size="2">Original</font> 
+</p>
+</td>
+</tr>
+</table>
+
+
+
+## 🧭 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  
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/additional_resources/tools_seg.png" alt="MELAGE" width="400" style="border:1px solid black" object-fit="contain"/>
+</p>
+
+
+## 🔀 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  
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/additional_resources/tools_ruler.png" alt="MELAGE" width="400" style="border:1px solid black" object-fit="contain"/>
+</p>
+
+🔄 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  
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/tools_tools.png" alt="MELAGE" width="400" style="border:1px solid black" object-fit="contain"/>
+</p>
+
+### 🧮 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.
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/tools_n4b.png" alt="MELAGE" width="600" style="border:1px solid black" object-fit="contain"/>
+</p> 
+
+
+### 🎭 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`.
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/tools_masking.png" alt="MELAGE" width="600" style="border:1px solid black" object-fit="contain"/>
+</p> 
+
+
+
+### 🧠 Brain Extraction Tool (BET)
+Implements [Smith 2002](https://pubmed.ncbi.nlm.nih.gov/12391568/).  
+Parameters:
+- Advanced mode  
+- Iterations  
+- Adaptive thresholding  
+- Fractional threshold  
+- Search distance  
+- Radius of curvature  
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/tools_bet.png" alt="MELAGE" width="400" style="border:1px solid black" object-fit="contain"/>
+</p> 
+
+
+
+### 🤖 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.
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/tools_deepbet.png" alt="MELAGE" width="600" style="border:1px solid black" object-fit="contain"/>
+</p>
+
+
+### ⚖️ Image Thresholding
+Multi-Otsu based thresholding:
+- Image selection  
+- Number of classes  
+- Apply  
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/tools_threshold.png" alt="MELAGE" width="600" style="border:1px solid black" object-fit="contain"/>
+</p>
+
+
+### ➕➖ Masking Operations
+Combine masks using summation or subtraction:
+- Masking color(s)  
+- Operation  
+- Image selection  
+- Apply  
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/tools_maskO.png" alt="MELAGE" width="600" style="border:1px solid black" object-fit="contain"/>
+</p> 
+
+
+
+### 🧭 Change CS (Coordinate System)
+- Image selection  
+- From (current system)  
+- To (desired system)  
+- Apply  
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/tools_cs.png" alt="MELAGE" width="600" style="border:1px solid black" object-fit="contain"/>
+</p> 
+
+
+
+### 📊 Basic Info
+Tools for inspecting and resizing images.
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/tools_basic.png" alt="MELAGE" width="400" style="border:1px solid black" object-fit="contain"/>
+</p> 
+
+- 📈 **Histogram** – view image histogram  
+- 📐 **Resize** – isotropic resize  
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/tools_resize.png" alt="MELAGE" width="400" style="border:1px solid black" object-fit="contain"/>
+</p> 
+
+- ℹ️ **Image info** – metadata with search  
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/tools_imageinfo.png" alt="MELAGE" width="500" style="border:1px solid black" object-fit="contain"/>
+</p> 
+
+
+
+# 📂 File Menu
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/menu_file.png" alt="MELAGE" width="500" style="border:1px solid black" object-fit="contain"/>
+</p> 
+
+Options include:
+- 🆕 **New project** – start fresh  
+- 📂 **Load project** – open saved project  
+- 💾 **Save** – overwrite project  
+- 💾 **Save as** – save under new name  
+- 📥 **Import** – import segmentation  
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/menu_file_import.png" alt="MELAGE" width="500" style="border:1px solid black" object-fit="contain"/>
+</p> 
+
+- 📤 **Export** – save modified image/segmentation with suffix  
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/menu_file_export.png" alt="MELAGE" width="500" style="border:1px solid black" object-fit="contain"/>
+</p> 
+
+- 📸 **Screenshot** – capture a plane or whole scene  
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/menu_file_ss.png" alt="MELAGE" width="500" style="border:1px solid black" object-fit="contain"/>
+</p> 
+
+- ❌ **Close top image** – close first (top) image  
+- ❌ **Close bottom image** – close second (bottom) image  
+- ⚙️ **Settings** – change application defaults  
+
+<p align="center"> 
+<img src="https://raw.githubusercontent.com/BahramJafrasteh/MELAGE/main/resource/manual_images/menu_file_settings.png" alt="MELAGE" width="500" style="border:1px solid black" object-fit="contain"/>
+</p> 
+
+- 🚪 **Exit** – close app (confirmation window will ask to save project)
+
+# 📜 License  
+For licensing inquiries, please contact:  
+- [b.jafrasteh@gmail.com](mailto:b.jafrasteh@gmail.com)  
+- [baj4003@med.cornell.edu](mailto:baj4003@med.cornell.edu)  
+
+##  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](https://www.safecreative.org/work/2211222681375-melage?0)  
+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](https://github.com/BahramJafrasteh/MELAGE/releases).  
+- 🟢 **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.