HDF5 Reader

A PyQt5-based HDF5 file viewer with an expandable tree interface and dataset preview capabilities.

Features

• Expandable Tree View: Navigate through HDF5 groups and datasets with an intuitive tree interface
• Dataset Preview: View 2D table representations of datasets with support for:
  • Slicing for multidimensional arrays (>2D)
  • Paging for large arrays
  • Various data types including strings and binary data
• Metadata Display: View dataset shape, dtype, and attributes
• Drag & Drop Support: Simply drag .h5/.hdf5 files onto the window to open them
• File Menu: Traditional file open dialog for selecting HDF5 files

Installation

Method 1: Install as a Python Package (Recommended)

# Install from the directory containing pyproject.toml
pip install .

# Or for development installation
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"

After installation, you can run the program from anywhere:

# Any of these commands will work:
hdf5-reader
hdf5-viewer
hdf5-reader-gui

# With a file argument:
hdf5-reader /path/to/your/file.hdf5

Method 2: Install Dependencies and Run Directly

# Install dependencies
pip install -r requirements.txt

# Run directly
python hdf5_reading.py /path/to/your/file.hdf5

# Or use the standalone script
./hdf5-reader /path/to/your/file.hdf5

Method 3: Desktop Integration (Linux)

For easy desktop integration on Linux systems:

# Run the desktop installer
./install-desktop.sh

This will:

• Install a desktop entry in your applications menu
• Allow you to open .h5/.hdf5 files by double-clicking
• Make HDF5 Reader available in your file manager's "Open with" menu

Requirements

• Python 3.7+
• PyQt5 >= 5.12.0
• h5py >= 3.0.0
• numpy >= 1.19.0

Usage

Command Line

# Open HDF5 Reader with a file dialog
hdf5-reader

# Open a specific file
hdf5-reader /path/to/your/data.hdf5

# Alternative commands (all equivalent)
hdf5-viewer /path/to/your/data.hdf5
python hdf5_reading.py /path/to/your/data.hdf5
./hdf5-reader /path/to/your/data.hdf5

GUI Usage

1. Opening Files:

   • Use File → Open menu
   • Drag and drop .h5/.hdf5 files onto the window
   • Pass filename as command line argument

2. Navigation:

   • Click on groups in the left tree to expand them
   • Click on datasets to preview their contents
   • Use the right panel slicers for multidimensional data

3. Dataset Preview:

   • 2D data is displayed directly in a table

   • 2D data can be sliced using the dimension controls

   • Large datasets are paged automatically
   • Metadata and attributes are shown in the bottom panel

Development

Setting up Development Environment

# Clone/download the project
git clone <your-repo-url>
cd hdf5_reading

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

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

Project Structure

hdf5_reading/
├── hdf5_reader/           # Main package
│   ├── __init__.py        # Package initialization
│   └── viewer.py          # Main viewer application
├── hdf5_reading.py        # Original standalone script
├── hdf5-reader            # Standalone executable script
├── hdf5-reader.desktop    # Desktop entry file
├── install-desktop.sh     # Desktop integration installer
├── setup.py               # Setup script (legacy)
├── pyproject.toml         # Modern Python packaging
├── requirements.txt       # Dependencies
└── README.md              # This file

Building and Distribution

# Install build tools
pip install build twine

# Build the package
python -m build

# This creates:
# - dist/hdf5_reader-1.0.0.tar.gz (source distribution)
# - dist/hdf5_reader-1.0.0-py3-none-any.whl (wheel)

Running Tests

# Install test dependencies
pip install -e ".[dev]"

# Run tests (when test suite is available)
pytest

License

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

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Troubleshooting

Common Issues

1. PyQt5 Installation Issues:

   # On Ubuntu/Debian
   sudo apt-get install python3-pyqt5
   
   # Or try installing from conda
   conda install pyqt

2. HDF5 Library Issues:

   # On Ubuntu/Debian
   sudo apt-get install libhdf5-dev
   
   # On macOS with Homebrew
   brew install hdf5

3. Permission Issues with Desktop Integration:

   # Make sure the script is executable
   chmod +x hdf5-reader
   chmod +x install-desktop.sh

Getting Help

• Check the GitHub Issues page for known problems
• Create a new issue with:
  • Your operating system and Python version
  • Full error messages
  • Steps to reproduce the problem

Changelog

Version 1.0.0

• Initial release
• HDF5 tree navigation
• Dataset preview with slicing
• Drag & drop support
• Desktop integration
• Package structure for easy installation