Scene authoring tools: Difference between revisions
No edit summary |
Eric Martz (talk | contribs) |
||
| (38 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
The '''Scene authoring | The '''Scene authoring tool''' (SAT) is used to create and edit molecular scenes. Scenes created using the ''Scene authoring tool'' can then be inserted into [[Proteopedia]] pages. This is a reference page explaining the details once you are familiar with the basics. For a tutorial introduction, see [[Proteopedia:DIY:Scenes|Instructions for creating a molecular scene with Proteopedia's Scene Authoring Tools]], and watch the introductory videos, e.g. [https://youtu.be/P-LsB2U8rNM]. | ||
==Where are the ''Scene authoring tools''== | ==Where are the ''Scene authoring tools''?== | ||
[[Image:SAT show.JPG|350px]] | |||
The ''Scene authoring tools'' are accessible when you are editing a page. Click the tab '''edit this page''' at the top of the page where you wish to create a molecular scene. On the edit page, near the top, you'll see a big box where all the wikitext of the page lives--here you can change the text of the page. If you scroll down some, near the bottom, you'll find in bold letters '''Scene authoring tools [show]'''. Click on '''show''' to expand and open the ''Scene authoring tools''. | The ''Scene authoring tools'' are accessible when you are editing a page. Click the tab '''edit this page''' at the top of the page where you wish to create a molecular scene. On the edit page, near the top, you'll see a big box where all the wikitext of the page lives--here you can change the text of the page. If you scroll down some, near the bottom, you'll find in bold letters '''SAT (Scene authoring tools) [show]'''. Click on '''show''' to expand and open the ''Scene authoring tools''. If, however, the page does not contain a Jmol window yet (no <Structure> or <StructureSection> tags), the page will lack access to the SAT. In this case, first edit the page to include a Jmol window (using the [[Image:Structure buttons.JPG|50px]] buttons above the text-editing area), save and then edit again to see the link to the SAT. New pages have placeholder content that includes these tags, but this page for example does not. | ||
<!-- | |||
<!--<Structure load=' | |||
---- | |||
Insert PDB code or filename here' size='350' frame='true' align='right' caption='Insert caption here' scene='Insert optional scene name here' /> | |||
A short and rough, temporary video tutorial can be viewed here: http://www.weizmann.ac.il/ISPC/Proteopedia.html. | A short and rough, temporary video tutorial can be viewed here: http://www.weizmann.ac.il/ISPC/Proteopedia.html. | ||
--> | --> | ||
| Line 21: | Line 25: | ||
#Provide a figure caption, decide on whether the scene will be displayed, and save the scene with a meaningful name. | #Provide a figure caption, decide on whether the scene will be displayed, and save the scene with a meaningful name. | ||
#Inserting the scene into the Proteopedia page. | #Inserting the scene into the Proteopedia page. | ||
[[Image:SAT_tabs.JPG|600px]] | |||
Creating the 3D scene is mostly done with the controls available via the tabs, while the right side of the user interface is a Jmol viewer to preview the scene as it is built. | |||
There is a printable cheat sheet available giving an overview of the workflow and of the available choices [[Image:SAT overview.pdf]]. | There is a printable cheat sheet available giving an overview of the workflow and of the available choices [[Image:SAT overview.pdf]]. | ||
| Line 30: | Line 38: | ||
To load a file that has a PDB ID, input the ID into the first input area and click the load button. The file will be fetched from the PDB database. | To load a file that has a PDB ID, input the ID into the first input area and click the load button. The file will be fetched from the PDB database. | ||
To load a file that is not part of the PDB, first upload the file to Proteopedia at [[Special:Upload]] (you can get there also by using the link called 'upload file' on the left hand column-toolbar of Proteopedia). Once a file has been uploaded, you can specify its name in the input area next to the words "From Proteopedia | To load a file that is not part of the PDB, first upload the file to Proteopedia at [[Special:Upload]] (you can get there also by using the link called 'upload file' on the left hand column-toolbar of Proteopedia). Once a file has been uploaded, you can specify its name in the input area next to the words "From Proteopedia uploaded file" and click load. | ||
Uploaded file can have various formats recognized by Jmol's "load" command. For example, you can load a .PNGJ file to load coordinates and a 3D scene in one step. | Uploaded file can have various formats recognized by Jmol's "load" command. For example, you can load a .PNGJ file to load coordinates and a 3D scene in one step. | ||
There is a checkbox to add calculated positions of '''hydrogen''' atoms to the structure as it is loaded. This allows to show the multiplicity of bonds (i.e. whether a bond is a single, double or triple bond) in the 3D scenes. | |||
Another optional field allows to enter instructions that will be used to '''filter''' which atoms of the original model will be either loaded or ignored. | |||
For example, to load just the alpha carbons, to exclude water, include or exclude other hetero groups (ligands), load a specified biomolecule (biological unit), etc. See [[Biological Unit: Showing]] for instructions. | |||
You can also check the [{{ScriptingDoc}} Jmol Scripting Documentation] for details about the syntax of such filter specifications (in that page, search for <code style="color:maroon">load "filename" FILTER</code>). | |||
=='load scene' tab== | =='load scene' tab== | ||
The first | The first box shows the '''current page name'''. First, you proceed to choose the '''scene name''' using the drop-down selector. All scenes associated with the scenes inserted in the page you edit will be listed (see [[Remixing#Remixing_3D_scenes_from_Proteopedia|remixing scenes]]) . Once a scene is selected, all of its versions are available for selection using the drop-down '''version number''' menu. When a version number is selected, that version of the scene is loaded onto the Jmol applet that is part of the ''Scene authoring tools'' and the description and caption that were given to the scene are also recalled. At the same time, the wikitext that is needed for insertion of the scene into the page is displayed. | ||
Each distinct scene has 4 parameters to distinguish it from all other scenes: domain, pageId, scenename, and versionnumber (e.g. 77/778341/Ballstick/1). The '''domain''' are the first two digits of the pageId, and the '''pageId''' is the unique internal identifier of the Proteopedia page on which the scene was initially created. The '''scenename''' is given by the user. The '''versionnumber''' is incremental: If no scene by the given name exists for the given page, then the first version will be version 1. If there exist previous versions of the same scenename on the same pagename, then the newest saved version will not overwrite older versions of the scene, but will instead be automatically saved as the newest version (by incrementing the versionnumber by one). To find out which page is associated with a scene, create the URL of the script by prepending "proteopedia.org/wiki/scripts/" and appending ".spt". e.g. the scene called 77/778341/Ballstick/1 is stored at [https://proteopedia.org/wiki/scripts/77/778341/Ballstick/1.spt]. Inspection of the first couple of lines of the file shows, after the keyword "documentBase", that it originated from a user page. | |||
==Controls below the Jmol window== | |||
[[Image:SAT controls outside of tabs.JPG|600px]] | |||
These controls are available no matter which tab is open. The first line is informational, only; the "currently loaded" text area displays the name of the currently loaded file and its datestamp. | |||
Below that, you can select "ALL" or "NONE" to quickly select all or no atoms. To see which atoms are selected, use the controls next to "Show Selected with Halos". If you have something selected, you will see your selection highlighted by yellow halos. These halos are NOT part of your scene and have no impact other than to indicate to you what atoms are currently selected. | |||
The "<-Undo" and "Redo->" controls allow you to quickly correct mistakes, or to compare before and after changing the scene. | |||
===Advanced controls=== | |||
Opening the JSmol console allows you to get more information from Jmol (e.g. the command "show sequence" shows all the residues/groups that contain selected atoms). For one-line commands (e.g. "set zshade on") without feedback from the console, you can use the text input field and the "execute" button. More usage examples are at [[Jmol/Using the console]] and [[Jmol/Useful one-liners]]. | |||
=='selections' tab== | =='selections' tab== | ||
It is advised that you use selection halos while creating or modifying a selection to make sure your selection is the one you want before you change the scene. | |||
The selections tab is used to select particular groups of atoms so that you can later change that group's color, representations, or labels. When you choose a representation, a color, or a label using the ''Scene authoring tools'' other tabs, the change is almost always applied ONLY to the currently selected atoms. That is why it is important to be aware of what atoms are selected at any given time. | |||
=== | ===build your selection=== | ||
[[Image:SAT build selection.JPG|500px]] | |||
In the "build your selection" box, you can select by group, sites, chains, residue types, residue numbers and chemical elements. For example, you could select all sulfur atoms in cysteine residues of chain B of the model by entering those specifications (see input in picture above). The buttons below determine what happens to the selection you just built. You can use it as your new selection ("replace selection") or you can combine it with the current selection in different ways ("add to selection", "remove from selection"). | |||
Each input box allows you to specify certain parameters in order to best choose what to add or remove to/from your selection. There is an imaginary 'AND' (or intersection) connecting each input box (a Boolean AND), but an 'OR' (or union) connecting the chosen elements within each input box. What this means is that if you choose in the 'groups' box the items 'all protein' and 'dna' and in the 'limit to elements' box you type in 'C,O' and click "add to selection", then you will add to your selection all the carbon and oxygen atoms that are part of either the protein or the dna in your loaded file (it's like saying "(all protein OR dna) AND (carbon OR oxygen)" ) | Each input box allows you to specify certain parameters in order to best choose what to add or remove to/from your selection. There is an imaginary 'AND' (or intersection) connecting each input box (a Boolean AND), but an 'OR' (or union) connecting the chosen elements within each input box. What this means is that if you choose in the 'groups' box the items 'all protein' and 'dna' and in the 'limit to elements' box you type in 'C,O' and click "add to selection", then you will add to your selection all the carbon and oxygen atoms that are part of either the protein or the dna in your loaded file (it's like saying "(all protein OR dna) AND (carbon OR oxygen)" ) | ||
The 'groups' | The 'groups' selector lists various pre-defined groups of atoms by name. You can select more than one item by pressing the <ctrl> key while selecting items. The 'limit to chains' box allows you to choose specific chains by the names they are given in the loaded file (ex: A,C,D). The 'limit to resi types' allows specification of residues by their 3-letter codes (ex: PHE,ALA,GLY). The 'limit to residue nos' box allows specification of residues by their number (ex: 18,23-25,32). The 'limit to elements' box allows choosing specific elements or even specific isotopes (ex: Fe,2H,31P). The 'limit to atom nos' box allows specifying atoms by their number. The 'sites' box appears only if your file is a PDB file that has predefined sites that the authors defined when they submitted the file to the Protein Data Bank. | ||
The button 'add to selection' checks the information that was specified by you in the boxes in the 'add to or remove from selection' area and then adds what you specified into the current selection. The 'remove from selection' does the same, but rather than adding to the current selection, it removes from the current selection. | The button 'add to selection' checks the information that was specified by you in the boxes in the 'add to or remove from selection' area and then adds what you specified into the current selection. The 'remove from selection' does the same, but rather than adding to the current selection, it removes from the current selection. | ||
===invert and center=== | |||
The "invert current selection" button selects everything that was not selected. The "center on current selection" places the center of rotation (when you or the reader of the page changes the orientation of the displayed structure with the mouse, or when spinning is on) on the currently selected atoms. | |||
===select within distance=== | ===select within distance=== | ||
The "select within distance" box allows you to select atoms within a specified distance form the currently selected atoms (these will remain selected). For example, if you had a ligand selected, and then specify a distance of 4 A and hit 'go', then all atoms within 4 Angstroms of that ligand would be added to your selection. Your selection would then be composed of the ligand as well as all atoms within 4 Angstroms of it.It also allows you to expand the selection to entire residues (or more generally "groups", i.e entire ligand, or building block of nucleic acids and carbohydrates). | |||
===mouse click selects=== | ===mouse click selects=== | ||
The "mouse click selects" allows you to change the effect of a mouse click from nothing to centering on the atom, or selecting all atoms of the same chemical elements by clicking on one of them, or selecting an entire group("residue/ligand") or an entire chain by clicking on one atom in it. | |||
Choosing 'default' sets it so that mouse clicks on the Jmol applet are set to their default setting in Jmol. In the default setting, clicking does not select or deselect any atoms, but clicking to create measurements is enabled. Choosing 'center' makes it so that any click on an atom, centers both the view and the axis of rotation on the atom. Choosing 'atom' is perhaps the most useful setting for creating selections as each click on an atom either adds it to the selection, or if it is already part of the selection, removes it from the selection. Choosing 'element' makes it so that clicking on an atom will select all other atoms of the same element. Choosing 'molecule' makes it so that clicking on an atom selects all other atoms of the same molecule. | Choosing 'default' sets it so that mouse clicks on the Jmol applet are set to their default setting in Jmol. In the default setting, clicking does not select or deselect any atoms, but clicking to create measurements is enabled. Choosing 'center' makes it so that any click on an atom, centers both the view and the axis of rotation on the atom. Choosing 'atom' is perhaps the most useful setting for creating selections as each click on an atom either adds it to the selection, or if it is already part of the selection, removes it from the selection. Choosing 'element' makes it so that clicking on an atom will select all other atoms of the same element. Choosing 'molecule' makes it so that clicking on an atom selects all other atoms of the same molecule. | ||
=='representations' tab== | =='representations' tab== | ||
This contains commands to draw selected parts of the structure, using different representations. | |||
===set selection representation=== | |||
The 'set selection representation' box provides a variety of choices for setting the representation of the current selection. Multiple representations can be turned on for the same selection of atoms (for instance using both wireframe and spacefill can create a 'ball and stick' scheme). Click on the representations that you would like to turn on for your current selection and then press 'set representation'. Every representation that has been checked off (to the left of the representation's name) will be displayed. Some representations have an input field to their direct right. If they do, then you may enter values in order to change the form of the representation, usually its size. If you leave the input field blank, the default will be used. | The 'set selection representation' box provides a variety of choices for setting the representation of the current selection. Multiple representations can be turned on for the same selection of atoms (for instance using both wireframe and spacefill can create a 'ball and stick' scheme). Click on the representations that you would like to turn on for your current selection and then press 'set representation'. Every representation that has been checked off (to the left of the representation's name) will be displayed. Some representations have an input field to their direct right. If they do, then you may enter values in order to change the form of the representation, usually its size. If you leave the input field blank, the default will be used. | ||
Clicking on 'hide selection' turns off all representations for the selection. | Clicking on 'hide selection' turns off all representations for the selection. | ||
===disulfide and hydrogen bonds=== | |||
This box allows you to choose how (covalent) disulfide bonds and (non-covalent) hydrogen bonds are drawn between the selected atoms. For disulfide bonds, you can use a schematic connecting the C-alpha carbon atoms of the backbone (appropriate when showing a backbone representation such as a cartoon) or the actual bonds between two sulfur atoms (appropriate when showing the side chain atoms, e.g. as ball-and-stick). | |||
=='colors' tab== | =='colors' tab== | ||
Here, you can color the current selection, the background and surfaces. | |||
===color=== | |||
The 'color' area first lets you choose whether you would like to change the color of the current selection, or of the background. The color palette is clickable and as soon as you click on a color, either your selection or the background (as was previously selected) will change to the clicked color. Hover over a color to view its name. There is a series of buttons below the color palette, each representing a specific color scheme. | The 'color' area first lets you choose whether you would like to change the color of the current selection, or of the background. The color palette is clickable and as soon as you click on a color, either your selection or the background (as was previously selected) will change to the clicked color. Hover over a color to view its name. There is a series of buttons below the color palette, each representing a specific color scheme. | ||
CPK is the standard CPK coloring scheme. Amino and amino2 color each amino acid as a different color. Chain colors each chain different colors. Spectrum colors protein and nucleic acids from blue to red on a spectrum with the N or 5' terminus as blue and the C or 3' terminus as red. Structure colors according to secondary structure. Fixed and relative temperature color according to temperature and formal and partial charge according to charge. DRuMS composition colors according to the DRuMS scheme (http://www.umass.edu/molvis/drums/). Hydrophobic/polar colors hydrophobic amino acids grey and polar (charged or uncharged) residues pink. Charge colors hydrophobic residues grey, polar-uncharged residues pink, cationic residues blue, anionic residues red, and backbone atoms purple whether charged or uncharged. More information on Jmol colors is available at http://jmol.sourceforge.net/jscolors/. | CPK is the standard CPK coloring scheme. Amino and amino2 color each amino acid as a different color. Chain colors each chain different colors. Spectrum colors protein and nucleic acids from blue to red on a spectrum with the N or 5' terminus as blue and the C or 3' terminus as red. Structure colors according to secondary structure. Fixed and relative temperature color according to temperature and formal and partial charge according to charge. DRuMS composition colors according to the DRuMS scheme (http://www.umass.edu/molvis/drums/). Hydrophobic/polar colors hydrophobic amino acids grey and polar (charged or uncharged) residues pink. Charge colors hydrophobic residues grey, polar-uncharged residues pink, cationic residues blue, anionic residues red, and backbone atoms purple whether charged or uncharged. More information on Jmol colors is available at http://jmol.sourceforge.net/jscolors/. | ||
===transparency=== | |||
The 'transparency' area allows you to render your selection transparent. Zero percent transparent will be opaque, 100 percent transparent will be invisible, and anywhere in between will be transparent to a degree. | The 'transparency' area allows you to render your selection transparent. Zero percent transparent will be opaque, 100 percent transparent will be invisible, and anywhere in between will be transparent to a degree. | ||
=='labels' tab== | =='labels' tab== | ||
This tab allows you to add labels to atoms that move with the atom as the structure is rotated and moved. It also also you to choose styles for measurements of distances and angles. | |||
The 'mouse click selects' area is similar to the 'mouse click selects' area in the 'selections' tab and allows changing between the ' | ===mouse click selects=== | ||
The 'mouse click selects' area is similar to the 'mouse click selects' area in the 'selections' tab and allows changing between the 'nothing' mouse picking style and the 'atom' mouse picking style. See the 'selections' tab section above for an explanation about the different mouse picking styles. | |||
===label selected atoms=== | |||
The 'label atoms' area is used to label atoms. First, an atom must be selected. Next, you choose how the label should look by choosing between entering text, displaying the atom name, the element, the 3-letter residue code, the residue number, and the chain letter of the atom being labeled (you can combine all of these options however you want). When you are ready to create the label, click on 'set label'. Note that if you have a selection of atoms when you assign a label by clicking 'set label', then each atom in the selection will get a label. 'Clear labels from selection' will clear all the labels from the current selection. To delete all labels, first 'select all' and then 'clear labels from selection'. | The 'label atoms' area is used to label atoms. First, an atom must be selected. Next, you choose how the label should look by choosing between entering text, displaying the atom name, the element, the 3-letter residue code, the residue number, and the chain letter of the atom being labeled (you can combine all of these options however you want). When you are ready to create the label, click on 'set label'. Note that if you have a selection of atoms when you assign a label by clicking 'set label', then each atom in the selection will get a label. 'Clear labels from selection' will clear all the labels from the current selection. To delete all labels, first 'select all' and then 'clear labels from selection'. | ||
To change the label properties, you can choose label color, label size, and an optional pointer from the label to the atom. | To change the label properties, you can choose label color, label size, and an optional pointer from the label to the atom. | ||
===measurements=== | |||
The 'measurements' area allows control over the appearance of measurements. Measurements can be created by a combination of double and single clicking on atoms while in the 'default' mouse picking setting. Measurements are explained in the 'how to' tab of the ''Scene authoring tools''. Here in the 'measurements' area, you can control the color, size, and units of the measurements. Changing the color or the size will affect all existing and future measurements but changing the units will only affect future measurements. The labels on the measurements can also be turned off or on. | The 'measurements' area allows control over the appearance of measurements. Measurements can be created by a combination of double and single clicking on atoms while in the 'default' mouse picking setting. Measurements are explained in the 'how to' tab of the ''Scene authoring tools''. Here in the 'measurements' area, you can control the color, size, and units of the measurements. Changing the color or the size will affect all existing and future measurements but changing the units will only affect future measurements. The labels on the measurements can also be turned off or on. | ||
=='save scene' tab== | =='save scene' tab== | ||
| Line 105: | Line 133: | ||
Once you have created your scene, you can save it here. | Once you have created your scene, you can save it here. | ||
You must choose a name for your scene, and enter a description. If you started by loading a scene, then by default, its name will appear as a suggested name for the scene you are about to save because Proteopedia assumes you might be editing a scene to save an updated version. If you specify the name of a scene that already exists, then your scene will be saved as the newest version (i.e. if versions 1 through 5 for that scene already exist, then your scene will be saved as version 6). | You must choose a name for your scene, and enter a description and a caption. The caption is displayed under the Jmol window when the scene is loaded. If you started by loading a scene, then by default, its name will appear as a suggested name for the scene you are about to save because Proteopedia assumes you might be editing a scene to save an updated version. If you specify the name of a scene that already exists, then your scene will be saved as the newest version (i.e. if versions 1 through 5 for that scene already exist, then your scene will be saved as version 6). | ||
After saving, wikitext for inserting your scene into the Proteopedia page will appear in the 'Wikitext' area. | After saving, wikitext for inserting your scene into the Proteopedia page will appear in the 'Wikitext' area, and a button for turning a selected word into a green link. | ||
==='advanced options' : choosing a non-standard scene transition=== | ==='advanced options' : choosing a non-standard scene transition=== | ||