diff --git a/.bumpversion.cfg b/.bumpversion.cfg index 9443e81..850b29e 100644 --- a/.bumpversion.cfg +++ b/.bumpversion.cfg @@ -1,5 +1,5 @@ [bumpversion] -current_version = 0.1.15 +current_version = 0.1.16 commit = True tag = True diff --git a/README.md b/README.md index c108d6d..e1aa3b2 100644 --- a/README.md +++ b/README.md @@ -3,122 +3,38 @@ [![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) -**QuickView** is an interactive visualization tool for atmospheric scientists -working with E3SM (Energy Exascale Earth System Model) data. It provides an -intuitive interface for exploring atmospheric simulation outputs without the -steep learning curve of general-purpose visualization tools. - -![quickview](docs/images/main.png) - -## Quick Start - -### Installation - -Download the latest release from the -[releases page](https://github.com/ayenpure/QuickView/releases): - -- **macOS**: `QuickView-{version}.dmg` - Double-click to install -- **Linux**: Coming soon -- **Windows**: Coming soon - -Pre-built binaries include all dependencies - no Python or ParaView required. - -## Data - -QuickView works with E3SM Atmosphere Model (EAM) output files in NetCDF format. -Sample data files and their corresponding connectivity files are available at -[Zenodo](https://zenodo.org/records/16895849). - -### Data Files - -QuickView supports EAM output files from different model versions: - -- **EAM Version 2**: Standard atmospheric simulation outputs (e.g., - `EAMv2_ne30pg2_F2010.eam.h0.nc`) -- **EAM Version 4 (interim)**: Newer format outputs (e.g., - `EAMxx_ne4pg2_202407.nc`) - -These files contain atmospheric variables such as temperature, pressure, wind -fields, and other model diagnostics on finite-volume physics grids. - -### Connectivity Files - -Each data file requires a corresponding connectivity file that describes the -horizontal grid structure: - -- Connectivity files follow the naming pattern: - `connectivity_{resolution}_TEMPEST.scrip.nc` -- These files are generated using TempestRemap and contain grid topology - information -- **Important**: The connectivity file resolution must match the data file - resolution for proper visualization - -For example: - -- Data file: `EAMv2_ne30pg2_F2010.eam.h0.nc` -- Connectivity file: `connectivity_ne30pg2_TEMPEST.scrip.nc` - -Both files use the same `ne30pg2` grid resolution and must be loaded together -for the application to function correctly. - -## Documentation - -- **[Installation Guide](docs/setup/requirements.md)** - Detailed setup - instructions -- **[User Guide](docs/userguide/launch.md)** - How to use QuickView -- **[Data Requirements](docs/data-requirements.md)** - NetCDF file format - specifications -- **[Control Panel Reference](docs/userguide/control_panel.md)** - UI components - and features +**EAM QuickView** is an interactive visualization tool +tailored for scientists working with the atmospheric component of the +[Energy Exascale Earth System Model (E3SM)](https://e3sm.org/), the +E3SM Atmosphere Model (EAM). +The Graphical User Interface (GUI) built with Python and +powered by [Trame](https://www.kitware.com/trame/) +gives users intuitive access to the powerful visualization capabilities of +[ParaView](https://www.paraview.org/) without requiring a steep learning curve. ## Key Features -- Clean, minimalist interface tailored for atmospheric modeling -- Multi-variable visualization with drag-and-drop layout -- Geographic projections (Plate Carrée, Robinson, etc.) -- Persistent sessions - pick up where you left off -- Support for EAM v2, v3, and upcoming v4 data formats - -## Development - -### Python Development Installation - -```bash -# Clone the repository -git clone https://github.com/ayenpure/QuickView.git -cd QuickView - -# Set up conda environment -conda env create -f quickview-env.yml -conda activate quickview - -# Install QuickView -pip install -e . -``` - -### Running from Source - -```bash -python -m quickview.app --data /path/to/your/data.nc --conn /path/to/connectivity.nc +- Intuitive, minimalist interface tailored for atmospheric modeling. +- Multi-variable visualization with drag-and-drop layout. +- Persistent sessions - pick up where you left off. +- Support for EAM v2, v3, and upcoming v4 output formats. -# Launch server only (no browser popup) -python --server -m quickview.app --data /path/to/your/data.nc --conn /path/to/connectivity.nc -``` - -The application starts a web server at `http://localhost:8080` - -### Development Utilities - -```bash -# Run linter -ruff check quickview/ - -# Run tests -python -m quickview.app --help +## Quick Start -# Bump version -bumpversion patch -``` +- Install and launch the app for [end users](docs/setup/for_end_users.md) + and [app developers](docs/setup/for_app_developers.md). +- Download connectivity files of EAM's cubed-sphere grids from + [Zenodo](https://doi.org/10.5281/zenodo.16908567). +- Optional: download [sample simulation output](https://zenodo.org/records/16922608) + to test the app. +- For EAMv2 and v3 developers and users: if your simulation data files + are *not* the original files written out by the model, + i.e., if your files were generated by NCO, CDO, etc. + check QuickView's [data format requirements](docs/userguide/data_requirements.md). +- For EAMxx developers and users: EAMxx's most recent output format + updates might not have been accommodated. If your run into issues + opening your data files, please contact our + [lead developer](https://www.kitware.com/abhishek-yenpure/). ## About @@ -126,9 +42,9 @@ QuickView is developed by [Kitware, Inc.](https://www.kitware.com/) in collaboration with [Pacific Northwest National Laboratory](https://www.pnnl.gov/), supported by the U.S. Department of Energy's -[BER](https://www.energy.gov/science/ber/biological-and-environmental-research) -and [ASCR](https://www.energy.gov/science/ascr/advanced-scientific-computing-research) +and +[BER](https://www.energy.gov/science/ber/biological-and-environmental-research) programs via [SciDAC](https://www.scidac.gov/). ### Contributors diff --git a/app-icon.png b/app-icon.png index c78fa00..290e7a7 100644 Binary files a/app-icon.png and b/app-icon.png differ diff --git a/docs/README.md b/docs/README.md index 69ca30a..966b504 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,12 +1,23 @@ -# EAM QuickView +# QuickView Homepage ![eam-quickview-full](../images/eam-quickview-full.png) -## Overview +## What is QuickView? -EAM QuickView is an open-source, Python-based application for interactive -visualization of simulation data produced by the atmosphere component of the -[Energy Exascale Earth System Model](https://e3sm.org/), EAM. + +**EAM QuickView** is an interactive visualization tool +tailored for scientists working with the atmospheric component of the +[Energy Exascale Earth System Model](https://e3sm.org/) (EAM, +[Rasch et al., 2019](https://doi.org/10.1029/2019MS001629); +[Golaz et al., 2022](https://doi.org/10.1029/2022MS003156); +[Donahue et al., 2024](10.1029/2024MS004314)). +The Graphical User Interface (GUI) built with Python and +powered by [Trame](https://www.kitware.com/trame/) +gives users intuitive access to the powerful visualization capabilities of +[ParaView](https://www.paraview.org/) +without requiring a steep learning curve. + +## Why QuickView? While comprehensive tools like [ParaView](https://www.paraview.org/) and [VisIt](https://visit-dav.github.io/visit-website/index.html) are widely used in @@ -32,12 +43,11 @@ multivariate visualization and is currently focused on the EAM model. ## Key Features -- Clean and minimalist user interface tailored for atmosphere modeling - workflows. +- Minimalist user interface tailored for atmosphere modeling workflows. - Push-button visualization of multiple variables. - Persistent state: "Pick up where you left off". - Supports EAM simulation data from current (EAMv2, v3) and upcoming (v4) - versions + versions. ## Further Reading @@ -58,17 +68,13 @@ For information about data file requirements and supported formats, see the The lead developer of EAM QuickView is [Abhishek Yenpure (abhi.yenpure@kitware.com)](https://www.kitware.com/abhishek-yenpure/) -at [Kitware, Inc.](https://www.kitware.com/). - -Other key contributors include Berk Geveci (and Sebastien Jourdain?) at -[Kitware, Inc.](https://www.kitware.com/); Hui Wan and Kai Zhang at -[Pacific Northwest National Laboratory](https://www.pnnl.gov/atmospheric-climate-and-earth-sciences-division). +at [Kitware, Inc.](https://www.kitware.com/). Other key contributors at Kitware, Inc. include [Berk Geveci](https://www.kitware.com/berk-geveci/) and [Sebastien Jourdain](https://www.kitware.com/sebastien-jourdain/). Key contributors on the atmospheric science side are Hui Wan and Kai Zhang at [Pacific Northwest National Laboratory](https://www.pnnl.gov/atmospheric-climate-and-earth-sciences-division). EAM QuickView is a product of an interdisciplinary collaboration 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 +the U.S. Department of Energy Office of Science’s [Advanced Scientific Computing Research (ASCR)](https://www.energy.gov/science/ascr/advanced-scientific-computing-research) +and +[Biological and Environmental Research (BER)](https://www.energy.gov/science/ber/biological-and-environmental-research) via the [Scientific Discovery through Advanced Computing (SciDAC](https://www.scidac.gov/)) program. diff --git a/docs/future.md b/docs/future.md new file mode 100644 index 0000000..84a97b4 --- /dev/null +++ b/docs/future.md @@ -0,0 +1,11 @@ +# Planned Improvements + +Below is a list of improvements that are being worked on or have been planned. +Addional suggestions are welcome. Bug reports and feature requests +can be made by opening new +[issues](https://github.com/ayenpure/QuickView/issues) on GitHub. + + +1. Server-client model and deployment of servers to Department of Energy's Leadership Computing Facilities. + +1. diff --git a/docs/images/tool-bar.png b/docs/images/tool-bar.png deleted file mode 100644 index 2bd09e5..0000000 --- a/docs/images/tool-bar.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:9df55fcdb0cf2ad439fdddb22f12c4b1d4b2df55e56eb8095397c468d64b7b50 -size 63585 diff --git a/docs/images/toolbar.png b/docs/images/toolbar.png new file mode 100644 index 0000000..65f6027 --- /dev/null +++ b/docs/images/toolbar.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e41d3cb5c519feee30f04b9d751eb66915f462af75637c9fe3f3c1473e37d469 +size 99744 diff --git a/docs/images/toolbar_conn_and_data_load.png b/docs/images/toolbar_conn_and_data_load.png new file mode 100644 index 0000000..b5ffa33 --- /dev/null +++ b/docs/images/toolbar_conn_and_data_load.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1ae21b62f7936b0c83ae5507b8ead022043ef53445374232aa75a810c3bf551f +size 47901 diff --git a/docs/images/toolbar_misc.png b/docs/images/toolbar_misc.png new file mode 100644 index 0000000..496504c --- /dev/null +++ b/docs/images/toolbar_misc.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2c39ec02cd3ed0f1df96f513c0d34bfdbb9046b829948aaa8874d990739b43bf +size 113206 diff --git a/docs/images/toolbar_state_save_and_load.png b/docs/images/toolbar_state_save_and_load.png new file mode 100644 index 0000000..2f743b8 --- /dev/null +++ b/docs/images/toolbar_state_save_and_load.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d73203517ccd0d85624a851275e2eaf15d6b1e8fd6c6b85859b7612447261b91 +size 20227 diff --git a/docs/setup/for_app_developers.md b/docs/setup/for_app_developers.md new file mode 100644 index 0000000..8d9654d --- /dev/null +++ b/docs/setup/for_app_developers.md @@ -0,0 +1,62 @@ +# Installation and Launch for App Developers + +At version 1.0, QuickView is expected to be installed and used from a personal computer with the data files also being local. Future versions will support the server-client model allowing access to remote data files. + +Releases so far have focused on MacOS. Support for Linux and Windows systems can be provided upon request. + +---- +## Cloning the repo + +``` +git clone https://github.com/ayenpure/QuickView.git +cd QuickView +``` + +---- +## Installing basic requirements + +``` +# Set up conda environment +conda env create -f quickview-env.yml +conda activate quickview + +# Install QuickView +pip install -e . +``` + +---- +## Additional requirements + +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` + +---- +## Launching the app from command line + +To launch the EAM QuickView GUI in its dedicated window, use +``` +python -m quickview.app --data /path/to/your/data.nc --conn /path/to/connectivity.nc +``` + +To launch server only (no browser popup), use +``` +python --server -m quickview.app --data /path/to/your/data.nc --conn /path/to/connectivity.nc +``` + +---- +## Development utilities + +``` +# Run linter +ruff check quickview/ + +# Run tests +python -m quickview.app --help + +# Bump version +bumpversion patch +``` diff --git a/docs/setup/for_end_users.md b/docs/setup/for_end_users.md new file mode 100644 index 0000000..c549fe4 --- /dev/null +++ b/docs/setup/for_end_users.md @@ -0,0 +1,23 @@ +# Installation and Launch for End Users + + +At version 1.0, QuickView is expected to be installed and used from a personal computer with the data files also being local. Future versions will support the server-client model allowing access to remote data files. + +Releases so far have focused on MacOS. Installers for Linux and Windows systems can be provided upon request. + +--- +# Installation + +For end users, we provide pre-built binaries that can be installed using just a few clicks. + +1. Download the latest installer from the [releases page](https://github.com/ayenpure/QuickView/releases/tag/v0.1.13). Mac users with Apple Silicon chips should download `QuickView_{version}_aarch64.dmg`, and those with Intel chips should download a `*_x64.dmg` file. +2. Double-click the downloaded `.dmg` file. In the pop-up window, drag the QuickView icon into the Applications folder. + + +The pre-built binaries include all dependencies needed to start the app on a local computer. +Additional dependencies needed for data processing and visualization are downloaded and installed automatically when the app is launched for the first time. + +--- +# Launch + +To launch the EAM QuickView GUI, simply double-click the app icon in your Applications folder. diff --git a/docs/userguide/camera.md b/docs/userguide/camera.md new file mode 100644 index 0000000..0008beb --- /dev/null +++ b/docs/userguide/camera.md @@ -0,0 +1 @@ +# Camera Widget diff --git a/docs/userguide/connectivity.md b/docs/userguide/connectivity.md index 9c70bca..5ca64ea 100644 --- a/docs/userguide/connectivity.md +++ b/docs/userguide/connectivity.md @@ -1,64 +1,35 @@ # Connectivity files + +## Background + The horizontal grids used by EAM are cubed spheres. Since these are unstructed -grids, EAM QuickView needs to know how to map data to the globe. Therefore, each -time the app is launched, a "connectivity file" needs to be provided together -with the simulation data file. +grids, the QuickView app needs to know how to map data to the globe. Therefore, +for each simulation data file, a "connectivity file" needs to be provided. In EAMv2, v3, and v4, most of the variables (physical quantities) are archived on the "physics grid" described in -[Hannah et al. (2021)](https://doi.org/10.1029/2020MS002419). The naming -convention for such grids is `neXpg2`, with `X` being a number, typically 4, 30, -or 120. - -_Hui's note from 4/29/2025: I am inclined to NOT include connectivity files in -our repo or binary. How should we provide them, then? If we will be distributing -binaries, then I imagine we could provide connectivity files from that web page. -A related note: the script I used for generating those files was from Mark -Taylor. I think we should ask him how he wants to be credited for that. One -option could be including here the instructions he gave me together with a link -to his script (see below), but would he be interested in involved in our work in -some way? I can ask him._ - -A collection of connectivity files can be downloaded from [here (where?)](). - -Users can also generate connectivity files with the -[`TempestRemap`](https://github.com/ClimateGlobalChange/tempestremap) tool using -[this script](https://github.com/mt5555/remap-ncl/blob/master/makeSE.sh) shared -by Mark A. Taylor at Sandia National Laboratories. (`TempestRemap` can be -installed following the instructions at -[https://github.com/ClimateGlobalChange/tempestremap](https://github.com/ClimateGlobalChange/tempestremap), -and it is also available as a part of the -[`E3SM-Unified`](https://github.com/E3SM-Project/e3sm-unified) conda -environment.) - -For example, the command - -``` -./makeSE.sh 30 -``` - -will generate several different files for the `ne30pg2` grid, including, e.g., - -- `TEMEPST_NE30pg2.g` (Exodus format), -- `TEMPEST_ne30pg2.scrip.nc` (SCRIP format). - -EAM QuickView uses the SCRIP format. - -## References - -Hannah, W. M., Bradley, A. M., Guba, O., Tang, Q., Golaz, J.-C., & Wolfe, J. -(2021). Separating physics and dynamics grids for improved computational -efficiency in spectral element earth system models. Journal of Advances in -Modeling Earth Systems, 13, e2020MS002419. -[https://doi.org/10.1029/2020MS002419](https://doi.org/10.1029/2020MS002419) - -Paul A. Ullrich and Mark A. Taylor, 2015: Arbitrary-Order Conservative and -Consistent Remapping and a Theory of Linear Maps: Part 1. Mon. Wea. Rev., 143, -2419–2440, -[doi:10.1175/MWR-D-14-00343.1](https://doi.org/10.1175/MWR-D-14-00343.1) - -Paul A. Ullrich, Darshi Devendran and Hans Johansen, 2016: Arbitrary-Order -Conservative and Consistent Remapping and a Theory of Linear Maps, Part 2. Mon. -Wea. Rev., 144, 1529-1549, -[doi:10.1175/MWR-D-15-0301.1](https://doi.org/10.1175/MWR-D-15-0301.1) +[Hannah et al. (2021)](https://doi.org/10.1029/2020MS002419). +The naming convention for such grids is `neXpg2`, with `X` being a number, +typically 4, 30, or 120. Further details about EAM's cubed-sphere grids +can be found in EAM's documention, for example in +[this overview](https://e3sm.atlassian.net/wiki/spaces/DOC/pages/34113147/SE+Atmosphere+Grid+Overview+EAM+CAM) +and [this description](https://e3sm.atlassian.net/wiki/spaces/DOC/pages/872579110/Running+E3SM+on+New+Atmosphere+Grids). + +## Download + +A collection of connectivity files can be found on [Zenodo](https://doi.org/10.5281/zenodo.16908567). + +## Generation + +Users can also generate connectivity files with +[`TempestRemap`](https://github.com/ClimateGlobalChange/tempestremap) ( +[Ullrich and Taylor, 2015](https://doi.org/10.1175/MWR-D-14-00343.1); +[Ullrich et al., 2016](https://doi.org/10.1175/MWR-D-15-0301.1)) +using commands documented [here](https://e3sm.atlassian.net/wiki/spaces/DOC/pages/872579110/Running+E3SM+on+New+Atmosphere+Grids#2A.-Generate-control-volume-mesh-files-for-E3SM-v2-%22pg2%22-grids). +`TempestRemap` it is available as a part of the +[`E3SM-Unified`](https://github.com/E3SM-Project/e3sm-unified) conda environment; +it can also be installed following the instructions from the +[TempestRemap repo](https://github.com/ClimateGlobalChange/tempestremap). + +EAM QuickView uses the SCRIP format of the connectivity files. diff --git a/docs/data-requirements.md b/docs/userguide/data_requirements.md similarity index 100% rename from docs/data-requirements.md rename to docs/userguide/data_requirements.md diff --git a/docs/userguide/gui_overview.md b/docs/userguide/gui_overview.md new file mode 100644 index 0000000..a839c9e --- /dev/null +++ b/docs/userguide/gui_overview.md @@ -0,0 +1,27 @@ +# Graphical User Interface (GUI) + +EAM QuickView's GUI contains the four main components summarized below. +Detailed descriptions can be found on the linked pages. + +1. The [toolbar](toolbar.md) located at the top of the GUI + contains buttons and text boxes for loading data files and + controling various global properties of the application. + +2. The collapsible [control panel](control_panel.md) located on the left + of the GUI allows the user to select data slices to represent, + i.e., variables, time slices, vertical levels, horizontal domains + and map projections. The control panel can be collapsed or + made visible using the hamburger icon (three horizontal lines stacked + on top of each other ) + on the left end of the [toolbar](toolbar.md). + +3. The [viewport](view_port.md) displays one or more variables for + the user. For each variable, the colormap, contour level etc. + can be adjusted individually using the associated gear icon. + +4. The [camera action widget](camera.md) located in the bottom right + corner of the viewport are used for centrally adjusting all views + in the viewport, i.e., zooming in or out, or moving the displayed + images with respect to the GUI. + +![eam-quickview-full-enum](../images/eam-quickview-full-enum.png) diff --git a/docs/userguide/launch.md b/docs/userguide/old_launch_page.md similarity index 100% rename from docs/userguide/launch.md rename to docs/userguide/old_launch_page.md diff --git a/docs/userguide/reminders.md b/docs/userguide/reminders.md index ac813f2..39aab41 100644 --- a/docs/userguide/reminders.md +++ b/docs/userguide/reminders.md @@ -1,30 +1,45 @@ -# Key reminders for using EAM QuickView +# Key Reminders for Using EAM QuickView -- EAM QuickView can be [launched](launch.md) in two ways: from simulation data - (for starting a new visualization) or from a state file (for resuming an - analysis). +!!! tip "Tip: Two Modes of Use" -- Regardless of which way of launch is used, a - [connectivity file](connectivity.md) is needed together with the simulation - data file. + EAM QuickView can be used in two modes: + a new-viz mode (for starting a new visualization) or + a resume mode (for resuming an analysis). Further details can be found on + the [toolbar description page](toolbar.md). + +!!! tip "Tip: Connectivity File" -- Most buttons, sliders, and selection boxes in the GUI apply their effects - immediately upon user interaction. The only exception is the variable - selection: after variables are chosen for the first time following app launch, - or after the selection is changed, the user must click the `LOAD VARIABLES` - button in the [toolbar](toolbar.md) for the new selection to take effect. + Regardless of which mode is used, a + [connectivity file](connectivity.md) is needed in addition to the simulation + data file. Further details can be found on the documentation pages + describing the [connectivity files](connectivity.md) and the + [toolbar](toolbar.md). + +!!! tip "Tip: The `LOAD VARIABLES` Button" -- In the current version, after the `LOAD VARIABLES` button is clicked, some of - the variables showing up in the [viewport](viewport.md) might exhibit a - display issue, e.g., erroneously showing the same color or a few color stripes - over the entire globe or region. This can be remedied by clicking the refresh - button at the right end of the [toolbar](toolbar.md), and we are hoping to - resolve the issue for future versions. + Most buttons, sliders, and selection boxes in the GUI apply their effects + immediately upon user interaction. The only exception is the variable + selection: after variables are chosen for the first time following file load + or after the selection is changed, the user must click the `LOAD VARIABLES` + button in the [toolbar](toolbar.md) for the new selection to take effect. + +!!! tip "Tip: Viewport Layout" -- The QuickView app is designed to present multiple variables simultaneously in - an informative way. Users can rearrange the individual views (i.e., global or - regional maps of different variables) in the [viewport](viewport.md) via - drag-and-drop, and resize each view separately by clicking and dragging its - bottom-right corner. Furthermore, if a user saves a state file after these - adjustments, they can later resume their analysis with the customized - arrangement. + The QuickView app is designed to present multiple variables simultaneously in + an informative way. Users can rearrange the individual views (i.e., global or + regional maps of different variables) in the [viewport](viewport.md) via + drag-and-drop, and resize each view separately by clicking and dragging its + bottom-right corner. Furthermore, if a user saves a state file after these + adjustments, they can later resume their analysis with the customized + arrangement. + +!!! warning "Trick: Camera Refresh" + + In the current version, after the `LOAD VARIABLES` button is clicked or + a visualization settings is changed, some (or all) of + the images in the [viewport](viewport.md) might exhibit a display issue, e.g., + erroneously showing the same color or a few color stripes over the entire + globe or region. This can be remedied by clicking the camera refresh + button at the right end of the [toolbar](toolbar.md), and we are hoping to + resolve the issue for future versions. + diff --git a/docs/userguide/toolbar.md b/docs/userguide/toolbar.md index e5fe008..0efa1d9 100644 --- a/docs/userguide/toolbar.md +++ b/docs/userguide/toolbar.md @@ -1,22 +1,84 @@ -## The Toolbar - -![tool-bar](../images/tool-bar.png) - -The toolbar is a means of presenting the user with global app controls, along -with the display of some useful information. Starting from the left and going to -the right in the above image, the toolbar: - -1. provides a button to show/hide the control panel for the application -2. displays the information of the current version of the QuickView app -3. contains a helpful widget to control the camera for the variables being - currently explored -- by zooming in/out, and moving camera up/down or - left/right. -4. contains the button used to load views with the current variable selection, - this process does not happen interactively as the user selects/deselects - variables to analyze. -5. contains some useful options for selecting color presets. -6. displays data and connectivity file names and locations that are currently - being used for analysis -7. provides a button to save the application configuration/state to the disk, - which can be later imported. -8. provides a button to reset all the views at once. + +![toolbar](../images/toolbar.png) + +The toolbar located at the top of the GUI contains UI elements (buttons +and text boxes) that control global features of the current +visualization session ("global" in the sense of being shared by +all the variables being displayed). +In the following, we explain in detail the elements +that support the two modes of usage of the app, new-viz and resume, and +then introduce the other elements. + +---- +## New-viz mode: starting a new visualization + +![connectivity and data file buttons](../images/toolbar_conn_and_data_load.png) + +To start a new analysis/visualization, the user needs to specify +a [connecitivy file](connectivity.md) and +a [simulation data file](data_requirements.md) using +the portion of the toolbar shown above, by either typing +the file paths and names in the corresponding boxes +or using the file folder icons to bring up system dialogue windows to +select files. + +After both files have been specified, click on the `Load Files` button +(the icon of a page with a check mark). If the red circle with an exclamation +mark shown in the picture above becomes a green circle with a check mark, +the files have been loaded and the ParaView Reader behind the GUI has +identified variables in the data file that the app can visualize. +The user can then move on to using the [Toolbar](toolbar.md) to select +variables and spatial/temporal slices to display. + +If the red circle persists, then the variable dimensions in the data file +have not been parsed correctly. Possible reasons for the error are: + +- The data file and connectivity file correspond to different cubed-sphere + meshes. E.g., one is ne30pg2 and the other is ne4pg2. +- The data file is missing some of the coordinate variables needed by the + app, or the dimensions are named or ordered in ways not yet known by + the app, see [data format requirements](data_requirements.md). + +---- +## Resume mode: pick up where you left off + +![state save and load](../images/toolbar_state_save_and_load.png) + +The current state of the visualization can be saved—and reloaded later to +resume the analysis—using the `Save State` and `Load State` icons shown above. + +Note that a state file is a JSON file that contains the paths and names of +the connectivity and data files being used as well as the settings +the user has chosen for the visualization; the *contents* of the +connectivity and data files are *not* included. +If the user wished to use the same settings but for a different set of files +or for files located under different paths, then the file names and paths +at the beginning of the state file need to be edited before the state +file is loaded in the app. + +---- +## Other elements of the toolbar + +![toolbar misc](../images/toolbar_misc.png) + +1. The hamburger icon hides or shows the [control panel](control_panel.md). +1. The `LOAD VARIABLES` button, when clicked, executes the action of loading + the [user-selected variables](control_panel.md) from the data file and + displaying them in the [viewport](viewport.md). +1. The eye icon is a toggle for loading a group of colorblind-friendly colormaps + to the GUI for the user to choose from in the [viewport](viewport.md). + A lot of these colormaps are from + [Crameri, F. (2018)](https://doi.org/10.5281/zenodo.1243862). + The paint palette icon is a toggle for loading a set of colormaps that + may not be colorblind-friendly. Currently, these are mostly "presets" + taken from [PareView](https://www.paraview.org/). +1. The `Camera Reset` button refreshes all contents in the [viewport](viewport.md) + so that the contour plots are recentered and resized to their + individual windows ("views"). + +!!! tip "Tip on Camera Reset" + + As mentioned on the [Reminders](reminders.md) page, the app may exhibit + display issue after new variable selection or setting changes have been made. + In those cases, a click on the `Camera Reset` should reload the visualization + properly, and we are working on resolving the problem for future releases. diff --git a/mkdocs.yml b/mkdocs.yml index 3bdac13..40d3c8e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,15 +5,23 @@ plugins: - mkdocstrings nav: - Home: README.md - - Setup: - - Requirements: setup/requirements.md - - Execution: setup/execution.md - - User Guide: - - Key Reminders: userguide/reminders.md + - Installation and Launch: + - For End Users: setup/for_end_users.md + - For App Developers: setup/for_app_developers.md + - User's Guide: + - Key Reminders: userguide/reminders.md - Connectivity Files: userguide/connectivity.md - - Launch: userguide/launch.md - - Toolbar: userguide/toolbar.md - - Control Panel: userguide/control_panel.md - - Viewport: userguide/viewport.md + - Data File Format: userguide/data_requirements.md + - GUI Overview: userguide/gui_overview.md + - Toolbar: userguide/toolbar.md + - Control Panel: userguide/control_panel.md + - Viewport: userguide/viewport.md + - Camera Widget: userguide/camera.md + - Plans: future.md markdown_extensions: - attr_list + - admonition + - pymdownx.details + - pymdownx.superfences + - md_in_html + - pymdownx.blocks.caption diff --git a/pyproject.toml b/pyproject.toml index 4344fdd..cdf7854 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "quickview" -version = "0.1.15" +version = "0.1.16" 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 index c6420ac..a1420d2 100644 --- a/quickview/__init__.py +++ b/quickview/__init__.py @@ -1,5 +1,5 @@ """QuickView: Visual Analysis for E3SM Atmosphere Data.""" -__version__ = "0.1.15" +__version__ = "0.1.16" __author__ = "Kitware Inc." __license__ = "Apache-2.0" diff --git a/quickview/assets/quick-view-text.png b/quickview/assets/quick-view-text.png new file mode 100644 index 0000000..f1c3c2f Binary files /dev/null and b/quickview/assets/quick-view-text.png differ diff --git a/quickview/interface.py b/quickview/interface.py index ec77a6c..ea66553 100644 --- a/quickview/interface.py +++ b/quickview/interface.py @@ -1,5 +1,6 @@ import os import json +import base64 import numpy as np import xml.etree.ElementTree as ET @@ -37,6 +38,23 @@ rc.vtkProcessModule.PROCESS_BATCH, 0 ) +# ----------------------------------------------------------------------------- +# Load logo image as base64 +# ----------------------------------------------------------------------------- + + +def get_logo_base64(): + """Load the QuickView logo as base64 encoded string.""" + logo_path = Path(__file__).parent / "assets" / "quick-view-text.png" + if logo_path.exists(): + with open(logo_path, "rb") as f: + return base64.b64encode(f.read()).decode("utf-8") + return "" # Return empty string if logo not found + + +# Cache the logo at module load time +LOGO_BASE64 = get_logo_base64() + # ----------------------------------------------------------------------------- # trame setup # ----------------------------------------------------------------------------- @@ -727,8 +745,8 @@ def ui(self) -> SinglePageWithDrawerLayout: ): ( html.Img( - src="https://raw.githubusercontent.com/ayenpure/QuickView/master/app-icon.png", - style="height: 32px; width: 32px; border-radius: 4px; margin-bottom: 2px;", + src=f"data:image/png;base64,{LOGO_BASE64}", + style="height: 40px; width: 80px; border-radius: 4px; margin-bottom: 2px;", ), ) html.Span( diff --git a/src-tauri/Cargo.toml b/src-tauri/Cargo.toml index 52dbfe2..7a7aa23 100644 --- a/src-tauri/Cargo.toml +++ b/src-tauri/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "app" -version = "0.1.15" +version = "0.1.16" description = "QuickView: Visual Analyis for E3SM Atmosphere Data" authors = ["Kitware"] license = "" diff --git a/src-tauri/icons/128x128.png b/src-tauri/icons/128x128.png index 18f244c..137e78e 100644 Binary files a/src-tauri/icons/128x128.png and b/src-tauri/icons/128x128.png differ diff --git a/src-tauri/icons/128x128@2x.png b/src-tauri/icons/128x128@2x.png index a56fb89..e33da5d 100644 Binary files a/src-tauri/icons/128x128@2x.png and b/src-tauri/icons/128x128@2x.png differ diff --git a/src-tauri/icons/32x32.png b/src-tauri/icons/32x32.png index 1a140fc..cca1538 100644 Binary files a/src-tauri/icons/32x32.png and b/src-tauri/icons/32x32.png differ diff --git a/src-tauri/icons/Square107x107Logo.png b/src-tauri/icons/Square107x107Logo.png index 2411ecd..7dd8513 100644 Binary files a/src-tauri/icons/Square107x107Logo.png and b/src-tauri/icons/Square107x107Logo.png differ diff --git a/src-tauri/icons/Square142x142Logo.png b/src-tauri/icons/Square142x142Logo.png index 453a47a..370ba95 100644 Binary files a/src-tauri/icons/Square142x142Logo.png and b/src-tauri/icons/Square142x142Logo.png differ diff --git a/src-tauri/icons/Square150x150Logo.png b/src-tauri/icons/Square150x150Logo.png index a884fd4..e2b6cf5 100644 Binary files a/src-tauri/icons/Square150x150Logo.png and b/src-tauri/icons/Square150x150Logo.png differ diff --git a/src-tauri/icons/Square284x284Logo.png b/src-tauri/icons/Square284x284Logo.png index ff42d84..f7339fe 100644 Binary files a/src-tauri/icons/Square284x284Logo.png and b/src-tauri/icons/Square284x284Logo.png differ diff --git a/src-tauri/icons/Square30x30Logo.png b/src-tauri/icons/Square30x30Logo.png index 8a7ad80..267707e 100644 Binary files a/src-tauri/icons/Square30x30Logo.png and b/src-tauri/icons/Square30x30Logo.png differ diff --git a/src-tauri/icons/Square310x310Logo.png b/src-tauri/icons/Square310x310Logo.png index c869238..1e2a5b6 100644 Binary files a/src-tauri/icons/Square310x310Logo.png and b/src-tauri/icons/Square310x310Logo.png differ diff --git a/src-tauri/icons/Square44x44Logo.png b/src-tauri/icons/Square44x44Logo.png index 5392bf3..1193523 100644 Binary files a/src-tauri/icons/Square44x44Logo.png and b/src-tauri/icons/Square44x44Logo.png differ diff --git a/src-tauri/icons/Square71x71Logo.png b/src-tauri/icons/Square71x71Logo.png index a9764f0..ddb1311 100644 Binary files a/src-tauri/icons/Square71x71Logo.png and b/src-tauri/icons/Square71x71Logo.png differ diff --git a/src-tauri/icons/Square89x89Logo.png b/src-tauri/icons/Square89x89Logo.png index 8d33593..df34574 100644 Binary files a/src-tauri/icons/Square89x89Logo.png and b/src-tauri/icons/Square89x89Logo.png differ diff --git a/src-tauri/icons/StoreLogo.png b/src-tauri/icons/StoreLogo.png index ca97122..36a32b6 100644 Binary files a/src-tauri/icons/StoreLogo.png and b/src-tauri/icons/StoreLogo.png differ diff --git a/src-tauri/icons/icon.icns b/src-tauri/icons/icon.icns index 99a3c1b..350c769 100644 Binary files a/src-tauri/icons/icon.icns and b/src-tauri/icons/icon.icns differ diff --git a/src-tauri/icons/icon.ico b/src-tauri/icons/icon.ico index 5859d5c..f07dacd 100644 Binary files a/src-tauri/icons/icon.ico and b/src-tauri/icons/icon.ico differ diff --git a/src-tauri/icons/icon.png b/src-tauri/icons/icon.png index 8f9e67e..0a02904 100644 Binary files a/src-tauri/icons/icon.png and b/src-tauri/icons/icon.png differ diff --git a/src-tauri/tauri.conf.json b/src-tauri/tauri.conf.json index df182c8..19390ae 100644 --- a/src-tauri/tauri.conf.json +++ b/src-tauri/tauri.conf.json @@ -7,7 +7,7 @@ }, "package": { "productName": "QuickView", - "version": "0.1.15" + "version": "0.1.16" }, "tauri": { "allowlist": { @@ -51,7 +51,7 @@ }, "resources": ["server"], "shortDescription": "", - "targets": ["app", "dmg"], + "targets": ["dmg"], "windows": { "certificateThumbprint": null, "digestAlgorithm": "sha256",