diff --git a/.bumpversion.cfg b/.bumpversion.cfg index 972bc1c..d27ca64 100644 --- a/.bumpversion.cfg +++ b/.bumpversion.cfg @@ -1,5 +1,5 @@ [bumpversion] -current_version = 0.1.20 +current_version = 0.1.21 commit = True tag = True diff --git a/README.md b/README.md index e1aa3b2..e0fa703 100644 --- a/README.md +++ b/README.md @@ -3,14 +3,14 @@ [![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) -**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. +**EAM QuickView** is an open-source, interactive visualization tool +designed for scientists working with the atmospheric component of the +[Energy Exascale Earth System Model (E3SM)](https://e3sm.org/), +known as the E3SM Atmosphere Model (EAM). +Its Python- and [Trame](https://www.kitware.com/trame/)-based +Graphical User Interface (GUI) provides +intuitive access to [ParaView](https://www.paraview.org/)'s +powerful analysis and visualization capabilities, without the steep learning curve. ## Key Features @@ -22,21 +22,25 @@ gives users intuitive access to the powerful visualization capabilities of ## Quick Start - Install and launch the app for [end users](docs/setup/for_end_users.md) - and [app developers](docs/setup/for_app_developers.md). + or [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) + [Zenodo](https://doi.org/10.5281/zenodo.16908566). +- Optional: download [sample simulation output](https://zenodo.org/records/16922607) 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/). + changes might not have been accommodated. If your run into problems + opening your data files, please check the + [Issues tab on GitHub](https://github.com/ayenpure/QuickView/issues) and + open a new issue if needed. -## About +More detailed descriptions of how to download, install, and use QuickView +can be found in the [documentation](https://quickview.readthedocs.io/en/latest/). + +## Project Background QuickView is developed by [Kitware, Inc.](https://www.kitware.com/) in collaboration with diff --git a/docs/README.md b/docs/README.md index 966b504..b1b4f44 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,74 +1,101 @@ # QuickView Homepage -![eam-quickview-full](../images/eam-quickview-full.png) -## What is QuickView? +!!! info inline end "Useful Links" + + - [Releases (binary download)](https://github.com/ayenpure/QuickView/releases) + - Quick start (see this page) + - [Documentation](https://quickview.readthedocs.io/en/latest/) + - [Connecitivity file download](https://zenodo.org/records/16908566) + - [Sample data download](https://zenodo.org/records/16922607) + - [Repository](https://github.com/ayenpure/QuickView) + - [Bug reports / feature requests](https://github.com/ayenpure/QuickView/issues) +![EAM QuickView screenshot](images/eam_quickview_full.png){ width="62%" } -**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. +## What is QuickView? +**EAM QuickView** is an open-source, interactive visualization tool +designed for scientists working with the atmospheric component of the +[Energy Exascale Earth System Model (E3SM)](https://e3sm.org/), +known as the E3SM Atmosphere Model (EAM). +Its Python- and [Trame](https://www.kitware.com/trame/)-based +Graphical User Interface (GUI) provides +intuitive access to [ParaView](https://www.paraview.org/)'s +powerful analysis and visualization capabilities, without the steep learning curve. + +--- +## Quick Start + +- Install and launch the app for [end users](setup/for_end_users.md) + or for [app developers](setup/for_app_developers.md). +- Download [connectivity files](https://doi.org/10.5281/zenodo.16908566) + of EAM's cubed-sphere grids from Zenodo. +- Optional: download [sample simulation output](https://zenodo.org/records/16922607) + 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](userguide/data_requirements.md). +- For EAMxx developers and users: EAMxx's most recent output format + changes might not have been accommodated. If your run into problems + opening your data files, please check the + [Issues tab on GitHub](https://github.com/ayenpure/QuickView/issues) and + open a new issue if needed. + +For more details, go to the navigation bar of this website and look for +our User's Guide. + +--- ## Why QuickView? -While comprehensive tools like [ParaView](https://www.paraview.org/) and +While comprehensive visualization tools like +[ParaView](https://www.paraview.org/) and [VisIt](https://visit-dav.github.io/visit-website/index.html) are widely used in the scientific community, they often present a steep learning curve—requiring -users to navigate unfamiliar interfaces, functions, and jargon. Moreover, these +users who are not experts in visual analytics +to navigate unfamiliar interfaces, functions, and jargon. Moreover, these general-purpose tools may lack out-of-the-box support for key requirements in -atmospheric science, such as globe and map projections or support for specific +atmospheric sciences, such as globe and map projections or support for specific data formats and structures, leading to time-consuming customization or feature requests. EAM QuickView was developed to address these limitations by offering a focused, user-friendly platform that streamlines the analysis of atmospheric simulations. It minimizes the need for EAM developers and users to write custom -scripts, thereby reducing “last-mile” effort and accelerating the path from data -to insight. +scripts, thereby shortening the path from data to insight. The core goal of EAM QuickView is a first glance at the contents in a simulation -data file—the characteristic values of physical quantities and their variations -with respect to geographical location, altitude, and time, a capability that is -especially valuable for tasks such as simulation/model verification, validation, -and qualitative data exploration. Compared to earlier and widely used tools like +data file, i.e., a first inspection of the characteristic values of +physical quantities and their variations +with respect to geographical location, altitude, and time, +as well as a quick inspection across different physical quantities +for similarities or distinctions. +Compared to earlier and widely used tools like [ncview](https://cirrus.ucsd.edu/ncview/) and [ncvis](https://github.com/SEATStandards/ncvis), QuickView has an emphasis on multivariate visualization and is currently focused on the EAM model. ## Key Features -- 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. - -## Further Reading - -EAM QuickView leverages [ParaView](https://www.paraview.org/) for backend data -processing and [trame](https://kitware.github.io/trame/) for an intuitive, -browser-based user interface. +- 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. -To learn more about the installation of EAM QuickView, checkout the -[installation guide](setup/requirements.md) -To learn more about using EAM QuickView, checkout the -[brief overview.](tutorials/eamapp.md) +--- +## Bug reports and feature requests -For information about data file requirements and supported formats, see the -[data requirements documentation](data-requirements.md) +Please use the [Issues tab on GitHub](https://github.com/ayenpure/QuickView/issues). -## Point of Contact +--- +## Project Background 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 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). +at [Kitware, Inc.](https://www.kitware.com/). Other key contributors at Kitware, Inc. +include Berk Geveci and 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 Office of Science’s diff --git a/docs/future.md b/docs/future.md index 84a97b4..ac83e5b 100644 --- a/docs/future.md +++ b/docs/future.md @@ -1,11 +1,17 @@ # 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. - +For the upcoming versions, we plan to prioritize the following: -1. Server-client model and deployment of servers to Department of Energy's Leadership Computing Facilities. +- adding support for the server-client model and deploying server to + Department of Energy's Leadership Computing Facilities; +- leveraging [ParaView's](https://www.paraview.org/) parallel processing + capabilities to process many variables or high-resolution data; +- adding support for the cubed-sphere meshes used by EAM's dynamical + core, i.e., the np4 grids; +- addressing the display issues that currently need a camera refresh + as a remedy (see the [Reminders page](userguide/reminders.md); +- allowing the center longitude on the maps to be customized . -1. +Addional suggestions are welcome. +Bug reports and feature requests can be made by opening new +[issues](https://github.com/ayenpure/QuickView/issues) on GitHub. diff --git a/docs/images/colorbar_hover_over.png b/docs/images/colorbar_hover_over.png new file mode 100644 index 0000000..2005188 --- /dev/null +++ b/docs/images/colorbar_hover_over.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:610ba3bf4ebecf4e680ac887b944d32776d09d6c11f7a8661a0ed0ffad278281 +size 78643 diff --git a/docs/images/control-panel.png b/docs/images/control-panel.png deleted file mode 100644 index d61074c..0000000 --- a/docs/images/control-panel.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:19781a39f3cf9072bec45d2fbf6c221595a4ca5fecbd0c5d080656fedb76d03b -size 96678 diff --git a/docs/images/control_panel_map_projection.png b/docs/images/control_panel_map_projection.png new file mode 100644 index 0000000..6e5e995 --- /dev/null +++ b/docs/images/control_panel_map_projection.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5e391e6ee2dcb0a2b11f115e2cb8133a144bcc869db37894b3aebc6ffe7df807 +size 55450 diff --git a/docs/images/control_panel_slice_selection.png b/docs/images/control_panel_slice_selection.png new file mode 100644 index 0000000..e0c9c4c --- /dev/null +++ b/docs/images/control_panel_slice_selection.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:17656533047e78b6d46038a743ee2d49549163ce1b6fde1c9dea7c6dd6d05972 +size 102214 diff --git a/docs/images/control_panel_variable_selection.png b/docs/images/control_panel_variable_selection.png new file mode 100644 index 0000000..9cac7ae --- /dev/null +++ b/docs/images/control_panel_variable_selection.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8beffaed5dbff699f5730d3a619a1f4d48abbd3669611486184609cc2c461c15 +size 164055 diff --git a/docs/images/eam-quickview-full-enum.png b/docs/images/eam-quickview-full-enum.png deleted file mode 100644 index 035ba22..0000000 --- a/docs/images/eam-quickview-full-enum.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:15739857425b509f814e337910f78de069a12e9795bb5f56d5ea2f02d68dd565 -size 2290825 diff --git a/docs/images/eam-quickview-full.png b/docs/images/eam-quickview-full.png deleted file mode 100644 index 299a618..0000000 --- a/docs/images/eam-quickview-full.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:95c4617523cfe61e24b2dd44c6e13c7d5329029129cd6418067008faa91b2f57 -size 1737962 diff --git a/docs/images/eam_quickview_full.png b/docs/images/eam_quickview_full.png new file mode 100644 index 0000000..4e036d3 --- /dev/null +++ b/docs/images/eam_quickview_full.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:78d91320fc9e3dea918e41cc56719ed7b450e0c3ceac3eb641776599fba25913 +size 2566455 diff --git a/docs/images/main.png b/docs/images/main.png deleted file mode 100644 index a8d4bbf..0000000 --- a/docs/images/main.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:a4fbfe24c8789ee9ddbd09550d91f3ca683caf59eb1a3569faa4e64ab7c039a8 -size 1285101 diff --git a/docs/images/mini-menu.png b/docs/images/mini-menu.png deleted file mode 100644 index 16e7a10..0000000 --- a/docs/images/mini-menu.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:091f6fe0f1a3fb490778ec428333ac2cedcfe925200f5051c159a9c41751e402 -size 1114775 diff --git a/docs/images/six_variables_default.png b/docs/images/six_variables_default.png deleted file mode 100644 index 72e69d4..0000000 --- a/docs/images/six_variables_default.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:f808d0dfde475b89690f4536563efb567de85240b96090b15a299d56875e069d -size 5607537 diff --git a/docs/images/six_variables_rearranged.png b/docs/images/six_variables_rearranged.png deleted file mode 100644 index 2460744..0000000 --- a/docs/images/six_variables_rearranged.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:103a18f56acf42ec65001f7cc362a7e9df13e97db32c04a06570bc1c830ac2a2 -size 4380959 diff --git a/docs/images/state_files/state_4views_BURDEN1_PS_T_Q b/docs/images/state_files/state_4views_BURDEN1_PS_T_Q new file mode 100644 index 0000000..c33003d --- /dev/null +++ b/docs/images/state_files/state_4views_BURDEN1_PS_T_Q @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4c1764c4a1bfa064f175add876cdf94f68817da3fb5807468ac4a68f61e4b49b +size 1740 diff --git a/docs/images/state_files/state_4views_aerosol b/docs/images/state_files/state_4views_aerosol new file mode 100644 index 0000000..dd6771d --- /dev/null +++ b/docs/images/state_files/state_4views_aerosol @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:626764ae2a4f78657ef9bf7227df82e6aaf41e21ccb623010855edeb2217d2ed +size 1817 diff --git a/docs/images/state_files/state_for_gear_menu_examples b/docs/images/state_files/state_for_gear_menu_examples new file mode 100644 index 0000000..03fc088 --- /dev/null +++ b/docs/images/state_files/state_for_gear_menu_examples @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:82fcf3e76eeb26fda0a98cd8f8e8ec29753f361f5db1a08e89a05b916c404fdd +size 1271 diff --git a/docs/images/state_files/state_many_views_rearranged b/docs/images/state_files/state_many_views_rearranged new file mode 100644 index 0000000..87dea65 --- /dev/null +++ b/docs/images/state_files/state_many_views_rearranged @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:75fdef3de66c5ce56b758b668f8e81249f2a9e9738d185a0ffde657b0e6983f1 +size 2579 diff --git a/docs/images/toolbar.png b/docs/images/toolbar.png index 65f6027..34737bf 100644 --- a/docs/images/toolbar.png +++ b/docs/images/toolbar.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:e41d3cb5c519feee30f04b9d751eb66915f462af75637c9fe3f3c1473e37d469 -size 99744 +oid sha256:0312a336d1e1c988927f40f8efccf39e36c8ea56fb010ca09b677e95dc1cf5df +size 36382 diff --git a/docs/images/toolbar_busy_indicator.png b/docs/images/toolbar_busy_indicator.png new file mode 100644 index 0000000..e5c028a --- /dev/null +++ b/docs/images/toolbar_busy_indicator.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9d77761e066d5bfadc12babd0f39d79b92808758fab5cb970178135b1ccf7766 +size 5845 diff --git a/docs/images/toolbar_camera_actions.png b/docs/images/toolbar_camera_actions.png new file mode 100644 index 0000000..0276ee9 --- /dev/null +++ b/docs/images/toolbar_camera_actions.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8e99ddaf9fa9f84bd3c7848055269eb53716de3db9446c21bc2956e9dc8c0886 +size 9118 diff --git a/docs/images/toolbar_camera_reset.png b/docs/images/toolbar_camera_reset.png new file mode 100644 index 0000000..385418d --- /dev/null +++ b/docs/images/toolbar_camera_reset.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5ed219a14997bcc6d5262c6fde1dc43673842086d2dd19c1499a69212c8d8f88 +size 5972 diff --git a/docs/images/toolbar_circle_green.png b/docs/images/toolbar_circle_green.png new file mode 100644 index 0000000..ac823db --- /dev/null +++ b/docs/images/toolbar_circle_green.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6c20713c75116c818a64d8285e1a79373632ef14d8b2d63b1c2624966691c004 +size 6416 diff --git a/docs/images/toolbar_circle_red.png b/docs/images/toolbar_circle_red.png new file mode 100644 index 0000000..dac82e3 --- /dev/null +++ b/docs/images/toolbar_circle_red.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:95f9f16a3e7ab8929b4f4fb87c7cc4395dcf04be09c4e19e6ef59c029b09aac3 +size 6257 diff --git a/docs/images/toolbar_colormap_groups.png b/docs/images/toolbar_colormap_groups.png new file mode 100644 index 0000000..7f175dc --- /dev/null +++ b/docs/images/toolbar_colormap_groups.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:411951fcc2ee95b2bccee0efa4508fc069ddb45b00a1075ee36bb7a6f9917080 +size 7723 diff --git a/docs/images/toolbar_conn_and_data_load.png b/docs/images/toolbar_conn_and_data_load.png index b5ffa33..5a42cbe 100644 --- a/docs/images/toolbar_conn_and_data_load.png +++ b/docs/images/toolbar_conn_and_data_load.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:1ae21b62f7936b0c83ae5507b8ead022043ef53445374232aa75a810c3bf551f -size 47901 +oid sha256:cc7884af82813976739cab16769fd4e14d3b0758aef0a894ea5aa648504c2268 +size 15762 diff --git a/docs/images/toolbar_hamburger.png b/docs/images/toolbar_hamburger.png new file mode 100644 index 0000000..cb3a932 --- /dev/null +++ b/docs/images/toolbar_hamburger.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:cebbaeb1bcfdbbecfb477c6e021496c83b9f9e28d3cbb7ad81127dfa25167226 +size 5144 diff --git a/docs/images/toolbar_load_variables.png b/docs/images/toolbar_load_variables.png new file mode 100644 index 0000000..afe8e3c --- /dev/null +++ b/docs/images/toolbar_load_variables.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:73f5956f3722f3934bf2ddb92570dc93250790691e864a92bcb48554f2f0b1cf +size 10816 diff --git a/docs/images/toolbar_misc.png b/docs/images/toolbar_misc.png deleted file mode 100644 index 496504c..0000000 --- a/docs/images/toolbar_misc.png +++ /dev/null @@ -1,3 +0,0 @@ -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 index 2f743b8..1a0512f 100644 --- a/docs/images/toolbar_state_save_and_load.png +++ b/docs/images/toolbar_state_save_and_load.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:d73203517ccd0d85624a851275e2eaf15d6b1e8fd6c6b85859b7612447261b91 -size 20227 +oid sha256:e38f43a349ed8c0d54254c108e33b18e73285b67a53227eccc9bb719f6ba0071 +size 5428 diff --git a/docs/images/variable-select.png b/docs/images/variable-select.png deleted file mode 100644 index 2f7bf57..0000000 --- a/docs/images/variable-select.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:861e4ca9a2f8c2fc3586f98dc846d2fe1736efaa056a426f5b7dfa3d98db9bb3 -size 61231 diff --git a/docs/images/view-collapsed.png b/docs/images/view-collapsed.png deleted file mode 100644 index 2e6b071..0000000 --- a/docs/images/view-collapsed.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:bb9e3241f3b1304e8c7f6228d9bb7f11b0dde6aa1716c59398cbb518a548354e -size 1317274 diff --git a/docs/images/view-expanded.png b/docs/images/view-expanded.png deleted file mode 100644 index 6f5a224..0000000 --- a/docs/images/view-expanded.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:04ffe302e04bf1df54959634a56aa82fa262be95c00b37b47087f0548b97fb96 -size 1325717 diff --git a/docs/images/viewport_four_views.png b/docs/images/viewport_four_views.png new file mode 100644 index 0000000..3b76aa0 --- /dev/null +++ b/docs/images/viewport_four_views.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:238558148ec76b32108543dc71b3d05b6898eb1901c2052de5fee88fbdc26ada +size 1663122 diff --git a/docs/images/viewport_gear_menu_range_auto.png b/docs/images/viewport_gear_menu_range_auto.png new file mode 100644 index 0000000..44c8495 --- /dev/null +++ b/docs/images/viewport_gear_menu_range_auto.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:39b938b75dea7975545551d70b6fa26503bee17cc74c6bc6b2649a2c3a2594ab +size 977502 diff --git a/docs/images/viewport_gear_menu_range_manual.png b/docs/images/viewport_gear_menu_range_manual.png new file mode 100644 index 0000000..92b3455 --- /dev/null +++ b/docs/images/viewport_gear_menu_range_manual.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f4e4adc80791cb6f73f1109057312a35d0c8c1fa7f36aa9d7b8639f271c8ab52 +size 982882 diff --git a/docs/images/viewport_many_views_rearranged.png b/docs/images/viewport_many_views_rearranged.png new file mode 100644 index 0000000..41ef805 --- /dev/null +++ b/docs/images/viewport_many_views_rearranged.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0dcccda7246292e2e3c8bd7166d972fd36424f4997b8b9b87b2609c3077c3d8c +size 2614046 diff --git a/docs/setup/for_app_developers.md b/docs/setup/for_app_developers.md index 8d9654d..253aafb 100644 --- a/docs/setup/for_app_developers.md +++ b/docs/setup/for_app_developers.md @@ -1,11 +1,15 @@ -# Installation and Launch for App Developers +# Install 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. +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. -Releases so far have focused on MacOS. Support for Linux and Windows systems can be provided upon request. +Releases so far have focused on macOS. Support for +more systems will be added in the near [future](../future.md). ---- -## Cloning the repo +## Clone the repo ``` git clone https://github.com/ayenpure/QuickView.git @@ -13,7 +17,7 @@ cd QuickView ``` ---- -## Installing basic requirements +## Install basic requirements ``` # Set up conda environment @@ -35,7 +39,7 @@ distributed with the ParaView binaries. The `pvpython` binary is present in the `/Applications/ParaView-5.13.0.app/Contents/bin/pvpython` ---- -## Launching the app from command line +## Launch the app from command line To launch the EAM QuickView GUI in its dedicated window, use ``` diff --git a/docs/setup/for_end_users.md b/docs/setup/for_end_users.md index c549fe4..f2dca0e 100644 --- a/docs/setup/for_end_users.md +++ b/docs/setup/for_end_users.md @@ -1,23 +1,56 @@ -# Installation and Launch for End Users +# Install 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. +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. -Releases so far have focused on MacOS. Installers for Linux and Windows systems can be provided upon request. +Releases so far have focused on macOS. Support for +more systems will be added in the near [future](../future.md). --- -# Installation +# Install -For end users, we provide pre-built binaries that can be installed using just a few clicks. +For end users, pre-built binaries are available and can be installed +with just a few steps, as described below. -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. +1. Download a pre-built binary from the + [releases page](https://github.com/ayenpure/QuickView/releases/). + macOS users with Apple Silicon chips should download a `*_aarch64.dmg`, + and those with Intel chips should download a `*_x64.dmg` file. +2. **Important:** After the download, use the following command in Terminal to + unblock the app for macOS: + ``` + xattr -d com.apple.quarantine .dmg + ``` + Explanation: In order to facilitate frequent iterations between our + developers on the software and science sides, disk images are + built and made public using GitHub's automated release process + rather than being manually built and then signed at Kitware. + Hence the `.dmg` files on the GitHub releases page have not been + signed using an Apple Developer ID, and the command provided above is needed, + so that after download, the macOS Gatekeeper will not block the app. -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. +3. Double-click the downloaded `.dmg` file. In the pop-up window, + drag the QuickView icon into the Applications folder. + + +!!! tip "Tip: No Worries about Dependencies" + + The pre-built binaries include the dependencies required to + start the app locally. Any additional dependencies for data processing + and visualization are downloaded and installed automatically on the first launch. --- # Launch -To launch the EAM QuickView GUI, simply double-click the app icon in your Applications folder. +To launch the EAM QuickView GUI, simply double-click the app icon in the Applications folder. + +!!! tip "Tip: Patience with the First Launch" + + On the first launch of a new app version, required dependencies are + downloaded and installed. This may take a minute or more, depending + on the Internet connection. Subsequent launches typically take only a few seconds. + diff --git a/docs/setup/requirements.md b/docs/setup/requirements.md deleted file mode 100644 index 6179f69..0000000 --- a/docs/setup/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -## Requirements - -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 are expected to -support the server-client model. - -EAM QuickView has two key requirements, python version `>=3.10` and ParaView -`>=5.13` - -### Python version 3.10 - -Python can be installed using either `homebrew` if using macOS like - -``` -brew install python3.10 -``` - -or `apt` if using Ubuntu Linux. - -``` -sudo apt install python3.10 -``` - -Alternatively, python can also be installed using anaconda/miniconda - -``` -conda create --name eamapp python=3.10.0 -conda activate eamapp -``` - -However, this would require activating/deactivating the conda environment -before/after using the application. - -### ParaView 5.13 installed on the system - -ParaView can be installed from the binaries found at -https://www.paraview.org/download - -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` diff --git a/docs/userguide/connectivity.md b/docs/userguide/connectivity.md index 5ca64ea..20a1092 100644 --- a/docs/userguide/connectivity.md +++ b/docs/userguide/connectivity.md @@ -1,35 +1,55 @@ # Connectivity files -## Background +!!! tip inline end "Tip: Connecitivity File Download" + + A collection of connectivity files can be found on + [Zenodo](https://doi.org/10.5281/zenodo.16908566). + The archive is continually updated as more users inform us + about the grids their data files use. The horizontal grids used by EAM are cubed spheres. Since these are unstructed -grids, the QuickView app needs to know how to map data to the globe. Therefore, +grids, QuickView 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 +In EAMv2, v3, and v4, most of the variables (physical quantities) are +written out on a "physics grid" (also referred to as "physgrid", "FV grid", +or "control volume mesh") 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. Further details about EAM's cubed-sphere grids +The naming convention for such grids is `ne*pg2`, with `*` being a number, +e.g., 4, 30, 120, 256. 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). +Future versions of QuickView will also support the cubed-sphere meshes +used by EAM's dynamical core, i.e., the `ne*np4` grids +(also referred to as "native grids" or "GLL grids"). -## Generation +## Generate connectivity files -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); +Users can 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). +using [this script](https://github.com/mt5555/remap-ncl/blob/master/makeSE.sh) +shared by Mark A. Taylor at Sandia National Laboratories. +(`TempestRemap` +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 provided in its +[repo](https://github.com/ClimateGlobalChange/tempestremap).) + +For example, using Mark's script, the command + +``` +./makeSE.sh 30 +``` + +will generate serveral 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. -EAM QuickView uses the SCRIP format of the connectivity files. diff --git a/docs/userguide/control_panel.md b/docs/userguide/control_panel.md index 264b3a8..919424a 100644 --- a/docs/userguide/control_panel.md +++ b/docs/userguide/control_panel.md @@ -1,37 +1,109 @@ -## The Control Panel -![control-panel](../images/control-panel.png){ width="400" } +!!! tip inline end "Tip" -The control panel lets users control the context of visual analysis for the -data, i.e, it allows the users to select the time, middle and interface layers, -and the variables for analysis, among other operations. The panel can be divided -into three main parts + 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). -1. **Data Slice Selection** The data slice selection allows users to slice and - dice data spatio-temporally for analysis +# Control Panel - - a. It allows data slice selection along the dimensions of time, middle and - interface layer. - - b. It allows users to control the geo-spatial region by controlling the - longitude, latitude ranges. +The control panel allows users to select variables from the simulation +data file as well the spatial and temporal ranges of data to visualize, +as explained below. - Users can interactively select the data slice by interacting with the - sliders, or using the media buttons to skip-previous, skip-next, or play an - animation. -2. **Map Projection Selection** The map projection selection allows users to - chose different representation of the data. Currently, it allows for - Cylindrical-Equidistant, Robinson, and Mollweide projections. In the future, - additional features are planned, e.g. selection of center meridian. +----- +## Variable selection -3. **Variable Selections** - ![variable-select](../images/variable-select.png){ width="400" } - The variable selections allow users to control variables of interest for - analysis. The variables are separated into three types -- the 2D (surface) - variables, middle layer variables, and interface layer variables. Users can - select and unselect the variables and to render the views, click the - `Load Variables` button located in the tool bar. The reason for not making - the views appear dynamically post variable selections is to allow for stable - and better application behavior. +### Variable categories + +![variable selection sections](../images/control_panel_variable_selection.png){ width="240", align=right } + +EAM's simulation output files typically contain many variables +corresponding to physical quantities with spatial coverages over the +entire globe. + +- Some of those variables may not have a vertical dimension; + these are referred to as "surface variables" in our app. +- Some of those variables have "lev" or "ilev" as the vertical + dimension; these are referred to as "variables at layer midpoints" + and "variables at layer interfaces", respectively. + +The three variable categories each have their own collapsible +submenu in the control panel, as shown in the screenshot here. +Variables of other dimension sizes are currently igored by the app +but can be supported upon request. + + +### Select and load + +!!! warning inline end "The `LOAD VARIABLE` button" + + After a selection of variables is made or changed, the `LOAD VARIABLES` + button in the [toolbar](toolbar.md) must be clicked in order for the + (new) selection to take effect. + In contrast, all other buttons, sliders, and text boxes + apply their effects immediately upon user interaction. + +After a simulation data file and a connectivity have been loaded and +the status icon in the [toolbar](toolbar.md) has turned into a green +circle with a check mark, +the variable selection submenu of each variable category, +if expanded, will show a list of variables that have been recognized +by the app, as shown in the screenshot above. +Checking the boxes to the left of the variable names +*and then clicking the* `LOAD VARIABLES` *button in the toolbar* +will render contour plots in the [viewport](viewport.md). + +### Variable search + +EAM output files often contain a large number of variables, +resulting in long lists in the varaible selection submenus. +In such cases, the user can hover their cursor over the list +and then scroll up and down to review the full list. + +Typing a string in the `Search variables` box and then hitting +the `return` key on the keyboard will +replace the full variable list by a filtered list. + +Clicking the `CLEAR` button in the submenu will unselect all +variables in the category. + +*Here, we emphasize again that any changes in variable selection needs to be +followed by a click on the `LOAD VARIABLES` button in the [toolbar](toolbar.md) +in order for these changes to take effect.* + + + +----- +## Data slice selection + +![variable selection sections](../images/control_panel_slice_selection.png){ width="240", align=right } + +To keep the QuickView app lightweight and easy to use, we decided to only +support color-filled contour plots of the globe or a latitude-longitude box. +The slice selection portion of the control panel provides a set of sliders +for the user to select which vertical levels, time levels, and latitude-longitude +ranges to create contour plots for. + +For the vertical dimensions and the time dimension, the control panel +also provides buttons for moving to (displaying) the previous or next element +in the dimension, as well as "play"/"pause" (toggle) buttons for cycling over +these dimensions or pausing the cycle. +If the user clicks on a second "play" button when the app is cycling through +a first dimension, then the cycling in the first dimension will be paused. + + +----- +## Map Projection + +![variable selection sections](../images/control_panel_map_projection.png){ width="240", align=right } + +QuickView currently provides a very simple map setting submenu +that contains a few commonly used map projections. +More projections can be added upon request. +In the near future, the center longitude of the map +will become customizable. + diff --git a/docs/userguide/data_requirements.md b/docs/userguide/data_requirements.md index bb08878..50826a8 100644 --- a/docs/userguide/data_requirements.md +++ b/docs/userguide/data_requirements.md @@ -1,185 +1,108 @@ -# 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 - -## Obtaining Sample Data - -Sample E3SM Atmosphere Model (EAM) data files and their corresponding -connectivity files are available at -[Zenodo](https://zenodo.org/records/16895849). The dataset includes: - -### Available Data Files - -- **EAM Version 2 outputs**: - - `EAMv2_ne120pg2_F2010_spinup.eam.h0.nc` (525.3 MB) - - `EAMv2_ne30pg2_F2010_aermic.eam.h0.nc` (498.3 MB) - - `EAMv2_ne30pg2_F2010_cld.eam.h0.nc` (745.5 MB) -- **EAM Version 4 (interim) outputs**: - - `EAMxx_ne4pg2_202407.nc` (13.2 MB) - -### Available Connectivity Files - -- `connectivity_ne120pg2_TEMPEST.scrip.nc` (31.8 MB) -- `connectivity_ne30pg2_TEMPEST.scrip.nc` (2.0 MB) -- `connectivity_ne4pg2_TEMPEST.scrip.nc` (48.8 kB) - -### Important: File Correspondence - -**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. - -## 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: +QuickView has been developed using EAM's history output +on the physics grids (`pg2` grids) written by +EAMv2, v3, and an intermediate version towards v4 (EAMxx). +Those sample output files can be found on +[Zenodo](https://zenodo.org/records/16922607). + +Developers and users of EAM often use tools like NCO and CDO +or write their own scripts to calculate time averages +and/or select a subset of variables from the original model output. +For those use cases, we clarify below the features of the data format +that QuickView expects in order to +properly read and visualize the simulation data. + +!!! tip "Tip: Consistency Between Simulation File and Connecitivity File" + + One of the repeatedly encountered causes of error when loading files + in QuickView + is that the grid described by the connecitivity file does not match + the grid in the simulation data file. + If the `Load Files` button in the [toolbar](toolbar.md) has been clicked + but the status icon continues to show a red circle with an exclamation mark + after many seconds of time, the first thing we suggest + checking is whether the two specified files correspond to the same grid. + +!!! warning "Caution: Newer EAMxx Output Files" + + The EAMxx output file that QuickView has been tested for + was generated in late 2024. As EAMxx further evolves and its output + format changes, QuickView might need to be updated accordingly. + If the user encounters such a case, we recommend reaching out to our lead developer + [(abhi.yenpure@kitware.com)](https://www.kitware.com/abhishek-yenpure/) + or using the [Issue tab on GitHub](https://github.com/ayenpure/QuickView/issues) + to start a discussion. + +---- +## Overview + +The ParaView Reader behind the QuickView GUI detects and categorizes variables +based on their dimensions. +Variables with dimensions not matching the expected patterns are ignored. + +---- +## 2D variables + +QuickView recognizes variables with—and only with—the +^^dimensions `time` and `ncol`^^ as 2D variables, +i.e., physical quantities varying with latitude and +longitude but without a vertical dimension. +These are referred to as "surface variables" in the +[control panel](control_panel.md). +For these variables, the only required ^^coordinate variable^^ is ^^`time`^^. +Grid information, including latitude and longitude, are obtained +from the [connecitivity file](connecitivity.md). + +If an `area` variable with the dimension `ncol` is also present, +this variable is used for calculating the area-weighted horizontal averages +displayed in the [viewport](viewport.md). +If the `area` variable is not present, then an arithmetic average +is calculated and displayed. + +---- +## 3D variables + +If a variables has not only `time` and `ncol` but also a vertical dimension, +QuickView expects the dimension to be named ^^`lev`^^ for variables defined at +layer midpoints and ^^`ilev`^^ for variables defined at layer interfaces. + +For variables defined at layer midpoints, in order for the `Slice Selection` +section of the [control panel](control_panel.md) to work properly, +the simulation data +file needs to contain a 1D coordinate variable named `lev`, +the values of which are interpreted as pressure in hPa. +If `lev` is not present, QuickView attempts to find two 1D variables, +`hyam` and `hybm`, of that dimension size, from which QuickView calculates +`lev` using ``` -pressure = (hyam * P0) + (hybm * PS0) +lev = (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 +where PS0 = 1000 hPa; P0 is read from the data file and set to 1000 hPa +if not found. -### 2D Variables (Surface Variables) +Similarly, for variables defined at layer interfaces, QuickView looks for +either `ilev` or `hyai` and `hybi` for parsing the vertical dimension. -- Dimensions: `(time, ncol)` -- Example: `TS` (surface temperature), `PS` (surface pressure) -- These represent surface or column-integrated quantities -### 3D Midpoint Variables +---- +## Variable with more dimensions -- Dimensions: `(time, lev, ncol)` or `(time, ncol, lev)` -- Example: `T` (temperature), `U` (zonal wind), `Q` (specific humidity) -- These are defined at layer midpoints +QuickView currently only visualizes the variables types discussed above. +For variables that have extra dimensions in addition to `time`, `ncol`, +and `lev` or `ilev`, for example aggregated tracer arrays or +[COSP](https://climatedataguide.ucar.edu/climate-data/cosp-cloud-feedback-model-intercomparison-project-cfmip-observation-simulator-package)-related variables, +support can be provided if there is sufficient +interest from the users. Please contact our lead developer +[(abhi.yenpure@kitware.com)](https://www.kitware.com/abhishek-yenpure/) +for a discussion. -### 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) ; -``` +---- +## Missing values -## Notes +If a variable has an attribute named `missing_value` or `_FillValue`, +the value is converted to NaN and ignored +in the calculation of global averages and for the visualization. -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/userguide/gui_overview.md b/docs/userguide/gui_overview.md index a839c9e..8a057c7 100644 --- a/docs/userguide/gui_overview.md +++ b/docs/userguide/gui_overview.md @@ -1,27 +1,25 @@ # Graphical User Interface (GUI) -EAM QuickView's GUI contains the four main components summarized below. +EAM QuickView's GUI contains the three 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 +![EAM QuickView screenshot](../images/eam_quickview_full.png){ width="95%" } + +**Toolbar**: +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 +**Control Panel**: +The [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). + shown using the hamburger icon (three stacked lines) + at 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. +**Viewport** + The [viewport](view_port.md) displays one or more variables for + the user. For each variable, the colormap, value ranges 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/old_data_requirements.md b/docs/userguide/old_data_requirements.md new file mode 100644 index 0000000..bb08878 --- /dev/null +++ b/docs/userguide/old_data_requirements.md @@ -0,0 +1,185 @@ +# 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 + +## Obtaining Sample Data + +Sample E3SM Atmosphere Model (EAM) data files and their corresponding +connectivity files are available at +[Zenodo](https://zenodo.org/records/16895849). The dataset includes: + +### Available Data Files + +- **EAM Version 2 outputs**: + - `EAMv2_ne120pg2_F2010_spinup.eam.h0.nc` (525.3 MB) + - `EAMv2_ne30pg2_F2010_aermic.eam.h0.nc` (498.3 MB) + - `EAMv2_ne30pg2_F2010_cld.eam.h0.nc` (745.5 MB) +- **EAM Version 4 (interim) outputs**: + - `EAMxx_ne4pg2_202407.nc` (13.2 MB) + +### Available Connectivity Files + +- `connectivity_ne120pg2_TEMPEST.scrip.nc` (31.8 MB) +- `connectivity_ne30pg2_TEMPEST.scrip.nc` (2.0 MB) +- `connectivity_ne4pg2_TEMPEST.scrip.nc` (48.8 kB) + +### Important: File Correspondence + +**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. + +## 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/userguide/reminders.md b/docs/userguide/reminders.md index 39aab41..a29fc83 100644 --- a/docs/userguide/reminders.md +++ b/docs/userguide/reminders.md @@ -3,15 +3,15 @@ !!! tip "Tip: Two Modes of Use" 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 + 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" - 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 + Regardless of which mode is used, a connectivity file 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). @@ -19,27 +19,30 @@ 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` + 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 + The QuickView app is designed to present multiple variables simultaneously + in an informative way. Users can ^^rearrange^^ the individual views + (i.e., contour plots) 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., + a visualization setting is changed, some (or all) of + the views in the [viewport](viewport.md) may exhibit display issues, 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. - + globe or region. This can be remedied by clicking the camera reset + button at the right end of the [toolbar](toolbar.md). We are working on + solving the display problem for future versions. + diff --git a/docs/userguide/toolbar.md b/docs/userguide/toolbar.md index 0efa1d9..d764ca3 100644 --- a/docs/userguide/toolbar.md +++ b/docs/userguide/toolbar.md @@ -3,82 +3,156 @@ 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 +visualization session, "global" in the sense that they affect +the overall appearance and state of the GUI, including all views +of physical quantities displayed in the [viewport](viewport.md). +In the following, we first explain in detail the UI 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) + +![connectivity and data file selection](../images/toolbar_conn_and_data_load.png){ width="59%", align=right } 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 portion of the toolbar shown here, by either pasting/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, +![green circle](../images/toolbar_circle_green.png){ width="5%", align=right } +![red circle](../images/toolbar_circle_red.png){ width="5%", align=right } + +After both files have been specified, the `Load Files` button +next to the `Data File` box +(i.e., the icon of a page with a check mark) must be clicked. +If the red circle with an exclamation +mark shown in the picture here 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 +The user can then start using the [control panel](control_panel.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: +!!! warning "Tip: File Loading Error" -- 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). + After the `Load Files` button is clicked, + if the red circle-and-exclamation icon persists, + then the variable dimensions in the data file + are not parsed correctly. Below are some common reasons for the error: + + - The data file and the connectivity file correspond to different cubed-sphere + grids. 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) +![state save and load](../images/toolbar_state_save_and_load.png){ width="10%", align=right } 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. +resume the analysis—using the `Save State` (downward arrow) +and `Load State` (upward arrow) buttons shown here. + +For loading a state, the upward arrow button brings up a window for +the user to select a state file from the computer. After the file +is selected and the `Open` button in that dialogue window is clicked, +the app will immediately start loading the state; the user is *not* +supposed to click on the Load Files button designed for the new-viz scenario. +If the state file is successfully loaded (the contents are correctly parsed), +the red circle-and-exclamation icon will turn into to a green circle-and-check-mark icon, +like in the new-viz mode. Loading a state for an ne30 simulation +usually takes a couple of seconds. + +!!! info "Info: What's in a State File?" + + 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 a state file is shared among multiple users or used across different + file systems, or if a user wants to apply the same visualization settings + to a different simulation data file, 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. + +!!! warning "Tip: State File Loading Error" + + If the app seems nonresponsive after a state file has been chosen + and the `Open` button in the dialogue window has been clicked, + there is a high chance that the paths and names of + the connectivity and simulation data files contain errors. + The user should consider using a text editor to inspect the first + few lines of the state file and verify correctness. ---- ## 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" + + +![hamburger icon](../images/toolbar_hamburger.png){ width="6%", align=right } + +**Control Panel Hide/Show**: +The hamburger icon (three stacked lines) at the left end of the toolbar +hides or shows the [control panel](control_panel.md). + + + +![busy inidcator](../images/toolbar_busy_indicator.png){ width="5%", align=right } + +**Busy Indicator**: +The gray circle is a busy indicator. When a rotating segment appears, +the app is processing data in the background—for example, loading data files +or a state file as explained ealier on this page, +or loading newly selected variables +(see description of the [control panel](control_panel.md)). + + + +![LOAD VARIABLES button](../images/toolbar_load_variables.png){ width="18%", align=right } + +**`LOAD VARIABLES`**: +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). + + + +![colormap groups](../images/toolbar_colormap_groups.png){ width="12%", align=right } + +**Colormap Groups**: +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 "presets" +from [PareView](https://www.paraview.org/). + + + +![camera actions](../images/camera_actions.png){ width="25%", align=right } + +**Camera Actions**: +A set of buttons are provided to simultaneously adjust all views +in the [viewport](viewport.md): move them up, down, left, or right with +respect to the GUI, zoom in or out, or +refresh all contents in the [viewport](viewport.md) +so that the contour plots are recentered and resized to their +individual frames. + +!!! tip "Tip: Camera Refresh for Addressing Display Error" + + ![camera reset](../images/toolbar_camera_reset.png){ width="6%", align=right } 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. + display issues after new variables are loaded or when visualization + settings are changed. + In those cases, a click on the `Camera Reset` button at the right end + of the tool bar should reload the visualization + properly, and we are working on resolving the display problem for future releases. diff --git a/docs/userguide/viewport.md b/docs/userguide/viewport.md index a49b841..3a9b6f6 100644 --- a/docs/userguide/viewport.md +++ b/docs/userguide/viewport.md @@ -1,49 +1,85 @@ # Viewport +![Four views](../images/viewport_four_views.png){ width="50%", align=right } + Once the user has selected variables using the [control panel](control_panel.md) and clicked the `LOAD VARIABLES` button in the [toolbar](toolbar.md), the app -will show each variable in its own frame (which we refer to as a "view") inside -the viewport. Below is an example showing six views. +will show each variable in its own little frame (which we refer to as a "view") inside +the viewport. On the right is an example showing four views. -At the top of each view, the variable name is shown in the top-left corner -together with the area-weighted global average on that vertical level. Indices -of the vertical level and time being displayed are indicated in the top-right -corner of each view. +Within each view, the variable name is noted together with +the indices of the vertical level (if applicable) and time slice being displayed, +and the area-weighted global average on that vertical level. +If the "area" variable is not present in the data file, then the arithmetic +average is calculated and displayed. -![Six views in default layout](../images/six_variables_default.png){width="600"} +----- ## Custimizing the viewport +![Many views resized and rearranged](../images/viewport_many_views_rearranged.png){ width="50%", align=right} + To help present multiple variables in an informative way, the app allows users -to rearrange the views via drag-and-drop and resize each view separately by -clicking and dragging its bottom-right corner. Below is an example with -rearranged views. +to + +- rearrange the views via ^^drag-and-drop^^, and +- resize each view separately by clicking and dragging its + ^^bottom-right corner^^. + +The screenshot on the right shows an example with rearranged views. Furthermore, if a user saves a state file after these adjustments, they can -later resume their analysis with the customized arrangement. +later continue their analysis with the customized layout +by using the app in the resume mode, as described in on the description +of the [toolbar](toolbar.md). -![Six views resized and rearranged](../images/six_variables_rearranged.png){width="700"} +----- ## Custimizing individual views Each view can be further customized individually by clicking on the gear button in the bottom-left corner of the view. The click brings up a mini menu as shown -in the example below. +in the examples below. -_[Hui's note from 4/30/2025: the title of the colorbar reads "Component". Is -this a bug? We'd like the title to show the variable name; or we could remove -the title.]_ +The mini menu contains options to control various properties of the view: +a dropdown menu for colormap selection, +checkboxes to turn on/off logarithmic scale and to invert/restore the color sequence, +text boxes for changing the minimum and maximum values for color mapping, and +a button to reset the color mapping to fit the value range of data slice. -![Mini menu for custimizing a view](../images/mini-menu.png){width="400"} +![gear menu with auto range](../images/viewport_gear_menu_range_auto.png){ width="48%"} +![gear menu with manual range](../images/viewport_gear_menu_range_manual.png){width="48%"} -The mini menu contains options to control various properties of the view: +!!! tip "Tip: Automatic or Fixed Colormap Ranges" + + + By default, the app will automatically span the colormap over the range of values + of the current time slice and vertical level. The maximum and minimum values can be found + in the mini menu, as seen in the left example shown above. + When the "play" button in the [control panel](control_panel.md) is used to cycle + through different data slices, + the colormap is automatically re-adjusted to fit the data range of each slice. + + If the user specifies maximum and/or minimum values in the mini menu, a blue icon + with a picture of a lock and the text "Manual" will appear above the maximum + value, as can be seen on the right in the example shown above. + In such a case, when the "play" button in the [control panel](control_panel.md) + is used to cycle through different data slices, + the colormap will be fixed to the user-specified range. + + +!!! tip "Tip: Field Value Lookup in Colorbar" + + ![colorbar hover over](../images/colorbar_hover_over.png){ width="55%", align=right } + + If the user hovers their cursor over a colorbar, the corresponding field + value will be displayed, as shown by the example here. + + +!!! tip "Tip: Colormap Groups" -- A dropdown menu for color map selection. -- Checkboxes to turn on/off logarithmic scale and invert color map. -- Text boxes for changing the minimum and maximum values for color mapping. -- A button to reset the color mapping to fit the range of values in the data. + The [toolbar](toolbar.md) at the top of the GUI includes icons for two colormap + groups: colorblind-friendly and other. Only the colormaps belonging to the + selected group (or groups) are shown in the `Color Map` drop-down menu + brought up by the gear button. -Note that the zoom level and centering (i.e., the size and relative position) of -the displayed variable within each view, as well as the visibility of the color -bar, can also be adjusted. These settings are controlled centrally—for all -views—via buttons in the [toolbar](toolbar.md) near the top of the GUI. diff --git a/mkdocs.yml b/mkdocs.yml index 40d3c8e..6ca1949 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,18 +5,17 @@ plugins: - mkdocstrings nav: - Home: README.md - - Installation and Launch: + - Install 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 - - Data File Format: userguide/data_requirements.md + - Simulation Files: 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 @@ -25,3 +24,8 @@ markdown_extensions: - pymdownx.superfences - md_in_html - pymdownx.blocks.caption + - pymdownx.critic + - pymdownx.caret + - pymdownx.keys + - pymdownx.mark + - pymdownx.tilde diff --git a/pyproject.toml b/pyproject.toml index ee08e13..ef073e1 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "quickview" -version = "0.1.20" +version = "0.1.21" 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 59db7a3..b983d34 100644 --- a/quickview/__init__.py +++ b/quickview/__init__.py @@ -1,5 +1,5 @@ """QuickView: Visual Analysis for E3SM Atmosphere Data.""" -__version__ = "0.1.20" +__version__ = "0.1.21" __author__ = "Kitware Inc." __license__ = "Apache-2.0" diff --git a/quickview/interface.py b/quickview/interface.py index f22b383..0d3ca32 100644 --- a/quickview/interface.py +++ b/quickview/interface.py @@ -368,6 +368,8 @@ def generate_state(self): return to_export def load_state(self, state_file): + self._on_change_pipeline_valid(False) + self.viewmanager._on_change_pipeline_valid(False) self.state.pipeline_valid = False from_state = json.loads(Path(state_file).read_text()) data_file = from_state["data_file"] @@ -399,7 +401,11 @@ def load_state(self, state_file): self.update_state_from_config(from_state) self.state.pipeline_valid = is_valid + self.ctrl.view_reset_camera() + def load_data(self): + self._on_change_pipeline_valid(False) + self.viewmanager._on_change_pipeline_valid(False) state = self.state # Update returns True/False for validity # force_reload=True since user explicitly clicked Load Files button @@ -560,6 +566,7 @@ def update_available_color_maps(self): else: # Fallback to standard colors if nothing is selected state.colormaps = noncvd + state.colormaps.sort(key=lambda x: x["text"]) def set_manual_color_range(self, index, type, value): # Get current values from state to handle min/max independently diff --git a/quickview/plugins/eam_reader.py b/quickview/plugins/eam_reader.py index 672bd66..275cf10 100644 --- a/quickview/plugins/eam_reader.py +++ b/quickview/plugins/eam_reader.py @@ -92,10 +92,8 @@ def FindSpecialVariable(data, lev, hya, hyb): lev = data[lev][:].flatten() return lev - from numpy.core.defchararray import find - - _hyai = var[find(var, hya) != -1] - _hybi = var[find(var, hyb) != -1] + _hyai = [v for v in var if hya in v] + _hybi = [v for v in var if hyb in v] if len(_hyai) != len(_hybi): raise Exception("Unmatched pair of hya and hyb variables found") diff --git a/quickview/presets/berlin_PARAVIEW.xml b/quickview/presets/berlin_PARAVIEW.xml new file mode 100644 index 0000000..bb5420d --- /dev/null +++ b/quickview/presets/berlin_PARAVIEW.xml @@ -0,0 +1,260 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/quickview/presets/lisbon_PARAVIEW.xml b/quickview/presets/lisbon_PARAVIEW.xml new file mode 100644 index 0000000..e460d29 --- /dev/null +++ b/quickview/presets/lisbon_PARAVIEW.xml @@ -0,0 +1,260 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/quickview/presets/managua_PARAVIEW.xml b/quickview/presets/managua_PARAVIEW.xml new file mode 100644 index 0000000..d6f8891 --- /dev/null +++ b/quickview/presets/managua_PARAVIEW.xml @@ -0,0 +1,260 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/quickview/presets/vanimo_PARAVIEW.xml b/quickview/presets/vanimo_PARAVIEW.xml new file mode 100644 index 0000000..dee411c --- /dev/null +++ b/quickview/presets/vanimo_PARAVIEW.xml @@ -0,0 +1,260 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/quickview/ui/toolbar.py b/quickview/ui/toolbar.py index 40e0e5e..000d52a 100644 --- a/quickview/ui/toolbar.py +++ b/quickview/ui/toolbar.py @@ -192,7 +192,7 @@ def __init__( v_bind="attrs", v_on="on", ) - html.Span("SCRIP or TEMPEST connectivity/mesh file (.nc)") + html.Span("Connectivity file (SCRIP format .nc file)") with v2.VTooltip(bottom=True): with html.Template(v_slot_activator="{ on, attrs }"): v2.VTextField( @@ -209,7 +209,7 @@ def __init__( v_bind="attrs", v_on="on", ) - html.Span("E3SM/EAM atmospheric data file (.nc)") + html.Span("EAM simulation output (.nc file)") with v2.VTooltip(bottom=True): with html.Template(v_slot_activator="{ on, attrs }"): with v2.VBtn( diff --git a/quickview/utils/color.py b/quickview/utils/color.py index a4adbb9..d9466dc 100644 --- a/quickview/utils/color.py +++ b/quickview/utils/color.py @@ -195,6 +195,10 @@ def get_cached_colorbar_image(colormap_name, inverted=False): "normal": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAP8AAAABCAIAAACe8u/0AAAAxUlEQVQokW2PQQ7DIAwEd80j+tv+nJ0eDCRpK1nWMF6I4/dLHl5V9pCrWS67XBtcl9T96C+W7tKd1za2T+Bn6n/J/ZqOP+b6UFftTO2+QNU/c+RYcrNr6MHjGNWwjxnyv+5iM67uaNBehSsuVDSrUHefHjkNOPK9T/QANGnWXEclmg1o5jIJE82058hEExIlZJtcZgEhiJAISOAJ3AGRBQoAEUGsjHamzckICOrRuX5iPY0I65Etl1+B5w7Zu4UAWTsndH0AoR4v4nBAd8IAAAAASUVORK5CYII=", "inverted": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAP8AAAABCAIAAACe8u/0AAAA0ElEQVQokWWPQY4gIRDD4vCi+e18lmQPTQM9K6GScQUoGD+/Nnth2WAMGCzMWQijxejtCrBkALz8kssA0gqfLjy3rdjKXAdPBt0zPJkN/oItjBHrXzI3yMboMeM1A9kaxmhYg0uiYRkNtI3RoK+skelAVm/41li1aoVPjRUaHm5opNBJgyaNuqoy6dTL/9dmKrOHs0xmF2dzEyU9Jk3bLdsPVO27bdO2emFL9Rilra6w2otXTOueP8ndPQ+9x093sfZI0Z4kh9XZpp1q2tnO/gOZg0urikp4YQAAAABJRU5ErkJggg==", }, + "vanimo": { + "normal": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAP8AAAABCAIAAACe8u/0AAAAv0lEQVQokW2NUXLFMAwCAeX+N+uRBP2wZee9diaRlyWKmZ92O22308M+xv6Kh/2qPudu7fQ6p/VOA39M1sjtvj59xX7JTttet3V62u4sOfBt2vEF7F917PiYCzvGsOEsSIIENpLNfx8ACQLgTgKLB0AAAAOAPHF4gCQI6sbF1PUUKWhVAsUrtYHkYS1ztz6ktG7hf7u33Sscz7P+kmfyM0rDUu24X0m1DnFAVTNLJamGS3pUG+rGR3pUm0uP6vkFRqZfaI03/wEAAAAASUVORK5CYII=", + "inverted": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAP8AAAABCAIAAACe8u/0AAAAxklEQVQokW2NwXHEMAwDAbD/MtJGKjOBPCRa9uVmNNRiSUr87R/35b7al/tyt/vyzb66215+wD3Vw97Vzr7ttu3skNju2I6zozOcJK/oJBiG8yExK8jeQrK9P7tnxTPzkp+7a32Pze+3BHI4CYLjJyI4gGEA4YoAAHIAAUHgWUmA4JdDCiREUKQgkoIEiRQXqCDxDVSxblOs4gNURRUlDjyN9qS0WvspLS9tvuFb5FzP8h48hjW+Rtbxz6ra3SPr0ar/rVrmD0AJPNOWINzbAAAAAElFTkSuQmCC", + }, "tokyo": { "normal": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAP8AAAABCAIAAACe8u/0AAAAoUlEQVQokW2Syw3DMAxD+eh7J+gY3X+2HiRZih0EEEjq+R++nx/IwsgCyWDxCDlD2C2MzJPhWZ08IwfhEGVDxBSZSNXVsGqbcCd6dCXuVjNHIilm0+jedVheAN6BS/Tq99JcQ/pERU5s3M/J+4DBewgg+RbQ5K4onyyf8NQpnLU+XMZhQrnUGnZFXdtie5kKqXAKhTVqi8hEgC2QHdvtX89/EjgCyIkUtH0AAAAASUVORK5CYII=", "inverted": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAP8AAAABCAIAAACe8u/0AAAAq0lEQVQokXWSQQ6DMAwEp/9/Y9/QD5SdHuIEJ6gCWbvLYISd1+f7FiVRsekENakkYkxKJ2bZmHh1ca0kV4WZYVaNmcBto9M5WtZloqtqVIllm0aMqOGuQlRQwikEGSSOEITs1tmq3c0KnDw7xkbWIzayC5c9XuQfwAE8+nvw/vtu6X0CbH/nPi7bfGx2JpqRr9Om4jx8qby2Z2iLnZV723PJU4x9doZHyB3+APLS0HEVvfePAAAAAElFTkSuQmCC", @@ -219,6 +223,18 @@ def get_cached_colorbar_image(colormap_name, inverted=False): "normal": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAP8AAAABCAIAAACe8u/0AAAAvUlEQVQokW2Q0W3FMAwDSXm8ztH9F6jIfkhWlNcmgnFHEXAQfsdXnHMi4tQ0xon1vAPuVZBrwbUnm/kIWzjtYU4tyEoW7/Clp8LRP7AYh0/5kEGsQnOQh8MfgCBZAAZxuYEVAiQCLCD+GQwYhDFgwKWXawTYtiFDBXKxml1JyrJTlpwqUF7O4VRr+kdqTVWSnXywJGVaD0uS5AtSSvIVe4WexC91e2084vt207fZ3bXSbffdfa/v4fVh8zv0CzRYXG5OJkEEAAAAAElFTkSuQmCC", "inverted": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAP8AAAABCAIAAACe8u/0AAAAvUlEQVQokW2QQY7DMAwDSarX/dn+/zcme7DsCG2DQJ6RaMcI//4hsqQSJUkUVdLlBkl8Apwdsol8pmd0suQM8x4+k5pnnjvc72pcTCWJ1aDqysEqqYr1g3k7L11lqX/DZB0Vd0X1lSlCpIjLJBqAzSQ274rmoDXA1gBbf7xJAAMJgvjWwA1xcxJ4a/INaza9tQMrsXvaMd/84AG9cYPt2X/Un03bSRynyV+8/YHed3hgr+c5uj5W2+vIWl6tb9Q4Uct7Ls3FAAAAAElFTkSuQmCC", }, + "lisbon": { + "normal": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAP8AAAABCAIAAACe8u/0AAAAv0lEQVQokXWN240DMQwDSar/MpMuTN6HX9pFTjDs0YiQ+f1k2CMZtp1hN4jtBjNzoGVyM/8lnV+yJZ33j21hT9q57anxeu3sHfPN+mSZxLngZDE8pkFGbCx2PJAZ8ILFY3GCBeeEMBJgcgAzASaHBBECYAiQIENABEkSJERQJCGShESS0mx52wXUlBtEUk8vipKe05MXJb1H2zzaw+zy3nVZElVqRWmLurir+qyZarIkqaqtri5vq1LNTPMlqf4AXTRc4dgYTmkAAAAASUVORK5CYII=", + "inverted": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAP8AAAABCAIAAACe8u/0AAAAt0lEQVQokW2MQZLEIAwD1eL/D9zHYO0hOHFmhgKX1JIh+avaVbt2HVFVtfOQwffL5hOO+ey2eJEatZtmJsNmP+l75rYZ0cUfmy/Sdkap1CENnzRvflaU22ZaVZIolYpybiqKlJAokkKkiEQSERIByRECyYLIAuH3RRgsluzWlo/AS5grssXiirzA2DTBpqG9sI3xsg+xDR5nnfeB7rW2renOIBw+miwPyA/Y4szF/PZ3c/m70wL+AVF/dNRI9cmXAAAAAElFTkSuQmCC", + }, + "managua": { + "normal": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAP8AAAABCAIAAACe8u/0AAAAsElEQVQokXWNUW4FMQwCGS7b4/ZGph+2k129VymKAA2Y/P6kklJVWqRSK1KpFcPkbZvMA4tua+EaoeRjJw97unnMZvPLqBa49RVruztkZU+/k5q10beSJtvqq01UIVotEiWUlM5Fi4h51zpwcxyhI3BAcrAgWJuLDufF6GHlf4Qt4GVNd22wjDCNDdP8+x/s/GxlNCADyAf4sFt/JTa948eaZ+3k59y2NvzEvjI3MeYPUfEsdP/GMIoAAAAASUVORK5CYII=", + "inverted": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAP8AAAABCAIAAACe8u/0AAAAqklEQVQokXWM2w0DMRACYTtPtemCycf6ebpI1mrAgD9fSL9oAAokE94cXjIE8RqDRHD7OSoNl6MEnlIBjrWLs2+APK7IDEfbzypq+IEIlhR/gIi4u80LxJSYSDG0byLR4AZhsFrKZvuSTW2Qja0StsqyVJ583D/Stqpauiw/ecDpdMUD9j3AI1my5eru+Brdmtz+uVPecoXXyMxc3Tpmy6P42Fmx9qv9q/IDYtw/QqfIVtUAAAAASUVORK5CYII=", + }, + "berlin": { + "normal": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAP8AAAABCAIAAACe8u/0AAAAwElEQVQokW2Q0Q3EIAxDbbP/CjfDLYh9Hwm09Iqq6OXFRBX8fGPEiJN5gUvOxMhE3OCOZfOtZrNn7Nhe0DxtO46n00N7JjvYO2zHxl16Jo6P9Thke2TBurWniM+Lvn7f3knsnWVutTZgcZsYDmLGSOoVyyBBwhgIY66WqyVC5AJEABEyBNhcAHEZQEB5VYwPoPaU98rNIkkIFCmCLDg/aTRQlMRBSVQXShpLXOfRStI45TiT4230Jv9gNDz86/Qpf7dSTmRawDOQAAAAAElFTkSuQmCC", + "inverted": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAP8AAAABCAIAAACe8u/0AAAAvElEQVQokX2QUQ7DMAhDbXP/o+yIsfdRaNqtW1Shh3mhUpjXy7a9bC8v91n/w9/TR7DzFB4cP/kfpu9mt+ukzG9ytnGyEttOPr4kDpwYSQMSGMiNYSCAg6DzADe4aAFH7vxIAiQM6HYYMLwAFTAU2C2mBQkKIii0oCNhw64c5ndVtSBxQ0FiO0X1Bqou5jizYU9V14tjFmfDmEVJErlDqUhpWBRV6kFJ0kXd63BuYeG7srmBAqufqR2hNYFvAulCW3Q7HqMAAAAASUVORK5CYII=", + }, "lajolla": { "normal": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAP8AAAABCAIAAACe8u/0AAAArElEQVQokXWRUY5EIQgEq5pTzP0vuh+Co+/tJMY01YgKfj6ogrQAFVmw9QW9LJ/WkaNC8N8wAxfJT60SjIrxEFfIDjOud3i4bFgaePGLVPO9MznrnWxLiUbcbvcIQ6ZB04juhYEDdtE9g6zxLCEPuIb3zV93D7+TOcZwHX+m+So7K8ctd+X+dn/EGzqPl57o6k6mRyHRkGD87kVKQwrLFMYUFpYWv3SvjM6b/AE3AwLH88Pa5AAAAABJRU5ErkJggg==", "inverted": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAP8AAAABCAIAAACe8u/0AAAAqklEQVQokW2RWw7DMAzDuPsfbWeKuI84TrMGKAqZVl7yx3xhYHBoCbwQiw9y12ZgTPOQyYOZfxINRURNUKJKwAmnwIggRKd4QjEsrcIuKX9a+1pC70kOz8WWxynHtq9r5IBuXTdsMt/acH7R1aIScgawQpJgKq0S0fBsOR56df0jo8jJD6hn2WZPc5cusxJq+RrpRe/Z1rtXxq+yRrEFlZk94d3ir7XhnuEPk2frRoSfIrIAAAAASUVORK5CYII=", diff --git a/quickview/view_manager.py b/quickview/view_manager.py index 7b1b3ce..47cb713 100644 --- a/quickview/view_manager.py +++ b/quickview/view_manager.py @@ -1,7 +1,7 @@ import paraview.servermanager as sm from trame.widgets import paraview as pvWidgets -from trame.decorators import TrameApp, trigger +from trame.decorators import TrameApp, trigger, change from paraview.simple import ( Delete, @@ -198,9 +198,6 @@ def __init__(self, source: EAMVisSource, server, state): self.registry = ViewRegistry() # Central registry for view management self.to_delete = [] - # Register state change listener for pipeline_valid - self.state.change("pipeline_valid")(self._on_pipeline_valid_change) - def get_default_colormap(self): """Get default colormap from interface or fallback""" # Try to get from the server's interface instance @@ -209,9 +206,11 @@ def get_default_colormap(self): # Fallback to a reasonable default return "Cool to Warm (Extended)" - def _on_pipeline_valid_change(self, pipeline_valid, **kwargs): + @change("pipeline_valid") + def _on_change_pipeline_valid(self, pipeline_valid, **kwargs): """Clear view registry when pipeline becomes invalid.""" if not pipeline_valid: + print("Clearing registry") # Clear all views and variables from registry self.registry.clear() # Clear widgets and colors tracking diff --git a/src-tauri/Cargo.toml b/src-tauri/Cargo.toml index dbb3d94..d997f71 100644 --- a/src-tauri/Cargo.toml +++ b/src-tauri/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "app" -version = "0.1.20" +version = "0.1.21" description = "QuickView: Visual Analyis for E3SM Atmosphere Data" authors = ["Kitware"] license = "" diff --git a/src-tauri/tauri.conf.json b/src-tauri/tauri.conf.json index df49b04..68b460a 100644 --- a/src-tauri/tauri.conf.json +++ b/src-tauri/tauri.conf.json @@ -7,7 +7,7 @@ }, "package": { "productName": "QuickView", - "version": "0.1.20" + "version": "0.1.21" }, "tauri": { "allowlist": {