PyMOL Web Services

### PyMOL Web GUI (PWG) Files

We have invented PyMOL Web GUI (PWG) files in order to enable users to automatically launch PyMOL on their desktop when they click a link or open a web page with a frame referencing a PWG file.

PWG files are associated with a new MIME type (application/x-pymol) which binds the PyMOL desktop application to the (.pwg) file extension. This approach works much like other web helper applications, such as binding Acrobat Reader for opening .pdf files (via the application/x-pdf MIME type).

Using PyMOL Web GUI files provides a simple way of firing up a PyMOL instance for use with the web-based GUI. This can be done via a PWG file stored on the desktop, or via a PWG file linked on a web-page.

Normally, the first time a user clicks to download a .pwg file, a standard popup appears asking the which application should be associated with this file type. On some platforms (Windows & Mac) .pwg files should pre-associated with PyMOL, and thus, the user may simply need to confirm this choice (or perhaps choose which copy of PyMOL to open). Once the association has been made, subsequent PWG files linked from web pages should automatically start PyMOL.

Using Firefox on Windows, the "Opening start.pwg" popup appears, with the "Choose Helper Application" popup appearing after selecting "Open with" and "Other..." from the pull down. You will probably also want to select "Do this automatically from now on."
After clicking OK on the "Choose Helper Application" popup, the following popup remains. Clicking OK causes PyMOL to open properly using the contents of the PWG file.

PWG files contain only the minimal amount of information necessary for the server to launch and successfully connect with a web browser.

For example, the PWG file which launches Sample11 is merely:

    port 8081

which tells PyMOL to launch its PyMOL web server on port 8081. This assumption in such a scerario is that the current web page will direct content to that PyMOL server (and thus, will be subject to the browser's multi-origin security restrictions).

In contrast, the PWG file which launches the Sample 01 application is:

    root $PYMOL_PATH/modules/web/examples/sample01/htdocs
    browser

which tells PyMOL to (1) launch its internal web server on a dynamically assigned port with a root content directory of $PYMOL_PATH/modules/web/examples/sample01/htdocs and (2) open up a local browser window pointing at that server instance. The assumption in this scenario is that this newly-opened web page will be responsible for sending requests to the PyMOL server (and thus, will not be subject to the browser's multi-origin security restrictions).

#### Commands

`port <number>` | Web server port
`root <directory>` | Web server document root
`header add <key> <value>` | Add a HTTP response header (e.g.: `Access-Control-Allow-Origin *`) New in PyMOL 2.4
`options <pymol-launch-options>` | PyMOL launch options (e.g.: `-q -W 250`)
`browser` | Open a web browser for `http://localhost:port`
`launch <module>` | Import Python module and call `module.__launch__(cmd)`
`report <url>` | Make a request to `url + port`
`delete` | Delete the PWG file after processing
`logging <0/1>` | Can suppress `BaseHTTPRequestHandler.log_message`
`wrap_native_return_types` | Return `result` instead of `{'status': status, 'result': result}`