# Running pyFormex

To run pyFormex, simply enter the command `pyformex` in a terminal window. This will start the Graphical User Interface (GUI), from where you can launch examples or load, edit and run your own scripts.

The installation procedure may have installed into your desktop menu or even have created a start button in the desktop panel. These provide convenient shortcuts to start the GUI by the click of a mouse button.

The program takes some optional command line arguments, that modify the behaviour of the program. Appendix Command line options gives a full list of all options. For normal use however you will seldom need to use any of them. Therefore, we will only explain here the more commonly used ones.

By default, sends diagnostical and informational messages to the terminal from which the program was started. Sometimes this may be inconvenient, e.g. because the user has no access to the starting terminal. You can redirect these messages to the message window of the GUI by starting pyformex with the command `pyformex --redirect`. The desktop starters installed by the installation procedure use this option.

In some cases the user may want to use the mathematical power of without the GUI. This is e.g. useful to run complex automated procedures from a script file. For convenience, will automatically enter this batch mode (without GUI) if the name of a script file was specified on the command line; when a script file name is absent, start in GUI mode. Even when specifying a script file, You can still force the GUI mode by adding the option –gui to the command line.

# Command line options

The following is a complete list of the options for the pyformex command.This output can also be generated by the command `pyformex --help`.

    usage: pyformex [-h] [--version] [--gui] [--nogui] [--nocanvas]
                    [--interactive] [--uselib] [--nouselib] [--config CONFIG]
                    [--nodefaultconfig] [--redirect] [--noredirect]
                    [--debug DEBUG] [--debuglevel DEBUGLEVEL] [--mesa] [--dri]
                    [--nodri] [--opengl OPENGL] [--shader SHADER] [--vtk VTK]
                    [--newviewports] [--testcamera] [--memtrack] [--fastnurbs]
                    [--pyside] [--pyqt4] [--unicode] [--experimental]
                    [--listfiles] [--listmodules [PKG [PKG ...]]] [--search]
                    [--remove] [--whereami] [--detect]
                    [--doctest [MODULE [MODULE ...]]]
                    [--pytest [MODULE [MODULE ...]]]
                    [--docmodule [MODULE [MODULE ...]]] [-c SCRIPT]
                    [FILE [FILE ...]]

    pyFormex is a tool for generating, manipulating and transforming large
    geometrical models of 3D structures by sequences of mathematical
    transformations.

    positional arguments:
      FILE                  pyFormex script files to be executed on startup. The
                            files should have a .py extension. Their contents will
                            be executed as a pyFormex script. While mostly used
                            with the --nogui option, this will also work in GUI
                            mode.

    optional arguments:
      -h, --help            show this help message and exit
      --version             show program's version number and exit
      --gui                 Start the GUI (this is the default when no scriptname
                            argument is given)
      --nogui               Do not start the GUI (this is the default when a
                            scriptname argument is given)
      --nocanvas            Do not add an OpenGL canvas to the GUI (this is for
                            development purposes only!)
      --interactive         Go into interactive mode after processing the command
                            line parameters. This is implied by the --gui option.
      --uselib              Use the pyFormex C lib if available. This is the
                            default.
      --nouselib            Do not use the pyFormex C-lib.
      --config CONFIG       Use file CONFIG for settings. This file is loaded in
                            addition to the normal configuration files and
                            overwrites their settings. Any changes will be saved
                            to this file.
      --nodefaultconfig     Skip the default site and user config files. This
                            option can only be used in conjunction with the
                            --config option.
      --redirect            Redirect standard output to the message board (ignored
                            with --nogui)
      --noredirect          Do not redirect standard output to the message board.
      --debug DEBUG         Display debugging information to sys.stdout. The value
                            is a comma-separated list of (case-insensitive)
                            strings corresponding with the attributes of the
                            DebugLevels class. The individual values are OR-ed
                            together to produce a final debug value. The special
                            value 'all' can be used to switch on all debug info.
      --debuglevel DEBUGLEVEL
                            Display debugging info to sys.stdout. The value is an
                            int with the bits of the requested debug levels set. A
                            value of -1 switches on all debug info. If this option
                            is used, it overrides the --debug option.
      --mesa                Force the use of software 3D rendering through the
                            mesa libs. The default is to use hardware accelerated
                            rendering whenever possible. This flag can be useful
                            when running pyFormex remotely on another host. The
                            hardware accelerated version will not work over remote
                            X.
      --dri                 Use Direct Rendering Infrastructure. By default,
                            direct rendering will be used if available.
      --nodri               Do not use the Direct Rendering Infrastructure. This
                            may be used to turn off the direc rendering, e.g. to
                            allow better capturing of images and movies.
      --opengl OPENGL       Force the use of a specific OpenGL version. The
                            version should be specified as a string 'a.b'. The
                            default is 2.0
      --shader SHADER       Force the use of an alternate GPU shader for the
                            OpenGL rendering. If the default selected shader does
                            not work well for your hardware, you can use this
                            option to try one of the alternate shaders. See
                            'pyformex --detect' for a list of the available
                            shaders.
      --vtk VTK             Specify which version of python-vtk to use in vtk_itf
                            plugin. The value can be one of: 'standard', 'light',
                            or 'default'. 'standard' is the version as distributed
                            from python-vtk. 'light' is the trimmed vtk6 version
                            as distributed with pyFormex.
      --newviewports        Use the new multiple viewport canvas implementation.
                            This is an experimental feature only intended for
                            developers.
      --testcamera          Print camera settings whenever they change.
      --memtrack            Track memory for leaks. This is only for developers.
      --fastnurbs           Test C library nurbs drawing: only for developers!
      --pyside              Use the PySide bindings for QT4 libraries
      --pyqt4               Use the PyQt4 bindings for QT4 libraries
      --unicode             Allow unicode filenames. Beware: this is experimental!
      --experimental        Allow the pyformex/experimental modules to be loaded.
                            Beware: this should only be used if you know what you
                            are doing!
      --listfiles           List the pyFormex Python source files and exit.
      --listmodules [PKG [PKG ...]]
                            List the Python modules in the specified pyFormex
                            subpackage and exit. Specify 'core' to just list the
                            modules in the pyFormex top level. Specify 'all' to
                            list all modules. The default is to list the modules
                            in core, lib, plugins, gui, opengl.
      --search              Search the pyformex source for a specified pattern and
                            exit. This can optionally be followed by -- followed
                            by options for the grep command and/or '-a' to search
                            all files in the extended search path. The final
                            argument is the pattern to search. '-e' before the
                            pattern will interprete this as an extended regular
                            expression. '-l' option only lists the names of the
                            matching files.
      --remove              Remove the pyFormex installation and exit. This option
                            only works when pyFormex was installed from a tarball
                            release using the supplied install procedure. If you
                            install from a distribution package (e.g. Debian), you
                            should use your distribution's package tools to remove
                            pyFormex. If you run pyFormex directly from SVN
                            sources, you should just remove the whole checked out
                            source tree.
      --whereami            Show where the pyformex package is installed and exit.
      --detect              Show detected helper software and exit.
      --doctest [MODULE [MODULE ...]]
                            Run the docstring tests for the specified pyFormex
                            modules and exit. MODULE name is specified in Python
                            syntax, relative to pyformex package (e.g. coords,
                            plugins.curve).
      --pytest [MODULE [MODULE ...]]
                            Run the pytest tests for the specified pyFormex
                            modules and exit. MODULE name is specified in Python
                            syntax, relative to pyformex package (e.g. coords,
                            plugins.curve).
      --docmodule [MODULE [MODULE ...]]
                            Print the autogenerated documentation for module
                            MODULE and exit. This is mostly useful during the
                            generation of the pyFormex reference manual, as the
                            produced result still needs to be run through the
                            Sphinx documentation generator. MODULE is the name of
                            a pyFormex module (Python syntax).
      -c SCRIPT, --script SCRIPT
                            A pyFormex script to be executed at startup. It is
                            executed before any specified script files. This is
                            mostly used in --nogui mode, when the script to
                            execute is very short.

    More info on http://pyformex.org

# Running without the GUI

If you start with the `--nogui` option, no Graphical User Interface is created. This is extremely useful to run automated scripts in batch mode. In this operating mode, will interprete all arguments remaining after interpreting the options, as filenames of scripts to be run (and possibly arguments to be interpreted by these scripts). Thus, if you want to run a script myscript.py in batch mode, just give the command pyformex myscript.py.

The running script has access to the remaining arguments in the global list variable argv. The script can use any arguments of it and pop them of the list. Any arguments remaining in the argv list when the script finishes, will be used for another execution cycle. This means that the first remaining argument should again be a script.