From 656fb6fc783107fe39dcfa99e7b0bcfca159af21 Mon Sep 17 00:00:00 2001 From: Nicolas Vuaille Date: Fri, 7 Feb 2025 11:15:34 +0100 Subject: [PATCH 1/3] Fix path formatting to display backslashes --- doc/source/ReferenceManual/customizingParaView.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/ReferenceManual/customizingParaView.rst b/doc/source/ReferenceManual/customizingParaView.rst index 1543aa5..e4a4b41 100644 --- a/doc/source/ReferenceManual/customizingParaView.rst +++ b/doc/source/ReferenceManual/customizingParaView.rst @@ -440,10 +440,10 @@ several locations. If you installed |ParaView| in the directory ``INSTALL``, then the |ParaView| executables will search for the site settings file in these directories in the specified order: -* `INSTALL/share/paraview-X.Y` ( `INSTALL\share\paraview-X.Y` in Windows systems) -* `INSTALL/lib` (`INSTALL\lib` in Windows systems) +* `INSTALL/share/paraview-X.Y` ( ``INSTALL\share\paraview-X.Y`` in Windows systems) +* `INSTALL/lib` (``INSTALL\lib`` in Windows systems) * `INSTALL` -* `INSTALL/..` (`INSTALL/lib` in Windows systems) +* `INSTALL/..` (``INSTALL\lib`` in Windows systems) where ``X`` is |ParaView|'s major version number and ``Y`` is the minor version number. |ParaView| executables will search these -- GitLab From 5f868eecc322301eba8854d3aa2745cf7a17e995 Mon Sep 17 00:00:00 2001 From: Nicolas Vuaille Date: Fri, 7 Feb 2025 11:15:56 +0100 Subject: [PATCH 2/3] Update environment variable reference to new system --- doc/source/ReferenceManual/customizingParaView.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/doc/source/ReferenceManual/customizingParaView.rst b/doc/source/ReferenceManual/customizingParaView.rst index e4a4b41..e28e1af 100644 --- a/doc/source/ReferenceManual/customizingParaView.rst +++ b/doc/source/ReferenceManual/customizingParaView.rst @@ -461,10 +461,9 @@ file will be used. This is true for both custom default settings and application-settings set through the :guilabel:`Edit > Settings` menu. To aid in debugging problems with the site settings file location, you -can define an evironment variable named ``PV_SETTINGS_DEBUG`` -to something other than an empty string. This will turn on verbose -output showing where the |ParaView| executables are looking for the site -settings file. +can define the PARAVIEW_LOG_APPLICATION_VERBOSITY to INFO. +This will turn on verbose output about application configuration, including +showing where the |ParaView| executables are looking for the site settings file. .. _sec:ConfiguringServerSettings: -- GitLab From 185855f3975a04ad81112bd7779a904de632b731 Mon Sep 17 00:00:00 2001 From: Nicolas Vuaille Date: Fri, 7 Feb 2025 12:04:19 +0100 Subject: [PATCH 3/3] Update settings path-finding information --- .../ReferenceManual/customizingParaView.rst | 202 +++++++++++++----- .../parallelDataVisualization.rst | 6 +- 2 files changed, 149 insertions(+), 59 deletions(-) diff --git a/doc/source/ReferenceManual/customizingParaView.rst b/doc/source/ReferenceManual/customizingParaView.rst index e28e1af..ee3a115 100644 --- a/doc/source/ReferenceManual/customizingParaView.rst +++ b/doc/source/ReferenceManual/customizingParaView.rst @@ -1,4 +1,4 @@ -.. include:: ../macros.hrst +5. include:: ../macros.hrst .. include:: ../abbreviations.hrst .. _chapter:CustomizingParaView: @@ -49,7 +49,7 @@ launch |paraview|, you'll still be using the same settings chosen earlier. To revert to the default, use the ``Restore Defaults`` button. You can also manually edit the setting file as in :numref:`sec:ConfiguringSettingsJSON`. Furthermore, site maintainers can provide site-wide defaults for these, as is -explained in :numref:`sec:ConfiguringSettingsSiteWide`. +explained in :numref:`sec:ConfigurationLocations`. Next, we will see some of the important options available. Those that are only available in the advanced mode are indicated as such using the @@ -348,12 +348,25 @@ create a new layout. Click on the ``Render View`` button. A new render view will be created with the custom background color you just saved as default. + +.. _sec:ConfigurationFiles: + +Configuration files +=================== + +|ParaView| enables you to configure various aspects of its operation, +from specifying default property values (described in :numref:sec:CustomDefaultSettings) +to graphical interface organization. Some configuration options can be specified for all +users on a system through site-wide configuration files while individual users +can further customize |ParaView| with per-user configuration files. + + .. _sec:ConfiguringSettingsJSON: Configuring settings with JSON -============================== +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Settings are stored in a text file in the |JSON| format. +Some |ParaView| settings are stored in a text file in the |JSON| format. We recommend to use the user interface in |paraview| to set most default values, but it is possible to set them by editing the |JSON| settings file directly. It is @@ -362,13 +375,18 @@ manual editing. The |ParaView| executables read from and write to a file named ``ParaView-UserSettings.json``, which is located in your home -directory on your computer. On Windows, this file is located at -``%APPDATA%/ParaView/ParaView-UserSettings.json``, where the -``APPDATA`` environment variable is usually something like -``C:/Users/USERNAME/AppData/Roaming``, where ``USERNAME`` is -your login name. On Unix-like systems, it is located under -``~/.config/ParaView/ParaView-UserSettings.json``. This file will -exist if you have made any default settings changes through the user +directory on your computer. +The search procedure is detailed in :numref:`sec:ConfigurationLocations`. + +.. admonition:: **Notice** + :class: error + + The JSON settings configuration is named depending on its location! + Use ``ParaView-SiteSettings.json`` file for the install locations, + and ``ParaView-UserSettings.json`` for the user space version. + + +This file will exist if you have made any default settings changes through the user interface in the |paraview| executable. Once set, these default settings will be available in subsequent versions of |ParaView|. @@ -421,49 +439,6 @@ object. settings file. Hence, if you have changed the application settings, you will see some entries under a group named "settings". -.. _sec:ConfiguringSettingsSiteWide: - -Configuring site-wide settings -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In addition to individual settings, |ParaView| offers a -way to specify site-wide settings for a |ParaView| -installation. These site-wide settings must be defined in a -|JSON| file with the same structure as the user settings file. In fact, -one way to create a site settings file is to set the settings as -desired in |paraview|, close the program, and then copy the -user settings file to the site settings file. The site settings file -must be named ``ParaView-SiteSettings.json``. - -The |ParaView| executables will search for the site settings file in -several locations. If you installed |ParaView| in the directory -``INSTALL``, then the |ParaView| executables will search for the -site settings file in these directories in the specified order: - -* `INSTALL/share/paraview-X.Y` ( ``INSTALL\share\paraview-X.Y`` in Windows systems) -* `INSTALL/lib` (``INSTALL\lib`` in Windows systems) -* `INSTALL` -* `INSTALL/..` (``INSTALL\lib`` in Windows systems) - -where ``X`` is |ParaView|'s major version number and ``Y`` is -the minor version number. |ParaView| executables will search these -directories in the given order, reading in the first -``ParaView-SiteSettings.json`` file it finds. The conventional -location for this kind of configuration file is in the ``share`` -directory (the first directory searched), so we recommend placing the -site settings file there. - -The user settings take precedence over site settings. -If the same settings are specified in both the -``ParaView-SiteSettings.json`` file and ``ParaView-UserSettings.json`` -file in a user's directory, the setting specified in the ``ParaView-UserSettings.json`` -file will be used. This is true for both custom default settings and -application-settings set through the :guilabel:`Edit > Settings` menu. - -To aid in debugging problems with the site settings file location, you -can define the PARAVIEW_LOG_APPLICATION_VERBOSITY to INFO. -This will turn on verbose output about application configuration, including -showing where the |ParaView| executables are looking for the site settings file. .. _sec:ConfiguringServerSettings: @@ -474,9 +449,7 @@ In addition to settings for |ParaView|, it is possible to specify default values for |pvserver|, |pvdataserver| and |pvrenderserver| command line options using server settings. -Server settings file are located in the same potential locations -as the user settings described in :numref:`sec:ConfiguringSettingsJSON`, -but the name of the file itself is ``ParaViewServer-UserSettings.json``. +Server settings file is named ``ParaViewServer-UserSettings.json``. Only the following connection command-line options can be specified: - ``--connect-id`` @@ -512,8 +485,121 @@ application. The application-wide settings logic is also valid for server settings and a ``ParaViewServer-SiteSettings.json`` in the locations - specified in the :numref:`sec:ConfiguringSettingsSiteWide` will be used in the + specified in the :numref:`sec:ConfigurationLocations` will be used in the same way. .. |pqAdvanced| image:: ../images/icons/pqAdvanced.svg :width: 20px + + +Configuring application environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For a smoother experience, the |ParaView| graphical application +will also save and restore your environment: panel positions, +recent files used and more. + +This informations is stored in a ``ParaViewX.Y.ini`` file (``X.Y`` being the version numbers), +that will be written in your user space when |ParaView| exits. + +This file is not intended to be edited from a text editor. +It is more like a snapshot of the application organization the last time you close it. + + +Property Panel Visibilities +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For an advanced control of the |ParaView| interface, a ``PropertyPanelVisibilities.json`` +can be provided either in user space or under a site directory, +in any of the directories mentioned in :numref:`sec:ConfigurationLocations`. + +This file will override the visibility of any property to be either "default", "advanced", or "never". +The structure of this JSON file is similar to the ``ParaView-UserSettings`` one: +it should should be a collection of object per proxy group, containing one object per proxy, +itself having a list of properties. + +Example of PropertyPanelVisibilities.json + +.. code-block:: json + + { + "annotations" : + { + "GridAxes3DActor" : + { + "XTitle" : "advanced" + } + }, + "sources" : + { + "SphereSource" : + { + "StartTheta" : "default", + "StartPhi" : "never" + } + } + } + +|ParaView| does not generate this file, it is intended to be provided +when deploying the application. + +.. _sec:ConfigurationLocations: + +Configuration locations +======================= + +Each configuration file can be located in several directory locations. +|ParaView| expects a writeable directory in the user space +so that it can store user-customized settings files. +Additional configuration files that apply to all users of a system can be configured +as part of the |ParaView| installation process. These types of configuration files +are called "site settings". + +User settings: configuration at the user level +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The user space contains the files that can be written by the |ParaView| +application. This also were you can add your own configurations. + +On Windows, this is located at ``%APPDATA%/ParaView/``, where the +``APPDATA`` environment variable is usually something like +``C:/Users/USERNAME/AppData/Roaming``, where ``USERNAME`` is +your login name. +On Unix-like systems, it is located under ``$XDG_CONFIG_HOME/ParaView/`` +if defined or under ``$HOME/.config/ParaView/``. + + +Site settings: configuration at installation level +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The |ParaView| executables will search for the site settings file in +several locations. If you installed |ParaView| in the directory +``INSTALL``, then the |ParaView| executables will search for the +site settings file in these directories in the specified order: + +* ``INSTALL`` +* ``INSTALL/share/paraview-X.Y`` ( ``INSTALL\share\paraview-X.Y`` in Windows systems) +* ``INSTALL/lib`` (``INSTALL\lib`` in Windows systems) +* ``INSTALL/..`` (``INSTALL\..`` in Windows systems) + +On macOS additional paths are searched. Considering a ``ROOT`` directory +at ``INSTALL/../../..``, following paths are added: + +* ``ROOT`` +* ``ROOT/../lib`` +* ``INSTALL/../lib/paraview-X.Y`` +* ``INSTALL/../Support`` +* ``ROOT/../Support`` + +where ``X`` is |ParaView|'s major version number and ``Y`` is +the minor version number. |ParaView| executables will search these +directories in the given order, reading in the first +file it finds. + +.. admonition:: **Did you know?** + :class: tip + + To aid in debugging problems with the site settings file location, you + can define the ``PARAVIEW_LOG_APPLICATION_VERBOSITY`` to ``INFO``. + This will turn on verbose output about application configuration, including + showing where the |ParaView| executables are looking for the configuration files. diff --git a/doc/source/ReferenceManual/parallelDataVisualization.rst b/doc/source/ReferenceManual/parallelDataVisualization.rst index 6f6cda9..61aaab4 100644 --- a/doc/source/ReferenceManual/parallelDataVisualization.rst +++ b/doc/source/ReferenceManual/parallelDataVisualization.rst @@ -460,7 +460,8 @@ During startup, ParaView looks at several locations for server configurations to * On Unix-based systems and macOS * ``default_servers.pvsc`` in the ParaView executable directory (you can do a ``ls -l /proc//exe`` to identify the executable directory) - * ``/usr/share/ParaView/servers.pvsc`` + * under each of ``XDG_DATA_DIRS``, looking for ``ParaView/servers.pvsc``. + * ``/usr/local/share/ParaView/servers.pvsc`` or ``/usr/share/ParaView/servers.pvsc`` * ``$HOME/.config/ParaView/servers.pvsc`` (ParaView will save user defined servers here) * On Windows @@ -468,6 +469,9 @@ During startup, ParaView looks at several locations for server configurations to * ``%COMMON_APPDATA%\ParaView\servers.pvsc`` * ``%APPDATA%\ParaView\servers.pvsc`` (ParaView will save user defined servers here) +The exact procedure to find the writable directory is detailed in +:numref:`sec:ConfigurationLocations`. + Here are a few examples of some common use-cases. Case One: Simple command server startup -- GitLab