ayenpure · ayenpure · Aug 11, 2025 · Aug 3, 2025 · Aug 3, 2025 · Aug 4, 2025
diff --git a/.bumpversion.cfg b/.bumpversion.cfg
@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.1.8
+current_version = 0.1.9
 commit = True
 tag = True
 

diff --git a/README.md b/README.md
@@ -3,70 +3,141 @@
 [![Test](https://github.com/ayenpure/QuickView/actions/workflows/test.yml/badge.svg)](https://github.com/ayenpure/QuickView/actions/workflows/test.yml)
 [![Package and Release](https://github.com/ayenpure/QuickView/actions/workflows/package-and-release.yml/badge.svg)](https://github.com/ayenpure/QuickView/actions/workflows/package-and-release.yml)
 
-A scientific visualization application for exploring atmospheric data from the
-E3SM (Energy Exascale Earth System Model) project.
+**QuickView** is an interactive visualization tool designed specifically for
+atmospheric scientists working with E3SM (Energy Exascale Earth System Model)
+data. Built on ParaView and Trame, it provides an intuitive interface for
+exploring atmospheric simulation outputs without the steep learning curve of
+general-purpose visualization tools.
 
-## Setting up conda environment
+![quickview](docs/images/main.png)
 
-This trame application has two requirements.
+## Why QuickView?
 
-### Python version 3.10
+Traditional visualization tools like ParaView and VisIt, while powerful, often
+require significant time investment to master their complex interfaces and may
+lack atmospheric science-specific features out of the box. QuickView addresses
+these challenges by:
 
-Python can be installed using either `homebrew` if using macOS like
+- **Reducing the learning curve** - Atmospheric scientists can start visualizing
+  their data immediately
+- **Eliminating "last-mile" effort** - No need to write custom scripts or
+  plugins for common tasks
+- **Accelerating insights** - Focus on science, not software configuration
+- **Building on proven technology** - Leverages ParaView's robust data
+  processing with a tailored interface
 
-`brew install python3.10`
+## Installation
 
-or `apt` if using Ubuntu Linux.
+### Using Conda (Recommended)
 
-`sudo apt install python3.10`
+1. Create and activate a conda environment:
 
-Alternatively, python can also be installed using anaconda/miniconda
+```bash
+conda env create -f quickview-env.yml
+conda activate quickview
+```
 
-`conda create --name eamapp python=3.10.0 conda activate eamapp`
+2. Install QuickView:
 
-However, this would require activating the conda environment before using the
-app.
+```bash
+pip install .
+```
 
-### ParaView 5.13 installed on the system
+### Requirements
 
-ParaView can be installed from the binaries found at
-https://www.paraview.org/download
+- Python 3.13
+- ParaView 5.13.3 (installed automatically with conda environment)
+- Trame and other dependencies (installed automatically)
 
-The additional requirements for the app are satisfied once the app is launched
-for the very first time using Python virtual environments `venv`. An additional
-step for the use is to provide the path to ParaView's Python client that is
-distributed with the ParaView binaries. The `pvpython` binary is present in the
-`bin` directory of ParaView, on macOS the path is something like
-`/Applications/ParaView-5.13.0.app/Contents/bin/pvpython`
+## Getting the Code
 
-To clone this repository use the following commands
+### Clone from GitHub
 
+```bash
+git clone https://github.com/ayenpure/QuickView.git
+cd QuickView
 ```
-git clone https://gitlab.kitware.com/ayenpure/eamapp.git
-cd eamapp
-git lfs install
-git lfs pull
+
+### Download as Archive
+
+```bash
+wget https://github.com/ayenpure/QuickView/archive/main.tar.gz
+tar -xvzf main.tar.gz
+cd QuickView-main
 ```
 
-Alternatively, the code can also be downloaded as a tarball
+## Running the Application
+
+To run QuickView with a data file:
 
+```bash
+python -m quickview.app --data data/aerosol_F2010.eam.h0.2014-12.nc
 ```
-wget https://gitlab.kitware.com/ayenpure/eamapp/-/archive/master/eamapp-master.tar.gz
-tar -xvzf eamapp-master.tar.gz
-cd eamapp-master
+
+### Command Line Options
+
+- `--data`: Path to the NetCDF data file (required)
+- `--conn`: Path to the connectivity file (optional)
+- `--port`: Server port (default: 8080)
+- `--host`: Server host (default: localhost)
+
+### Example with Custom Files
+
+```bash
+python -m quickview.app --data /path/to/your/data.nc --conn /path/to/your/connectivity.nc
 ```
 
-To run the app, execute
+The application will start a Trame web server. Open your browser and navigate
+to:
 
 ```
-python3 launch.py --data data/aerosol_F2010.eam.h0.2014-12.nc
+http://localhost:8080
 ```
 
-Please ensure that the `python3` is the correct version. In the above execution
-the data file is provided as the sample data out of the repository. The
-repository also contains the connectivity file that it uses by default. If
-another connectivity and data files are to be used please specify the paths
-using the `--conn` and `--data` options.
+## Sample Data
+
+The repository includes sample data files in the `data/` directory for testing:
+
+- `aerosol_F2010.eam.h0.2014-12.nc` - Sample atmospheric data
+- Default connectivity file is automatically loaded
+
+## Development
+
+For development setup and contribution guidelines, please see
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Documentation
+
+Comprehensive documentation is available in the [docs/](docs/) directory,
+including:
+
+- [User Guide](docs/userguide/launch.md) - Detailed usage instructions
+- [Control Panel Guide](docs/userguide/control_panel.md) - Interface overview
+- [Viewport Customization](docs/userguide/viewport.md) - Working with multiple
+  variables
+- [Data Requirements](docs/data-requirements.md) - NetCDF file format and
+  required variables
+
+## About
+
+QuickView is developed by [Kitware, Inc.](https://www.kitware.com/) in
+collaboration with
+[Pacific Northwest National Laboratory](https://www.pnnl.gov/). It is supported
+by the U.S. Department of Energy's
+[Biological and Environmental Research (BER)](https://www.energy.gov/science/ber/biological-and-environmental-research)
+and
+[Advanced Scientific Computing Research (ASCR)](https://www.energy.gov/science/ascr/advanced-scientific-computing-research)
+programs via the
+[Scientific Discovery through Advanced Computing (SciDAC)](https://www.scidac.gov/)
+program.
+
+### Contributors
+
+- **Lead Developer**: Abhishek Yenpure (Kitware, Inc.)
+- **Key Contributors**: Berk Geveci, Sebastien Jourdain (Kitware, Inc.); Hui
+  Wan, Kai Zhang (PNNL)
+
+## License
 
-The above command will start the Trame app server. On the browser proceed to
-`http://localhost:8080` to use the app
+This project is licensed under the Apache Software License - see the
+[LICENSE](LICENSE) file for details.
diff --git a/docs/README.md b/docs/README.md
@@ -51,6 +51,9 @@ To learn more about the installation of EAM QuickView, checkout the
 To learn more about using EAM QuickView, checkout the
 [brief overview.](tutorials/eamapp.md)
 
+For information about data file requirements and supported formats, see the
+[data requirements documentation](data-requirements.md)
+
 ## Point of Contact
 
 The lead developer of EAM QuickView is

diff --git a/docs/data-requirements.md b/docs/data-requirements.md
@@ -0,0 +1,154 @@
+# QuickView Data File Requirements
+
+This document describes the NetCDF file format and variable requirements for
+QuickView to properly read and visualize E3SM atmospheric data.
+
+## Overview
+
+QuickView requires two NetCDF files:
+
+1. **Data File** - Contains the atmospheric variables and time-varying data
+2. **Connectivity File** - Contains the mesh geometry and grid structure
+
+## Required Dimensions
+
+The following dimensions must be present in the data files:
+
+### In Data File:
+
+- `time` - Time dimension for temporal data
+- `ncol` - Number of columns (horizontal grid points)
+- `lev` - Number of vertical levels at layer midpoints
+- `ilev` - Number of vertical levels at layer interfaces
+
+### In Connectivity File:
+
+- `grid_size` or `ncol` - Total number of grid cells
+
+## Required Variables
+
+### 1. Coordinate Variables
+
+#### Latitude and Longitude (Required)
+
+The connectivity file must contain corner coordinates for grid cells:
+
+- **Variables containing `corner_lat`** - Latitude coordinates of cell corners
+- **Variables containing `corner_lon`** - Longitude coordinates of cell corners
+
+These are used to construct the unstructured grid geometry.
+
+#### Vertical Coordinate Variables
+
+For proper vertical level display, the data file should contain either:
+
+**Option A: Direct level values**
+
+- `lev` - Pressure levels at layer midpoints (hPa)
+- `ilev` - Pressure levels at layer interfaces (hPa)
+
+**Option B: Hybrid coordinate coefficients** If `lev` and `ilev` are not
+directly provided, they will be computed from:
+
+- Variables containing `hyam` - Hybrid A coefficient at layer midpoints
+- Variables containing `hybm` - Hybrid B coefficient at layer midpoints
+- Variables containing `hyai` - Hybrid A coefficient at layer interfaces
+- Variables containing `hybi` - Hybrid B coefficient at layer interfaces
+
+The pressure levels are computed as:
+
+```
+pressure = (hyam * P0) + (hybm * PS0)
+```
+
+where P0 = 100000 Pa (reference pressure) and PS0 = 100000 Pa (surface
+pressure).
+
+### 2. Time Variable (Required)
+
+- `time` - Time coordinate variable containing timestamps for each time step
+
+### 3. Area Variable (Optional but Recommended)
+
+- Variable containing `area` in its name - Grid cell areas used for computing
+  area-weighted averages
+  - If not present, simple arithmetic averaging will be used instead
+
+## Variable Types Supported
+
+QuickView categorizes variables based on their dimensions:
+
+### 1D Variables (Info Variables)
+
+- Dimensions: `(ncol)`
+- Example: `area`
+- These are typically time-invariant grid properties
+
+### 2D Variables (Surface Variables)
+
+- Dimensions: `(time, ncol)`
+- Example: `TS` (surface temperature), `PS` (surface pressure)
+- These represent surface or column-integrated quantities
+
+### 3D Midpoint Variables
+
+- Dimensions: `(time, lev, ncol)` or `(time, ncol, lev)`
+- Example: `T` (temperature), `U` (zonal wind), `Q` (specific humidity)
+- These are defined at layer midpoints
+
+### 3D Interface Variables
+
+- Dimensions: `(time, ilev, ncol)` or `(time, ncol, ilev)`
+- Example: `OMEGA` (vertical velocity)
+- These are defined at layer interfaces
+
+## Variable Attributes
+
+### Fill Values
+
+Variables should include the `_FillValue` attribute to indicate missing or
+undefined data. QuickView will convert these to NaN values for proper handling.
+
+## Example Data Structure
+
+### Data File Structure:
+
+```
+dimensions:
+    time = 12 ;
+    ncol = 48602 ;
+    lev = 72 ;
+    ilev = 73 ;
+
+variables:
+    double time(time) ;
+    double T(time, lev, ncol) ;
+        T:_FillValue = 9.96920996838687e+36 ;
+    double TS(time, ncol) ;
+        TS:_FillValue = 9.96920996838687e+36 ;
+    double hyam(lev) ;
+    double hybm(lev) ;
+    double hyai(ilev) ;
+    double hybi(ilev) ;
+```
+
+### Connectivity File Structure:
+
+```
+dimensions:
+    grid_size = 48602 ;
+    grid_corners = 4 ;
+
+variables:
+    double grid_corner_lat(grid_size, grid_corners) ;
+    double grid_corner_lon(grid_size, grid_corners) ;
+```
+
+## Notes
+
+1. The reader automatically detects and categorizes variables based on their
+   dimensions
+2. Variables with dimensions not matching the expected patterns are ignored
+3. The reader caches geometry and special variables for performance
+4. Time interpolation is handled automatically when requesting specific time
+   steps
diff --git a/docs/images/main.png b/docs/images/main.png
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "quickview"
-version = "0.1.8"
+version = "0.1.9"
 description = "An application to explore/analyze data for atmosphere component for E3SM"
 authors = [
     {name = "Kitware Inc."},

diff --git a/quickview/__init__.py b/quickview/__init__.py
@@ -1,5 +1,5 @@
 """QuickView: Visual Analysis for E3SM Atmosphere Data."""
 
-__version__ = "0.1.8"
+__version__ = "0.1.9"
 __author__ = "Kitware Inc."
 __license__ = "Apache-2.0"