src/jalview/structure/StructureCommandsBase.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.structure;
  22
  23 import java.awt.Color;
  24 import java.util.ArrayList;
  25 import java.util.List;
  26 import java.util.Map;
  27 import java.util.Map.Entry;
  28
  29 /**
  30  * A base class holding methods useful to all classes that implement commands
  31  * for structure viewers
  32  *
  33  * @author gmcarstairs
  34  *
  35  */
  36 public abstract class StructureCommandsBase implements StructureCommandsI
  37 {
  38   public static final String NAMESPACE_PREFIX = "jv_";
  39
  40   private static final String CMD_SEPARATOR = ";";
  41
  42   /**
  43    * Returns something that separates concatenated commands
  44    *
  45    * @return
  46    */
  47   protected String getCommandSeparator()
  48   {
  49     return CMD_SEPARATOR;
  50   }
  51
  52   /**
  53    * Returns the lowest model number used by the structure viewer
  54    *
  55    * @return
  56    */
  57   @Override
  58   public int getModelStartNo()
  59   {
  60     return 0;
  61   }
  62
  63   /**
  64    * Helper method to add one contiguous range to the AtomSpec model for the
  65    * given value (creating the model if necessary). As used by Jalview,
  66    * {@code value} is
  67    * <ul>
  68    * <li>a colour, when building a 'colour structure by sequence' command</li>
  69    * <li>a feature value, when building a 'set Chimera attributes from features'
  70    * command</li>
  71    * </ul>
  72    *
  73    * @param map
  74    * @param value
  75    * @param model
  76    * @param startPos
  77    * @param endPos
  78    * @param chain
  79    */
  80   public static final void addAtomSpecRange(Map<Object, AtomSpecModel> map,
  81           Object value, String model, int startPos, int endPos,
  82           String chain)
  83   {
  84     /*
  85      * Get/initialize map of data for the colour
  86      */
  87     AtomSpecModel atomSpec = map.get(value);
  88     if (atomSpec == null)
  89     {
  90       atomSpec = new AtomSpecModel();
  91       map.put(value, atomSpec);
  92     }
  93
  94     atomSpec.addRange(model, startPos, endPos, chain);
  95   }
  96
  97   /**
  98    * Makes a structure viewer attribute name for a Jalview feature type by
  99    * prefixing it with "jv_", and replacing any non-alphanumeric characters with
 100    * an underscore
 101    *
 102    * @param featureType
 103    * @return
 104    */
 105   protected String makeAttributeName(String featureType)
 106   {
 107     StringBuilder sb = new StringBuilder();
 108     if (featureType != null)
 109     {
 110       for (char c : featureType.toCharArray())
 111       {
 112         sb.append(Character.isLetterOrDigit(c) ? c : '_');
 113       }
 114     }
 115     String attName = NAMESPACE_PREFIX + sb.toString();
 116     return attName;
 117   }
 118
 119   /**
 120    * Traverse the map of colours/models/chains/positions to construct a list of
 121    * 'color' commands (one per distinct colour used). The format of each command
 122    * is specific to the structure viewer.
 123    * <p>
 124    * The default implementation returns a single command containing one command
 125    * per colour, concatenated.
 126    *
 127    * @param colourMap
 128    * @return
 129    */
 130   @Override
 131   public List<StructureCommandI> colourBySequence(
 132           Map<Object, AtomSpecModel> colourMap)
 133   {
 134     List<StructureCommandI> commands = new ArrayList<>();
 135     StringBuilder sb = new StringBuilder(colourMap.size() * 20);
 136     boolean first = true;
 137     for (Object key : colourMap.keySet())
 138     {
 139       Color colour = (Color) key;
 140       final AtomSpecModel colourData = colourMap.get(colour);
 141       StructureCommandI command = getColourCommand(colourData, colour);
 142       if (!first)
 143       {
 144         sb.append(getCommandSeparator());
 145       }
 146       first = false;
 147       sb.append(command.getCommand());
 148     }
 149
 150     commands.add(new StructureCommand(sb.toString()));
 151     return commands;
 152   }
 153
 154   /**
 155    * Returns a command to colour the atoms represented by {@code atomSpecModel}
 156    * with the colour specified by {@code colourCode}.
 157    *
 158    * @param atomSpecModel
 159    * @param colour
 160    * @return
 161    */
 162   protected StructureCommandI getColourCommand(AtomSpecModel atomSpecModel,
 163           Color colour)
 164   {
 165     String atomSpec = getAtomSpec(atomSpecModel, AtomSpecType.RESIDUE_ONLY);
 166     return colourResidues(atomSpec, colour);
 167   }
 168
 169   /**
 170    * Returns a command to colour the atoms described (in viewer command syntax)
 171    * by {@code atomSpec} with the colour specified by {@code colourCode}
 172    *
 173    * @param atomSpec
 174    * @param colour
 175    * @return
 176    */
 177   protected abstract StructureCommandI colourResidues(String atomSpec,
 178           Color colour);
 179
 180   @Override
 181   public List<StructureCommandI> colourByResidues(
 182           Map<String, Color> colours)
 183   {
 184     List<StructureCommandI> commands = new ArrayList<>();
 185     for (Entry<String, Color> entry : colours.entrySet())
 186     {
 187       commands.add(colourResidue(entry.getKey(), entry.getValue()));
 188     }
 189     return commands;
 190   }
 191
 192   private StructureCommandI colourResidue(String resName, Color col)
 193   {
 194     String atomSpec = getResidueSpec(resName);
 195     return colourResidues(atomSpec, col);
 196   }
 197
 198   /**
 199    * Helper method to append one start-end range to an atomspec string
 200    *
 201    * @param sb
 202    * @param start
 203    * @param end
 204    * @param chain
 205    * @param firstPositionForModel
 206    */
 207   protected void appendRange(StringBuilder sb, int start, int end,
 208           String chain, boolean firstPositionForModel, boolean isChimeraX)
 209   {
 210     if (!firstPositionForModel)
 211     {
 212       sb.append(",");
 213     }
 214     if (end == start)
 215     {
 216       sb.append(start);
 217     }
 218     else
 219     {
 220       sb.append(start).append("-").append(end);
 221     }
 222
 223     if (!isChimeraX)
 224     {
 225       sb.append(".");
 226       if (!" ".equals(chain))
 227       {
 228         sb.append(chain);
 229       }
 230     }
 231   }
 232
 233   /**
 234    * Returns the atom specifier meaning all occurrences of the given residue
 235    *
 236    * @param residue
 237    * @return
 238    */
 239   protected abstract String getResidueSpec(String residue);
 240
 241   @Override
 242   public List<StructureCommandI> setAttributes(
 243           Map<String, Map<Object, AtomSpecModel>> featureValues)
 244   {
 245     // default does nothing, override where this is implemented
 246     return null;
 247   }
 248
 249   @Override
 250   public List<StructureCommandI> startNotifications(String uri)
 251   {
 252     return null;
 253   }
 254
 255   @Override
 256   public List<StructureCommandI> stopNotifications()
 257   {
 258     return null;
 259   }
 260
 261   @Override
 262   public StructureCommandI getSelectedResidues()
 263   {
 264     return null;
 265   }
 266
 267   @Override
 268   public StructureCommandI listResidueAttributes()
 269   {
 270     return null;
 271   }
 272
 273   @Override
 274   public StructureCommandI getResidueAttributes(String attName)
 275   {
 276     return null;
 277   }
 278 }