napari-nifti-viewer

napari-nifti-viewer

A powerful napari plugin for comprehensive NIfTI file analysis and visualization.

Overview

napari-nifti-viewer is a comprehensive napari plugin specifically designed for reading, analyzing, and visualizing NIfTI (.nii/.nii.gz) files. It provides detailed metadata extraction, intelligent label detection, and seamless integration with napari's visualization capabilities.

Features

🔍 Complete NIfTI Support

• Read .nii and .nii.gz format files
• Support for NIfTI-1 standard
• Compatible with both image and label data

📊 Comprehensive Metadata Analysis

• Extract complete NIfTI header information (40+ fields)
• Display affine transformation matrices
• Show coordinate system information
• Analyze voxel spacing and orientation

🏷️ Intelligent Label Detection

• Automatic label image detection
• Statistical analysis of label distributions
• Label value counting and percentage calculations

📈 Data Statistics

• Complete data shape and type information
• Statistical measures (min, max, mean, std)
• Non-zero voxel counting
• Unique value analysis

💾 Export Capabilities

• Export complete metadata as JSON
• Preserve all numerical precision
• Human-readable format

🎨 User-Friendly Interface

• Clean, organized tabbed interface
• Real-time data loading
• Seamless napari integration

Interface

The plugin provides a clean, organized interface with three main tabs:

📋 File Overview Tab

Displays basic file information and data statistics including file size, format, data shape, and statistical measures.

📊 Detailed Information Tab

Shows complete NIfTI header fields and metadata in an organized table format, alongside full JSON metadata export.

🏷️ Label Analysis Tab

Provides intelligent label detection and statistical analysis with automatic identification of label images and distribution analysis.

Installation

From PyPI (Recommended)

pip install napari-nifti-viewer

From Source

git clone https://github.com/yohanchiu/napari-nifti-viewer.git
cd napari-nifti-viewer
pip install -e .

Quick Start

• Launch napari with the plugin installed
• Open the plugin from the Plugins menu → napari-nifti-viewer
• Load a file by clicking "Browse..." and selecting a .nii/.nii.gz file
• Explore the data across three informative tabs:
  • File Overview: Basic information and statistics
  • Detailed Info: Complete NIfTI headers and metadata
  • Label Analysis: Label detection and analysis
• Visualize in napari by clicking "Load to Napari"

Usage Examples

Loading a Medical Image

import napari
from napari_nifti_viewer import NiftiViewerWidget

# Create napari viewer
viewer = napari.Viewer()

# The plugin will be available in the Plugins menu
# Or you can add it programmatically:
widget = NiftiViewerWidget(viewer)
viewer.window.add_dock_widget(widget, name="NIfTI Viewer")

Exporting Metadata

The plugin allows you to export complete metadata including:

• File information (size, format, version)
• NIfTI header fields (all 40+ standard fields)
• Data statistics (shape, type, value ranges)
• Coordinate system information
• Affine transformation matrices

Requirements

• napari >= 0.4.18
• nibabel >= 5.2.1
• numpy >= 1.21.0
• qtpy >= 2.0.0
• magicgui >= 0.7.0
• Python >= 3.8

Supported File Formats

• .nii - Uncompressed NIfTI files
• .nii.gz - Compressed NIfTI files
• Compatible with NIfTI-1 standard
• Support for both neuroimaging and medical imaging data

Development

Setting up Development Environment

# Clone the repository
git clone https://github.com/yohanchiu/napari-nifti-viewer.git
cd napari-nifti-viewer

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
python -m pytest

Running Tests

# Basic functionality test
python test_plugin.py

# Test with napari interface
python test_plugin.py --napari

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Ways to Contribute

• 🐛 Report bugs
• 💡 Suggest new features
• 📝 Improve documentation
• 🔧 Submit pull requests

License

This project is licensed under the MIT License - see the LICENSE file for details.

Citation

If you use this plugin in your research, please consider citing:

@software{napari_nifti_viewer,
  title={napari-nifti-viewer: Comprehensive NIfTI Analysis for napari},
  author={Qiu Yuheng},
  year={2024},
  url={https://github.com/yohanchiu/napari-nifti-viewer}
}

Acknowledgments

• Built with napari - a fast, interactive, multi-dimensional image viewer
• Uses nibabel for NIfTI file handling
• Inspired by the neuroimaging and medical imaging communities

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Made with ❤️ for the napari and neuroimaging communities