From 261e0c379417d40f4ebcf37ac80e34c3403614da Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Fri, 22 Aug 2025 11:40:56 -0700 Subject: [PATCH 01/28] docs: variable selection --- docs/README.md | 24 +++++-- docs/images/control-panel.png | 3 - docs/images/slice_selection.png | 3 + docs/images/variable-select.png | 3 - docs/images/variable_selection.png | 3 + docs/userguide/control_panel.md | 102 +++++++++++++++++++++++------ 6 files changed, 106 insertions(+), 32 deletions(-) delete mode 100644 docs/images/control-panel.png create mode 100644 docs/images/slice_selection.png delete mode 100644 docs/images/variable-select.png create mode 100644 docs/images/variable_selection.png diff --git a/docs/README.md b/docs/README.md index 966b504..841af09 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,19 +1,28 @@ # QuickView Homepage + ![eam-quickview-full](../images/eam-quickview-full.png) + ## What is QuickView? +!!! info inline end "Useful links" + + - [Repository](https://github.com/ayenpure/QuickView) on GitHub + - [Releases page](https://github.com/ayenpure/QuickView/releases/tag/v0.1.14) + - [Latest documentation](https://quickview.readthedocs.io/en/latest/) + - [Quick start](https://github.com/ayenpure/QuickView?tab=readme-ov-file#quick-start) + - Connecitivity file [download](https://zenodo.org/records/16908567) + - Sample data [download](https://zenodo.org/records/16922608) + -**EAM QuickView** is an interactive visualization tool +**EAM QuickView** is an open-source, 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)). +[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 +powered by [Trame](https://www.kitware.com/trame/) gives users an intuitive +access to the powerful analysis and visualization capabilities of [ParaView](https://www.paraview.org/) without requiring a steep learning curve. @@ -49,6 +58,7 @@ multivariate visualization and is currently focused on the EAM model. - 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 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/slice_selection.png b/docs/images/slice_selection.png new file mode 100644 index 0000000..d4bc7d5 --- /dev/null +++ b/docs/images/slice_selection.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:640d310a6035d91565241652fc7fe5b6723c605b3094d0a3e55879cd3648e7c7 +size 146743 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/variable_selection.png b/docs/images/variable_selection.png new file mode 100644 index 0000000..9cac7ae --- /dev/null +++ b/docs/images/variable_selection.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8beffaed5dbff699f5730d3a619a1f4d48abbd3669611486184609cc2c461c15 +size 164055 diff --git a/docs/userguide/control_panel.md b/docs/userguide/control_panel.md index 264b3a8..ec8edbe 100644 --- a/docs/userguide/control_panel.md +++ b/docs/userguide/control_panel.md @@ -1,13 +1,85 @@ -## The Control Panel -![control-panel](../images/control-panel.png){ width="400" } +!!! info 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 +# Control Panel + +The control panel allows users to select variables from the data file +as well the spatial and temporal ranges of data to visualize, +as explained below. + + +----- +## Variable selection + +![variable selection sections](../images/variable_selection.png){ width="300", align=right } + + +### Variable categories + +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. + +These three categories of variables 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 + +!!! tip 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. 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 + + +The data slice selection allows users to slice and dice data spatio-temporally for analysis - a. It allows data slice selection along the dimensions of time, middle and @@ -19,19 +91,11 @@ into three main parts 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 +----- +## Map Projection + +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. -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. From 3d410996365f8f527ca129a76e30a9c279640e73 Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Fri, 22 Aug 2025 13:04:20 -0700 Subject: [PATCH 02/28] docs: slice selection and map projection --- docs/images/map_projection.png | 3 +++ docs/images/slice_selection.png | 4 ++-- docs/userguide/control_panel.md | 36 ++++++++++++++++++--------------- 3 files changed, 25 insertions(+), 18 deletions(-) create mode 100644 docs/images/map_projection.png diff --git a/docs/images/map_projection.png b/docs/images/map_projection.png new file mode 100644 index 0000000..d355d61 --- /dev/null +++ b/docs/images/map_projection.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8ae1520cf7c395565828590ab377e98fe701c9e84d91fde8e07991ffd7847526 +size 72963 diff --git a/docs/images/slice_selection.png b/docs/images/slice_selection.png index d4bc7d5..86dd315 100644 --- a/docs/images/slice_selection.png +++ b/docs/images/slice_selection.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:640d310a6035d91565241652fc7fe5b6723c605b3094d0a3e55879cd3648e7c7 -size 146743 +oid sha256:c61e264ac46247302ec1a5a08d6f732a4b52b4060f7bf144ebe6a75d2fa52f69 +size 100136 diff --git a/docs/userguide/control_panel.md b/docs/userguide/control_panel.md index ec8edbe..09d3e8a 100644 --- a/docs/userguide/control_panel.md +++ b/docs/userguide/control_panel.md @@ -1,5 +1,5 @@ -!!! info inline end "Tip" +!!! tip inline end "Tip" 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 @@ -38,7 +38,7 @@ but can be supported upon request ### Select and load -!!! tip inline end "The `LOAD VARIABLE` button" +!!! 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 @@ -76,26 +76,30 @@ in order for these changes to take effect.* ----- -## Data slice +## Data slice selection +![variable selection sections](../images/slice_selection.png){ width="300", align=right } -The data slice selection allows users to slice and - dice data spatio-temporally for analysis +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. - - 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. +For the vertical dimensions and the time dimension, the control panel +also provides buttons for moving to (displaying) the previous or next element +in a dimension, as well as "play" buttons for cycling over these dimensions. +If the user clicks on a second "play" button when the app is cycling through +a first dimension, the the cycling through the first dimension will be paused. - 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. ----- ## Map Projection -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 sections](../images/map_projection.png){ width="300", 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, and we plan to allow +the user to choose the center longitude of the map in the near future. From fbd88e75dae0847c9ac17c7bc5ff8a8dae2edc68 Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Fri, 22 Aug 2025 16:45:33 -0700 Subject: [PATCH 03/28] docs: viewport description --- docs/future.md | 15 +++-- docs/images/camera_widget.png | 3 + docs/images/colorbar_hover_over.png | 3 + docs/images/cvd.png | 3 + docs/images/four_views.png | 3 + docs/images/gear_menu_range_auto.png | 3 + docs/images/gear_menu_range_manual.png | 3 + docs/images/six_variables_default.png | 3 - docs/userguide/gui_overview.md | 9 ++- docs/userguide/viewport.md | 87 ++++++++++++++++++++------ mkdocs.yml | 1 - 11 files changed, 98 insertions(+), 35 deletions(-) create mode 100644 docs/images/camera_widget.png create mode 100644 docs/images/colorbar_hover_over.png create mode 100644 docs/images/cvd.png create mode 100644 docs/images/four_views.png create mode 100644 docs/images/gear_menu_range_auto.png create mode 100644 docs/images/gear_menu_range_manual.png delete mode 100644 docs/images/six_variables_default.png diff --git a/docs/future.md b/docs/future.md index 84a97b4..487df49 100644 --- a/docs/future.md +++ b/docs/future.md @@ -1,11 +1,14 @@ # Planned Improvements -Below is a list of improvements that are being worked on or have been planned. +For the upcoming releases, we plan to prioritize the following: + +- adding support for server-client model and deploying servers to + Department of Energy's Leadership Computing Facilities; +- addressing the display issues that currently need a camera reset + as a remedy (see the [Reminders page](reminders.md); +- providing the functionality of allowing the user to specify + a center longitude for the contour plots. + Addional suggestions are welcome. Bug reports and feature requests can be made by opening new [issues](https://github.com/ayenpure/QuickView/issues) on GitHub. - - -1. Server-client model and deployment of servers to Department of Energy's Leadership Computing Facilities. - -1. diff --git a/docs/images/camera_widget.png b/docs/images/camera_widget.png new file mode 100644 index 0000000..fbd0fcb --- /dev/null +++ b/docs/images/camera_widget.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:47a685909c7094706286062bf36312c2e6795a8fdf0c2f3e8093b3b1433ecdf9 +size 10171 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/cvd.png b/docs/images/cvd.png new file mode 100644 index 0000000..218344a --- /dev/null +++ b/docs/images/cvd.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3f257eeb77b4a9f62c496a05a79ad57568c9a1fafbf15f0bca0f1845d6a0791a +size 7598 diff --git a/docs/images/four_views.png b/docs/images/four_views.png new file mode 100644 index 0000000..2f8d236 --- /dev/null +++ b/docs/images/four_views.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a35f88a1f2e544ccd0e47bb65fe36e98fd41dcb4899a534065a16da8bcb7d6e0 +size 2621058 diff --git a/docs/images/gear_menu_range_auto.png b/docs/images/gear_menu_range_auto.png new file mode 100644 index 0000000..7f36ec5 --- /dev/null +++ b/docs/images/gear_menu_range_auto.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:655b4ff09f900995b3f3a64a8f2dbb9e5da70d39e22d403192c82e5e413947d6 +size 955625 diff --git a/docs/images/gear_menu_range_manual.png b/docs/images/gear_menu_range_manual.png new file mode 100644 index 0000000..1d71845 --- /dev/null +++ b/docs/images/gear_menu_range_manual.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d6c758bf88c9906ca35c8b2b3eec9b41d5eb8bff1371e7fafefe78225982f063 +size 959885 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/userguide/gui_overview.md b/docs/userguide/gui_overview.md index a839c9e..1085d16 100644 --- a/docs/userguide/gui_overview.md +++ b/docs/userguide/gui_overview.md @@ -1,6 +1,6 @@ # 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 @@ -16,11 +16,10 @@ Detailed descriptions can be found on the linked pages. on the left end of the [toolbar](toolbar.md). 3. The [viewport](view_port.md) displays one or more variables for - the user. For each variable, the colormap, contour level etc. + 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 + The viewport also contains a camera widget in its bottom-right + corner, which can be used to centrally adjusting all views in the viewport, i.e., zooming in or out, or moving the displayed images with respect to the GUI. diff --git a/docs/userguide/viewport.md b/docs/userguide/viewport.md index a49b841..2d04ee1 100644 --- a/docs/userguide/viewport.md +++ b/docs/userguide/viewport.md @@ -1,19 +1,26 @@ # Viewport +![Four views](../images/four_views.png){ width="65%", 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 +will show each variable in its own little frame (which we refer to as a "view") inside the viewport. Below is an example showing six 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. +At the top of each view, +the indices of the vertical level (if applicable) and time slice being displayed +are shown in the top-left corner of each view. +The variable name is shown in the top-right corner +together with 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 +![Six views resized and rearranged](../images/six_variables_rearranged.png){ width="65%", 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 @@ -22,28 +29,68 @@ rearranged views. Furthermore, if a user saves a state file after these adjustments, they can later resume their analysis with the customized arrangement. -![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 range of values in the data. -![Mini menu for custimizing a view](../images/mini-menu.png){width="400"} +![gear menu with auto range](../images/gear_menu_range_auto.png){ width="48%"} +![gear menu with manual range](../images/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 max. and min. values can be found + in the mini menu, as seen in the left example above. + When the "play" button in the [control panel](control_panel.md) is used to cycle + through different data slices in a dimension, + the colormap will be automatically adjusted for each data slice. + + If the user enters min./max. values in the mini menu and hit the `return` key + on the key board, a blue icon with a lock and the text "Manual" will show up + above the text box for the max. value, as can be seen in the right example above. + After that, when the "play" button in the [control panel](control_panel.md) + is used to cycle through different data slices in a dimension, + the colormap will be fixed for the user-specified range. + + +!!! tip "Tip: Field Value Lookup in Colorbar" + + ![colorbar hover over](../images/colorbar_hover_over.png){ width="55%", align=right } -- 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. + 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" + + 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. + +--- +## Camera widget + + +![camera widget](../images/camera_widget.png){ width="40%", align=right } 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. +the displayed variable within each view can also be adjusted. +These settings are controlled centrally—for all +views—via the camera widge (see screenshot) located in the bottom-right +corner of the viewport. + +Also recall that the camera refresh button located at the right end of the +tool bar can be used to reset the size and location of all views +to the default setting. + diff --git a/mkdocs.yml b/mkdocs.yml index 40d3c8e..3e68a40 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -16,7 +16,6 @@ nav: - 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 From ad964a8c8a227eed13b4ffc533dcafd6498ac81e Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Sat, 23 Aug 2025 06:34:32 -0700 Subject: [PATCH 04/28] docs: README pages and plans page --- README.md | 14 ++++++++----- docs/README.md | 56 ++++++++++++++++++++++---------------------------- docs/future.md | 11 ++++++---- 3 files changed, 41 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index e1aa3b2..5781d8b 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ 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) @@ -32,11 +32,15 @@ gives users intuitive access to the powerful visualization capabilities of 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 841af09..91279d1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,11 +9,11 @@ !!! info inline end "Useful links" - [Repository](https://github.com/ayenpure/QuickView) on GitHub - - [Releases page](https://github.com/ayenpure/QuickView/releases/tag/v0.1.14) - - [Latest documentation](https://quickview.readthedocs.io/en/latest/) + - [Releases](https://github.com/ayenpure/QuickView/releases) + - [Documentation](https://quickview.readthedocs.io/en/latest/) - [Quick start](https://github.com/ayenpure/QuickView?tab=readme-ov-file#quick-start) - - Connecitivity file [download](https://zenodo.org/records/16908567) - - Sample data [download](https://zenodo.org/records/16922608) + - [Connecitivity file download](https://zenodo.org/records/16908567) + - [Sample data download](https://zenodo.org/records/16922608) **EAM QuickView** is an open-source, interactive visualization tool @@ -28,57 +28,51 @@ without requiring a steep learning curve. ## 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. +- Intuitive, 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) +- Support for EAM simulation data from current (EAMv2, v3) and upcoming (v4) versions. - -## Further Reading +## Bug reports and feature requests -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. +Please use the [Issues tab on GitHub](https://github.com/ayenpure/QuickView/issues). -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) - -For information about data file requirements and supported formats, see the -[data requirements documentation](data-requirements.md) - -## Point of Contact +## Points of Contact 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 487df49..c92d76b 100644 --- a/docs/future.md +++ b/docs/future.md @@ -2,12 +2,15 @@ For the upcoming releases, we plan to prioritize the following: -- adding support for server-client model and deploying servers to +- adding support for the server-client model and deploying servers 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 reset - as a remedy (see the [Reminders page](reminders.md); -- providing the functionality of allowing the user to specify - a center longitude for the contour plots. + as a remedy (see the [Reminders page](userguide/reminders.md); +- allowing the user to specify a center longitude for the contour plots. Addional suggestions are welcome. Bug reports and feature requests can be made by opening new From 345b5e816528250e5f7e81ac4180b5be611df93f Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Sat, 23 Aug 2025 06:35:36 -0700 Subject: [PATCH 05/28] docs: minor edit in doc homepage --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 91279d1..7752c9d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -65,7 +65,7 @@ multivariate visualization and is currently focused on the EAM model. Please use the [Issues tab on GitHub](https://github.com/ayenpure/QuickView/issues). -## Points of Contact +## Project Background The lead developer of EAM QuickView is [Abhishek Yenpure (abhi.yenpure@kitware.com)](https://www.kitware.com/abhishek-yenpure/) From e5e07ea5750f497bac31eb7c229834b396968a68 Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Sat, 23 Aug 2025 08:49:45 -0700 Subject: [PATCH 06/28] docs: revise and clean up pages on install and launch --- docs/setup/for_app_developers.md | 16 ++++++---- docs/setup/for_end_users.md | 53 ++++++++++++++++++++++++++------ docs/setup/requirements.md | 44 -------------------------- mkdocs.yml | 2 +- 4 files changed, 55 insertions(+), 60 deletions(-) delete mode 100644 docs/setup/requirements.md diff --git a/docs/setup/for_app_developers.md b/docs/setup/for_app_developers.md index 8d9654d..217509f 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 files. -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. We plan to add support for +more systems 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..ccbb9df 100644 --- a/docs/setup/for_end_users.md +++ b/docs/setup/for_end_users.md @@ -1,23 +1,58 @@ -# 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 files. -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. We plan to add support for +more systems 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, we provide pre-built binaries that can be installed using +just a few clicks. -1. Download the latest installer from the [releases page](https://github.com/ayenpure/QuickView/releases/tag/v0.1.13). Mac users with Apple Silicon chips should download `QuickView_{version}_aarch64.dmg`, and those with Intel chips should download a `*_x64.dmg` file. -2. Double-click the downloaded `.dmg` file. In the pop-up window, drag the QuickView icon into the Applications folder. +1. Download the latest binary from the + [releases page](https://github.com/ayenpure/QuickView/releases/). + macOS users with Apple Silicon chips should download `QuickView_{version}_aarch64.dmg`, + and those with Intel chips should download a `*_x64.dmg` file. +2. **Important** for intermediate releases with 3-digit version numbers + (e.g., 1.0.1): 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, only major releases with + two-digit version numbers like 1.0, 1.1 etc. are signed and notarized using + Kitware's Apple Developer ID. + Hence the command provided above is needed for intermediate releases, + 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 Need to Worry about Dependencies" + + The pre-built binaries include all dependencies needed to start the app + on a local computer. Additional dependencies needed for data processing + and visualization are downloaded and installed automatically when the app is launched for the first time. --- # Launch To launch the EAM QuickView GUI, simply double-click the app icon in your Applications folder. + +!!! tip "Tip: Patience with First launch" + + When a new version of the app is launched on your computer for the + first time, a significant amount of dependencies will be identified, + downloaded, and installed, which will take about a minute to a few minutes. + + Subsequent launches should take just 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/mkdocs.yml b/mkdocs.yml index 3e68a40..0beae44 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,7 +5,7 @@ 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: From 917a684fe35bb5cc2ca073f78dcdc55ccc37e2b7 Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Sat, 23 Aug 2025 15:52:03 -0700 Subject: [PATCH 07/28] docs: data requirement and misc --- docs/README.md | 52 +++-- docs/images/eam-quickview-full.png | 3 - docs/images/eam_quickview_full.png | 3 + docs/userguide/connectivity.md | 19 +- docs/userguide/control_panel.md | 3 +- docs/userguide/data_requirements.md | 263 +++++++++--------------- docs/userguide/old_data_requirements.md | 185 +++++++++++++++++ docs/userguide/reminders.md | 34 +-- mkdocs.yml | 7 +- 9 files changed, 357 insertions(+), 212 deletions(-) delete mode 100644 docs/images/eam-quickview-full.png create mode 100644 docs/images/eam_quickview_full.png create mode 100644 docs/userguide/old_data_requirements.md diff --git a/docs/README.md b/docs/README.md index 7752c9d..3e0abf2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,20 +1,19 @@ # QuickView Homepage -![eam-quickview-full](../images/eam-quickview-full.png) +!!! info inline end "Useful Links" - -## What is QuickView? - -!!! info inline end "Useful links" - - - [Repository](https://github.com/ayenpure/QuickView) on GitHub - - [Releases](https://github.com/ayenpure/QuickView/releases) + - [Releases (binary download)](https://github.com/ayenpure/QuickView/releases) + - [Quick start](#Quick-Start) - [Documentation](https://quickview.readthedocs.io/en/latest/) - - [Quick start](https://github.com/ayenpure/QuickView?tab=readme-ov-file#quick-start) - [Connecitivity file download](https://zenodo.org/records/16908567) - [Sample data download](https://zenodo.org/records/16922608) + - [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%" } + +## What is QuickView? **EAM QuickView** is an open-source, interactive visualization tool tailored for scientists working with the atmospheric component of the @@ -26,6 +25,29 @@ access to the powerful analysis and visualization capabilities of [ParaView](https://www.paraview.org/) without requiring a 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.16908567) + of EAM's cubed-sphere grids from Zenodo. +- Optional: download [sample simulation output](https://zenodo.org/records/16922608) + to test the app. +- For EAMv2 and v3 developers and users: if your simulation data files + are *not* the original files written out by the model, + i.e., if your files were generated by NCO, CDO, etc. + check QuickView's [data format requirements](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 visualization tools like @@ -55,16 +77,18 @@ multivariate visualization and is currently focused on the EAM model. ## Key Features -- Intuitive, minimalist user interface tailored for atmosphere modeling workflows. -- Push-button visualization of multiple variables. -- Persistent state: "Pick up where you left off". -- Support for EAM simulation data from current (EAMv2, v3) and upcoming (v4) - versions. +- 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. + +--- ## Bug reports and feature requests Please use the [Issues tab on GitHub](https://github.com/ayenpure/QuickView/issues). +--- ## Project Background The lead developer of EAM QuickView is 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..4a3ea20 --- /dev/null +++ b/docs/images/eam_quickview_full.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:822e2dd0651f6d21a4822c43dd22c41933dc181c2e4360614e2984e9b15fb5a3 +size 2998402 diff --git a/docs/userguide/connectivity.md b/docs/userguide/connectivity.md index 5ca64ea..2e8daf3 100644 --- a/docs/userguide/connectivity.md +++ b/docs/userguide/connectivity.md @@ -1,26 +1,30 @@ # 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.16908567). + The archive is continuously 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 [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 +e.g., 4, 30, 120, or 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 `neXnp4` grids. -## Generation +## Generate connectivity files Users can also generate connectivity files with [`TempestRemap`](https://github.com/ClimateGlobalChange/tempestremap) ( @@ -33,3 +37,4 @@ it can also be installed following the instructions from the [TempestRemap repo](https://github.com/ClimateGlobalChange/tempestremap). EAM QuickView uses the SCRIP format of the connectivity files. + diff --git a/docs/userguide/control_panel.md b/docs/userguide/control_panel.md index 09d3e8a..a56bfcd 100644 --- a/docs/userguide/control_panel.md +++ b/docs/userguide/control_panel.md @@ -88,7 +88,8 @@ 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 a dimension, as well as "play" buttons for cycling over these dimensions. +in a 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, the the cycling through the first dimension will be paused. diff --git a/docs/userguide/data_requirements.md b/docs/userguide/data_requirements.md index bb08878..e464a76 100644 --- a/docs/userguide/data_requirements.md +++ b/docs/userguide/data_requirements.md @@ -1,185 +1,106 @@ -# 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/16922608). + +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 you have clicked on the `Load Files` button in the + [toolbar](toolbar.md) but the status icon next to it continues to show + a red circle with an exclamation mark, 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 you run into such a case, please reach out to our lead developer + [(abhi.yenpure@kitware.com)](https://www.kitware.com/abhishek-yenpure/) + or use the [Issue tab on GitHub](https://github.com/ayenpure/QuickView/issues). + +---- +## 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 that 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 +in 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) ``` -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 P0 = 1000 hPa and PS0 = 1000 Pa. -### 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 visualize the types of variables discussed above. +For variables that have extra dimensions in addition to `time`, `ncol`, +and `lev` or `ilev`, for example different tracers or +[COSP](https://climatedataguide.ucar.edu/climate-data/cosp-cloud-feedback-model-intercomparison-project-cfmip-observation-simulator-package)-related +dimensions, +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 provided 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/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..972e5d7 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). @@ -20,26 +20,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` + 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 + an informative way. Users can ^^rearrange^^ the individual views + (i.e., global or regional maps of different variables) in the + [viewport](viewport.md) ^^via drag-and-drop^^, + and ^^resize^^ each view separately ^^by clicking and dragging + its bottom-right corner^^. + + + Furthermore, if a user saves a state file after these adjustments, they can later resume their analysis with the customized arrangement. !!! warning "Trick: Camera Refresh" In the current version, after the `LOAD VARIABLES` button is clicked or - a visualization settings is changed, some (or all) of + a visualization setting is changed, some (or all) of the images in the [viewport](viewport.md) might exhibit a display issue, e.g., erroneously showing the same color or a few color stripes over the entire - globe or region. This can be remedied by clicking the camera refresh - button at the right end of the [toolbar](toolbar.md), and we are hoping to - resolve the issue for future versions. - + globe or region. This can be remedied by clicking the camera reset + button at the right end of the [toolbar](toolbar.md), and we are working on + resolving the issue for future versions. + diff --git a/mkdocs.yml b/mkdocs.yml index 0beae44..6ca1949 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,7 +11,7 @@ nav: - 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 @@ -24,3 +24,8 @@ markdown_extensions: - pymdownx.superfences - md_in_html - pymdownx.blocks.caption + - pymdownx.critic + - pymdownx.caret + - pymdownx.keys + - pymdownx.mark + - pymdownx.tilde From f99ae673897309acb3ed0df9f30be1ee84bc69b9 Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Sat, 23 Aug 2025 16:43:44 -0700 Subject: [PATCH 08/28] docs: add back pointer to Mark's script --- docs/README.md | 4 ++-- docs/userguide/connectivity.md | 29 +++++++++++++++++++++-------- 2 files changed, 23 insertions(+), 10 deletions(-) diff --git a/docs/README.md b/docs/README.md index 3e0abf2..d89726c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,14 +4,14 @@ !!! info inline end "Useful Links" - [Releases (binary download)](https://github.com/ayenpure/QuickView/releases) - - [Quick start](#Quick-Start) + - Quick start (see this page) - [Documentation](https://quickview.readthedocs.io/en/latest/) - [Connecitivity file download](https://zenodo.org/records/16908567) - [Sample data download](https://zenodo.org/records/16922608) - [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 screenshot](images/eam_quickview_full.png){ width="62%" } ## What is QuickView? diff --git a/docs/userguide/connectivity.md b/docs/userguide/connectivity.md index 2e8daf3..b3c65ce 100644 --- a/docs/userguide/connectivity.md +++ b/docs/userguide/connectivity.md @@ -15,14 +15,14 @@ for each simulation data file, a "connectivity file" needs to be provided. In EAMv2, v3, and v4, most of the variables (physical quantities) are archived on the "physics grid" described in [Hannah et al. (2021)](https://doi.org/10.1029/2020MS002419). -The naming convention for such grids is `neXpg2`, with `X` being a number, +The naming convention for such grids is `ne*pg2`, with `*` being a number, e.g., 4, 30, 120, or 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). Future versions of QuickView will also support the cubed-sphere meshes -used by EAM's dynamical core, i.e., the `neXnp4` grids. +used by EAM's dynamical core, i.e., the `ne*np4` grids. ## Generate connectivity files @@ -30,11 +30,24 @@ Users can also generate connectivity files with [`TempestRemap`](https://github.com/ClimateGlobalChange/tempestremap) ( [Ullrich and Taylor, 2015](https://doi.org/10.1175/MWR-D-14-00343.1); [Ullrich et al., 2016](https://doi.org/10.1175/MWR-D-15-0301.1)) -using commands documented [here](https://e3sm.atlassian.net/wiki/spaces/DOC/pages/872579110/Running+E3SM+on+New+Atmosphere+Grids#2A.-Generate-control-volume-mesh-files-for-E3SM-v2-%22pg2%22-grids). -`TempestRemap` it is available as a part of the -[`E3SM-Unified`](https://github.com/E3SM-Project/e3sm-unified) conda environment; -it can also be installed following the instructions from the -[TempestRemap repo](https://github.com/ClimateGlobalChange/tempestremap). +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 at +[https://github.com/ClimateGlobalChange/tempestremap](https://github.com/ClimateGlobalChange/tempestremap).) -EAM QuickView uses the SCRIP format of the connectivity files. +For example, 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. From cdb826a27e2523633f17ae280e049dd9fcef3fb7 Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Sun, 24 Aug 2025 08:14:06 -0700 Subject: [PATCH 09/28] docs: update all-version DOI's for Zenodo archives --- README.md | 4 ++-- docs/README.md | 8 ++++---- docs/setup/for_end_users.md | 4 ++-- docs/userguide/connectivity.md | 2 +- docs/userguide/data_requirements.md | 2 +- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 5781d8b..e25e4be 100644 --- a/README.md +++ b/README.md @@ -24,8 +24,8 @@ gives users intuitive access to the powerful visualization capabilities of - Install and launch the app for [end users](docs/setup/for_end_users.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, diff --git a/docs/README.md b/docs/README.md index d89726c..392e256 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,8 +6,8 @@ - [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/16908567) - - [Sample data download](https://zenodo.org/records/16922608) + - [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) @@ -30,9 +30,9 @@ without requiring a steep learning curve. - 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.16908567) +- 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/16922608) +- 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, diff --git a/docs/setup/for_end_users.md b/docs/setup/for_end_users.md index ccbb9df..0bf3114 100644 --- a/docs/setup/for_end_users.md +++ b/docs/setup/for_end_users.md @@ -20,7 +20,7 @@ just a few clicks. macOS users with Apple Silicon chips should download `QuickView_{version}_aarch64.dmg`, and those with Intel chips should download a `*_x64.dmg` file. -2. **Important** for intermediate releases with 3-digit version numbers +2. **Important** for intermediate releases with three-part version numbers (e.g., 1.0.1): After the download, use the following command in Terminal to unblock the app for macOS: ``` @@ -28,7 +28,7 @@ just a few clicks. ``` Explanation: in order to facilitate frequent iterations between our developers on the software and science sides, only major releases with - two-digit version numbers like 1.0, 1.1 etc. are signed and notarized using + two-part version numbers like 1.0, 1.1 etc. are signed and notarized using Kitware's Apple Developer ID. Hence the command provided above is needed for intermediate releases, so that after download, the macOS Gatekeeper will not block the app. diff --git a/docs/userguide/connectivity.md b/docs/userguide/connectivity.md index b3c65ce..76f3a52 100644 --- a/docs/userguide/connectivity.md +++ b/docs/userguide/connectivity.md @@ -4,7 +4,7 @@ !!! tip inline end "Tip: Connecitivity File Download" A collection of connectivity files can be found on - [Zenodo](https://doi.org/10.5281/zenodo.16908567). + [Zenodo](https://doi.org/10.5281/zenodo.16908566). The archive is continuously updated as more users inform us about the grids their data files use. diff --git a/docs/userguide/data_requirements.md b/docs/userguide/data_requirements.md index e464a76..199868b 100644 --- a/docs/userguide/data_requirements.md +++ b/docs/userguide/data_requirements.md @@ -3,7 +3,7 @@ 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/16922608). +[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 From 0349513fff22a6065db1d23752d1f41ace3ee31c Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Sun, 24 Aug 2025 13:44:08 -0700 Subject: [PATCH 10/28] docs: partial revision of toolbar page --- docs/images/toolbar.png | 4 +- docs/images/toolbar_busy_indicator.png | 3 + docs/images/toolbar_colormap_groups.png | 3 + docs/images/toolbar_conn_and_data_load.png | 4 +- docs/images/toolbar_hamburger.png | 3 + docs/images/toolbar_load_variables.png | 3 + docs/images/toolbar_misc.png | 3 - docs/images/toolbar_state_save_and_load.png | 4 +- docs/userguide/toolbar.md | 133 +++++++++++++------- 9 files changed, 108 insertions(+), 52 deletions(-) create mode 100644 docs/images/toolbar_busy_indicator.png create mode 100644 docs/images/toolbar_colormap_groups.png create mode 100644 docs/images/toolbar_hamburger.png create mode 100644 docs/images/toolbar_load_variables.png delete mode 100644 docs/images/toolbar_misc.png diff --git a/docs/images/toolbar.png b/docs/images/toolbar.png index 65f6027..a540202 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:1d8965b7d3a09ea439af7b17c1b0481d59a1110de5f9fd9665d620ba60750688 +size 43320 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_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..ffbe3c7 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:a5b07f6cff1850286163c40a54d6e7176997231cfa5b9ac0ebadafac7d0d1b94 +size 17827 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/userguide/toolbar.md b/docs/userguide/toolbar.md index 0efa1d9..d76b9d3 100644 --- a/docs/userguide/toolbar.md +++ b/docs/userguide/toolbar.md @@ -12,71 +12,118 @@ then introduce the other elements. ---- ## New-viz mode: starting a new visualization -![connectivity and data file buttons](../images/toolbar_conn_and_data_load.png) To start a new analysis/visualization, the user needs to specify a [connecitivy file](connectivity.md) and a [simulation data file](data_requirements.md) using -the portion of the toolbar shown above, by either typing +the 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, +![connectivity and data file buttons](../images/toolbar_conn_and_data_load.png){ width="59%", align=right } + +After both files have been specified, the `Load Files` button +(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 move on to 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: - -- 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). +!!! warning "Tip: File Loading Error" + + After the `Load Files` button is clicked, + if the circle-shaped busy indicator on the left side of the toolbar + does not start spinning in a second or two, and the red circle with an + exclamation mark shown above persists, + then the variable dimensions in the data file + have not been parsed correctly. Possible reasons for the error are: + + - The data file and connectivity file correspond to different cubed-sphere + meshes. E.g., one is ne30pg2 and the other is ne4pg2. + - The data file is missing some of the coordinate variables needed by the + app, or the dimensions are named or ordered in ways not yet known by + the app, see [data format requirements](data_requirements.md). ---- ## Resume mode: pick up where you left off -![state save and load](../images/toolbar_state_save_and_load.png) +![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 will bring up a windew for +the user to select a state file from the file system. After the file +is selected and the `Open` button is clicked, the app will immediately +start loading the state. If successful, the icon of a red circle with +an exclamation mark will turn to a green circle with a check mark, +like in the new-viz mode. Loading a state for an ne30 simulation +usually takes a second or two. + +!!! info "Info: What is 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 user passes a state file to another user or file system, + or if they want to use the same visualization settings but for + 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. ---- ## 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" + + +![toolbar misc](../images/toolbar_hamburger.png){ width="6%", align=right } + +**Control Panel Hide/Show**: +The hamburger icon (three stacked lines) hides or shows the [control panel](control_panel.md). + + + +![toolbar misc](../images/toolbar_busy_indicator.png){ width="5%", align=right } + +**Busy Indicator**: +The gray circle is a busy indicator. When a rotating segment is shown, +the app is processing data in the background (e.g., loading data files or +a state file (see earlier sections on this page), +updating loading newly selected variables (see [control panel](control_panel.md)), +etc. + + +![toolbar misc](../images/toolbar_load_variables.png){ width="18%", align=right } + +**`LOAD VARIABLES` Button** +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). + + +![toolbar misc](../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 mostly "presets" +taken from [PareView](https://www.paraview.org/). + + +**Camera Reset** +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"). + +!!! warning "Tip on Camera Refresh" As mentioned on the [Reminders](reminders.md) page, the app may exhibit display issue after new variable selection or setting changes have been made. From 7b5d2c0e74e6ebb326c1ea6394f3d2726d089dfe Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Sun, 24 Aug 2025 15:41:08 -0700 Subject: [PATCH 11/28] docs: further revise toolbar description --- docs/images/camera_actions.png | 3 ++ docs/images/camera_widget.png | 3 -- docs/images/toolbar_camera_actions.png | 3 ++ docs/userguide/toolbar.md | 69 ++++++++++++++++---------- 4 files changed, 50 insertions(+), 28 deletions(-) create mode 100644 docs/images/camera_actions.png delete mode 100644 docs/images/camera_widget.png create mode 100644 docs/images/toolbar_camera_actions.png diff --git a/docs/images/camera_actions.png b/docs/images/camera_actions.png new file mode 100644 index 0000000..d7492f9 --- /dev/null +++ b/docs/images/camera_actions.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:451f71a27566c5fee2196deba7067467bde77fdbe5eb0e39ad7ff38086e7b926 +size 8454 diff --git a/docs/images/camera_widget.png b/docs/images/camera_widget.png deleted file mode 100644 index fbd0fcb..0000000 --- a/docs/images/camera_widget.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:47a685909c7094706286062bf36312c2e6795a8fdf0c2f3e8093b3b1433ecdf9 -size 10171 diff --git a/docs/images/toolbar_camera_actions.png b/docs/images/toolbar_camera_actions.png new file mode 100644 index 0000000..a540202 --- /dev/null +++ b/docs/images/toolbar_camera_actions.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1d8965b7d3a09ea439af7b17c1b0481d59a1110de5f9fd9665d620ba60750688 +size 43320 diff --git a/docs/userguide/toolbar.md b/docs/userguide/toolbar.md index d76b9d3..c77d9c6 100644 --- a/docs/userguide/toolbar.md +++ b/docs/userguide/toolbar.md @@ -3,9 +3,10 @@ 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 the images +displayed in the [viewport](viewport.md)). +In the following, we first explain in detail the elements that support the two modes of usage of the app, new-viz and resume, and then introduce the other elements. @@ -29,17 +30,15 @@ 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 [control panel](control_panel.md) to select +The user can then start using the [control panel](control_panel.md) to select variables and spatial/temporal slices to display. -!!! warning "Tip: File Loading Error" +!!! warning "Tip: Simulation File Loading Error" After the `Load Files` button is clicked, - if the circle-shaped busy indicator on the left side of the toolbar - does not start spinning in a second or two, and the red circle with an - exclamation mark shown above persists, + if the red circle-and-exclamation icon persists, then the variable dimensions in the data file - have not been parsed correctly. Possible reasons for the error are: + are not parsed correctly. Possible reasons for the error include: - The data file and connectivity file correspond to different cubed-sphere meshes. E.g., one is ne30pg2 and the other is ne4pg2. @@ -59,23 +58,34 @@ and `Load State` (upward arrow) buttons shown here. For loading a state, the upward arrow button will bring up a windew for the user to select a state file from the file system. After the file is selected and the `Open` button is clicked, the app will immediately -start loading the state. If successful, the icon of a red circle with -an exclamation mark will turn to a green circle with a check mark, +start loading the state (i.e., the user is *not* expected to click on the +"Load Files" meant for the new-viz scenario). +If the state file is successfully loaded (the contents 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 second or two. +usually takes a second to a few seconds. -!!! info "Info: What is in a State File?" +!!! 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 user passes a state file to another user or file system, - or if they want to use the same visualization settings but for - a different simulation data file, then the file names and paths + If a state file is shared with 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 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 @@ -92,23 +102,25 @@ The hamburger icon (three stacked lines) hides or shows the [control panel](cont **Busy Indicator**: The gray circle is a busy indicator. When a rotating segment is shown, -the app is processing data in the background (e.g., loading data files or -a state file (see earlier sections on this page), -updating loading newly selected variables (see [control panel](control_panel.md)), +the app is processing data in the background, e.g., loading new data files or +a state file (see earlier sections on this page) or +loading newly selected variables (see [control panel](control_panel.md)), etc. + ![toolbar misc](../images/toolbar_load_variables.png){ width="18%", align=right } -**`LOAD VARIABLES` Button** +**`LOAD VARIABLES` Button**: 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). + ![toolbar misc](../images/toolbar_colormap_groups.png){ width="12%", align=right } -**Colormap Groups** +**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 @@ -118,14 +130,21 @@ may not be colorblind-friendly. Currently, these are mostly "presets" taken from [PareView](https://www.paraview.org/). -**Camera Reset** -The camera reset button refreshes all contents in the [viewport](viewport.md) + +![camera widget](../images/camera_actions.png){ width="25%", align=right } + +**Camera Actions**: +A set of buttons are provided to simultaneously adjust all variables displayed +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 windows ("views"). -!!! warning "Tip on Camera Refresh" +!!! tip "Tip: Camera Refresh for Addressing Display Error" As mentioned on the [Reminders](reminders.md) page, the app may exhibit - display issue after new variable selection or setting changes have been made. + display issue after new variables are loaded or visualization + settings are changed. 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. From 6b2dabec8fff73d3540eeab4a6192cd3a5e15798 Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Sun, 24 Aug 2025 15:45:01 -0700 Subject: [PATCH 12/28] docs: update viewport description --- docs/images/mini-menu.png | 3 -- docs/images/multiview_rearranged.png | 3 ++ docs/images/six_variables_rearranged.png | 3 -- ...four_views.png => viewport_four_views.png} | 0 docs/userguide/gui_overview.md | 17 ++++---- docs/userguide/viewport.md | 39 +++++++------------ 6 files changed, 27 insertions(+), 38 deletions(-) delete mode 100644 docs/images/mini-menu.png create mode 100644 docs/images/multiview_rearranged.png delete mode 100644 docs/images/six_variables_rearranged.png rename docs/images/{four_views.png => viewport_four_views.png} (100%) 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/multiview_rearranged.png b/docs/images/multiview_rearranged.png new file mode 100644 index 0000000..c6f9ae4 --- /dev/null +++ b/docs/images/multiview_rearranged.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:71de690781c22cc0583d753caf67bea9b2a3873b9ee454017ea10bcf694a3e58 +size 4454428 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/four_views.png b/docs/images/viewport_four_views.png similarity index 100% rename from docs/images/four_views.png rename to docs/images/viewport_four_views.png diff --git a/docs/userguide/gui_overview.md b/docs/userguide/gui_overview.md index 1085d16..f6ac6f7 100644 --- a/docs/userguide/gui_overview.md +++ b/docs/userguide/gui_overview.md @@ -3,11 +3,17 @@ 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 +**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. + The rightmost portion is a group of camera action buttons + that centrally adjust all views in the viewport, + i.e., zooming in or out, or moving or resizing the displayed + images with respect to the GUI. -2. The collapsible [control panel](control_panel.md) located on the left +**Control Panel**: +The collapsible [control panel](control_panel.md) located on the left of the GUI allows the user to select data slices to represent, i.e., variables, time slices, vertical levels, horizontal domains and map projections. The control panel can be collapsed or @@ -15,12 +21,9 @@ Detailed descriptions can be found on the linked pages. on top of each other ) on the left end of the [toolbar](toolbar.md). -3. The [viewport](view_port.md) displays one or more variables for +**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. - The viewport also contains a camera widget in its bottom-right - corner, which can be used to 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/viewport.md b/docs/userguide/viewport.md index 2d04ee1..87a5eaf 100644 --- a/docs/userguide/viewport.md +++ b/docs/userguide/viewport.md @@ -1,6 +1,6 @@ # Viewport -![Four views](../images/four_views.png){ width="65%", align=right } +![Four views](../images/viewport_four_views.png){ width="65%", 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 @@ -19,15 +19,20 @@ average is calculated and displayed. ----- ## Custimizing the viewport -![Six views resized and rearranged](../images/six_variables_rearranged.png){ width="65%", align=right} +![Many views resized and rearranged](../images/multiview_rearranged.png){ width="40%", 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 arrangement +by using the app in the resume mode, as described in on the description +of the [toolbar](toolbar.md). ----- @@ -56,9 +61,9 @@ a button to reset the color mapping to fit the range of values in the data. through different data slices in a dimension, the colormap will be automatically adjusted for each data slice. - If the user enters min./max. values in the mini menu and hit the `return` key - on the key board, a blue icon with a lock and the text "Manual" will show up - above the text box for the max. value, as can be seen in the right example above. + If the user specifies min. and/or max. values in the mini menu, a blue icon + with a picture of a lock and the text "Manual" will show up above the max. + value, as can be seen on the right in the example above. After that, when the "play" button in the [control panel](control_panel.md) is used to cycle through different data slices in a dimension, the colormap will be fixed for the user-specified range. @@ -78,19 +83,3 @@ a button to reset the color mapping to fit the range of values in the data. groups: colorblind-friendly and other. Only the colormaps belonging to the selected group (or groups) are shown in the `Color Map` drop-down menu. ---- -## Camera widget - - -![camera widget](../images/camera_widget.png){ width="40%", align=right } - -Note that the zoom level and centering (i.e., the size and relative position) of -the displayed variable within each view can also be adjusted. -These settings are controlled centrally—for all -views—via the camera widge (see screenshot) located in the bottom-right -corner of the viewport. - -Also recall that the camera refresh button located at the right end of the -tool bar can be used to reset the size and location of all views -to the default setting. - From 3dc6c9073714a9c951f0da3e4989d7841dbcbc60 Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Sun, 24 Aug 2025 15:45:30 -0700 Subject: [PATCH 13/28] docs: update slice section screenshot for lat/lon sliders --- docs/images/slice_selection.png | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/images/slice_selection.png b/docs/images/slice_selection.png index 86dd315..e0c9c4c 100644 --- a/docs/images/slice_selection.png +++ b/docs/images/slice_selection.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:c61e264ac46247302ec1a5a08d6f732a4b52b4060f7bf144ebe6a75d2fa52f69 -size 100136 +oid sha256:17656533047e78b6d46038a743ee2d49549163ce1b6fde1c9dea7c6dd6d05972 +size 102214 From b0a9364e5257ccc775d5ecdbfdb20d4733911530 Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Sun, 24 Aug 2025 15:46:01 -0700 Subject: [PATCH 14/28] docs: misc small edits --- docs/setup/for_end_users.md | 5 +++-- docs/userguide/data_requirements.md | 3 ++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/setup/for_end_users.md b/docs/setup/for_end_users.md index 0bf3114..bdb570e 100644 --- a/docs/setup/for_end_users.md +++ b/docs/setup/for_end_users.md @@ -50,9 +50,10 @@ To launch the EAM QuickView GUI, simply double-click the app icon in your Applic !!! tip "Tip: Patience with First launch" - When a new version of the app is launched on your computer for the + When a new version of the app is launched on a computer for the first time, a significant amount of dependencies will be identified, - downloaded, and installed, which will take about a minute to a few minutes. + downloaded, and installed, which will take about a minute to a few minutes + and can be affected by the Internet connection. Subsequent launches should take just a few seconds. diff --git a/docs/userguide/data_requirements.md b/docs/userguide/data_requirements.md index 199868b..4d129e0 100644 --- a/docs/userguide/data_requirements.md +++ b/docs/userguide/data_requirements.md @@ -77,7 +77,8 @@ If `lev` is not present, QuickView attempts to find two 1D variables, pressure = (hyam * P0) + (hybm * PS0) ``` -where P0 = 1000 hPa and PS0 = 1000 Pa. +where PS0 = 1000 hPa; P0 is read from the data file and set to 1000 hPa +if not found. Similarly, for variables defined at layer interfaces, QuickView looks for either `ilev` or `hyai` and `hybi` for parsing the vertical dimension. From 93e66aa6d65e5209838924cc74be3dc9c467c912 Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Mon, 25 Aug 2025 07:35:46 -0700 Subject: [PATCH 15/28] docs: revise setup/for_end_users.md (quarantine and misc) --- docs/setup/for_end_users.md | 31 ++++++++++++++----------------- 1 file changed, 14 insertions(+), 17 deletions(-) diff --git a/docs/setup/for_end_users.md b/docs/setup/for_end_users.md index bdb570e..155b244 100644 --- a/docs/setup/for_end_users.md +++ b/docs/setup/for_end_users.md @@ -20,17 +20,17 @@ just a few clicks. macOS users with Apple Silicon chips should download `QuickView_{version}_aarch64.dmg`, and those with Intel chips should download a `*_x64.dmg` file. -2. **Important** for intermediate releases with three-part version numbers - (e.g., 1.0.1): After the download, use the following command in Terminal to +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, only major releases with - two-part version numbers like 1.0, 1.1 etc. are signed and notarized using - Kitware's Apple Developer ID. - Hence the command provided above is needed for intermediate releases, + 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. 3. Double-click the downloaded `.dmg` file. In the pop-up window, @@ -39,21 +39,18 @@ just a few clicks. !!! tip "Tip: No Need to Worry about Dependencies" - 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. + 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 First launch" +!!! tip "Tip: Patience with the First Launch" - When a new version of the app is launched on a computer for the - first time, a significant amount of dependencies will be identified, - downloaded, and installed, which will take about a minute to a few minutes - and can be affected by the Internet connection. - - Subsequent launches should take just a few seconds. + 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. From 1853530a862178c76f2fd6ec085bf2e4df363552 Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Mon, 25 Aug 2025 08:33:55 -0700 Subject: [PATCH 16/28] docs: update README files; add state file for image --- README.md | 16 ++++++++-------- docs/README.md | 13 ++++++------- docs/images/eam_quickview_full.png | 4 ++-- docs/images/state_files/state_4views_aerosol | 3 +++ 4 files changed, 19 insertions(+), 17 deletions(-) create mode 100644 docs/images/state_files/state_4views_aerosol diff --git a/README.md b/README.md index e25e4be..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 diff --git a/docs/README.md b/docs/README.md index 392e256..b1b4f44 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,14 +16,13 @@ ## What is QuickView? **EAM QuickView** is an open-source, interactive visualization tool -tailored for scientists working with the atmospheric component of the +designed 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 an intuitive -access to the powerful analysis and visualization capabilities of -[ParaView](https://www.paraview.org/) -without requiring a steep learning curve. +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 diff --git a/docs/images/eam_quickview_full.png b/docs/images/eam_quickview_full.png index 4a3ea20..4e036d3 100644 --- a/docs/images/eam_quickview_full.png +++ b/docs/images/eam_quickview_full.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:822e2dd0651f6d21a4822c43dd22c41933dc181c2e4360614e2984e9b15fb5a3 -size 2998402 +oid sha256:78d91320fc9e3dea918e41cc56719ed7b450e0c3ceac3eb641776599fba25913 +size 2566455 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 From 382567b4236503ab08ec0670ff2c0dc7c8c0a2cf Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Mon, 25 Aug 2025 08:44:22 -0700 Subject: [PATCH 17/28] docs: update installation pages --- docs/setup/for_app_developers.md | 6 +++--- docs/setup/for_end_users.md | 20 ++++++++++---------- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/setup/for_app_developers.md b/docs/setup/for_app_developers.md index 217509f..253aafb 100644 --- a/docs/setup/for_app_developers.md +++ b/docs/setup/for_app_developers.md @@ -3,10 +3,10 @@ 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. +to remote data. -Releases so far have focused on macOS. We plan to add support for -more systems in the near [future](../future.md). +Releases so far have focused on macOS. Support for +more systems will be added in the near [future](../future.md). ---- ## Clone the repo diff --git a/docs/setup/for_end_users.md b/docs/setup/for_end_users.md index 155b244..d1fc7f8 100644 --- a/docs/setup/for_end_users.md +++ b/docs/setup/for_end_users.md @@ -4,20 +4,20 @@ 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. +to remote data. -Releases so far have focused on macOS. We plan to add support for -more systems in the near [future](../future.md). +Releases so far have focused on macOS. Support for +more systems will be added in the near [future](../future.md). --- # 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 binary from the +1. Download a pre-built binary from the [releases page](https://github.com/ayenpure/QuickView/releases/). - macOS users with Apple Silicon chips should download `QuickView_{version}_aarch64.dmg`, + 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 @@ -25,7 +25,7 @@ just a few clicks. ``` xattr -d com.apple.quarantine .dmg ``` - Explanation: in order to facilitate frequent iterations between our + 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. @@ -37,7 +37,7 @@ just a few clicks. drag the QuickView icon into the Applications folder. -!!! tip "Tip: No Need to Worry about Dependencies" +!!! tip "Tip: no need to worry about dependencies" The pre-built binaries include the dependencies required to start the app locally. Any additional dependencies for data processing @@ -48,7 +48,7 @@ just a few clicks. To launch the EAM QuickView GUI, simply double-click the app icon in the Applications folder. -!!! tip "Tip: Patience with the First Launch" +!!! 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 From 847976d1cd7287822c0cf865dc1b7cc4df216718 Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Mon, 25 Aug 2025 09:08:23 -0700 Subject: [PATCH 18/28] docs: minor edit in setup/for_end_users.md --- docs/setup/for_end_users.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/setup/for_end_users.md b/docs/setup/for_end_users.md index d1fc7f8..f2dca0e 100644 --- a/docs/setup/for_end_users.md +++ b/docs/setup/for_end_users.md @@ -37,7 +37,7 @@ with just a few steps, as described below. drag the QuickView icon into the Applications folder. -!!! tip "Tip: no need to worry about dependencies" +!!! 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 @@ -48,7 +48,7 @@ with just a few steps, as described below. To launch the EAM QuickView GUI, simply double-click the app icon in the Applications folder. -!!! tip "Tip: patience with the first launch" +!!! 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 From 835471ab64460367776fee900936235c6497abc8 Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Mon, 25 Aug 2025 09:39:18 -0700 Subject: [PATCH 19/28] docs: update toolbar page and images --- docs/images/toolbar.png | 4 +- docs/images/toolbar_camera_actions.png | 4 +- docs/images/toolbar_camera_reset.png | 3 + docs/images/toolbar_circle_green.png | 3 + docs/images/toolbar_circle_red.png | 3 + docs/images/toolbar_conn_and_data_load.png | 4 +- docs/userguide/toolbar.md | 88 ++++++++++++---------- 7 files changed, 63 insertions(+), 46 deletions(-) create mode 100644 docs/images/toolbar_camera_reset.png create mode 100644 docs/images/toolbar_circle_green.png create mode 100644 docs/images/toolbar_circle_red.png diff --git a/docs/images/toolbar.png b/docs/images/toolbar.png index a540202..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:1d8965b7d3a09ea439af7b17c1b0481d59a1110de5f9fd9665d620ba60750688 -size 43320 +oid sha256:0312a336d1e1c988927f40f8efccf39e36c8ea56fb010ca09b677e95dc1cf5df +size 36382 diff --git a/docs/images/toolbar_camera_actions.png b/docs/images/toolbar_camera_actions.png index a540202..0276ee9 100644 --- a/docs/images/toolbar_camera_actions.png +++ b/docs/images/toolbar_camera_actions.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:1d8965b7d3a09ea439af7b17c1b0481d59a1110de5f9fd9665d620ba60750688 -size 43320 +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_conn_and_data_load.png b/docs/images/toolbar_conn_and_data_load.png index ffbe3c7..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:a5b07f6cff1850286163c40a54d6e7176997231cfa5b9ac0ebadafac7d0d1b94 -size 17827 +oid sha256:cc7884af82813976739cab16769fd4e14d3b0758aef0a894ea5aa648504c2268 +size 15762 diff --git a/docs/userguide/toolbar.md b/docs/userguide/toolbar.md index c77d9c6..d764ca3 100644 --- a/docs/userguide/toolbar.md +++ b/docs/userguide/toolbar.md @@ -3,10 +3,10 @@ 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 that they affect -the overall appearance and state of the GUI, including all the images -displayed in the [viewport](viewport.md)). -In the following, we first 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. @@ -14,6 +14,8 @@ then introduce the other elements. ## New-viz mode: starting a new visualization +![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 @@ -22,10 +24,12 @@ the file paths and names in the corresponding boxes or using the file folder icons to bring up system dialogue windows to select files. -![connectivity and data file buttons](../images/toolbar_conn_and_data_load.png){ width="59%", align=right } +![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 -(the icon of a page with a check mark) must be clicked. +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 @@ -33,15 +37,15 @@ identified variables in the data file that the app can visualize. The user can then start using the [control panel](control_panel.md) to select variables and spatial/temporal slices to display. -!!! warning "Tip: Simulation File Loading Error" +!!! warning "Tip: File Loading Error" 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. Possible reasons for the error include: + are not parsed correctly. Below are some common reasons for the 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 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). @@ -55,15 +59,15 @@ The current state of the visualization can be saved—and reloaded later to 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 will bring up a windew for -the user to select a state file from the file system. After the file -is selected and the `Open` button is clicked, the app will immediately -start loading the state (i.e., the user is *not* expected to click on the -"Load Files" meant for the new-viz scenario). -If the state file is successfully loaded (the contents correctly parsed), -the red circle-and-exclamation icon will turn into to a green-circle-and-check-mark icon, +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 second to a few seconds. +usually takes a couple of seconds. !!! info "Info: What's in a State File?" @@ -71,7 +75,7 @@ usually takes a second to a few seconds. 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 with multiple users or used across different + 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 @@ -80,7 +84,7 @@ usually takes a second to a few seconds. !!! warning "Tip: State File Loading Error" If the app seems nonresponsive after a state file has been chosen - and the `Open` button has been clicked, + 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 @@ -91,60 +95,64 @@ usually takes a second to a few seconds. -![toolbar misc](../images/toolbar_hamburger.png){ width="6%", align=right } +![hamburger icon](../images/toolbar_hamburger.png){ width="6%", align=right } **Control Panel Hide/Show**: -The hamburger icon (three stacked lines) hides or shows the [control panel](control_panel.md). +The hamburger icon (three stacked lines) at the left end of the toolbar +hides or shows the [control panel](control_panel.md). -![toolbar misc](../images/toolbar_busy_indicator.png){ width="5%", align=right } +![busy inidcator](../images/toolbar_busy_indicator.png){ width="5%", align=right } **Busy Indicator**: -The gray circle is a busy indicator. When a rotating segment is shown, -the app is processing data in the background, e.g., loading new data files or -a state file (see earlier sections on this page) or -loading newly selected variables (see [control panel](control_panel.md)), -etc. +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)). -![toolbar misc](../images/toolbar_load_variables.png){ width="18%", align=right } +![LOAD VARIABLES button](../images/toolbar_load_variables.png){ width="18%", align=right } -**`LOAD VARIABLES` Button**: +**`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). -![toolbar misc](../images/toolbar_colormap_groups.png){ width="12%", align=right } +![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). +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/). +may not be colorblind-friendly; Currently, these are "presets" +from [PareView](https://www.paraview.org/). -![camera widget](../images/camera_actions.png){ width="25%", align=right } +![camera actions](../images/camera_actions.png){ width="25%", align=right } **Camera Actions**: -A set of buttons are provided to simultaneously adjust all variables displayed +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 windows ("views"). +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 variables are loaded or visualization + display issues after new variables are loaded or when visualization settings are changed. - 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. + 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. From a5c90a68ce81991af150b3d720878c70aaaa7c67 Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Mon, 25 Aug 2025 09:47:54 -0700 Subject: [PATCH 20/28] docs: update userguide/connectivity.md --- docs/userguide/connectivity.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/userguide/connectivity.md b/docs/userguide/connectivity.md index 76f3a52..20a1092 100644 --- a/docs/userguide/connectivity.md +++ b/docs/userguide/connectivity.md @@ -5,39 +5,41 @@ A collection of connectivity files can be found on [Zenodo](https://doi.org/10.5281/zenodo.16908566). - The archive is continuously updated as more users inform us + 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, 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 `ne*pg2`, with `*` being a number, -e.g., 4, 30, 120, or 256. Further details about EAM's cubed-sphere grids +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). Future versions of QuickView will also support the cubed-sphere meshes -used by EAM's dynamical core, i.e., the `ne*np4` grids. +used by EAM's dynamical core, i.e., the `ne*np4` grids +(also referred to as "native grids" or "GLL grids"). ## 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 [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 at -[https://github.com/ClimateGlobalChange/tempestremap](https://github.com/ClimateGlobalChange/tempestremap).) +It can also be installed following the instructions provided in its +[repo](https://github.com/ClimateGlobalChange/tempestremap).) -For example, the command +For example, using Mark's script, the command ``` ./makeSE.sh 30 From 0084b951a85d7827e8cd031b4e8c7de62fded82a Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Mon, 25 Aug 2025 09:53:46 -0700 Subject: [PATCH 21/28] docs: update reminders page --- docs/userguide/reminders.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/userguide/reminders.md b/docs/userguide/reminders.md index 972e5d7..a29fc83 100644 --- a/docs/userguide/reminders.md +++ b/docs/userguide/reminders.md @@ -19,18 +19,17 @@ 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 + 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^^. + 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 @@ -41,9 +40,9 @@ In the current version, after the `LOAD VARIABLES` button is clicked or a visualization setting is changed, some (or all) of - the images in the [viewport](viewport.md) might exhibit a display issue, e.g., + 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 reset - button at the right end of the [toolbar](toolbar.md), and we are working on - resolving the issue for future versions. + button at the right end of the [toolbar](toolbar.md). We are working on + solving the display problem for future versions. From c0e97575e3006dae0c7ea0dd2e96c6c7af0ffd9b Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Mon, 25 Aug 2025 10:05:59 -0700 Subject: [PATCH 22/28] docs: update userguide/data_requirements.md --- docs/userguide/data_requirements.md | 31 +++++++++++++++-------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/docs/userguide/data_requirements.md b/docs/userguide/data_requirements.md index 4d129e0..50826a8 100644 --- a/docs/userguide/data_requirements.md +++ b/docs/userguide/data_requirements.md @@ -18,9 +18,9 @@ properly read and visualize the simulation data. in QuickView is that the grid described by the connecitivity file does not match the grid in the simulation data file. - If you have clicked on the `Load Files` button in the - [toolbar](toolbar.md) but the status icon next to it continues to show - a red circle with an exclamation mark, the first thing we suggest + 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" @@ -28,9 +28,10 @@ properly read and visualize the simulation data. 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 you run into such a case, please reach out to our lead developer + 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 use the [Issue tab on GitHub](https://github.com/ayenpure/QuickView/issues). + or using the [Issue tab on GitHub](https://github.com/ayenpure/QuickView/issues) + to start a discussion. ---- ## Overview @@ -62,11 +63,12 @@ is calculated and displayed. ## 3D variables If a variables has not only `time` and `ncol` but also a vertical dimension, -QuickView expects that dimension to be named `lev` for variables defined at -layer midpoints and `ilev` for variables defined at layer interfaces. +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 -in the [control panel](control_panel.md) to work properly, the simulation data +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, @@ -74,7 +76,7 @@ If `lev` is not present, QuickView attempts to find two 1D variables, `lev` using ``` -pressure = (hyam * P0) + (hybm * PS0) +lev = (hyam * P0) + (hybm * PS0) ``` where PS0 = 1000 hPa; P0 is read from the data file and set to 1000 hPa @@ -87,11 +89,10 @@ either `ilev` or `hyai` and `hybi` for parsing the vertical dimension. ---- ## Variable with more dimensions -QuickView currently only visualize the types of variables discussed above. +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 different tracers or -[COSP](https://climatedataguide.ucar.edu/climate-data/cosp-cloud-feedback-model-intercomparison-project-cfmip-observation-simulator-package)-related -dimensions, +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/) @@ -102,6 +103,6 @@ for a discussion. ## Missing values If a variable has an attribute named `missing_value` or `_FillValue`, -the provided value is converted to NaN and ignored +the value is converted to NaN and ignored in the calculation of global averages and for the visualization. From 989f190f3118a2af4f2605831c3237eb4b03f1a3 Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Mon, 25 Aug 2025 10:23:05 -0700 Subject: [PATCH 23/28] docs: update GUI overview --- docs/images/camera_actions.png | 3 --- docs/images/cvd.png | 3 --- docs/images/eam-quickview-full-enum.png | 3 --- docs/images/main.png | 3 --- docs/images/view-collapsed.png | 3 --- docs/images/view-expanded.png | 3 --- docs/userguide/gui_overview.md | 14 +++++--------- 7 files changed, 5 insertions(+), 27 deletions(-) delete mode 100644 docs/images/camera_actions.png delete mode 100644 docs/images/cvd.png delete mode 100644 docs/images/eam-quickview-full-enum.png delete mode 100644 docs/images/main.png delete mode 100644 docs/images/view-collapsed.png delete mode 100644 docs/images/view-expanded.png diff --git a/docs/images/camera_actions.png b/docs/images/camera_actions.png deleted file mode 100644 index d7492f9..0000000 --- a/docs/images/camera_actions.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:451f71a27566c5fee2196deba7067467bde77fdbe5eb0e39ad7ff38086e7b926 -size 8454 diff --git a/docs/images/cvd.png b/docs/images/cvd.png deleted file mode 100644 index 218344a..0000000 --- a/docs/images/cvd.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:3f257eeb77b4a9f62c496a05a79ad57568c9a1fafbf15f0bca0f1845d6a0791a -size 7598 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/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/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/userguide/gui_overview.md b/docs/userguide/gui_overview.md index f6ac6f7..8a057c7 100644 --- a/docs/userguide/gui_overview.md +++ b/docs/userguide/gui_overview.md @@ -3,27 +3,23 @@ EAM QuickView's GUI contains the three main components summarized below. Detailed descriptions can be found on the linked pages. +![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. - The rightmost portion is a group of camera action buttons - that centrally adjust all views in the viewport, - i.e., zooming in or out, or moving or resizing the displayed - images with respect to the GUI. **Control Panel**: -The collapsible [control panel](control_panel.md) located on the left +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). **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. -![eam-quickview-full-enum](../images/eam-quickview-full-enum.png) From 05777ee0860a90d02e849ddeb0a04893e590a196 Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Mon, 25 Aug 2025 10:38:05 -0700 Subject: [PATCH 24/28] docs: update control panel description; rename screenshots --- docs/images/control_panel_map_projection.png | 3 +++ ....png => control_panel_slice_selection.png} | 0 ...g => control_panel_variable_selection.png} | 0 docs/images/map_projection.png | 3 --- docs/userguide/control_panel.md | 27 ++++++++++--------- 5 files changed, 18 insertions(+), 15 deletions(-) create mode 100644 docs/images/control_panel_map_projection.png rename docs/images/{slice_selection.png => control_panel_slice_selection.png} (100%) rename docs/images/{variable_selection.png => control_panel_variable_selection.png} (100%) delete mode 100644 docs/images/map_projection.png 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/slice_selection.png b/docs/images/control_panel_slice_selection.png similarity index 100% rename from docs/images/slice_selection.png rename to docs/images/control_panel_slice_selection.png diff --git a/docs/images/variable_selection.png b/docs/images/control_panel_variable_selection.png similarity index 100% rename from docs/images/variable_selection.png rename to docs/images/control_panel_variable_selection.png diff --git a/docs/images/map_projection.png b/docs/images/map_projection.png deleted file mode 100644 index d355d61..0000000 --- a/docs/images/map_projection.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:8ae1520cf7c395565828590ab377e98fe701c9e84d91fde8e07991ffd7847526 -size 72963 diff --git a/docs/userguide/control_panel.md b/docs/userguide/control_panel.md index a56bfcd..919424a 100644 --- a/docs/userguide/control_panel.md +++ b/docs/userguide/control_panel.md @@ -7,19 +7,20 @@ # Control Panel -The control panel allows users to select variables from the data file -as well the spatial and temporal ranges of data to visualize, +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. ----- ## Variable selection -![variable selection sections](../images/variable_selection.png){ width="300", align=right } ### 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. @@ -30,10 +31,10 @@ entire globe. dimension; these are referred to as "variables at layer midpoints" and "variables at layer interfaces", respectively. -These three categories of variables each have their own collapsible +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 +but can be supported upon request. ### Select and load @@ -51,7 +52,8 @@ 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. Checking the boxes to the left of the variable names +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). @@ -78,7 +80,7 @@ in order for these changes to take effect.* ----- ## Data slice selection -![variable selection sections](../images/slice_selection.png){ width="300", align=right } +![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. @@ -88,19 +90,20 @@ 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 a dimension, as well as "play"/"pause" (toggle) buttons for cycling over +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, the the cycling through the first dimension will be paused. +a first dimension, then the cycling in the first dimension will be paused. ----- ## Map Projection -![variable selection sections](../images/map_projection.png){ width="300", align=right } +![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, and we plan to allow -the user to choose the center longitude of the map in the near future. +More projections can be added upon request. +In the near future, the center longitude of the map +will become customizable. From 1a4c518c49c3cad2d16b86cfa0186cc2b17450ef Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Mon, 25 Aug 2025 11:16:48 -0700 Subject: [PATCH 25/28] docs: update viewport description and screenshots; include state files --- docs/images/gear_menu_range_auto.png | 3 -- docs/images/gear_menu_range_manual.png | 3 -- docs/images/multiview_rearranged.png | 3 -- .../state_files/state_4views_BURDEN1_PS_T_Q | 3 ++ .../state_files/state_for_gear_menu_examples | 3 ++ .../state_files/state_many_views_rearranged | 3 ++ docs/images/viewport_four_views.png | 4 +- docs/images/viewport_gear_menu_range_auto.png | 3 ++ .../viewport_gear_menu_range_manual.png | 3 ++ .../images/viewport_many_views_rearranged.png | 3 ++ docs/userguide/viewport.md | 50 +++++++++---------- 11 files changed, 45 insertions(+), 36 deletions(-) delete mode 100644 docs/images/gear_menu_range_auto.png delete mode 100644 docs/images/gear_menu_range_manual.png delete mode 100644 docs/images/multiview_rearranged.png create mode 100644 docs/images/state_files/state_4views_BURDEN1_PS_T_Q create mode 100644 docs/images/state_files/state_for_gear_menu_examples create mode 100644 docs/images/state_files/state_many_views_rearranged create mode 100644 docs/images/viewport_gear_menu_range_auto.png create mode 100644 docs/images/viewport_gear_menu_range_manual.png create mode 100644 docs/images/viewport_many_views_rearranged.png diff --git a/docs/images/gear_menu_range_auto.png b/docs/images/gear_menu_range_auto.png deleted file mode 100644 index 7f36ec5..0000000 --- a/docs/images/gear_menu_range_auto.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:655b4ff09f900995b3f3a64a8f2dbb9e5da70d39e22d403192c82e5e413947d6 -size 955625 diff --git a/docs/images/gear_menu_range_manual.png b/docs/images/gear_menu_range_manual.png deleted file mode 100644 index 1d71845..0000000 --- a/docs/images/gear_menu_range_manual.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:d6c758bf88c9906ca35c8b2b3eec9b41d5eb8bff1371e7fafefe78225982f063 -size 959885 diff --git a/docs/images/multiview_rearranged.png b/docs/images/multiview_rearranged.png deleted file mode 100644 index c6f9ae4..0000000 --- a/docs/images/multiview_rearranged.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:71de690781c22cc0583d753caf67bea9b2a3873b9ee454017ea10bcf694a3e58 -size 4454428 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_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/viewport_four_views.png b/docs/images/viewport_four_views.png index 2f8d236..3b76aa0 100644 --- a/docs/images/viewport_four_views.png +++ b/docs/images/viewport_four_views.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:a35f88a1f2e544ccd0e47bb65fe36e98fd41dcb4899a534065a16da8bcb7d6e0 -size 2621058 +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/userguide/viewport.md b/docs/userguide/viewport.md index 87a5eaf..3a9b6f6 100644 --- a/docs/userguide/viewport.md +++ b/docs/userguide/viewport.md @@ -1,17 +1,15 @@ # Viewport -![Four views](../images/viewport_four_views.png){ width="65%", align=right } +![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 little frame (which we refer to as a "view") inside -the viewport. Below is an example showing six views. +the viewport. On the right is an example showing four views. -At the top of each view, -the indices of the vertical level (if applicable) and time slice being displayed -are shown in the top-left corner of each view. -The variable name is shown in the top-right corner -together with the area-weighted global average on that vertical level. +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. @@ -19,18 +17,19 @@ average is calculated and displayed. ----- ## Custimizing the viewport -![Many views resized and rearranged](../images/multiview_rearranged.png){ width="40%", align=right} +![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^^. +- 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 continue 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). @@ -46,28 +45,28 @@ 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 range of values in the data. +a button to reset the color mapping to fit the value range of data slice. -![gear menu with auto range](../images/gear_menu_range_auto.png){ width="48%"} -![gear menu with manual range](../images/gear_menu_range_manual.png){width="48%"} +![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%"} !!! 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 max. and min. values can be found - in the mini menu, as seen in the left example above. + 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 in a dimension, - the colormap will be automatically adjusted for each data slice. + 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. - If the user specifies min. and/or max. values in the mini menu, a blue icon - with a picture of a lock and the text "Manual" will show up above the max. - value, as can be seen on the right in the example above. - After that, when the "play" button in the [control panel](control_panel.md) - is used to cycle through different data slices in a dimension, - the colormap will be fixed for the user-specified range. - !!! tip "Tip: Field Value Lookup in Colorbar" @@ -81,5 +80,6 @@ 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. + selected group (or groups) are shown in the `Color Map` drop-down menu + brought up by the gear button. From 571828a0dd5baa098d3870e81267632ec51dc37a Mon Sep 17 00:00:00 2001 From: Hui Wan Date: Mon, 25 Aug 2025 11:17:30 -0700 Subject: [PATCH 26/28] docs: minor edits in future.md --- docs/future.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/future.md b/docs/future.md index c92d76b..ac83e5b 100644 --- a/docs/future.md +++ b/docs/future.md @@ -1,17 +1,17 @@ # Planned Improvements -For the upcoming releases, we plan to prioritize the following: +For the upcoming versions, we plan to prioritize the following: -- adding support for the server-client model and deploying servers to +- 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 reset +- addressing the display issues that currently need a camera refresh as a remedy (see the [Reminders page](userguide/reminders.md); -- allowing the user to specify a center longitude for the contour plots. +- allowing the center longitude on the maps to be customized . -Addional suggestions are welcome. Bug reports and feature requests -can be made by opening new +Addional suggestions are welcome. +Bug reports and feature requests can be made by opening new [issues](https://github.com/ayenpure/QuickView/issues) on GitHub. From db84432725a588d054fdf947e26c2ccde530733b Mon Sep 17 00:00:00 2001 From: Abhishek Yenpure Date: Mon, 25 Aug 2025 14:02:25 -0700 Subject: [PATCH 27/28] fix: bug fixes and minor features 1. State loading and data loading still has remnant views/layouts 2. Fix broken numpy import while loading files that calculate lev/ilevs form hyam and hyai 3. Sort colormaps for display 4. Adding new cvd-friendly color maps (lisbon, berlin, vanimo, managua) --- quickview/interface.py | 7 + quickview/plugins/eam_reader.py | 6 +- quickview/presets/berlin_PARAVIEW.xml | 260 +++++++++++++++++++++++++ quickview/presets/lisbon_PARAVIEW.xml | 260 +++++++++++++++++++++++++ quickview/presets/managua_PARAVIEW.xml | 260 +++++++++++++++++++++++++ quickview/presets/vanimo_PARAVIEW.xml | 260 +++++++++++++++++++++++++ quickview/ui/toolbar.py | 4 +- quickview/utils/color.py | 16 ++ quickview/view_manager.py | 9 +- 9 files changed, 1071 insertions(+), 11 deletions(-) create mode 100644 quickview/presets/berlin_PARAVIEW.xml create mode 100644 quickview/presets/lisbon_PARAVIEW.xml create mode 100644 quickview/presets/managua_PARAVIEW.xml create mode 100644 quickview/presets/vanimo_PARAVIEW.xml 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 From fda3577263728b8bdff27dd6d5da03bd719893ab Mon Sep 17 00:00:00 2001 From: Abhishek Yenpure Date: Mon, 25 Aug 2025 14:30:05 -0700 Subject: [PATCH 28/28] =?UTF-8?q?Bump=20version:=200.1.20=20=E2=86=92=200.?= =?UTF-8?q?1.21?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .bumpversion.cfg | 2 +- pyproject.toml | 2 +- quickview/__init__.py | 2 +- src-tauri/Cargo.toml | 2 +- src-tauri/tauri.conf.json | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) 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/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/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": {