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.ext.rbvi.chimera;
23 import java.awt.Color;
24 import java.util.ArrayList;
25 import java.util.Arrays;
26 import java.util.List;
27 import java.util.Locale;
30 import jalview.structure.AtomSpecModel;
31 import jalview.structure.StructureCommand;
32 import jalview.structure.StructureCommandI;
33 import jalview.structure.StructureCommandsBase;
34 import jalview.util.ColorUtils;
37 * Routines for generating Chimera commands for Jalview/Chimera binding
42 public class ChimeraCommands extends StructureCommandsBase
44 // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/focus.html
45 private static final StructureCommand FOCUS_VIEW = new StructureCommand(
48 // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/listen.html#listresattr
49 private static final StructureCommand LIST_RESIDUE_ATTRIBUTES = new StructureCommand(
52 // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/stop.html
53 private static final StructureCommand CLOSE_CHIMERA = new StructureCommand(
56 // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/listen.html
57 private static final StructureCommand STOP_NOTIFY_SELECTION = new StructureCommand(
58 "listen stop selection");
60 private static final StructureCommand STOP_NOTIFY_MODELS = new StructureCommand(
61 "listen stop models");
63 // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/listen.html#listselection
64 private static final StructureCommand GET_SELECTION = new StructureCommand(
65 "list selection level residue");
67 private static final StructureCommand SHOW_BACKBONE = new StructureCommand(
68 "~display all;~ribbon;chain @CA|P");
70 private static final StructureCommandI COLOUR_BY_CHARGE = new StructureCommand(
71 "color white;color red ::ASP,GLU;color blue ::LYS,ARG;color yellow ::CYS");
73 // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/rainbow.html
74 private static final StructureCommandI COLOUR_BY_CHAIN = new StructureCommand(
77 // Chimera clause to exclude alternate locations in atom selection
78 private static final String NO_ALTLOCS = "&~@.B-Z&~@.2-9";
81 public StructureCommandI colourResidues(String atomSpec, Color colour)
83 // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/color.html
84 String colourCode = getColourString(colour);
85 return new StructureCommand("color " + colourCode + " " + atomSpec);
89 * Returns a colour formatted suitable for use in viewer command syntax
94 protected String getColourString(Color colour)
96 return ColorUtils.toTkCode(colour);
100 * Traverse the map of features/values/models/chains/positions to construct a
101 * list of 'setattr' commands (one per distinct feature type and value).
103 * The format of each command is
106 * <blockquote> setattr r <featureName> " " #modelnumber:range.chain
107 * e.g. setattr r jv_chain <value> #0:2.B,4.B,9-12.B|#1:1.A,2-6.A,...
115 public List<StructureCommandI> setAttributes(
116 Map<String, Map<Object, AtomSpecModel>> featureMap)
118 List<StructureCommandI> commands = new ArrayList<>();
119 for (String featureType : featureMap.keySet())
121 String attributeName = makeAttributeName(featureType);
124 * clear down existing attributes for this feature
126 // 'problem' - sets attribute to None on all residues - overkill?
127 // commands.add("~setattr r " + attributeName + " :*");
129 Map<Object, AtomSpecModel> values = featureMap.get(featureType);
130 for (Object value : values.keySet())
133 * for each distinct value recorded for this feature type,
134 * add a command to set the attribute on the mapped residues
135 * Put values in single quotes, encoding any embedded single quotes
137 AtomSpecModel atomSpecModel = values.get(value);
138 String featureValue = value.toString();
139 featureValue = featureValue.replaceAll("\\'", "'");
140 StructureCommandI cmd = setAttribute(attributeName, featureValue,
150 * Returns a viewer command to set the given residue attribute value on
151 * residues specified by the AtomSpecModel, for example
154 * setatr res jv_chain 'primary' #1:12-34,48-55.B
157 * @param attributeName
158 * @param attributeValue
159 * @param atomSpecModel
162 protected StructureCommandI setAttribute(String attributeName,
163 String attributeValue, AtomSpecModel atomSpecModel)
165 StringBuilder sb = new StringBuilder(128);
166 sb.append("setattr res ").append(attributeName).append(" '")
167 .append(attributeValue).append("' ");
168 sb.append(getAtomSpec(atomSpecModel, AtomSpecType.RESIDUE_ONLY));
169 return new StructureCommand(sb.toString());
173 * Makes a prefixed and valid Chimera attribute name. A jv_ prefix is applied
174 * for a 'Jalview' namespace, and any non-alphanumeric character is converted
179 * @see https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/setattr.html
182 protected String makeAttributeName(String featureType)
184 String attName = super.makeAttributeName(featureType);
187 * Chimera treats an attribute name ending in 'color' as colour-valued;
188 * Jalview doesn't, so prevent this by appending an underscore
190 if (attName.toUpperCase(Locale.ROOT).endsWith("COLOR"))
199 public StructureCommandI colourByChain()
201 return COLOUR_BY_CHAIN;
205 public List<StructureCommandI> colourByCharge()
207 return Arrays.asList(COLOUR_BY_CHARGE);
211 public String getResidueSpec(String residue)
213 return "::" + residue;
217 public StructureCommandI setBackgroundColour(Color col)
219 // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/set.html#bgcolor
220 return new StructureCommand("set bgColor " + ColorUtils.toTkCode(col));
224 public StructureCommandI focusView()
230 public List<StructureCommandI> showChains(List<String> toShow)
233 * Construct a chimera command like
235 * ~display #*;~ribbon #*;ribbon :.A,:.B
237 StringBuilder cmd = new StringBuilder(64);
238 boolean first = true;
239 for (String chain : toShow)
241 String[] tokens = chain.split(":");
242 if (tokens.length == 2)
244 String showChainCmd = tokens[0] + ":." + tokens[1];
249 cmd.append(showChainCmd);
255 * could append ";focus" to this command to resize the display to fill the
256 * window, but it looks more helpful not to (easier to relate chains to the
259 final String command = "~display #*; ~ribbon #*; ribbon :"
261 return Arrays.asList(new StructureCommand(command));
265 public List<StructureCommandI> superposeStructures(AtomSpecModel ref,
266 AtomSpecModel spec, AtomSpecType backbone)
269 * Form Chimera match command to match spec to ref
270 * (the first set of atoms are moved on to the second)
272 * match #1:1-30.B,81-100.B@CA #0:21-40.A,61-90.A@CA
274 * @see https://www.cgl.ucsf.edu/chimera/docs/UsersGuide/midas/match.html
276 StringBuilder cmd = new StringBuilder();
277 String atomSpecAlphaOnly = getAtomSpec(spec, backbone);
278 String refSpecAlphaOnly = getAtomSpec(ref, backbone);
279 cmd.append("match ").append(atomSpecAlphaOnly).append(" ")
280 .append(refSpecAlphaOnly);
283 * show superposed residues as ribbon
285 String atomSpec = getAtomSpec(spec, AtomSpecType.RESIDUE_ONLY);
286 String refSpec = getAtomSpec(ref, AtomSpecType.RESIDUE_ONLY);
287 cmd.append("; ribbon ");
288 cmd.append(atomSpec).append("|").append(refSpec).append("; focus");
290 return Arrays.asList(new StructureCommand(cmd.toString()));
294 public StructureCommandI openCommandFile(String path)
296 // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/filetypes.html
297 return new StructureCommand("open cmd:" + path);
301 public StructureCommandI saveSession(String filepath)
303 // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/save.html
304 return new StructureCommand("save " + filepath);
308 * Returns the range(s) modelled by {@code atomSpec} formatted as a Chimera
309 * atomspec string, e.g.
312 * #0:15.A,28.A,54.A,70-72.A|#1:2.A,6.A,11.A,13-14.A
317 * <li>#0 is a model number</li>
318 * <li>15 or 70-72 is a residue number, or range of residue numbers</li>
319 * <li>.A is a chain identifier</li>
320 * <li>residue ranges are separated by comma</li>
321 * <li>atomspecs for distinct models are separated by | (or)</li>
329 * @see https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/frameatom_spec.html
332 public String getAtomSpec(AtomSpecModel atomSpec, AtomSpecType specType)
334 StringBuilder sb = new StringBuilder(128);
335 boolean firstModel = true;
336 for (String model : atomSpec.getModels())
343 appendModel(sb, model, atomSpec, specType);
345 return sb.toString();
349 * A helper method to append an atomSpec string for atoms in the given model
356 protected void appendModel(StringBuilder sb, String model,
357 AtomSpecModel atomSpec, AtomSpecType specType)
359 sb.append("#").append(model).append(":");
361 boolean firstPositionForModel = true;
363 for (String chain : atomSpec.getChains(model))
365 chain = " ".equals(chain) ? chain : chain.trim();
367 List<int[]> rangeList = atomSpec.getRanges(model, chain);
368 for (int[] range : rangeList)
370 appendRange(sb, range[0], range[1], chain, firstPositionForModel,
372 firstPositionForModel = false;
375 if (specType == AtomSpecType.ALPHA)
378 * restrict to alpha carbon, no alternative locations
379 * (needed to ensuring matching atom counts for superposition)
381 sb.append("@CA").append(NO_ALTLOCS);
383 if (specType == AtomSpecType.PHOSPHATE)
385 sb.append("@P").append(NO_ALTLOCS);
390 public List<StructureCommandI> showBackbone()
392 return Arrays.asList(SHOW_BACKBONE);
396 public StructureCommandI loadFile(String file)
398 return new StructureCommand("open " + file);
402 public StructureCommandI openSession(String filepath)
404 // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/filetypes.html
405 // this version of the command has no dependency on file extension
406 return new StructureCommand("open chimera:" + filepath);
410 public StructureCommandI closeViewer()
412 return CLOSE_CHIMERA;
416 public List<StructureCommandI> startNotifications(String uri)
418 // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/listen.html
419 List<StructureCommandI> cmds = new ArrayList<>();
420 cmds.add(new StructureCommand("listen start models url " + uri));
421 cmds.add(new StructureCommand(
422 "listen start select prefix SelectionChanged url " + uri));
427 public List<StructureCommandI> stopNotifications()
429 List<StructureCommandI> cmds = new ArrayList<>();
430 cmds.add(STOP_NOTIFY_MODELS);
431 cmds.add(STOP_NOTIFY_SELECTION);
436 public StructureCommandI getSelectedResidues()
438 return GET_SELECTION;
442 public StructureCommandI listResidueAttributes()
444 return LIST_RESIDUE_ATTRIBUTES;
448 public StructureCommandI getResidueAttributes(String attName)
450 // this alternative command
451 // list residues spec ':*/attName' attr attName
452 // doesn't report 'None' values (which is good), but
453 // fails for 'average.bfactor' (which is bad):
454 return new StructureCommand("list residues attr '" + attName + "'");
458 public List<StructureCommandI> centerViewOn(List<AtomSpecModel> residues)
460 // TODO Auto-generated method stub