2 * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
3 * Copyright (C) $$Year-Rel$$ The Jalview Authors
5 * This file is part of Jalview.
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.
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.
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.
21 package jalview.structure;
23 import java.awt.Color;
24 import java.util.Collections;
25 import java.util.List;
29 * Methods that generate commands that can be sent to a molecular structure
30 * viewer program (e.g. Jmol, Chimera, ChimeraX)
35 public interface StructureCommandsI
38 * Returns the command to colour by chain
42 StructureCommandI colourByChain();
45 * Returns the command to colour residues using a charge-based scheme:
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>
55 List<StructureCommandI> colourByCharge();
58 * Returns the command to colour residues with the colours provided in the
59 * map, one per three letter residue code
64 List<StructureCommandI> colourByResidues(Map<String, Color> colours);
67 * Returns the command to set the background colour of the structure viewer
72 StructureCommandI setBackgroundColour(Color col);
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.
83 List<StructureCommandI> colourBySequence(
84 Map<Object, AtomSpecModel> colourMap);
87 * Returns a command to centre the display in the structure viewer
91 StructureCommandI focusView();
94 * Returns a command to show only the selected chains. The items in the input
95 * list should be formatted as "modelid:chainid".
100 List<StructureCommandI> showChains(List<String> toShow);
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.
111 * - superpose based on which kind of atomType
114 List<StructureCommandI> superposeStructures(AtomSpecModel refAtoms,
115 AtomSpecModel atomSpec, AtomSpecType backbone);
118 * Returns a command to open a file of commands at the given path
123 StructureCommandI openCommandFile(String path);
126 * Returns a command to save the current viewer session state to the given
132 StructureCommandI saveSession(String filepath);
136 RESIDUE_ONLY, ALPHA, PHOSPHATE
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
148 String getAtomSpec(AtomSpecModel model, AtomSpecType specType);
151 * Returns the lowest model number used by the structure viewer (likely 0 or
156 // TODO remove by refactoring so command generation is purely driven by
157 // AtomSpecModel objects derived in the binding classes?
158 int getModelStartNo();
161 * Returns command(s) to show only the backbone of the peptide (cartoons in
162 * Jmol, chain in Chimera)
166 List<StructureCommandI> showBackbone();
169 * Returns a command to open a file at the given path
174 // refactor if needed to distinguish loading data or session files
175 StructureCommandI loadFile(String file);
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.
183 * @param featureValues
186 List<StructureCommandI> setAttributes(
187 Map<String, Map<Object, AtomSpecModel>> featureValues);
190 * Returns command to open a saved structure viewer session file, or null if
196 StructureCommandI openSession(String filepath);
199 * Returns command to restore a previously saved version of an existing structure viewer session file.
200 * Default implementation calls 'openSession'
204 StructureCommandI restoreSession(String filePath);
208 * Returns a command to ask the viewer to close down
212 StructureCommandI closeViewer();
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
222 List<StructureCommandI> startNotifications(String uri);
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
231 List<StructureCommandI> stopNotifications();
234 * Returns a command to ask the viewer for its current residue selection, or
235 * null if no such command is supported
239 StructureCommandI getSelectedResidues();
242 * Returns a command to list the unique names of residue attributes, or null
243 * if no such command is supported
247 StructureCommandI listResidueAttributes();
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
255 StructureCommandI getResidueAttributes(String attName);
257 List<StructureCommandI> centerViewOn(List<AtomSpecModel> residues);
259 default List<StructureCommandI> showHetatms(List<String> toShow) {
260 return Collections.EMPTY_LIST;