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 command(s) to show only the backbone of the peptide (cartoons in
 124    * Jmol, chain in Chimera)
 125    *
 126    * @return
 127    */
 128   List<StructureCommandI> showBackbone();
 129
 130   /**
 131    * Returns a command to open a file at the given path
 132    *
 133    * @param file
 134    * @return
 135    */
 136   // refactor if needed to distinguish loading data or session files
 137   StructureCommandI loadFile(String file);
 138
 139   /**
 140    * Returns commands to set atom attributes or properties, given a map of
 141    * Jalview features as {featureType, {featureValue, AtomSpecModel}}. The
 142    * assumption is that one command can be constructed for each feature type and
 143    * value combination, to apply it to one or more residues.
 144    *
 145    * @param featureValues
 146    * @return
 147    */
 148   List<StructureCommandI> setAttributes(
 149           Map<String, Map<Object, AtomSpecModel>> featureValues);
 150
 151   /**
 152    * Returns command to open a saved structure viewer session file, or null if
 153    * not supported
 154    *
 155    * @param filepath
 156    * @return
 157    */
 158   StructureCommandI openSession(String filepath);
 159 }