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 import jalview.api.AlignmentViewPanel;
   8 import jalview.datamodel.SequenceI;
   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 a command to superpose structures by closest positioning of
  86    * residues in {@code atomSpec} to the corresponding residues in
  87    * {@code refAtoms}. If wanted, this may include commands to visually
  88    * highlight the residues that were used for the superposition.
  89    *
  90    * @param refAtoms
  91    * @param atomSpec
  92    * @return
  93    */
  94   List<StructureCommandI> superposeStructures(AtomSpecModel refAtoms,
  95           AtomSpecModel atomSpec);
  96
  97   /**
  98    * Returns a command to open a file of commands at the given path
  99    *
 100    * @param path
 101    * @return
 102    */
 103   StructureCommandI openCommandFile(String path);
 104
 105   /**
 106    * Returns a command to save the current viewer session state to the given
 107    * file
 108    *
 109    * @param filepath
 110    * @return
 111    */
 112   StructureCommandI saveSession(String filepath);
 113
 114   /**
 115    * Returns a representation of the atom set represented by the model, in
 116    * viewer syntax format. If {@code alphaOnly} is true, this is restricted to
 117    * Alpha Carbon (peptide) or Phosphorous (rna) only
 118    *
 119    * @param model
 120    * @param alphaOnly
 121    * @return
 122    */
 123   String getAtomSpec(AtomSpecModel model, boolean alphaOnly);
 124
 125   /**
 126    * Returns the lowest model number used by the structure viewer (likely 0 or
 127    * 1)
 128    *
 129    * @return
 130    */
 131   // TODO remove by refactoring so command generation is purely driven by
 132   // AtomSpecModel objects derived in the binding classes?
 133   int getModelStartNo();
 134
 135   /**
 136    * Returns command(s) to show only the backbone of the peptide (cartoons in
 137    * Jmol, chain in Chimera)
 138    *
 139    * @return
 140    */
 141   List<StructureCommandI> showBackbone();
 142
 143   /**
 144    * Returns a command to open a file at the given path
 145    *
 146    * @param file
 147    * @return
 148    */
 149   // refactor if needed to distinguish loading data or session files
 150   StructureCommandI loadFile(String file);
 151
 152   /**
 153    * Returns commands to set atom attributes or properties, given a map of
 154    * Jalview features as {featureType, {featureValue, AtomSpecModel}}. The
 155    * assumption is that one command can be constructed for each feature type and
 156    * value combination, to apply it to one or more residues.
 157    *
 158    * @param featureValues
 159    * @return
 160    */
 161   List<StructureCommandI> setAttributes(
 162           Map<String, Map<Object, AtomSpecModel>> featureValues);
 163 }