.. include:: ../macros.hrst .. include:: ../abbreviations.hrst .. _chapter:CommandLineArguments: Command Line Arguments ###################### Command-line arguments offer control over runtime application behavior and configuration of settings, and integrate easily with scripts or automated pipelines. All |ParaView| executables, detailed in :numref:`sec:ParaViewExecutables`, share a common set of command-line options, although each program also supports unique arguments specific to its functionality. The following basic syntax rules apply to all |ParaView| executables: * Values for options can be provided after a space or an equals sign. * ``--option value`` is equivalent to ``--option=value``. * For options that accept multiple values, denoted ``--moption TYPE ...``, you can either provide the option multiple times or separate the values with a comma. * ``--moption=foo --moption=bar`` is equivalent to ``--moption=foo,bar``. * Options may expect a certain type of value. * ``TEXT``: A text string. * ``INT``: An integer number. * ``FLOAT``: A floating-point number. * ``ENUM``: One of several predefined values. .. _sec:CommonCommandLineArguments: Common Options ============== The options below are common to all |ParaView| executables: |paraview|, |pvpython|, |pvbatch|, |pvserver|, |pvdataserver| and |pvrenderserver|. **General options**: * ``-h``, ``--help``: Prints the help message and exit. * ``-V``, ``--version``: Prints version number and exit. * ``-v``, ``--verbosity ENUM:verbosity``: Controls log verbosity on stderr, using integer values in the range ``[-9, 9]`` or one of ``INFO``, ``WARNING``, ``ERROR``, or ``OFF``. Defaults to ``INFO(0)``. * ``-d``, ``--dr``, ``--disable-registry``: Skips user-specific applications settings and configuration options. * ``--print-monitors``: Prints monitor information and exit. This option is only available on Windows. * ``--venv TEXT``: Initializes python with a virtual environment at this path. **Debugging and logging options**: * ``--enable-bt``: Generates stack-trace on crash, if possible. * ``--cslog TEXT``: Specifies the filename to use for generating a ClientServerStream log. * ``-l``, ``--log TEXT[,ENUM:verbosity] ...``: Additional log files to generate. Can be specified multiple times. By default, log verbosity is set to ``INFO(0)`` and may be overridden per file by adding suffix ``,verbosity``, where verbosity values are same as those accepted for the ``--verbosity`` argument. **MPI options**: * ``--mpi``: Initializes MPI for the current process, even if not necessary. * Excludes: ``--no-mpi``. * ``--no-mpi``: Skips initializing MPI on current process, if not required. * Excludes: ``--mpi``. * ``--use-mpi-ssend``: Use ``MPI_SSend`` instead of ``MPI_Send``, whenever possible. Useful for debugging race conditions in distributed environments. * This setting can also be configured via the ``PARAVIEW_USE_MPI_SSEND`` environment variable. **Plugin options**: * ``--plugins TEXT ...``: Specify plugins to load on startup. * ``--plugin-search-paths TEXT ...``: Specify search paths for plugins when resolving plugin names. **Connection options**: * ``--connect-id INT``: An identifier used to match client-server connections. Non-zero values require the client and server to use the same identifier. Default is ``0``. * ``--hostname TEXT``: Override the hostname used for connecting to this process. By default, the hostname is determined using appropriate system calls. **Rendering options** (for all but |pvdataserver|): * ``--force-offscreen-rendering``: If supported by the build and platform, creates headless (offscreen) render windows for rendering results. * Excludes: ``--force-onscreen-rendering``. * ``--force-onscreen-rendering`` : If supported by the build and platform, creates on-screen render windows. * Excludes ``--force-offscreen-rendering``. * This setting can also be configured via the ``PV_DEBUG_REMOTE_RENDERING`` environment variable. * ``--opengl-window-backend ENUM`` Specify the OpenGL window backend to use. Supported values are ``GLX``, ``EGL``, ``OSMesa``, ``Win32``. This option is only relevant for |pvbatch|, |pvpython|, |pvserver|, and |pvrenderserver|. * If not specified, the default backend is determined by the build and hardware configuration. **Display environment options** (for all but |pvdataserver|): * ``--disable-xdisplay-test``: Skips all X-display tests and OpenGL version checks. This is only applicable on systems with X. Use this if you're confident that your X environment and OpenGL support are set up correctly (experimental). * ``--displays TEXT ...``: Specify a list of rendering display or device ids. For X-based systems, this can be the value to set for the ``DISPLAY`` environment. For EGL-based systems, these are the available EGL device indices. When specified these are distributed among the number of rendering ranks using ``--displays-assignment-mode`` specified. * ``--displays-assignment-mode ENUM``: Specify how to assign displays (specified using ``--displays=``) among rendering ranks. Supported values are ``round-robin`` (default) and ``contiguous``. * Needs: ``--displays``. **Stereo rendering options** (for all but |pvdataserver|): * ``--stereo``: Enables stereo rendering. * ``--stereo-type INT``: Specify the stereo type to use. Possible values are ``Crystal Eyes``, ``Red-Blue``, ``Interlaced``, ``Dresden``, ``Anaglyph``, ``Checkerboard``, or ``SplitViewportHorizontal``. * Needs: ``--stereo``. * ``--eye-separation FLOAT``: Specify eye separation distance. * Needs: ``--stereo``. .. _sec:paraviewCommandLineArguments: |paraview|-Specific Options =========================== **Arguments controlling actions on application launch**: * ``filenames TEXT ...``: Positional arguments that may be used to pass either data, state, or script files. ``.pvsm`` files are treated as state files, ``.py`` are treated as scripts and all others are treated as data files. * Excludes: ``--state``, ``--script``, ``--data``. * ``--state TEXT`` State file (``.pvsm`` or ``.py``) to load when the application starts. * Excludes: ``--script``, ``--data``, ``filenames``. * ``--script TEXT``: Python script to execute when the application starts. * Excludes: ``--script``, ``--data``, ``filenames``. * ``--data TEXT ...``: Load the specified data file(s) when the client starts. For file series, replace the numeral with a dot (e.g., ``my0.vtk, my1.vtk...myN.vtk`` becomes ``my..vtk``). * Excludes: ``--state``, ``--script``, ``filenames``. * ``--live INT``: Connect to Catalyst Live session at the specified port number. Default is ``-1``. **Testing specific options**: * ``--baseline-directory TEXT``: Directory where the test recorder will store baseline images. * Can also be set via the ``PARAVIEW_TEST_BASELINE_DIR`` environment variable. * ``--test-directory TEXT``: Directory for temporary test results and files. * Can also be set via the ``PARAVIEW_TEST_DIR`` environment variable. * ``--data-directory TEXT``: Directory containing input data files for tests. * Can also be set via the ``PARAVIEW_DATA_ROOT`` environment variable. * ``--test-script TEXT ...``: Test scripts to execute, in the order specified on the command line. * ``--test-baseline TEXT: ...``: Specify baseline for test scripts provided. * ``--test-threshold FLOAT ...``: Test image comparison threshold for test scripts provided. * ``--exit``: Exits application when tests are finished. **Options affecting connections between client/server processes**: * ``--url``, ``--server-url TEXT``: Specify the server connection URL. On startup, the client will connect to the server using the URL specified. * Excludes: ``--server``. * ``-s``, ``--server TEXT``: Specify the server resource name for client connection. * Excludes: ``--url`` * ``--servers-file TEXT ...``: Additional servers configuration file(s) (``.pvsc``) to use. * ``--multi-servers``: (Experimental) Enables the client to connect to multiple independent servers at the same time. .. _sec:pvpythonCommandLineArguments: |pvpython|-Specific Options =========================== **Connection options**: These are the same as the connection options in the :ref:`sec:paraviewCommandLineArguments`. .. _sec:pvbatchCommandLineArguments: |pvbatch|-Specific Options ========================== **General options**: * ``-s``, ``--sym``, ``--symmetric``: When specified, the python script is processed symmetrically on all processes. .. _sec:pvserverCommandLineArguments: |pvserver|-Specific Options =========================== **Options affecting connections between client/server processes**: * ``--client-host TEXT``: Specify the hostname for reverse-connection mode. Default is ``localhost``. * ``-r``, ``--rc``, ``--reverse-connection``: Uses reverse connection mode, where instead of the client connecting to the server(s), the server(s) will connect back to the client. Default is ``0``. * ``-p``, ``--sp``, ``--server-port INT``: Port number to use to listen for connections from the client. In reverse-connection mode, this is the port number on which the client is listening for connections. Default is ``11111``. * ``--bind-address TEXT``: Specifies the address to bind the server socket to. Default is ``0.0.0.0``. * ``--timeout INT``: Specifies the timeout in minutes for a server connection. Default is ``0``. * ``--timeout-command TEXT``: Command for the server to periodically check remaining connection time. When executed, the command should write an integer value to stdout. * ``--timeout-command-interval INT``: Interval in seconds between consecutive calls to the timeout command. Default is ``60``. * Needs: ``--timeout-command``. **Tile-display specific options**: * ``--tdx``, ``--tile-dimensions-x INT``: Number of displays in the horizontal direction. * ``--tdy``, ``--tile-dimensions-y INT``: Number of displays in the vertical direction. * ``--tmx``, ``--tile-mullion-x INT``: Size of the gap in pixels between displays in the horizontal direction. * ``--tmy``, ``--tile-mullion-y INT``: Size of the gap in pixels between displays in the vertical direction. **CAVE specific options**: * ``--pvx TEXT``: ParaView CAVE configuration file (typically a ``.pvx`` file) that provides the configuration for screens in a CAVE. .. _sec:pvdataserverCommandLineArguments: |pvdataserver|-Specific Options =============================== **Connection options**: These are the same as in :ref:`sec:pvserverCommandLineArguments`, except that the ``-p, --sp, --server-port`` flag is replaced with: * ``-p``, ``--dsp``, ``--data-server-port INT``: Port number to use to listen for connections from the client. In reverse-connection mode, this is the port number on which the client is listening for connections. Default is ``11111``. .. _sec:pvrenderserverCommandLineArguments: |pvrenderserver|-Specific Options ================================= The **Tile Display**, **CAVE** and **Connection options** are the same as those in :ref:`sec:pvserverCommandLineArguments`, except that the ``-p, --sp, --server-port`` connection option is replaced with: * ``-p``, ``--rsp``, ``--render-server-port INT``: Port number to use to listen for connections from the client. In reverse-connection mode, this is the port number on which the client is listening for connections. Default is ``22221``.