UCSF Chimera Web Data format

UCSF Chimera Web Data Format

Chimera web data files (chimerax files) allow websites to send information and instructions to a locally running instance of Chimera. While several types of files linked to web pages can use Chimera as a helper application, the chimerax type was designed specifically for Chimera. See also: sites that provide Chimera web data

Chimerax files can instruct Chimera to:

retrieve and open files from the Web, provided they are in supported formats
retrieve and open files from the Protein Data Bank using PDB identifiers
execute arbitrary Chimera commands
execute arbitrary Python code

By default, molecular structure files are opened without applying any New Molecules preferences; this avoids inconsistencies that could result from the different preference settings of different users. However, the noprefs attribute described below can be used to indicate that the preferences should be applied.

Chimera web data files have the extension .chimerax and the MIME type application/x-chimerax. The browser must be configured to recognize such files. Clicking a link to a chimerax file sends the data to a locally running instance of Chimera that has been enabled to accept web data; if there is none, another instance of Chimera will be started and used to open the data. If there are multiple running instances of Chimera set to accept web data, the file will be sent to the instance that most recently had focus (was most recently clicked into).

Chimerax files can also be opened directly in Chimera. The chimerax file type can be designated with the suffix .chimerax (part of the filename) or the prefix chimerax: (not part of the filename).

Users will be asked to confirm whether files containing Chimera commands and/or Python code should be accepted. Because commands and code written with malicious intent may harm a user's computer, only files from a trusted source should be accepted.

(Note to webmasters and database administrators: the MIME type application/x-chimerax should be mapped to the extension .chimerax in the server configuration file. A CGI script that generates Chimerax files on the fly should specify the header field Content-type as application/x-chimerax.)

Chimerax File Format

The format will be described by walking through an example file, test_std.chimerax (for a more formal definition, see the document type descriptor std_webdata.dtd).

Chimerax files are in XML format, as indicated by the first line in test_std.chimerax:

     
<?xml version="1.0"?>

The <ChimeraPuppet> tag has a type attribute indicating the name of the file (minus the .py suffix) that will be used to handle the chimerax file when it is received by Chimera.

     
<ChimeraPuppet type="std_webdata">

In this case, the file std_webdata.py (included with Chimera) will be used. The handler std_webdata.py should be used for chimerax files that conform to the standard format described here. Different handlers can be written (for files that vary from the standard format), but this requires a high level of familiarity with Python.

The <web_files> tag specifies files to be downloaded from the Web:

     
<web_files>
   <file name="myfile.pdb" format="text" 
   loc="http://mysite.edu/dir/subdir/myfile.pdb" />
</web_files>

It can have zero or more sub-tags named <file>, each with the following attributes:

name indicates the name of the file to which the URL contents will be saved locally
format must be either "text" (plain text) or "html" (if the URL points to an HTML file, with the data between <pre></pre> tags)
loc indicates the URL to the file
noprefs (optional), either "true" (default) or "false" (meaning to apply the user's New Molecules preferences to molecule models)

The <pdb_files> tag specifies structures to be downloaded from the Protein Data Bank:

     
<pdb_files>
   <pdb id="1gcn" noprefs="true" />
</pdb_files>

It can have zero or more sub-tags named <pdb>, each with the following attributes:

id, the PDB identifier of a structure
noprefs (optional), either "true" (default) or "false" (meaning to apply the user's New Molecules preferences)

The <commands> tag contains commands and code to be executed once the models have been opened:

     
<commands>
  <mid_cmd>repr stick</mid_cmd>
  <mid_cmd>scale 2</mid_cmd>
  <py_cmd> m = chimera.openModels.list()[0] </py_cmd>
  <py_cmd> m.color = chimera.colorTable.getColorByName('blue') </py_cmd>
</commands>

It can have two sub-tags:

zero or more sub-tags named <mid_cmd>, each containing a Chimera command to execute
zero or more sub-tags named <py_cmd>, each containing Python code to execute. The code may span more than one line; indenting (if any) must be consistent within that block of code.

Commands and code are executed in the order given in the file, and <py_cmd> and <mid_cmd> tags can be interspersed.

Finally, the closing <ChimeraPuppet> tag marks the end of information in the file.

     
</ChimeraPuppet>

UCSF Computer Graphics Laboratory / June 2012