README.md

NetCDF Explorer

A Flask web application for uploading and analyzing NetCDF3 and NetCDF4 files.

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Configuration
5. Testing
6. Roadmap
7. Contact
8. Acknowledgments

About The Project

NetCDF Explorer (netex) is a web application that allows users to upload and analyze NetCDF3 and NetCDF4 files. It provides a simple interface for viewing file metadata and structure using xarray's HTML representation.

Key features:

• Upload and view NetCDF file summaries including dimensions, coordinates, and variables

Built With

• 
• 
• 
• 
• 
• 

NetCDF Engines

NetCDF Explorer uses xarray to read uploaded files. Since files are streamed from MinIO into memory, xarray selects a backend engine that supports reading from in-memory buffers. The engine is chosen automatically at runtime based on the file format:

File Format	Engine	Notes
NetCDF3 (classic)	scipy	Handles classic and 64-bit offset NetCDF formats
NetCDF4 / HDF5	h5netcdf	Reads HDF5-based NetCDF4 files via h5py

(back to top)

Getting Started

To get a local copy up and running, follow these steps.

Prerequisites

• Docker and Docker Compose (for containerized deployment)
• uv (for standalone development)
• Node.js (for Tailwind CSS compilation)

Installation

Docker Compose (Recommended)

1. Clone the repo

   git clone https://github.com/mversaggi/netcdf-explorer.git
   cd netcdf-explorer

2. Start the application with Docker Compose

   docker compose up

3. Access the application at http://localhost:5000

Standalone Development

1. Clone the repo

   git clone https://github.com/mversaggi/netcdf-explorer.git
   cd netcdf-explorer

2. Install Python 3.13 with uv

   uv python install 3.13

3. Install dependencies

   uv sync

4. Build Tailwind CSS

   npm install tailwindcss @tailwindcss/cli
   npx @tailwindcss/cli -i ./static/src/input.css -o ./static/dist/output.css

5. Run the application

   uv run flask --app "src/netex/app:create_app" run

(back to top)

Usage

1. Navigate to the home page
2. Select a NetCDF file using the file input
3. Click "Explore" to upload the file
4. View the file summary showing dimensions, coordinates, variables, and attributes

(back to top)

Configuration

Configuration is loaded from a TOML file with environment variable overrides. The config file path is specified by the NETEX_CONFIG environment variable.

Environment Variables

Variable	Description	Default
NETEX_CONFIG	Path to TOML config file	Required
FLASK_DEBUG	Enable Flask debug mode	false
FLASK_SECRET_KEY	Flask session secret key	Required
OBJECT_STORAGE_ENDPOINT	MinIO server endpoint	Required
OBJECT_STORAGE_ACCESS_KEY	MinIO access key	Required
OBJECT_STORAGE_SECRET_KEY	MinIO secret key	Required
OBJECT_STORAGE_SECURE	Use HTTPS for MinIO	false
LOGGER_LEVEL	Logging level (DEBUG, INFO, etc.)	INFO

Example Configuration File

[flask]
debug = true
secret_key = "your_secret_key"

[object_storage]
endpoint = "localhost:9000"
access_key = "minioadmin"
secret_key = "minioadmin"
secure = false

[logger]
level = "info"

(back to top)

Testing

This project uses pytest for testing.

# Run all tests
uv run pytest

# Run unit tests only
uv run pytest tests/unit/

# Run integration tests only (requires Docker for MinIO container)
uv run pytest tests/integration/

# Run with coverage
uv run pytest --cov=src --cov-report=html:tests/reports

Code Formatting

# Format Python code
uv run black src/ tests/

# Format Jinja2 templates
uv run djlint templates/ --reformat

(back to top)

Roadmap

• File upload and storage in MinIO
• Organized summary view of file
• Variable visualization on globe
• View saved files

See the open issues for a full list of proposed features and known issues.

(back to top)

Contact

Project Link: https://github.com/mversaggi/netcdf-explorer

(back to top)

Acknowledgments

• xarray - N-D labeled arrays and datasets in Python
• Best-README-Template - README template

(back to top)