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 [--verbose VERBOSE] [--gui] [--nogui] [--script SCRIPT]
                [--interactive] [--uselib] [--nouselib] [--config CONFIG]
                [--nodefaultconfig] [--geometry GEOMETRY]
                [--redirect REDIRECT] [--noredirect] [--debug DEBUG]
                [--debuglevel DEBUGLEVEL] [--debugitems] [--mesa] [--dri]
                [--nodri] [--gl3] [--mgl] [--opengl OPENGL] [--shader SHADER]
                [--nomultisample] [--fixcbo] [--bindings BINDINGS]
                [--memtrack] [--experimental] [--nocanvas] [--listfiles]
                [--listmodules [PKG ...]] [--search] [--remove] [--whereami]
                [--detect] [--doctest [MODULE ...]] [--pytest [MODULE ...]]
                [--docmodule [MODULE ...]] [--runall COUNT] [--version]
                [--usage] [--help]
                [FILE/APP [ARGS ... [++]] ...]

pyFormex is a tool for generating, manipulating and transforming large
geometrical models of 3D structures by sequences of mathematical
transformations. More info on http://pyformex.org

positional arguments:
  FILE/APP [ARGS ... [++]]
                        pyFormex script file or app to be executed on startup.
                        If it is a filename, it should have a .py suffix and
                        the contents will be executed in script mode. Else, it
                        is an app in Python pkg.module notation, and it should
                        be located under one of the application paths
                        specified in the 'appsdirs' configuration variable. In
                        both cases the arguments following FILE/APP will be
                        available to the script/app in a global variable
                        ``_argv_``. A '++' in the ARGS list ends the argument
                        list for the script/app, and the next argument will
                        again be interpreted as a FILE/APP. FILE/APP arguments
                        are mostly used in --nogui mode but also work in GUI
                        mode.

options:
  --verbose VERBOSE, -v VERBOSE
                        Set the verbosity level (0..5). (default: 2)
  --gui                 Start the GUI. This is the default when no FILE
                        argument is given.
  --nogui               Do not start the GUI. This is the default when a FILE
                        argument is given.
  --script SCRIPT, -c 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 be
                        executed is very short. (default: None)
  --interactive         Go into interactive mode after processing the command
                        line parameters. This is implied by the --gui option
                        and defaults to False with the --nogui option.
                        (default: False)
  --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. (default: None)
  --nodefaultconfig     Skip the default site and user config files. This
                        option can only be used in conjunction with the
                        --config option. (default: False)
  --geometry GEOMETRY   Set the main window geometry, overriding the user
                        settings. The value should be in X11 window geometry
                        style: WxH+X+Y. (default: None)
  --redirect REDIRECT   Override the 'gui/redirect' configuration setting.
                        Value should be one of 'oe', 'o', 'e' or ''.
  --noredirect          Do not redirect standard and error output to the
                        embedded Python console.
  --debug DEBUG         Display debugging information to sys.stdout. The value
                        is a comma-separated list of (case-insensitive) debug
                        items. Do 'pyformex --debugitems' to get a list of
                        available items. The special value 'all' can be used
                        to switch on all debug info. (default: None)
  --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. (default: 0)
  --debugitems          Show all available debug items and exit
  --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. (default: False)
  --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.
  --gl3                 Use the new development gl3 engine. Note: this is for
                        developers only. Most drawing functions will not work
                        if you use this. (default: False)
  --mgl                 Use moderngl instead of PyOpenGL. Note: this is for
                        developers only. Most drawing functions will not work
                        if you use this. (default: False)
  --opengl OPENGL       Force the use of a specific OpenGL version. The
                        version should be specified as a string 'a.b'.
                        (default: 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. (default: 130)
  --nomultisample       Switch off the use of multisample buffers in OpenGL.
                        (default: True)
  --fixcbo              Switch a bug on some graphics cards. (default: False)
  --bindings BINDINGS   Override the configuration setting for the Qt5
                        bindings. Available bindings are 'pyside2' or
                        'pyqt5'.A value 'any' may be given to let pyFormex
                        find out which bindings are available and use one of
                        these. (default: None)
  --memtrack            Track memory for leaks. This is only for developers.
                        (default: False)
  --experimental        Allow the pyformex/experimental modules to be loaded.
                        Beware: use only if you know what you are doing!
                        (default: False)
  --nocanvas            Do not add an OpenGL canvas to the GUI (use for
                        development purposes only!)
  --listfiles           List the pyFormex Python source files and exit.
  --listmodules [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 the git
                        source, you should just remove the whole cloned source
                        tree.
  --whereami            Show where the pyformex package is installed and exit.
  --detect              Show detected helper software and exit.
  --doctest [MODULE ...]
                        Run the docstring tests for the specified pyFormex
                        modules and exit. MODULE name is specified in Python
                        syntax, relative to the pyformex package (e.g. coords,
                        curve).
  --pytest [MODULE ...]
                        Run the pytest tests for the specified pyFormex
                        modules and exit. MODULE name is specified in Python
                        syntax, relative to the pyformex package (e.g. coords,
                        curve).
  --docmodule [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).
  --runall COUNT        Automatically run some random examples at startup.
                        Specify the number of examples, or -1 for all examples
                        (may take a while).
  --version             Show program's version number and exit
  --usage               Show pyformex command line usage and exit
  --help, -h            Show this help message and exit

All pyFormex options are available as long options. pyFormex options and
arguments may be preceded with (short) options for the Python interpreter. --,
-h or -c force the start of pyFormex options. Example: pyformex -v -- -v0 will
pass -v to Python and -v0 to pyFormex.

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.