src/jalview/structure/StructureCommandsI.java

   1 package jalview.structure;
   2
   3 import jalview.api.AlignmentViewPanel;
   4 import jalview.datamodel.SequenceI;
   5
   6 import java.awt.Color;
   7 import java.util.List;
   8 import java.util.Map;
   9
  10 /**
  11  * Methods that generate commands that can be sent to a molecular structure
  12  * viewer program (e.g. Jmol, Chimera, ChimeraX)
  13  *
  14  * @author gmcarstairs
  15  *
  16  */
  17 public interface StructureCommandsI
  18 {
  19   /**
  20    * Returns the command to colour by chain
  21    *
  22    * @return
  23    */
  24   StructureCommandI colourByChain();
  25
  26   /**
  27    * Returns the command to colour residues using a charge-based scheme:
  28    * <ul>
  29    * <li>Aspartic acid and Glutamic acid (negative charge) red</li>
  30    * <li>Lysine and Arginine (positive charge) blue</li>
  31    * <li>Cysteine - yellow</li>
  32    * <li>all others - white</li>
  33    * </ul>
  34    *
  35    * @return
  36    */
  37   List<StructureCommandI> colourByCharge();
  38
  39   /**
  40    * Returns the command to colour residues with the colours provided in the
  41    * map, one per three letter residue code
  42    *
  43    * @param colours
  44    * @return
  45    */
  46   List<StructureCommandI> colourByResidues(Map<String, Color> colours);
  47
  48   /**
  49    * Returns the command to set the background colour of the structure viewer
  50    *
  51    * @param col
  52    * @return
  53    */
  54   StructureCommandI setBackgroundColour(Color col);
  55
  56   /**
  57    * Returns commands to colour mapped residues of structures according to
  58    * Jalview's colouring (including feature colouring if applied). Parameter is
  59    * a map from Color to a model of all residues assigned that colour.
  60    *
  61    * @param colourMap
  62    * @return
  63    */
  64
  65   List<StructureCommandI> colourBySequence(
  66           Map<Object, AtomSpecModel> colourMap);
  67
  68   /**
  69    * Returns a command to centre the display in the structure viewer
  70    *
  71    * @return
  72    */
  73   StructureCommandI focusView();
  74
  75   /**
  76    * Returns a command to show only the selected chains. The items in the input
  77    * list should be formatted as "modelid:chainid".
  78    *
  79    * @param toShow
  80    * @return
  81    */
  82   List<StructureCommandI> showChains(List<String> toShow);
  83
  84   /**
  85    * Returns zero, one or more commands to set attributes on mapped residues in
  86    * the structure viewer for any features present and displayed in Jalview
  87    *
  88    * @param ssm
  89    * @param files
  90    * @param sequence
  91    * @param avp
  92    * @return
  93    */
  94   List<StructureCommandI> setAttributesForFeatures(
  95           StructureSelectionManager ssm,
  96           String[] files, SequenceI[][] sequence, AlignmentViewPanel avp);
  97
  98   /**
  99    * Returns a command to superpose structures by closest positioning of
 100    * residues in {@code atomSpec} to the corresponding residues in
 101    * {@code refAtoms}. If wanted, this may include commands to visually
 102    * highlight the residues that were used for the superposition.
 103    *
 104    * @param refAtoms
 105    * @param atomSpec
 106    * @return
 107    */
 108   List<StructureCommandI> superposeStructures(AtomSpecModel refAtoms,
 109           AtomSpecModel atomSpec);
 110
 111   /**
 112    * Returns a command to open a file of commands at the given path
 113    *
 114    * @param path
 115    * @return
 116    */
 117   StructureCommandI openCommandFile(String path);
 118
 119   /**
 120    * Returns a command to save the current viewer session state to the given
 121    * file
 122    *
 123    * @param filepath
 124    * @return
 125    */
 126   StructureCommandI saveSession(String filepath);
 127
 128   /**
 129    * Returns a representation of the atom set represented by the model, in
 130    * viewer syntax format. If {@code alphaOnly} is true, this is restricted to
 131    * Alpha Carbon (peptide) or Phosphorous (rna) only
 132    *
 133    * @param model
 134    * @param alphaOnly
 135    * @return
 136    */
 137   String getAtomSpec(AtomSpecModel model, boolean alphaOnly);
 138
 139   /**
 140    * Returns the lowest model number used by the structure viewer (likely 0 or
 141    * 1)
 142    *
 143    * @return
 144    */
 145   // TODO remove by refactoring so command generation is purely driven by
 146   // AtomSpecModel objects derived in the binding classes?
 147   int getModelStartNo();
 148
 149   /**
 150    * Returns command(s) to show only the backbone of the peptide (cartoons in
 151    * Jmol, chain in Chimera)
 152    *
 153    * @return
 154    */
 155   List<StructureCommandI> showBackbone();
 156
 157   /**
 158    * Returns a command to open a file at the given path
 159    *
 160    * @param file
 161    * @return
 162    */
 163   // refactor if needed to distinguish loading data or session files
 164   StructureCommandI loadFile(String file);
 165 }