JAL-2416 score matrix gap symbol (if any) dynamically determined
[jalview.git] / help / html / features / jmol.html
1 <html>
2 <!--
3  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
4  * Copyright (C) $$Year-Rel$$ The Jalview Authors
5  * 
6  * This file is part of Jalview.
7  * 
8  * Jalview is free software: you can redistribute it and/or
9  * modify it under the terms of the GNU General Public License 
10  * as published by the Free Software Foundation, either version 3
11  * of the License, or (at your option) any later version.
12  *  
13  * Jalview is distributed in the hope that it will be useful, but 
14  * WITHOUT ANY WARRANTY; without even the implied warranty 
15  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
16  * PURPOSE.  See the GNU General Public License for more details.
17  * 
18  * You should have received a copy of the GNU General Public License
19  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
20  * The Jalview Authors are detailed in the 'AUTHORS' file.
21  -->
22 <head>
23 <title>The Jmol PDB Viewer</title>
24 </head>
25 <body>
26   <p>
27     <strong>The Jmol PDB Viewer</strong>
28   </p>
29   <p>
30     Since Jalview 2.3, <a href="http://jmol.sourceforge.net/">Jmol</a>
31     has been integrated into Jalview for interactively viewing
32     structures opened by entries in the <strong>&quot;Structure&quot;</strong>
33     submenu in the <a href="../menus/popupMenu.html">sequence id
34       pop-up menu</a> (if you can't see this, then you need to <a
35       href="viewingpdbs.html">associate a PDB structure</a> with
36     the sequence). Jmol is available from the Jalview desktop and should
37     also run in the JalviewLite applet, providing the browser supports
38     Java 1.5. If Jmol is not available, then the original <a
39       href="pdbviewer.html">internal pdb viewer</a> will be used as a
40     fallback.
41   </p>
42   <!-- <p>The following menu entries are provided for viewing structure data<br>
43   <ul>
44     <li>The <strong>&quot;Structure&#8594;View
45         Structure&#8594;</strong> submenu allows a single PDB structure to be chosen
46       for display from the available structures for a sequence.
47     </li>
48     <li>The <strong>&quot;Structure&#8594;View all <em>N</em>
49         structures
50     </strong> option will open a new window containing all structures associated
51       with the current selection.
52     </li>
53     <li>The <strong>&quot;Structure&#8594;View all <em>N</em>
54         representative structures
55     </strong> option will open a new window containing exactly one structure per
56       currently selected sequence.<br />
57     <em>The View representative structures option was introduced in
58         Jalview 2.8.1</em></li>
59   </ul>
60   <br> 
61 </p> -->
62   <p>
63     <a name="align"><strong>Superposing structures based on
64         their aligned sequences</strong></a><br> If several structures are
65     available on the alignment, you may add additional structures to an
66     existing Jmol view by selecting their entry in the appropriate
67     pop-up menu. Jalview will ask you if you wish to add the structure
68     to the existing alignment, and if you do, it will import and
69     superimpose the new PDB file using the corresponding positions from
70     the alignment. If the alignment is subsequently edited, you can use
71     the <a href="#sAlign"><em>Jmol&#8594;Align</em></a> menu option from
72     the menu bar of the structure view window to superpose the
73     structures using the updated alignment.<br> <em>Sequence
74       based structure superposition was added in Jalview 2.6</em>
75   </p>
76   <p>
77     <strong>Controls</strong><br> The structure is by default rendered
78     as a ribbon diagram. Moving the mouse over the structure brings up
79     tooltips giving the residue name, PDB residue number and chain code,
80     atom name and number ([RES]Num:Chain.AtomName#AtomNumber). If a
81     mapping exists to a residue in any associated sequences, then this
82     will be highlighted in each one's alignment window. The converse
83     also occurs - moving the mouse over an associated residue in an
84     alignment window highlights the associated atoms in the displayed
85     structures. Press B or use
86     <em>Select&#8594;Select Highlighted columns</em> from any linked
87     alignment window to mark the columns highlighted after mousing over
88     the structure.
89   </p>
90   <p>Selecting a residue highlights its associated sequence residue
91     and alpha carbon location. Double clicking an atom allows distances
92     to be measured from it to any other atom in the structure.</p>
93   <p>
94   <table border="1">
95     <tr>
96       <td><strong>Action</strong></td>
97       <td><strong>Windows</strong></td>
98       <td><strong>Unix</strong></td>
99       <td><strong>Mac/OSX</strong></td>
100     </tr>
101     <tr>
102       <td>Rotate View</td>
103       <td>Left Click and Drag</td>
104       <td>Left Click and Drag</td>
105       <td>Click and Drag</td>
106     </tr>
107     <tr>
108       <td>Zoom</td>
109       <td>Shift + Left Click<br> drag mouse up or down
110       </td>
111       <td>Shift + Left Click<br> or middle button<br>
112         drag mouse up or down
113       </td>
114       <td>Left-Alt + Click and drag mouse up or down</td>
115     </tr>
116     <tr>
117       <td>Select/<br> Deselect<br> Residue
118       </td>
119       <td>Left Click</td>
120       <td>Left Click</td>
121       <td>Click</td>
122     </tr>
123     <tr>
124       <td>Roll View</td>
125       <td>Shift + Left Click<br> drag mouse to left or right
126       </td>
127       <td>Shift + Left Click<br> or middle button<br>
128         drag mouse to left or right
129       </td>
130       <td>Left-Alt + Click and drag mouse to left or right</td>
131     </tr>
132     <tr>
133       <td>Move Origin</td>
134       <td>Shift+Control+Left Click<br> or Middle Button<br>
135         + Drag
136       </td>
137       <td>Middle-Button<br> and<br> drag
138       </td>
139       <td>Shift+Control+Left Click<br> or Middle Button<br>
140         and drag
141       </td>
142     </tr>
143     <tr>
144       <td>Jmol Menu</td>
145       <td>Right-Click</td>
146       <td>Right-Click</td>
147       <td>Apple-Click</td>
148     </tr>
149   </table>
150   </p>
151   <p>The window has up to five menus:
152   <ul>
153     <li><Strong>File<br>
154     </strong>
155       <ul>
156         <li><strong>Save As<br>
157         </strong><em>Save the displayed PDB File, or the current view as an
158             EPS or PNG file.</em></li>
159         <li><strong>View Mapping<br>
160         </strong><em> Opens a text window showing the alignment between the
161             residues corresponding to alpha-carbon atoms in the PDB
162             structure and the residues in the associated sequence.</em></li>
163       </ul></li>
164     <li><strong>View</strong>
165       <ul>
166         <li><strong>Show Chains<br>
167         </strong><em>Select which of the PDB file's chains are to be
168             displayed.</em></li>
169         <li><strong>Colour by ..<br></strong><em>Submenu
170             allowing specific alignment views to be selected for
171             colouring associated chains in the structure display. This
172             menu contains all the alignment views associated with the
173             structure view, with those used to colour the view indicated
174             by ticks. Addditionally, it contains the following menu
175             entries:</em>
176           <ul>
177             <li><strong>Select many views<br></strong><em>When
178                 this option is enabled, selecting an alignment view adds
179                 it to the set used to colour the structures. Use this
180                 when colouring structures related to a number of
181                 alignments involving different domains or chains which
182                 are shown in the same structure view.</em></li>
183             <li><strong>Select all views<br></strong><em>This
184                 is only enabled when </em><strong>Select many views</strong><em>
185                 is also enabled, and will add all associated views to
186                 the set used to colour the structure display.</em></li>
187             <li><strong>Invert selection<br></strong><em>This
188                 is only enabled when </em><strong>Select many views</strong><em>
189                 is also enabled, and will replace the current set of
190                 views with any remaining views not currently used to
191                 colour the structure display.</em></li>
192           </ul></li>
193       </ul>
194     <li><strong>Colours<br>
195     </strong>
196       <ul>
197         <li><strong>By Sequence<br>
198         </strong><em> Colours each residue in the structure with the colour
199             of its corresponding residue in the associated sequence as
200             rendered in the associated alignment views, including any
201             UniProt sequence features or region colourings.<br />Pick
202             which of the associated alignment views are used to colour
203             the structures using the <strong>View&#8594;Colour
204               by ..</strong> sub menu.
205         </em><br> Residues which only exist in the PDB structure are
206           coloured white if they are insertions (relative to the
207           associated sequence in the alignment) and grey if they are N
208           or C terminal flanks outside the region mapped to the
209           alignment window's sequence.</em></li>
210         <li><strong>By Chain<br>
211         </strong><em> Assigns a random colour to each PDB chain.</em>
212         <li><strong>Charge &amp; Cysteine<br>
213         </strong><em> Highlights cysteines in yellow, anionic (Aspartic Acid
214             or Glutamic Acid) residues in red, and cationic (Lysine or
215             Arginine) residues in blue.</em></li>
216         <li><strong>Colour with Jmol<br></strong><em>Defers
217             any colouring operations to Jmol. Select this if you want to
218             use the Jmol scripting interface or menu to modify the view
219             directly.</em></li>
220         <li><strong>Standard and User Defined Jalview
221             colourschemes.<br>
222         </strong><em>The remaining entries apply the colourschemes available
223             from the standard and user defined <a
224             href="../colourSchemes/index.html">amino acid
225               colours</a>.
226         </em></li>
227       </ul></li>
228     <li><strong>Jmol<br>
229     </strong><em>This pulldown menu is only displayed if there are multiple
230         structures shown in the Jmol window, and Jalview can also locate
231         at least two of the structures in the currently associated
232         alignment view.</em>
233       <ul>
234         <li><strong><a name="sAlign">Align</a> <br> </strong><em>
235             When selected, the associated alignment will be used to
236             superimpose all the structures in the view onto the first
237             structure in the alignment. The regions used to calculate
238             the superposition will be highlighted using the 'Cartoon'
239             rendering style, and the remaining data shown as a chain
240             trace.<br> (This option was introduced in Jalview 2.6)
241         </em></li>
242       </ul></li>
243     <li><strong>Help<br>
244     </strong>
245       <ul>
246         <li><strong>Jmol Help<br>
247         </strong><em>Access the Jmol Help documentation in a new browser
248             window.</em></li>
249       </ul></li>
250   </ul>
251   </p>
252   <p>
253     <strong>Functionality provided by Jmol</strong>
254   </p>
255   <p>Jmol's own functions are accessed by clicking the 'Jmol' logo
256     or right-clicking in the structure display area. Either way will
257     open the Jmol pop-up menu, which provides access to a number of
258     features for controlling the colour and display of molecules, adding
259     measurements and labels, plotting surfaces, and display animation.
260     The 'Set Picking' menu controls the behaviour of single and double
261     mouse clicking on the structure, and the 'Console' option opens the
262     Jmol scripting console.</p>
263   <p>
264     The state of each Jmol display is stored within <a
265       href="jalarchive.html">Jalview archives</a> as a Jmol state
266     recovery script file. This means that any Jmol visualization effects
267     that you add beyond those provided by Jalview will be able to be
268     stored and recovered along with the displayed alignments in Jalview.
269   </p>
270   <p>
271     <strong>More Information</strong>
272   </p>
273   <p>
274     Jmol is a sophisticated program in its own right, with its own
275     command console and scripting language. Only the essentials have
276     been described here - the interested reader is referred to <a
277       href="http://jmol.sourceforge.net/docs/">Jmol's own
278       comprehensive online documentation</a>.
279   </p>
280   </p>
281 </body>
282 </html>