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 superpose structures by closest positioning of
  74    * residues in {@code atomSpec} to the corresponding residues in
  75    * {@code refAtoms}. If wanted, this may include commands to visually
  76    * highlight the residues that were used for the superposition.
  77    *
  78    * @param refAtoms
  79    * @param atomSpec
  80    * @return
  81    */
  82   List<StructureCommandI> superposeStructures(AtomSpecModel refAtoms,
  83           AtomSpecModel atomSpec);
  84
  85   /**
  86    * Returns a command to open a file of commands at the given path
  87    *
  88    * @param path
  89    * @return
  90    */
  91   StructureCommandI openCommandFile(String path);
  92
  93   /**
  94    * Returns a command to save the current viewer session state to the given
  95    * file
  96    *
  97    * @param filepath
  98    * @return
  99    */
 100   StructureCommandI saveSession(String filepath);
 101
 102   /**
 103    * Returns a representation of the atom set represented by the model, in
 104    * viewer syntax format. If {@code alphaOnly} is true, this is restricted to
 105    * Alpha Carbon (peptide) or Phosphorous (rna) only
 106    *
 107    * @param model
 108    * @param alphaOnly
 109    * @return
 110    */
 111   String getAtomSpec(AtomSpecModel model, boolean alphaOnly);
 112
 113   /**
 114    * Returns command(s) to show only the backbone of the peptide (cartoons in
 115    * Jmol, chain in Chimera)
 116    *
 117    * @return
 118    */
 119   List<StructureCommandI> showBackbone();
 120
 121   /**
 122    * Returns a command to open a file at the given path
 123    *
 124    * @param file
 125    * @return
 126    */
 127   // refactor if needed to distinguish loading data or session files
 128   StructureCommandI loadFile(String file);
 129
 130   /**
 131    * Returns commands to set atom attributes or properties, given a map of
 132    * Jalview features as {featureType, {featureValue, AtomSpecModel}}. The
 133    * assumption is that one command can be constructed for each feature type and
 134    * value combination, to apply it to one or more residues.
 135    *
 136    * @param featureValues
 137    * @return
 138    */
 139   List<StructureCommandI> setAttributes(
 140           Map<String, Map<Object, AtomSpecModel>> featureValues);
 141
 142   /**
 143    * Returns command to open a saved structure viewer session file, or null if
 144    * not supported
 145    *
 146    * @param filepath
 147    * @return
 148    */
 149   StructureCommandI openSession(String filepath);
 150
 151   /**
 152    * Returns a command to show structures in the viewer. If {@code restrictTo}
 153    * is null, all structures are included, otherwise the display is restricted
 154    * to positions represented in the model
 155    *
 156    * @param restrictTo
 157    * @return
 158    */
 159   StructureCommandI showStructures(AtomSpecModel restrictTo);
 160
 161   /**
 162    * Returns a command to hide the specified model chain in the structure viewer
 163    *
 164    * @param modelId
 165    * @param chainId
 166    * @return
 167    */
 168   StructureCommandI hideChain(String modelId, String chainId);
 169
 170   /**
 171    * Returns a command to hide everything in the structure viewer
 172    *
 173    * @return
 174    */
 175   StructureCommandI hideAll();
 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 }