src/jalview/ext/rbvi/chimera/ChimeraXCommands.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.ext.rbvi.chimera;
  22
  23 import java.awt.Color;
  24 import java.util.ArrayList;
  25 import java.util.Arrays;
  26 import java.util.List;
  27
  28 import jalview.structure.AtomSpecModel;
  29 import jalview.structure.StructureCommand;
  30 import jalview.structure.StructureCommandI;
  31 import jalview.structure.StructureCommandsI.AtomSpecType;
  32
  33 /**
  34  * Routines for generating ChimeraX commands for Jalview/ChimeraX binding
  35  */
  36 public class ChimeraXCommands extends ChimeraCommands
  37 {
  38   // https://www.cgl.ucsf.edu/chimerax/docs/user/commands/info.html#resattr
  39   private static final StructureCommand LIST_RESIDUE_ATTRIBUTES = new StructureCommand(
  40           "info resattr");
  41
  42   // https://www.cgl.ucsf.edu/chimerax/docs/user/commands/exit.html
  43   private static final StructureCommand CLOSE_CHIMERAX = new StructureCommand(
  44           "exit");
  45
  46   // https://www.cgl.ucsf.edu/chimerax/docs/user/commands/info.html#notify
  47   private static final StructureCommand STOP_NOTIFY_SELECTION = new StructureCommand(
  48           "info notify stop selection jalview");
  49
  50   private static final StructureCommand STOP_NOTIFY_MODELS = new StructureCommand(
  51           "info notify stop models jalview");
  52
  53   // https://www.cgl.ucsf.edu/chimerax/docs/user/commands/info.html#selection
  54   private static final StructureCommand GET_SELECTION = new StructureCommand(
  55           "info selection level residue");
  56
  57   private static final StructureCommand SHOW_BACKBONE = new StructureCommand(
  58           "~display all;~ribbon;show @CA|P atoms");
  59
  60   // https://www.cgl.ucsf.edu/chimerax/docs/user/commands/view.html
  61   private static final StructureCommand FOCUS_VIEW = new StructureCommand(
  62           "view");
  63
  64   private static final StructureCommandI COLOUR_BY_CHARGE = new StructureCommand(
  65           "color white;color :ASP,GLU red;color :LYS,ARG blue;color :CYS yellow");
  66
  67   @Override
  68   public List<StructureCommandI> colourByCharge()
  69   {
  70     return Arrays.asList(COLOUR_BY_CHARGE);
  71   }
  72
  73   @Override
  74   public String getResidueSpec(String residue)
  75   {
  76     return ":" + residue;
  77   }
  78
  79   @Override
  80   public StructureCommandI colourResidues(String atomSpec, Color colour)
  81   {
  82     // https://www.cgl.ucsf.edu/chimerax/docs/user/commands/color.html
  83     String colourCode = getColourString(colour);
  84
  85     return new StructureCommand("color " + atomSpec + " " + colourCode);
  86   }
  87
  88   @Override
  89   public StructureCommandI focusView()
  90   {
  91     return FOCUS_VIEW;
  92   }
  93
  94   /**
  95    * {@inheritDoc}
  96    *
  97    * @return
  98    */
  99   @Override
 100   public int getModelStartNo()
 101   {
 102     return 1;
 103   }
 104
 105   /**
 106    * Returns a viewer command to set the given residue attribute value on
 107    * residues specified by the AtomSpecModel, for example
 108    *
 109    * <pre>
 110    * setattr #0/A:3-9,14-20,39-43 res jv_strand 'strand' create true
 111    * </pre>
 112    *
 113    * @param attributeName
 114    * @param attributeValue
 115    * @param atomSpecModel
 116    * @return
 117    */
 118   @Override
 119   protected StructureCommandI setAttribute(String attributeName,
 120           String attributeValue, AtomSpecModel atomSpecModel)
 121   {
 122     StringBuilder sb = new StringBuilder(128);
 123     sb.append("setattr ")
 124             .append(getAtomSpec(atomSpecModel, AtomSpecType.RESIDUE_ONLY));
 125     sb.append(" res ").append(attributeName).append(" '")
 126             .append(attributeValue).append("'");
 127     sb.append(" create true");
 128     return new StructureCommand(sb.toString());
 129   }
 130
 131   @Override
 132   public StructureCommandI openCommandFile(String path)
 133   {
 134     // https://www.cgl.ucsf.edu/chimerax/docs/user/commands/open.html
 135     return new StructureCommand("open " + path);
 136   }
 137
 138   @Override
 139   public StructureCommandI saveSession(String filepath)
 140   {
 141     // https://www.cgl.ucsf.edu/chimerax/docs/user/commands/save.html
 142     // note ChimeraX will append ".cxs" to the filepath!
 143     return new StructureCommand("save " + filepath + " format session");
 144   }
 145
 146   /**
 147    * Returns the range(s) formatted as a ChimeraX atomspec, for example
 148    * <p>
 149    * #1/A:2-20,30-40/B:10-20|#2/A:12-30
 150    * <p>
 151    * Note there is no need to explicitly exclude ALTLOC atoms when
 152    * {@code alphaOnly == true}, as this is the default behaviour of ChimeraX (a
 153    * change from Chimera)
 154    *
 155    * @return
 156    */
 157   @Override
 158   public String getAtomSpec(AtomSpecModel atomSpec, AtomSpecType specType)
 159   {
 160     StringBuilder sb = new StringBuilder(128);
 161     boolean firstModel = true;
 162     for (String model : atomSpec.getModels())
 163     {
 164       if (!firstModel)
 165       {
 166         sb.append("|");
 167       }
 168       firstModel = false;
 169       appendModel(sb, model, atomSpec);
 170       if (specType == AtomSpecType.ALPHA)
 171       {
 172         sb.append("@CA");
 173       }
 174       if (specType == AtomSpecType.PHOSPHATE)
 175       {
 176         sb.append("@P");
 177       }
 178     }
 179     return sb.toString();
 180   }
 181
 182   /**
 183    * A helper method to append an atomSpec string for atoms in the given model
 184    *
 185    * @param sb
 186    * @param model
 187    * @param atomSpec
 188    */
 189   protected void appendModel(StringBuilder sb, String model,
 190           AtomSpecModel atomSpec)
 191   {
 192     sb.append("#").append(model);
 193
 194     for (String chain : atomSpec.getChains(model))
 195     {
 196       boolean firstPositionForChain = true;
 197       sb.append("/").append(chain.trim()).append(":");
 198       List<int[]> rangeList = atomSpec.getRanges(model, chain);
 199       boolean first = true;
 200       for (int[] range : rangeList)
 201       {
 202         if (!first)
 203         {
 204           sb.append(",");
 205         }
 206         first = false;
 207         appendRange(sb, range[0], range[1], chain, firstPositionForChain,
 208                 true);
 209       }
 210     }
 211   }
 212
 213   @Override
 214   public List<StructureCommandI> showBackbone()
 215   {
 216     return Arrays.asList(SHOW_BACKBONE);
 217   }
 218
 219   @Override
 220   public List<StructureCommandI> superposeStructures(AtomSpecModel ref,
 221           AtomSpecModel spec, AtomSpecType backbone)
 222   {
 223     /*
 224      * Form ChimeraX match command to match spec to ref
 225      *
 226      * match #1/A:2-94 toAtoms #2/A:1-93
 227      *
 228      * @see https://www.cgl.ucsf.edu/chimerax/docs/user/commands/align.html
 229      */
 230     StringBuilder cmd = new StringBuilder();
 231     String atomSpec = getAtomSpec(spec, backbone);
 232     String refSpec = getAtomSpec(ref, backbone);
 233     cmd.append("align ").append(atomSpec).append(" toAtoms ")
 234             .append(refSpec);
 235
 236     /*
 237      * show superposed residues as ribbon, others as chain
 238      */
 239     cmd.append("; ribbon ");
 240     cmd.append(getAtomSpec(spec, AtomSpecType.RESIDUE_ONLY)).append("|");
 241     cmd.append(getAtomSpec(ref, AtomSpecType.RESIDUE_ONLY))
 242             .append("; view");
 243
 244     return Arrays.asList(new StructureCommand(cmd.toString()));
 245   }
 246
 247   @Override
 248   public StructureCommandI openSession(String filepath)
 249   {
 250     // https://www.cgl.ucsf.edu/chimerax/docs/user/commands/open.html#composite
 251     // this version of the command has no dependency on file extension
 252     return new StructureCommand("open " + filepath + " format session");
 253   }
 254
 255   @Override
 256   public StructureCommandI closeViewer()
 257   {
 258     return CLOSE_CHIMERAX;
 259   }
 260
 261   @Override
 262   public List<StructureCommandI> startNotifications(String uri)
 263   {
 264     List<StructureCommandI> cmds = new ArrayList<>();
 265     cmds.add(new StructureCommand(
 266             "info notify start models jalview prefix ModelChanged url "
 267                     + uri));
 268     cmds.add(new StructureCommand(
 269             "info notify start selection jalview prefix SelectionChanged url "
 270                     + uri));
 271     return cmds;
 272   }
 273
 274   @Override
 275   public List<StructureCommandI> stopNotifications()
 276   {
 277     List<StructureCommandI> cmds = new ArrayList<>();
 278     cmds.add(STOP_NOTIFY_MODELS);
 279     cmds.add(STOP_NOTIFY_SELECTION);
 280     return cmds;
 281   }
 282
 283   @Override
 284   public StructureCommandI getSelectedResidues()
 285   {
 286     return GET_SELECTION;
 287   }
 288
 289   @Override
 290   public StructureCommandI listResidueAttributes()
 291   {
 292     return LIST_RESIDUE_ATTRIBUTES;
 293   }
 294 }