src/jalview/structure/StructureCommandsI.java

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