JAL-3518 more pull up / test coverage of structure command generation
[jalview.git] / src / jalview / ext / rbvi / chimera / ChimeraCommands.java
index 3c47ed1..1b1dd35 100644 (file)
@@ -1,6 +1,6 @@
 /*
- * Jalview - A Sequence Alignment Editor and Viewer (Version 2.8.2)
- * Copyright (C) 2014 The Jalview Authors
+ * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
+ * Copyright (C) $$Year-Rel$$ The Jalview Authors
  * 
  * This file is part of Jalview.
  * 
  */
 package jalview.ext.rbvi.chimera;
 
+import jalview.api.AlignViewportI;
+import jalview.api.AlignmentViewPanel;
 import jalview.api.FeatureRenderer;
-import jalview.api.SequenceRenderer;
 import jalview.datamodel.AlignmentI;
+import jalview.datamodel.MappedFeatures;
+import jalview.datamodel.SequenceFeature;
 import jalview.datamodel.SequenceI;
+import jalview.gui.Desktop;
+import jalview.structure.AtomSpecModel;
+import jalview.structure.StructureCommandsBase;
 import jalview.structure.StructureMapping;
-import jalview.structure.StructureMappingcommandSet;
 import jalview.structure.StructureSelectionManager;
-import jalview.util.Comparison;
+import jalview.util.ColorUtils;
+import jalview.util.IntRangeComparator;
 
 import java.awt.Color;
-import java.io.File;
-import java.io.FileOutputStream;
-import java.io.IOException;
 import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Iterator;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
@@ -44,46 +50,111 @@ import java.util.Map;
  * @author JimP
  * 
  */
-public class ChimeraCommands
+public class ChimeraCommands extends StructureCommandsBase
 {
+  public static final String NAMESPACE_PREFIX = "jv_";
+
+  private static final String CMD_COLOUR_BY_CHARGE = "color white;color red ::ASP;color red ::GLU;color blue ::LYS;color blue ::ARG;color yellow ::CYS";
+
+  private static final String CMD_COLOUR_BY_CHAIN = "rainbow chain";
+
+  // Chimera clause to exclude alternate locations in atom selection
+  private static final String NO_ALTLOCS = "&~@.B-Z&~@.2-9";
+
+  @Override
+  public String getColourCommand(String atomSpec, Color colour)
+  {
+    // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/color.html
+    String colourCode = getColourString(colour);
+    return "color " + colourCode + " " + atomSpec;
+  }
+
+  /**
+   * Returns a colour formatted suitable for use in viewer command syntax
+   * 
+   * @param colour
+   * @return
+   */
+  protected String getColourString(Color colour)
+  {
+    return ColorUtils.toTkCode(colour);
+  }
 
   /**
-   * utility to construct the commands to colour chains by the given alignment
-   * for passing to Chimera
+   * Constructs and returns Chimera commands to set attributes on residues
+   * corresponding to features in Jalview. Attribute names are the Jalview feature
+   * type, with a "jv_" prefix.
    * 
-   * @returns Object[] { Object[] { <model being coloured>,
+   * @param ssm
+   * @param files
+   * @param seqs
+   * @param viewPanel
+   * @return
+   */
+  @Override
+  public String[] setAttributesForFeatures(
+          StructureSelectionManager ssm, String[] files, SequenceI[][] seqs,
+          AlignmentViewPanel viewPanel)
+  {
+    Map<String, Map<Object, AtomSpecModel>> featureMap = buildFeaturesMap(
+            ssm, files, seqs, viewPanel);
+
+    return setAttributes(featureMap);
+  }
+
+  /**
+   * <pre>
+   * Helper method to build a map of 
+   *   { featureType, { feature value, AtomSpecModel } }
+   * </pre>
    * 
+   * @param ssm
+   * @param files
+   * @param seqs
+   * @param viewPanel
+   * @return
    */
-  public static StructureMappingcommandSet[] getColourBySequenceCommand(
-          StructureSelectionManager ssm, String[] files,
-          SequenceI[][] sequence, SequenceRenderer sr, FeatureRenderer fr,
-          AlignmentI alignment)
+  protected Map<String, Map<Object, AtomSpecModel>> buildFeaturesMap(
+          StructureSelectionManager ssm, String[] files, SequenceI[][] seqs,
+          AlignmentViewPanel viewPanel)
   {
-    String defAttrPath = null;
-    FileOutputStream fos = null;
-    try
-    {
-      File outFile = File.createTempFile("jalviewdefattr", ".xml");
-      outFile.deleteOnExit();
-      defAttrPath = outFile.getPath();
-      fos = new FileOutputStream(outFile);
-      fos.write("attribute: jalviewclr\n".getBytes());
-    } catch (IOException e1)
+    Map<String, Map<Object, AtomSpecModel>> theMap = new LinkedHashMap<>();
+
+    FeatureRenderer fr = viewPanel.getFeatureRenderer();
+    if (fr == null)
     {
-      e1.printStackTrace();
+      return theMap;
     }
-    List<StructureMappingcommandSet> cset = new ArrayList<StructureMappingcommandSet>();
+
+    AlignViewportI viewport = viewPanel.getAlignViewport();
+    List<String> visibleFeatures = fr.getDisplayedFeatureTypes();
 
     /*
-     * Map of { colour, positionSpecs}
+     * if alignment is showing features from complement, we also transfer
+     * these features to the corresponding mapped structure residues
      */
-    Map<String, StringBuilder> colranges = new LinkedHashMap<String, StringBuilder>();
-    StringBuilder setAttributes = new StringBuilder(256);
-    String lastColour = "none";
-    Color lastCol = null;
+    boolean showLinkedFeatures = viewport.isShowComplementFeatures();
+    List<String> complementFeatures = new ArrayList<>();
+    FeatureRenderer complementRenderer = null;
+    if (showLinkedFeatures)
+    {
+      AlignViewportI comp = fr.getViewport().getCodingComplement();
+      if (comp != null)
+      {
+        complementRenderer = Desktop.getAlignFrameFor(comp)
+                .getFeatureRenderer();
+        complementFeatures = complementRenderer.getDisplayedFeatureTypes();
+      }
+    }
+    if (visibleFeatures.isEmpty() && complementFeatures.isEmpty())
+    {
+      return theMap;
+    }
+
+    AlignmentI alignment = viewPanel.getAlignment();
     for (int pdbfnum = 0; pdbfnum < files.length; pdbfnum++)
     {
-      boolean startModel = true;
+      final int modelNumber = pdbfnum + getModelStartNo();
       StructureMapping[] mapping = ssm.getMapping(files[pdbfnum]);
 
       if (mapping == null || mapping.length < 1)
@@ -91,225 +162,504 @@ public class ChimeraCommands
         continue;
       }
 
-      int startPos = -1, lastPos = -1;
-      String lastChain = "";
-      for (int s = 0; s < sequence[pdbfnum].length; s++)
+      for (int seqNo = 0; seqNo < seqs[pdbfnum].length; seqNo++)
       {
-        for (int sp, m = 0; m < mapping.length; m++)
+        for (int m = 0; m < mapping.length; m++)
         {
-          final SequenceI seq = sequence[pdbfnum][s];
-          if (mapping[m].getSequence() == seq
-                  && (sp = alignment.findIndex(seq)) > -1)
+          final SequenceI seq = seqs[pdbfnum][seqNo];
+          int sp = alignment.findIndex(seq);
+          StructureMapping structureMapping = mapping[m];
+          if (structureMapping.getSequence() == seq && sp > -1)
           {
-            SequenceI asp = alignment.getSequenceAt(sp);
-            for (int r = 0; r < asp.getLength(); r++)
+            /*
+             * found a sequence with a mapping to a structure;
+             * now scan its features
+             */
+            if (!visibleFeatures.isEmpty())
             {
-              // no mapping to gaps in sequence
-              if (Comparison.isGap(asp.getCharAt(r)))
-              {
-                continue;
-              }
-              int pos = mapping[m].getPDBResNum(asp.findPosition(r));
-
-              if (pos < 1 || pos == lastPos)
-              {
-                continue;
-              }
-
-              Color col = getResidueColour(seq, r, sr, fr);
-              /*
-               * Just keep incrementing the end position for this colour range
-               * _unless_ colour, PDB model or chain has changed, or there is a
-               * gap in the mapped residue sequence
-               */
-              final boolean newColour = !col.equals(lastCol);
-              final boolean nonContig = lastPos + 1 != pos;
-              final boolean newChain = !mapping[m].getChain().equals(lastChain);
-              if (newColour || nonContig || startModel || newChain)
-              {
-                if (/* lastCol != null */startPos != -1)
-                {
-                  addColourRange(colranges, lastCol, pdbfnum, startPos,
-                          lastPos, lastChain, startModel);
-                  startModel = false;
-                }
-                // lastCol = null;
-                startPos = pos;
-              }
-              lastCol = col;
-              lastPos = pos;
-              // lastModel = pdbfnum;
-              lastChain = mapping[m].getChain();
+              scanSequenceFeatures(visibleFeatures, structureMapping, seq,
+                      theMap, modelNumber);
             }
-            // final colour range
-            if (lastCol != null)
+            if (showLinkedFeatures)
             {
-              addColourRange(colranges, lastCol, pdbfnum, startPos,
-                      lastPos, lastChain, false);
+              scanComplementFeatures(complementRenderer, structureMapping,
+                      seq, theMap, modelNumber);
             }
-            break;
           }
         }
       }
     }
-      try
-      {
-      lastColour = buildColourCommands(cset, colranges,
-                fos, setAttributes);
-      } catch (IOException e)
-      {
-        e.printStackTrace();
-      }
-
-    try
-    {
-      fos.close();
-    } catch (IOException e)
-    {
-      e.printStackTrace();
-    }
+    return theMap;
+  }
 
+  /**
+   * Scans visible features in mapped positions of the CDS/peptide complement, and
+   * adds any found to the map of attribute values/structure positions
+   * 
+   * @param complementRenderer
+   * @param structureMapping
+   * @param seq
+   * @param theMap
+   * @param modelNumber
+   */
+  protected static void scanComplementFeatures(
+          FeatureRenderer complementRenderer,
+          StructureMapping structureMapping, SequenceI seq,
+          Map<String, Map<Object, AtomSpecModel>> theMap, int modelNumber)
+  {
     /*
-     * Send a rangeColor command, preceded by either defattr or setattr,
-     * whichever we end up preferring!
-     * 
-     * rangecolor requires a minimum of two attribute values to operate on
+     * for each sequence residue mapped to a structure position...
      */
-    StringBuilder rangeColor = new StringBuilder(256);
-    rangeColor.append("rangecolor jalviewclr");
-    int colourId = 0;
-    for (String colour : colranges.keySet())
-    {
-      colourId++;
-      rangeColor.append(" " + colourId + " " + colour);
-    }
-    String rangeColorCommand = rangeColor.toString();
-    if (rangeColorCommand.split(" ").length < 5)
+    for (int seqPos : structureMapping.getMapping().keySet())
     {
-      rangeColorCommand += " max " + lastColour;
+      /*
+       * find visible complementary features at mapped position(s)
+       */
+      MappedFeatures mf = complementRenderer
+              .findComplementFeaturesAtResidue(seq, seqPos);
+      if (mf != null)
+      {
+        for (SequenceFeature sf : mf.features)
+        {
+          String type = sf.getType();
+
+          /*
+           * Don't copy features which originated from Chimera
+           */
+          if (JalviewChimeraBinding.CHIMERA_FEATURE_GROUP
+                  .equals(sf.getFeatureGroup()))
+          {
+            continue;
+          }
+
+          /*
+           * record feature 'value' (score/description/type) as at the
+           * corresponding structure position
+           */
+          List<int[]> mappedRanges = structureMapping
+                  .getPDBResNumRanges(seqPos, seqPos);
+
+          if (!mappedRanges.isEmpty())
+          {
+            String value = sf.getDescription();
+            if (value == null || value.length() == 0)
+            {
+              value = type;
+            }
+            float score = sf.getScore();
+            if (score != 0f && !Float.isNaN(score))
+            {
+              value = Float.toString(score);
+            }
+            Map<Object, AtomSpecModel> featureValues = theMap.get(type);
+            if (featureValues == null)
+            {
+              featureValues = new HashMap<>();
+              theMap.put(type, featureValues);
+            }
+            for (int[] range : mappedRanges)
+            {
+              addAtomSpecRange(featureValues, value, modelNumber, range[0],
+                      range[1], structureMapping.getChain());
+            }
+          }
+        }
+      }
     }
-    final String defAttrCommand = "defattr " + defAttrPath
-            + " raiseTool false";
-    final String setAttrCommand = setAttributes.toString();
-    final String attrCommand = false ? defAttrCommand : setAttrCommand;
-    cset.add(new StructureMappingcommandSet(ChimeraCommands.class, null,
-            new String[]
-            { attrCommand /* , rangeColorCommand */}));
-
-    return cset.toArray(new StructureMappingcommandSet[cset.size()]);
   }
 
   /**
-   * Get the residue colour at the given sequence position - as determined by
-   * the sequence group colour (if any), else the colour scheme, possibly
-   * overridden by a feature colour.
+   * Inspect features on the sequence; for each feature that is visible, determine
+   * its mapped ranges in the structure (if any) according to the given mapping,
+   * and add them to the map.
    * 
+   * @param visibleFeatures
+   * @param mapping
    * @param seq
-   * @param position
-   * @param sr
-   * @param fr
-   * @return
+   * @param theMap
+   * @param modelNumber
    */
-  protected static Color getResidueColour(final SequenceI seq,
-          int position, SequenceRenderer sr, FeatureRenderer fr)
+  protected static void scanSequenceFeatures(List<String> visibleFeatures,
+          StructureMapping mapping, SequenceI seq,
+          Map<String, Map<Object, AtomSpecModel>> theMap, int modelNumber)
   {
-    Color col = sr.getResidueBoxColour(seq, position);
-
-    if (fr != null)
+    List<SequenceFeature> sfs = seq.getFeatures().getPositionalFeatures(
+            visibleFeatures.toArray(new String[visibleFeatures.size()]));
+    for (SequenceFeature sf : sfs)
     {
-      col = fr.findFeatureColour(col, seq, position);
+      String type = sf.getType();
+
+      /*
+       * Don't copy features which originated from Chimera
+       */
+      if (JalviewChimeraBinding.CHIMERA_FEATURE_GROUP
+              .equals(sf.getFeatureGroup()))
+      {
+        continue;
+      }
+
+      List<int[]> mappedRanges = mapping.getPDBResNumRanges(sf.getBegin(),
+              sf.getEnd());
+
+      if (!mappedRanges.isEmpty())
+      {
+        String value = sf.getDescription();
+        if (value == null || value.length() == 0)
+        {
+          value = type;
+        }
+        float score = sf.getScore();
+        if (score != 0f && !Float.isNaN(score))
+        {
+          value = Float.toString(score);
+        }
+        Map<Object, AtomSpecModel> featureValues = theMap.get(type);
+        if (featureValues == null)
+        {
+          featureValues = new HashMap<>();
+          theMap.put(type, featureValues);
+        }
+        for (int[] range : mappedRanges)
+        {
+          addAtomSpecRange(featureValues, value, modelNumber, range[0],
+                  range[1], mapping.getChain());
+        }
+      }
     }
-    return col;
   }
 
   /**
-   * Helper method to build the colour commands for one PDBfile.
+   * Traverse the map of features/values/models/chains/positions to construct a
+   * list of 'setattr' commands (one per distinct feature type and value).
+   * <p>
+   * The format of each command is
+   * 
+   * <pre>
+   * <blockquote> setattr r <featureName> " " #modelnumber:range.chain 
+   * e.g. setattr r jv_chain &lt;value&gt; #0:2.B,4.B,9-12.B|#1:1.A,2-6.A,...
+   * </blockquote>
+   * </pre>
    * 
-   * @param cset
-   *          the list of commands to be added to
-   * @param colranges
-   *          the map of colours to residue positions already determined
-   * @param fos
-   *          file to write 'defattr' commands to
-   * @param setAttributes
-   * @throws IOException
+   * @param featureMap
+   * @return
    */
-  protected static String buildColourCommands(
-          List<StructureMappingcommandSet> cset,
-          Map<String, StringBuilder> colranges,
-          FileOutputStream fos, StringBuilder setAttributes)
-          throws IOException
+  protected String[] setAttributes(
+          Map<String, Map<Object, AtomSpecModel>> featureMap)
   {
-    int colourId = 0;
-    String lastColour = null;
-    for (String colour : colranges.keySet())
+    List<String> commands = new ArrayList<>();
+    for (String featureType : featureMap.keySet())
     {
-      lastColour = colour;
-      colourId++;
+      String attributeName = makeAttributeName(featureType);
+
       /*
-       * Using color command directly is slow for larger structures.
-       * setAttributes.append("color #" + colour + " " + colranges.get(colour)+
-       * ";");
+       * clear down existing attributes for this feature
        */
-      setAttributes.append("color " + colour + " " + colranges.get(colour)
-              + ";");
-      final String atomSpec = new String(colranges.get(colour));
-      // setAttributes.append("setattr r jalviewclr " + colourId + " "
-      // + atomSpec + ";");
-      fos.write(("\t" + atomSpec + "\t" + colourId + "\n").getBytes());
+      // 'problem' - sets attribute to None on all residues - overkill?
+      // commands.add("~setattr r " + attributeName + " :*");
+
+      Map<Object, AtomSpecModel> values = featureMap.get(featureType);
+      for (Object value : values.keySet())
+      {
+        /*
+         * for each distinct value recorded for this feature type,
+         * add a command to set the attribute on the mapped residues
+         * Put values in single quotes, encoding any embedded single quotes
+         */
+        AtomSpecModel atomSpecModel = values.get(value);
+        String featureValue = value.toString();
+        featureValue = featureValue.replaceAll("\\'", "&#39;");
+        String cmd = setAttribute(attributeName, featureValue,
+                atomSpecModel);
+        commands.add(cmd);
+      }
     }
-    return lastColour;
+
+    return commands.toArray(new String[commands.size()]);
   }
 
   /**
-   * Helper method to record a range of positions of the same colour.
+   * Returns a viewer command to set the given residue attribute value on
+   * residues specified by the AtomSpecModel, for example
    * 
-   * @param colranges
-   * @param colour
-   * @param model
-   * @param startPos
-   * @param endPos
-   * @param chain
-   * @param changeModel
+   * <pre>
+   * setatr res jv_chain 'primary' #1:12-34,48-55.B
+   * </pre>
+   * 
+   * @param attributeName
+   * @param attributeValue
+   * @param atomSpecModel
+   * @return
+   */
+  protected String setAttribute(String attributeName,
+          String attributeValue,
+          AtomSpecModel atomSpecModel)
+  {
+    StringBuilder sb = new StringBuilder(128);
+    sb.append("setattr res ").append(attributeName).append(" '")
+            .append(attributeValue).append("' ");
+    sb.append(getAtomSpec(atomSpecModel, false));
+    return sb.toString();
+  }
+
+  /**
+   * Makes a prefixed and valid Chimera attribute name. A jv_ prefix is applied
+   * for a 'Jalview' namespace, and any non-alphanumeric character is converted
+   * to an underscore.
+   * 
+   * @param featureType
+   * @return
+   * @see https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/setattr.html
    */
-  private static void addColourRange(Map<String, StringBuilder> colranges,
-          Color colour, int model, int startPos, int endPos, String chain,
-          boolean startModel)
+  protected static String makeAttributeName(String featureType)
   {
-    String colstring = "#" + ((colour.getRed() < 16) ? "0" : "")
-            + Integer.toHexString(colour.getRed())
-            + ((colour.getGreen()< 16) ? "0":"")+Integer.toHexString(colour.getGreen())
-            + ((colour.getBlue()< 16) ? "0":"")+Integer.toHexString(colour.getBlue());
-    StringBuilder currange = colranges.get(colstring);
-    if (currange == null)
+    StringBuilder sb = new StringBuilder();
+    if (featureType != null)
     {
-      colranges.put(colstring, currange = new StringBuilder(256));
+      for (char c : featureType.toCharArray())
+      {
+        sb.append(Character.isLetterOrDigit(c) ? c : '_');
+      }
     }
+    String attName = NAMESPACE_PREFIX + sb.toString();
+
+    /*
+     * Chimera treats an attribute name ending in 'color' as colour-valued;
+     * Jalview doesn't, so prevent this by appending an underscore
+     */
+    if (attName.toUpperCase().endsWith("COLOR"))
+    {
+      attName += "_";
+    }
+
+    return attName;
+  }
+
+  @Override
+  public String colourByChain()
+  {
+    return CMD_COLOUR_BY_CHAIN;
+  }
+
+  @Override
+  public String colourByCharge()
+  {
+    return CMD_COLOUR_BY_CHARGE;
+  }
+
+  @Override
+  public String getResidueSpec(String residue)
+  {
+    return "::" + residue;
+  }
+
+  @Override
+  public String setBackgroundColour(Color col)
+  {
+    // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/set.html#bgcolor
+    return "set bgColor " + ColorUtils.toTkCode(col);
+  }
+
+  @Override
+  public String focusView()
+  {
+    // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/focus.html
+    return "focus";
+  }
+
+  @Override
+  public String showChains(List<String> toShow)
+  {
+    /*
+     * Construct a chimera command like
+     * 
+     * ~display #*;~ribbon #*;ribbon :.A,:.B
+     */
+    StringBuilder cmd = new StringBuilder(64);
+    boolean first = true;
+    for (String chain : toShow)
+    {
+      String[] tokens = chain.split(":");
+      if (tokens.length == 2)
+      {
+        String showChainCmd = tokens[0] + ":." + tokens[1];
+        if (!first)
+        {
+          cmd.append(",");
+        }
+        cmd.append(showChainCmd);
+        first = false;
+      }
+    }
+
+    /*
+     * could append ";focus" to this command to resize the display to fill the
+     * window, but it looks more helpful not to (easier to relate chains to the
+     * whole)
+     */
+    final String command = "~display #*; ~ribbon #*; ribbon :"
+            + cmd.toString();
+    return command;
+  }
+
+  @Override
+  public String superposeStructures(AtomSpecModel spec, AtomSpecModel ref)
+  {
+    /*
+     * Form Chimera match command to match spec to ref
+     * 
+     * match #1:1-30.B,81-100.B@CA #0:21-40.A,61-90.A@CA
+     * 
+     * @see
+     * https://www.cgl.ucsf.edu/chimera/docs/UsersGuide/midas/match.html
+     */
+    StringBuilder cmd = new StringBuilder();
+    String atomSpec = getAtomSpec(spec, true);
+    String refSpec = getAtomSpec(ref, true);
+    cmd.append("match ").append(atomSpec).append(" ").append(refSpec);
+
     /*
-     * Format as (e.g.) #0:1-3.A,5.A,7-10.A,...#1:1-4.B,..etc
+     * show superposed residues as ribbon, others as chain
      */
-    // if (currange.length() > 0)
-    // {
-    // currange.append("|");
-    // }
-    // currange.append("#" + model + ":" + ((startPos==endPos) ? startPos :
-    // startPos + "-"
-    // + endPos) + "." + chain);
-    if (currange.length() == 0)
+    // fixme this should precede the loop over all alignments/structures
+    cmd.append(";~display all; chain @CA|P");
+    cmd.append("; ribbon ");
+    cmd.append(atomSpec).append("|").append(refSpec).append("; focus");
+
+    return cmd.toString();
+  }
+
+  @Override
+  public String openCommandFile(String path)
+  {
+    // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/filetypes.html
+    return "open cmd:" + path;
+  }
+
+  @Override
+  public String saveSession(String filepath)
+  {
+    // https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/save.html
+    return "save " + filepath;
+  }
+
+  /**
+   * Returns the range(s) modelled by {@code atomSpec} formatted as a Chimera
+   * atomspec string, e.g.
+   * 
+   * <pre>
+   * #0:15.A,28.A,54.A,70-72.A|#1:2.A,6.A,11.A,13-14.A
+   * </pre>
+   * 
+   * where
+   * <ul>
+   * <li>#0 is a model number</li>
+   * <li>15 or 70-72 is a residue number, or range of residue numbers</li>
+   * <li>.A is a chain identifier</li>
+   * <li>residue ranges are separated by comma</li>
+   * <li>atomspecs for distinct models are separated by | (or)</li>
+   * </ul>
+   * 
+   * <pre>
+   * 
+   * @param model
+   * @param alphaOnly
+   * @return
+   * @see https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/frameatom_spec.html
+   */
+  @Override
+  public String getAtomSpec(AtomSpecModel atomSpec, boolean alphaOnly)
+  {
+    StringBuilder sb = new StringBuilder(128);
+    boolean firstModel = true;
+    for (Integer model : atomSpec.getModels())
     {
-      currange.append("#" + model + ":");
+      if (!firstModel)
+      {
+        sb.append("|");
+      }
+      firstModel = false;
+      appendModel(sb, model, atomSpec, alphaOnly);
     }
-    else if (startModel)
+    return sb.toString();
+  }
+
+  /**
+   * A helper method to append an atomSpec string for atoms in the given model
+   * 
+   * @param sb
+   * @param model
+   * @param atomSpec
+   * @param alphaOnly
+   */
+  protected void appendModel(StringBuilder sb, Integer model,
+          AtomSpecModel atomSpec, boolean alphaOnly)
+  {
+    sb.append("#").append(model).append(":");
+
+    boolean firstPositionForModel = true;
+
+    for (String chain : atomSpec.getChains(model))
     {
-      currange.append(",#" + model + ":");
+      chain = " ".equals(chain) ? chain : chain.trim();
+
+      List<int[]> rangeList = atomSpec.getRanges(model, chain);
+
+      /*
+       * sort ranges into ascending start position order
+       */
+      Collections.sort(rangeList, IntRangeComparator.ASCENDING);
+
+      int start = rangeList.isEmpty() ? 0 : rangeList.get(0)[0];
+      int end = rangeList.isEmpty() ? 0 : rangeList.get(0)[1];
+
+      Iterator<int[]> iterator = rangeList.iterator();
+      while (iterator.hasNext())
+      {
+        int[] range = iterator.next();
+        if (range[0] <= end + 1)
+        {
+          /*
+           * range overlaps or is contiguous with the last one
+           * - so just extend the end position, and carry on
+           * (unless this is the last in the list)
+           */
+          end = Math.max(end, range[1]);
+        }
+        else
+        {
+          /*
+           * we have a break so append the last range
+           */
+          appendRange(sb, start, end, chain, firstPositionForModel, false);
+          firstPositionForModel = false;
+          start = range[0];
+          end = range[1];
+        }
+      }
+
+      /*
+       * and append the last range
+       */
+      if (!rangeList.isEmpty())
+      {
+        appendRange(sb, start, end, chain, firstPositionForModel, false);
+        firstPositionForModel = false;
+      }
     }
-    else
+    if (alphaOnly)
     {
-      currange.append(",");
+      /*
+       * restrict to alpha carbon, no alternative locations
+       * (needed to ensuring matching atom counts for superposition)
+       */
+      sb.append("@CA|P").append(NO_ALTLOCS);
     }
-    final String rangeSpec = (startPos == endPos) ? Integer
-            .toString(startPos) : (startPos + "-" + endPos);
-    currange.append(rangeSpec + "." + chain);
+  }
+
+  @Override
+  public String showBackbone()
+  {
+    return "~display all;chain @CA|P";
   }
 
 }