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