Scene authoring tools: Difference between revisions
Eric Martz (talk | contribs) |
|||
| (33 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''?== | ||
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''. | [[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 '''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 32: | 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 | 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== | ==Controls below the Jmol window== | ||
[[Image:SAT controls outside of tabs.JPG| | [[Image:SAT controls outside of tabs.JPG|600px]] | ||
These controls are available no matter which tab is open. | |||
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== | ||
| Line 53: | Line 70: | ||
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. | 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. | ||
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. 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 | ===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. | ||
| Line 84: | Line 105: | ||
=='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 113: | 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=== | ||