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