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