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