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    * @return
  90    */
  91   List<StructureCommandI> superposeStructures(AtomSpecModel refAtoms,
  92           AtomSpecModel atomSpec);
  93
  94   /**
  95    * Returns a command to open a file of commands at the given path
  96    *
  97    * @param path
  98    * @return
  99    */
 100   StructureCommandI openCommandFile(String path);
 101
 102   /**
 103    * Returns a command to save the current viewer session state to the given
 104    * file
 105    *
 106    * @param filepath
 107    * @return
 108    */
 109   StructureCommandI saveSession(String filepath);
 110
 111   /**
 112    * Returns a representation of the atom set represented by the model, in
 113    * viewer syntax format. If {@code alphaOnly} is true, this is restricted to
 114    * Alpha Carbon (peptide) or Phosphorous (rna) only
 115    *
 116    * @param model
 117    * @param alphaOnly
 118    * @return
 119    */
 120   String getAtomSpec(AtomSpecModel model, boolean alphaOnly);
 121
 122   /**
 123    * Returns the lowest model number used by the structure viewer (likely 0 or
 124    * 1)
 125    *
 126    * @return
 127    */
 128   // TODO remove by refactoring so command generation is purely driven by
 129   // AtomSpecModel objects derived in the binding classes?
 130   int getModelStartNo();
 131
 132   /**
 133    * Returns command(s) to show only the backbone of the peptide (cartoons in
 134    * Jmol, chain in Chimera)
 135    *
 136    * @return
 137    */
 138   List<StructureCommandI> showBackbone();
 139
 140   /**
 141    * Returns a command to open a file at the given path
 142    *
 143    * @param file
 144    * @return
 145    */
 146   // refactor if needed to distinguish loading data or session files
 147   StructureCommandI loadFile(String file);
 148
 149   /**
 150    * Returns commands to set atom attributes or properties, given a map of
 151    * Jalview features as {featureType, {featureValue, AtomSpecModel}}. The
 152    * assumption is that one command can be constructed for each feature type and
 153    * value combination, to apply it to one or more residues.
 154    *
 155    * @param featureValues
 156    * @return
 157    */
 158   List<StructureCommandI> setAttributes(
 159           Map<String, Map<Object, AtomSpecModel>> featureValues);
 160
 161   /**
 162    * Returns command to open a saved structure viewer session file, or null if
 163    * not supported
 164    *
 165    * @param filepath
 166    * @return
 167    */
 168   StructureCommandI openSession(String filepath);
 169
 170   /**
 171    * Returns a command to ask the viewer to close down
 172    *
 173    * @return
 174    */
 175   StructureCommandI closeViewer();
 176
 177   /**
 178    * Returns one or more commands to ask the viewer to notify model or selection
 179    * changes to the given uri. Returns null if this is not supported by the
 180    * structure viewer.
 181    *
 182    * @param uri
 183    * @return
 184    */
 185   List<StructureCommandI> startNotifications(String uri);
 186
 187   /**
 188    * Returns one or more commands to ask the viewer to stop notifying model or
 189    * selection changes. Returns null if this is not supported by the structure
 190    * viewer.
 191    *
 192    * @return
 193    */
 194   List<StructureCommandI> stopNotifications();
 195
 196   /**
 197    * Returns a command to ask the viewer for its current residue selection, or
 198    * null if no such command is supported
 199    *
 200    * @return
 201    */
 202   StructureCommandI getSelectedResidues();
 203
 204   /**
 205    * Returns a command to list the unique names of residue attributes, or null
 206    * if no such command is supported
 207    *
 208    * @return
 209    */
 210   StructureCommandI listResidueAttributes();
 211
 212   /**
 213    * Returns a command to list residues with an attribute of the given name,
 214    * with attribute value, or null if no such command is supported
 215    *
 216    * @return
 217    */
 218   StructureCommandI getResidueAttributes(String attName);
 219 }