src/jalview/structure/StructureCommandsI.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   3  * Copyright (C) $$Year-Rel$$ The Jalview Authors
   4  *
   5  * This file is part of Jalview.
   6  *
   7  * Jalview is free software: you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License
   9  * as published by the Free Software Foundation, either version 3
  10  * of the License, or (at your option) any later version.
  11  *
  12  * Jalview is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty
  14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE.  See the GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  19  * The Jalview Authors are detailed in the 'AUTHORS' file.
  20  */
  21 package jalview.structure;
  22
  23 import java.awt.Color;
  24 import java.util.List;
  25 import java.util.Map;
  26
  27 /**
  28  * Methods that generate commands that can be sent to a molecular structure
  29  * viewer program (e.g. Jmol, Chimera, ChimeraX)
  30  *
  31  * @author gmcarstairs
  32  *
  33  */
  34 public interface StructureCommandsI
  35 {
  36   /**
  37    * Returns the command to colour by chain
  38    *
  39    * @return
  40    */
  41   StructureCommandI colourByChain();
  42
  43   /**
  44    * Returns the command to colour residues using a charge-based scheme:
  45    * <ul>
  46    * <li>Aspartic acid and Glutamic acid (negative charge) red</li>
  47    * <li>Lysine and Arginine (positive charge) blue</li>
  48    * <li>Cysteine - yellow</li>
  49    * <li>all others - white</li>
  50    * </ul>
  51    *
  52    * @return
  53    */
  54   List<StructureCommandI> colourByCharge();
  55
  56   /**
  57    * Returns the command to colour residues with the colours provided in the
  58    * map, one per three letter residue code
  59    *
  60    * @param colours
  61    * @return
  62    */
  63   List<StructureCommandI> colourByResidues(Map<String, Color> colours);
  64
  65   /**
  66    * Returns the command to set the background colour of the structure viewer
  67    *
  68    * @param col
  69    * @return
  70    */
  71   StructureCommandI setBackgroundColour(Color col);
  72
  73   /**
  74    * Returns commands to colour mapped residues of structures according to
  75    * Jalview's colouring (including feature colouring if applied). Parameter is
  76    * a map from Color to a model of all residues assigned that colour.
  77    *
  78    * @param colourMap
  79    * @return
  80    */
  81
  82   List<StructureCommandI> colourBySequence(
  83           Map<Object, AtomSpecModel> colourMap);
  84
  85   /**
  86    * Returns a command to centre the display in the structure viewer
  87    *
  88    * @return
  89    */
  90   StructureCommandI focusView();
  91
  92   /**
  93    * Returns a command to show only the selected chains. The items in the input
  94    * list should be formatted as "modelid:chainid".
  95    *
  96    * @param toShow
  97    * @return
  98    */
  99   List<StructureCommandI> showChains(List<String> toShow);
 100
 101   /**
 102    * Returns a command to superpose structures by closest positioning of
 103    * residues in {@code atomSpec} to the corresponding residues in
 104    * {@code refAtoms}. If wanted, this may include commands to visually
 105    * highlight the residues that were used for the superposition.
 106    *
 107    * @param refAtoms
 108    * @param atomSpec
 109    * @param backbone
 110    *          - superpose based on which kind of atomType
 111    * @return
 112    */
 113   List<StructureCommandI> superposeStructures(AtomSpecModel refAtoms,
 114           AtomSpecModel atomSpec, AtomSpecType backbone);
 115
 116   /**
 117    * Returns a command to open a file of commands at the given path
 118    *
 119    * @param path
 120    * @return
 121    */
 122   StructureCommandI openCommandFile(String path);
 123
 124   /**
 125    * Returns a command to save the current viewer session state to the given
 126    * file
 127    *
 128    * @param filepath
 129    * @return
 130    */
 131   StructureCommandI saveSession(String filepath);
 132
 133   enum AtomSpecType
 134   {
 135     RESIDUE_ONLY, ALPHA, PHOSPHATE
 136   };
 137
 138   /**
 139    * Returns a representation of the atom set represented by the model, in
 140    * viewer syntax format. If {@code alphaOnly} is true, this is restricted to
 141    * Alpha Carbon (peptide) or Phosphorous (rna) only
 142    *
 143    * @param model
 144    * @param specType
 145    * @return
 146    */
 147   String getAtomSpec(AtomSpecModel model, AtomSpecType specType);
 148
 149   /**
 150    * Returns the lowest model number used by the structure viewer (likely 0 or
 151    * 1)
 152    *
 153    * @return
 154    */
 155   // TODO remove by refactoring so command generation is purely driven by
 156   // AtomSpecModel objects derived in the binding classes?
 157   int getModelStartNo();
 158
 159   /**
 160    * Returns command(s) to show only the backbone of the peptide (cartoons in
 161    * Jmol, chain in Chimera)
 162    *
 163    * @return
 164    */
 165   List<StructureCommandI> showBackbone();
 166
 167   /**
 168    * Returns a command to open a file at the given path
 169    *
 170    * @param file
 171    * @return
 172    */
 173   // refactor if needed to distinguish loading data or session files
 174   StructureCommandI loadFile(String file);
 175
 176   /**
 177    * Returns commands to set atom attributes or properties, given a map of
 178    * Jalview features as {featureType, {featureValue, AtomSpecModel}}. The
 179    * assumption is that one command can be constructed for each feature type and
 180    * value combination, to apply it to one or more residues.
 181    *
 182    * @param featureValues
 183    * @return
 184    */
 185   List<StructureCommandI> setAttributes(
 186           Map<String, Map<Object, AtomSpecModel>> featureValues);
 187
 188   /**
 189    * Returns command to open a saved structure viewer session file, or null if
 190    * not supported
 191    *
 192    * @param filepath
 193    * @return
 194    */
 195   StructureCommandI openSession(String filepath);
 196
 197   /**
 198    * Returns a command to ask the viewer to close down
 199    *
 200    * @return
 201    */
 202   StructureCommandI closeViewer();
 203
 204   /**
 205    * Returns one or more commands to ask the viewer to notify model or selection
 206    * changes to the given uri. Returns null if this is not supported by the
 207    * structure viewer.
 208    *
 209    * @param uri
 210    * @return
 211    */
 212   List<StructureCommandI> startNotifications(String uri);
 213
 214   /**
 215    * Returns one or more commands to ask the viewer to stop notifying model or
 216    * selection changes. Returns null if this is not supported by the structure
 217    * viewer.
 218    *
 219    * @return
 220    */
 221   List<StructureCommandI> stopNotifications();
 222
 223   /**
 224    * Returns a command to ask the viewer for its current residue selection, or
 225    * null if no such command is supported
 226    *
 227    * @return
 228    */
 229   StructureCommandI getSelectedResidues();
 230
 231   /**
 232    * Returns a command to list the unique names of residue attributes, or null
 233    * if no such command is supported
 234    *
 235    * @return
 236    */
 237   StructureCommandI listResidueAttributes();
 238
 239   /**
 240    * Returns a command to list residues with an attribute of the given name,
 241    * with attribute value, or null if no such command is supported
 242    *
 243    * @return
 244    */
 245   StructureCommandI getResidueAttributes(String attName);
 246 }