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