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