--- /dev/null
+<html>
+<!--
+ * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
+ * Copyright (C) $$Year-Rel$$ The Jalview Authors
+ *
+ * This file is part of Jalview.
+ *
+ * Jalview is free software: you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation, either version 3
+ * of the License, or (at your option) any later version.
+ *
+ * Jalview is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty
+ * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+ * PURPOSE. See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with Jalview. If not, see <http://www.gnu.org/licenses/>.
+ * The Jalview Authors are detailed in the 'AUTHORS' file.
+ -->
+<head>
+<title>The Pymol PDB Viewer</title>
+</head>
+<body>
+ <p>
+ <strong>The Pymol Viewer</strong>
+ </p>
+ <p>
+ In Jalview 2.11.2, support was added for viewing structures opened
+ via the <a href="structurechooser.html"><strong>"View
+ Structure Data.."</strong> dialog</a> with <a
+ href="https://pymol.org/2/">Pymol</a> (https://pymol.org/2/). Like
+ with <a href="chimera.html">Chimera and ChimeraX</a>, Pymol views
+ can be saved and restored from Jalview Project files on any machine
+ with it installed, and structures can be coloured and superimposed
+ according to the alignment.
+ </p>
+ <p>
+ <em>Configuring Jalview to use Pymol</em><br /> You can configure
+ Pymol as your preferred structure viewer in <a
+ href="preferences.html#structure"> Preferences</a>. Jalview will
+ look for an existing installation, and will ask you to specify the
+ installation's path if it cannot be found. You can also optionally
+ specify the path to the Pymol program here if you want Jalview to
+ use a specific installation.
+ </p>
+ <p>
+ <strong>Jalview requires Pymol V 2.5.0 (community edition)
+ or later</strong> <br />Jalview requires Pymol's RPC interface, which is
+ not available in older versions of the Pymol community edition.
+ </p>
+ <p>
+ <strong>Known Limitations</strong><br />
+ </p>
+ <ul>
+ <li>Pymol does not support some forms of legacy structural data
+ (e.g. the 1A70 C-alpha only PDB file included in the Jalview
+ example project).</li>
+ <li>Pymol to Jalview communication does not support transfer of
+ properties or highlighting sequence regions corresponding to
+ structure selections or mouse-overs in Pymol.</li>
+ </ul>
+ <p>
+ Basic screen operations (see <a
+ href="https://pymol.org/dokuwiki/doku.php?id=mouse">Pymol Wiki</a>
+ at https://pymol.org/dokuwiki/doku.php?id=mouse for full details).
+ <table border="1">
+ <tr>
+ <td><strong>Action</strong></td>
+ <td><strong>Windows</strong></td>
+ <td><strong>Unix</strong></td>
+ <td><strong>Mac/OSX</strong></td>
+ </tr>
+ <tr>
+ <td>Rotate View</td>
+ <td>Left Click and Drag</td>
+ <td>Left Click and Drag</td>
+ <td>Left Click and Drag</td>
+ </tr>
+ <tr>
+ <td>Zoom</td>
+ <td>Right Click<br> drag mouse up or down
+ </td>
+ <td>Right Click<br>drag mouse up or down
+ </td>
+ <td>cmd or Right + Click and drag mouse up or down, <br>or
+ use mouse scroll button
+ </td>
+ </tr>
+ <tr>
+ <td>Move Origin</td>
+ <td>Middle Button + Drag</td>
+ <td>Middle Button and drag</td>
+ <td>alt + Click<br> and drag
+ </td>
+ </tr>
+ <tr>
+ <td>Select Residues</td>
+ <td>Ctrl + Click (and drag to select a region)</td>
+ <td>Ctrl + Click (and drag)</td>
+ <td>Ctrl + Click (and drag)</td>
+ </tr>
+ </table>
+ </p>
+ <p>
+ <strong>Jalview Controls</strong>
+ <p>The Jalview Pymol View window has up to five menus:</p>
+ <ul>
+ <li><Strong>File<br>
+ </strong>
+ <ul>
+ <li><strong>View Mapping<br>
+ </strong><em> Opens a text window showing the alignment between the
+ residues corresponding to alpha-carbon atoms in the PDB
+ structure and the residues in the associated sequence.</em></li>
+ </ul></li>
+ <li><strong>View</strong>
+ <ul>
+ <li><strong>Show Chains<br>
+ </strong><em>Select which of the PDB file's chains (if more than
+ one) are to be displayed.</em></li>
+ <li><strong>Colour by ..<br></strong><em>Submenu
+ allowing specific alignment views to be selected for
+ colouring associated chains in the structure display. This
+ menu contains all the alignment views associated with the
+ structure view, with those used to colour the view indicated
+ by ticks. Addditionally, it contains the following menu
+ entries:</em>
+ <ul>
+ <li><strong>Select many views<br></strong><em>When
+ this option is enabled, selecting an alignment view adds
+ it to the set used to colour the structures. Use this
+ when colouring structures related to a number of
+ alignments involving different domains or chains which
+ are shown in the same structure view.</em></li>
+ <li><strong>Select all views<br></strong><em>This
+ is only enabled when </em><strong>Select many views</strong><em>
+ is also enabled, and will add all associated views to
+ the set used to colour the structure display.</em></li>
+ <li><strong>Invert selection<br></strong><em>This
+ is only enabled when </em><strong>Select many views</strong><em>
+ is also enabled, and will replace the current set of
+ views with any remaining views not currently used to
+ colour the structure display.</em></li>
+ </ul></li>
+ </ul>
+ <li><strong>Colours<br>
+ </strong>
+ <ul>
+ <li><strong>By Sequence<br>
+ </strong><em> Colours each residue in the structure with the colour
+ of its corresponding residue in the associated sequence as
+ rendered in the associated alignment views, including any
+ UniProt sequence features or region colourings.<br />Pick
+ which of the associated alignment views are used to colour
+ the structures using the <strong>View→Colour
+ by ..</strong> sub menu.
+ </em><br> Residues which only exist in the PDB structure are
+ coloured white if they are insertions (relative to the
+ associated sequence in the alignment) and grey if they are N
+ or C terminal flanks outside the region mapped to the
+ alignment window's sequence.</em></li>
+ <li><strong>By Chain<br>
+ </strong><em>Uses Pymol's 'spectrum(chain)' command to apply a
+ different colour to each chain.</em></li>
+ <li><strong>Charge & Cysteine<br>
+ </strong><em> Highlights cysteines in yellow, anionic (Aspartic Acid
+ or Glutamic Acid) residues in red, and cationic (Lysine or
+ Arginine) residues in blue.</em></li>
+ <li><strong>Colour with Pymol<br></strong><em>Defers
+ any colouring operations to Pymol. Select this if you want
+ to use the Pymol scripting interface or menu to modify the
+ view directly.</em></li>
+ <li><strong>Standard and User Defined Jalview
+ colourschemes.<br>
+ </strong><em>The remaining entries apply the colourschemes available
+ from the standard and user defined <a
+ href="../colourSchemes/index.html">amino acid colours</a>.
+ </em></li>
+ </ul></li>
+ <li><strong>Pymol<br>
+ </strong><em>This pulldown menu provides access to Pymol's capabilities
+ from Jalview.</em>
+ <ul>
+ <li><strong><a name="sAlign">Align</a> <br> </strong><em>
+ When selected, the associated alignment will be used to
+ superimpose all the structures in the view onto the first
+ structure in the alignment via the pair_fit command. The regions used to calculate
+ the superposition will be highlighted using the 'Cartoon'
+ rendering style, and the remaining data shown as a chain
+ trace. RMSD values are output in the Pymol log.<br /> <br />
+ </em></li>
+ <li><a name="annotxfer"><strong>Write Jalview
+ features</strong></a><br /> <em>Selecting this option will create
+ new atom properties for any features currently visible in
+ the associated alignment views. This allows those atoms to
+ be selected and analysed in Pymol directly. </em><br>
+ <ul>
+ <li>Feature transfer in Pymol is experimental.</li>
+ <li>To select by a particular feature use the string
+ matching syntax:<br> select foo,p.jv_helix in helix
+ </li>
+ <li>To view transferred properties use Pymol's
+ Properties Inspector</li>
+ <li>For more information see <a
+ href="https://pymol.org/dokuwiki/doku.php?id=properties#selection_language">Property
+ based selection in Pymol's Documentation</a>.
+ </li>
+ </ul></li>
+ </ul></li>
+ <li><strong>Help<br>
+ </strong>
+ <ul>
+ <li><strong>Pymol Help<br>
+ </strong><em>Access the Pymol Help documentation in a new browser
+ window. window.</em></li>
+ </ul></li>
+ </ul>
+ <p>
+ <strong>Troubleshooting</strong>
+ </p>
+ Jalview will try to automatically configure itself according to the
+ configured Pymol installation (or the first one it discovers in the
+ standard installation locations). You can see which Pymol executable
+ is being used by enabling
+ <em>DEBUG</em> output in
+ <a href="../logging.html">Jalview's Java console</a>.
+ <br />
+ <br />If Jalview raises warning messages about Pymol not being located
+ or executed, or no structures appear when Jalview launches Pymol,
+ please ask for help on
+ <a href="https://discourse.jalview.org">Jalview's discussion forum</a>.
+ <p>
+ <strong>Pymol and Windows Firewall</strong>
+ </p>
+ Jalview and Pymol communicate using the
+ <a href="https://pymolwiki.org/index.php/RPC">Pymol's XML-RPC over
+ HTTP interface</a> (https://pymolwiki.org/index.php/RPC).
+
+ <br> Technically this requires both Pymol and Jalview to open
+ ports on the local network, and this may be blocked by Windows
+ Firewall with a warning message such as
+ <br /> "Windows Firewall has blocked some features of this program"
+ (where the program may be java.exe or javaw.exe).
+ <br /> To allow Jalview and Pymol to interact, you may need to add
+ permission for the program to communicate over the network. This can
+ be done from the warning dialogue, or in Control Panel, Firewall
+ settings.
+</body>
+</html>
git://source.jalview.org / jalview.git / blobdiff