src/jalview/structure/StructureCommandsI.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   3  * Copyright (C) $$Year-Rel$$ The Jalview Authors
   4  *
   5  * This file is part of Jalview.
   6  *
   7  * Jalview is free software: you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License
   9  * as published by the Free Software Foundation, either version 3
  10  * of the License, or (at your option) any later version.
  11  *
  12  * Jalview is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty
  14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE.  See the GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  19  * The Jalview Authors are detailed in the 'AUTHORS' file.
  20  */
  21 package jalview.structure;
  22
  23 import java.awt.Color;
  24 import java.util.Collections;
  25 import java.util.List;
  26 import java.util.Map;
  27
  28 /**
  29  * Methods that generate commands that can be sent to a molecular structure
  30  * viewer program (e.g. Jmol, Chimera, ChimeraX)
  31  *
  32  * @author gmcarstairs
  33  *
  34  */
  35 public interface StructureCommandsI
  36 {
  37   /**
  38    * Returns the command to colour by chain
  39    *
  40    * @return
  41    */
  42   StructureCommandI colourByChain();
  43
  44   /**
  45    * Returns the command to colour residues using a charge-based scheme:
  46    * <ul>
  47    * <li>Aspartic acid and Glutamic acid (negative charge) red</li>
  48    * <li>Lysine and Arginine (positive charge) blue</li>
  49    * <li>Cysteine - yellow</li>
  50    * <li>all others - white</li>
  51    * </ul>
  52    *
  53    * @return
  54    */
  55   List<StructureCommandI> colourByCharge();
  56
  57   /**
  58    * Returns the command to colour residues with the colours provided in the
  59    * map, one per three letter residue code
  60    *
  61    * @param colours
  62    * @return
  63    */
  64   List<StructureCommandI> colourByResidues(Map<String, Color> colours);
  65
  66   /**
  67    * Returns the command to set the background colour of the structure viewer
  68    *
  69    * @param col
  70    * @return
  71    */
  72   StructureCommandI setBackgroundColour(Color col);
  73
  74   /**
  75    * Returns commands to colour mapped residues of structures according to
  76    * Jalview's colouring (including feature colouring if applied). Parameter is
  77    * a map from Color to a model of all residues assigned that colour.
  78    *
  79    * @param colourMap
  80    * @return
  81    */
  82
  83   List<StructureCommandI> colourBySequence(
  84           Map<Object, AtomSpecModel> colourMap);
  85
  86   /**
  87    * Returns a command to centre the display in the structure viewer
  88    *
  89    * @return
  90    */
  91   StructureCommandI focusView();
  92
  93   /**
  94    * Returns a command to show only the selected chains. The items in the input
  95    * list should be formatted as "modelid:chainid".
  96    *
  97    * @param toShow
  98    * @return
  99    */
 100   List<StructureCommandI> showChains(List<String> toShow);
 101
 102   /**
 103    * Returns a command to superpose structures by closest positioning of
 104    * residues in {@code atomSpec} to the corresponding residues in
 105    * {@code refAtoms}. If wanted, this may include commands to visually
 106    * highlight the residues that were used for the superposition.
 107    *
 108    * @param refAtoms
 109    * @param atomSpec
 110    * @param backbone
 111    *          - superpose based on which kind of atomType
 112    * @return
 113    */
 114   List<StructureCommandI> superposeStructures(AtomSpecModel refAtoms,
 115           AtomSpecModel atomSpec, AtomSpecType backbone);
 116
 117   /**
 118    * Returns a command to open a file of commands at the given path
 119    *
 120    * @param path
 121    * @return
 122    */
 123   StructureCommandI openCommandFile(String path);
 124
 125   /**
 126    * Returns a command to save the current viewer session state to the given
 127    * file
 128    *
 129    * @param filepath
 130    * @return
 131    */
 132   StructureCommandI saveSession(String filepath);
 133
 134   enum AtomSpecType
 135   {
 136     RESIDUE_ONLY, ALPHA, PHOSPHATE
 137   };
 138
 139   /**
 140    * Returns a representation of the atom set represented by the model, in
 141    * viewer syntax format. If {@code alphaOnly} is true, this is restricted to
 142    * Alpha Carbon (peptide) or Phosphorous (rna) only
 143    *
 144    * @param model
 145    * @param specType
 146    * @return
 147    */
 148   String getAtomSpec(AtomSpecModel model, AtomSpecType specType);
 149
 150   /**
 151    * Returns the lowest model number used by the structure viewer (likely 0 or
 152    * 1)
 153    *
 154    * @return
 155    */
 156   // TODO remove by refactoring so command generation is purely driven by
 157   // AtomSpecModel objects derived in the binding classes?
 158   int getModelStartNo();
 159
 160   /**
 161    * Returns command(s) to show only the backbone of the peptide (cartoons in
 162    * Jmol, chain in Chimera)
 163    *
 164    * @return
 165    */
 166   List<StructureCommandI> showBackbone();
 167
 168   /**
 169    * Returns a command to open a file at the given path
 170    *
 171    * @param file
 172    * @return
 173    */
 174   // refactor if needed to distinguish loading data or session files
 175   StructureCommandI loadFile(String file);
 176
 177   /**
 178    * Returns commands to set atom attributes or properties, given a map of
 179    * Jalview features as {featureType, {featureValue, AtomSpecModel}}. The
 180    * assumption is that one command can be constructed for each feature type and
 181    * value combination, to apply it to one or more residues.
 182    *
 183    * @param featureValues
 184    * @return
 185    */
 186   List<StructureCommandI> setAttributes(
 187           Map<String, Map<Object, AtomSpecModel>> featureValues);
 188
 189   /**
 190    * Returns command to open a saved structure viewer session file, or null if
 191    * not supported
 192    *
 193    * @param filepath
 194    * @return
 195    */
 196   StructureCommandI openSession(String filepath);
 197
 198   /**
 199    * Returns command to restore a previously saved version of an existing
 200    * structure viewer session file. Default implementation calls 'openSession'
 201    *
 202    * @param filePath
 203    * @return
 204    */
 205   StructureCommandI restoreSession(String filePath);
 206
 207   /**
 208    * Returns a command to ask the viewer to close down
 209    *
 210    * @return
 211    */
 212   StructureCommandI closeViewer();
 213
 214   /**
 215    * Returns one or more commands to ask the viewer to notify model or selection
 216    * changes to the given uri. Returns null if this is not supported by the
 217    * structure viewer.
 218    *
 219    * @param uri
 220    * @return
 221    */
 222   List<StructureCommandI> startNotifications(String uri);
 223
 224   /**
 225    * Returns one or more commands to ask the viewer to stop notifying model or
 226    * selection changes. Returns null if this is not supported by the structure
 227    * viewer.
 228    *
 229    * @return
 230    */
 231   List<StructureCommandI> stopNotifications();
 232
 233   /**
 234    * Returns a command to ask the viewer for its current residue selection, or
 235    * null if no such command is supported
 236    *
 237    * @return
 238    */
 239   StructureCommandI getSelectedResidues();
 240
 241   /**
 242    * Returns a command to list the unique names of residue attributes, or null
 243    * if no such command is supported
 244    *
 245    * @return
 246    */
 247   StructureCommandI listResidueAttributes();
 248
 249   /**
 250    * Returns a command to list residues with an attribute of the given name,
 251    * with attribute value, or null if no such command is supported
 252    *
 253    * @return
 254    */
 255   StructureCommandI getResidueAttributes(String attName);
 256
 257   List<StructureCommandI> centerViewOn(List<AtomSpecModel> residues);
 258
 259   default List<StructureCommandI> showHetatms(List<String> toShow)
 260   {
 261     return Collections.EMPTY_LIST;
 262   }
 263 }