X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=src%2Fjalview%2Fstructures%2Fmodels%2FAAStructureBindingModel.java;h=f1f2d307d4014f0a1424017e5a84a470d0561c6b;hb=05e40b4dd4e216024024fb921d797917d74daa76;hp=88c181cbed2f33925cfb1f47e752d63db34cc30a;hpb=dadeab44d8d46ef588e326efb69599baa86a083b;p=jalview.git

diff --git a/src/jalview/structures/models/AAStructureBindingModel.java b/src/jalview/structures/models/AAStructureBindingModel.java
index 88c181c..f1f2d30 100644
--- a/src/jalview/structures/models/AAStructureBindingModel.java
+++ b/src/jalview/structures/models/AAStructureBindingModel.java
@@ -20,6 +20,8 @@
  */
 package jalview.structures.models;
 
+import java.util.Locale;
+
 import java.awt.Color;
 import java.io.File;
 import java.io.IOException;
@@ -42,8 +44,13 @@ import jalview.api.structures.JalviewStructureDisplayI;
 import jalview.bin.Cache;
 import jalview.datamodel.AlignmentI;
 import jalview.datamodel.HiddenColumns;
+import jalview.datamodel.MappedFeatures;
 import jalview.datamodel.PDBEntry;
+import jalview.datamodel.SequenceFeature;
 import jalview.datamodel.SequenceI;
+import jalview.ext.rbvi.chimera.JalviewChimeraBinding;
+import jalview.gui.AlignmentPanel;
+import jalview.gui.Desktop;
 import jalview.gui.StructureViewer.ViewerType;
 import jalview.io.DataSourceType;
 import jalview.io.StructureFile;
@@ -62,7 +69,7 @@ import jalview.util.MessageManager;
 
 /**
  * 
- * A base class to hold common function for protein structure model binding.
+ * A base class to hold common function for 3D structure model binding.
  * Initial version created by refactoring JMol and Chimera binding models, but
  * other structure viewers could in principle be accommodated in future.
  * 
@@ -79,20 +86,20 @@ public abstract class AAStructureBindingModel
   public static class SuperposeData
   {
     public String filename;
-  
+
     public String pdbId;
-  
+
     public String chain = "";
-  
+
     public boolean isRna;
-  
+
     /*
      * The pdb residue number (if any) mapped to columns of the alignment
      */
     public int[] pdbResNo; // or use SparseIntArray?
-  
+
     public String modelId;
-  
+
     /**
      * Constructor
      * 
@@ -171,6 +178,8 @@ public abstract class AAStructureBindingModel
 
   public String fileLoadingError;
 
+  protected Thread externalViewerMonitor;
+
   /**
    * Constructor
    * 
@@ -256,6 +265,7 @@ public abstract class AAStructureBindingModel
     chains = newchains;
     return chainmaps > 0;
   }
+
   public StructureSelectionManager getSsm()
   {
     return ssm;
@@ -574,6 +584,7 @@ public abstract class AAStructureBindingModel
       }
     }
   }
+  
 
   @Override
   public abstract void highlightAtoms(List<AtomSpec> atoms);
@@ -653,7 +664,8 @@ public abstract class AAStructureBindingModel
    * @return
    */
   protected int findSuperposableResidues(AlignmentI alignment,
-          BitSet matched, AAStructureBindingModel.SuperposeData[] structures)
+          BitSet matched,
+          AAStructureBindingModel.SuperposeData[] structures)
   {
     int refStructure = -1;
     String[] files = getStructureFiles();
@@ -879,8 +891,8 @@ public abstract class AAStructureBindingModel
        * Calculate the superposable alignment columns ('matched'), and the
        * corresponding structure residue positions (structures.pdbResNo)
        */
-      int refStructure = findSuperposableResidues(alignment,
-              matched, structures);
+      int refStructure = findSuperposableResidues(alignment, matched,
+              structures);
 
       /*
        * require at least 4 positions to be able to execute superposition
@@ -888,8 +900,8 @@ public abstract class AAStructureBindingModel
       int nmatched = matched.cardinality();
       if (nmatched < MIN_POS_TO_SUPERPOSE)
       {
-        String msg = MessageManager.formatMessage("label.insufficient_residues",
-                nmatched);
+        String msg = MessageManager
+                .formatMessage("label.insufficient_residues", nmatched);
         error += view.getViewName() + ": " + msg + "; ";
         continue;
       }
@@ -921,7 +933,7 @@ public abstract class AAStructureBindingModel
           for (String reply : replies)
           {
             // return this error (Chimera only) to the user
-            if (reply.toLowerCase().contains("unequal numbers of atoms"))
+            if (reply.toLowerCase(Locale.ROOT).contains("unequal numbers of atoms"))
             {
               error += "; " + reply;
             }
@@ -933,7 +945,8 @@ public abstract class AAStructureBindingModel
     return error;
   }
 
-  private AtomSpecModel getAtomSpec(AAStructureBindingModel.SuperposeData superposeData,
+  private AtomSpecModel getAtomSpec(
+          AAStructureBindingModel.SuperposeData superposeData,
           BitSet matched)
   {
     AtomSpecModel model = new AtomSpecModel();
@@ -970,8 +983,8 @@ public abstract class AAStructureBindingModel
 
     // TODO: JAL-628 colour chains distinctly across all visible models
 
-    executeCommand(commandGenerator.colourByChain(), false,
-            COLOURING_STRUCTURES);
+    executeCommand(false, COLOURING_STRUCTURES,
+            commandGenerator.colourByChain());
   }
 
   /**
@@ -1002,7 +1015,7 @@ public abstract class AAStructureBindingModel
     {
       return;
     }
-    
+
     /*
      * build a map of {Residue3LetterCode, Color}
      */
@@ -1029,69 +1042,7 @@ public abstract class AAStructureBindingModel
   public void setBackgroundColour(Color col)
   {
     StructureCommandI cmd = commandGenerator.setBackgroundColour(col);
-    executeCommand(cmd, false, null);
-  }
-
-  /**
-   * Sends one command to the structure viewer. If {@code getReply} is true, the
-   * command is sent synchronously, otherwise in a deferred thread.
-   * <p>
-   * If a progress message is supplied, this is displayed before command
-   * execution, and removed afterwards.
-   * 
-   * @param cmd
-   * @param getReply
-   * @param msg
-   * @return
-   */
-  private List<String> executeCommand(StructureCommandI cmd,
-          boolean getReply, String msg)
-  {
-    if (getReply)
-    {
-      /*
-       * synchronous (same thread) execution so reply can be returned
-       */
-      final JalviewStructureDisplayI theViewer = getViewer();
-      final long handle = msg == null ? 0 : theViewer.startProgressBar(msg);
-      try
-      {
-        return executeCommand(cmd, getReply);
-      } finally
-      {
-        if (msg != null)
-        {
-          theViewer.stopProgressBar(null, handle);
-        }
-      }
-    }
-    else
-    {
-      /*
-       * asynchronous (new thread) execution if no reply needed
-       */
-      final JalviewStructureDisplayI theViewer = getViewer();
-      final long handle = msg == null ? 0 : theViewer.startProgressBar(msg);
-      
-      SwingUtilities.invokeLater(new Runnable()
-      {
-        @Override
-        public void run()
-        {
-          try
-          {
-            executeCommand(cmd, false);
-          } finally
-          {
-            if (msg != null)
-            {
-              theViewer.stopProgressBar(null, handle);
-            }
-          }
-        }
-      });
-      return null;
-    }
+    executeCommand(false, null, cmd);
   }
 
   /**
@@ -1105,84 +1056,117 @@ public abstract class AAStructureBindingModel
           boolean getReply);
 
   /**
-   * A helper method that converts list of commands to a vararg array
+   * Executes one or more structure viewer commands
    * 
    * @param commands
    * @param getReply
    * @param msg
    */
-  private List<String> executeCommands(List<StructureCommandI> commands,
+  protected List<String> executeCommands(List<StructureCommandI> commands,
           boolean getReply, String msg)
   {
-    return executeCommands(getReply, msg,
+    return executeCommand(getReply, msg,
             commands.toArray(new StructureCommandI[commands.size()]));
   }
 
   /**
-   * Executes one or more structure viewer commands. If a progress message is
-   * provided, it is shown first, and removed after all commands have been run.
+   * Executes one or more structure viewer commands, optionally returning the
+   * reply, and optionally showing a status message while the command is being
+   * executed.
+   * <p>
+   * If a reply is wanted, the execution is done synchronously (waits),
+   * otherwise it is done in a separate thread (doesn't wait). WARNING: if you
+   * are sending commands that need to execute before later calls to
+   * executeCommand (e.g. mouseovers, which clean up after previous ones) then
+   * set getReply true to ensure that commands are not executed out of order.
    * 
    * @param getReply
    * @param msg
-   * @param commands
+   * @param cmds
    * @return
    */
-  protected List<String> executeCommands(boolean getReply, String msg,
-          StructureCommandI[] commands)
+  protected List<String> executeCommand(boolean getReply, String msg,
+          StructureCommandI... cmds)
   {
-    // todo: tidy this up
-
-    /*
-     * show progress message if specified
-     */
-    final JalviewStructureDisplayI theViewer = getViewer();
+    JalviewStructureDisplayI theViewer = getViewer();
     final long handle = msg == null ? 0 : theViewer.startProgressBar(msg);
 
-    List<String> response = getReply ? new ArrayList<>() : null;
-    try
+    if (getReply)
     {
-      for (StructureCommandI cmd : commands)
+      /*
+       * execute and wait for reply
+       */
+      List<String> response = new ArrayList<>();
+      try
       {
-        List<String> replies = executeCommand(cmd, getReply, null);
-        if (getReply && replies != null)
+        for (StructureCommandI cmd : cmds)
         {
-          response.addAll(replies);
+          List<String> replies = executeCommand(cmd, true);
+          if (replies != null)
+          {
+            response.addAll(replies);
+          }
+        }
+        return response;
+      } finally
+      {
+        if (msg != null)
+        {
+          theViewer.stopProgressBar(null, handle);
         }
       }
-      return response;
-    } finally
+    }
+
+    /*
+     * fire and forget
+     */
+    String threadName = msg == null ? "StructureCommand" : msg;
+    new Thread(new Runnable()
     {
-      if (msg != null)
+      @Override
+      public void run()
       {
-        theViewer.stopProgressBar(null, handle);
+        try
+        {
+          for (StructureCommandI cmd : cmds)
+          {
+            executeCommand(cmd, false);
+          }
+        } finally
+        {
+          if (msg != null)
+          {
+            SwingUtilities.invokeLater(new Runnable()
+            {
+              @Override
+              public void run()
+              {
+                theViewer.stopProgressBar(null, handle);
+              }
+            });
+          }
+        }
       }
-    }
+    }, threadName).start();
+    return null;
   }
 
   /**
-   * colour any structures associated with sequences in the given alignment
-   * using the getFeatureRenderer() and getSequenceRenderer() renderers but only
-   * if colourBySequence is enabled.
+   * Colours any structures associated with sequences in the given alignment as
+   * coloured in the alignment view, provided colourBySequence is enabled
    */
   public void colourBySequence(AlignmentViewPanel alignmentv)
   {
-    if (!colourBySequence || !isLoadingFinished())
+    if (!colourBySequence || !isLoadingFinished() || getSsm() == null)
     {
       return;
     }
-    if (getSsm() == null)
-    {
-      return;
-    }
-    String[] files = getStructureFiles();
-
-    SequenceRenderer sr = getSequenceRenderer(alignmentv);
-    Map<Object, AtomSpecModel> colourMap = buildColoursMap(ssm, files,
-            sequence, sr, alignmentv);
+    Map<Object, AtomSpecModel> colourMap = buildColoursMap(ssm, sequence,
+            alignmentv);
 
     List<StructureCommandI> colourBySequenceCommands = commandGenerator
             .colourBySequence(colourMap);
-    executeCommands(colourBySequenceCommands, false, null);
+    executeCommands(colourBySequenceCommands, false, COLOURING_STRUCTURES);
   }
 
   /**
@@ -1190,7 +1174,7 @@ public abstract class AAStructureBindingModel
    */
   public void focusView()
   {
-    executeCommand(commandGenerator.focusView(), false, null);
+    executeCommand(false, null, commandGenerator.focusView());
   }
 
   /**
@@ -1238,8 +1222,7 @@ public abstract class AAStructureBindingModel
   }
 
   /**
-   * Returns the FeatureRenderer for the given alignment view, or null if
-   * feature display is turned off in the view.
+   * Returns the FeatureRenderer for the given alignment view
    * 
    * @param avp
    * @return
@@ -1248,9 +1231,11 @@ public abstract class AAStructureBindingModel
   {
     AlignmentViewPanel ap = (avp == null) ? getViewer().getAlignmentPanel()
             : avp;
-    return ap.getAlignViewport().isShowSequenceFeatures()
-            ? ap.getFeatureRenderer()
-            : null;
+    if (ap == null)
+    {
+      return null;
+    }
+    return ap.getFeatureRenderer();
   }
 
   protected void setStructureCommands(StructureCommandsI cmd)
@@ -1305,40 +1290,6 @@ public abstract class AAStructureBindingModel
   protected abstract ViewerType getViewerType();
 
   /**
-   * Send a structure viewer command asynchronously in a new thread. If the
-   * progress message is not null, display this message while the command is
-   * executing.
-   * 
-   * @param command
-   * @param progressMsg
-   */
-  protected void sendAsynchronousCommand(StructureCommandI command,
-          String progressMsg)
-  {
-    final JalviewStructureDisplayI theViewer = getViewer();
-    final long handle = progressMsg == null ? 0
-            : theViewer.startProgressBar(progressMsg);
-    SwingUtilities.invokeLater(new Runnable()
-    {
-      @Override
-      public void run()
-      {
-        try
-        {
-          executeCommand(command, false, null);
-        } finally
-        {
-          if (progressMsg != null)
-          {
-            theViewer.stopProgressBar(null, handle);
-          }
-        }
-      }
-    });
-
-  }
-
-  /**
    * Builds a data structure which records mapped structure residues for each
    * colour. From this we can easily generate the viewer commands for colour by
    * sequence. Constructs and returns a map of {@code Color} to
@@ -1354,16 +1305,16 @@ public abstract class AAStructureBindingModel
    * models and chains)
    * 
    * @param ssm
-   * @param files
    * @param sequence
-   * @param sr
    * @param viewPanel
    * @return
    */
   protected Map<Object, AtomSpecModel> buildColoursMap(
-          StructureSelectionManager ssm, String[] files,
-          SequenceI[][] sequence, SequenceRenderer sr, AlignmentViewPanel viewPanel)
+          StructureSelectionManager ssm, SequenceI[][] sequence,
+          AlignmentViewPanel viewPanel)
   {
+    String[] files = getStructureFiles();
+    SequenceRenderer sr = getSequenceRenderer(viewPanel);
     FeatureRenderer fr = viewPanel.getFeatureRenderer();
     FeatureColourFinder finder = new FeatureColourFinder(fr);
     AlignViewportI viewport = viewPanel.getAlignViewport();
@@ -1371,17 +1322,17 @@ public abstract class AAStructureBindingModel
     AlignmentI al = viewport.getAlignment();
     Map<Object, AtomSpecModel> colourMap = new LinkedHashMap<>();
     Color lastColour = null;
-  
+
     for (int pdbfnum = 0; pdbfnum < files.length; pdbfnum++)
     {
       final String modelId = getModelIdForFile(files[pdbfnum]);
       StructureMapping[] mapping = ssm.getMapping(files[pdbfnum]);
-  
+
       if (mapping == null || mapping.length < 1)
       {
         continue;
       }
-  
+
       int startPos = -1, lastPos = -1;
       String lastChain = "";
       for (int s = 0; s < sequence[pdbfnum].length; s++)
@@ -1401,14 +1352,14 @@ public abstract class AAStructureBindingModel
                 continue;
               }
               int pos = mapping[m].getPDBResNum(asp.findPosition(r));
-  
+
               if (pos < 1 || pos == lastPos)
               {
                 continue;
               }
-  
+
               Color colour = sr.getResidueColour(seq, r, finder);
-  
+
               /*
                * darker colour for hidden regions
                */
@@ -1416,9 +1367,9 @@ public abstract class AAStructureBindingModel
               {
                 colour = Color.GRAY;
               }
-  
+
               final String chain = mapping[m].getChain();
-  
+
               /*
                * Just keep incrementing the end position for this colour range
                * _unless_ colour, PDB model or chain has changed, or there is a
@@ -1431,8 +1382,8 @@ public abstract class AAStructureBindingModel
               {
                 if (startPos != -1)
                 {
-                  addAtomSpecRange(colourMap, lastColour, modelId,
-                          startPos, lastPos, lastChain);
+                  addAtomSpecRange(colourMap, lastColour, modelId, startPos,
+                          lastPos, lastChain);
                 }
                 startPos = pos;
               }
@@ -1484,8 +1435,9 @@ public abstract class AAStructureBindingModel
   }
 
   /**
-   * Helper method to add one contiguous range to the AtomSpec model for the given
-   * value (creating the model if necessary). As used by Jalview, {@code value} is
+   * Helper method to add one contiguous range to the AtomSpec model for the
+   * given value (creating the model if necessary). As used by Jalview,
+   * {@code value} is
    * <ul>
    * <li>a colour, when building a 'colour structure by sequence' command</li>
    * <li>a feature value, when building a 'set Chimera attributes from features'
@@ -1500,8 +1452,8 @@ public abstract class AAStructureBindingModel
    * @param chain
    */
   public static final void addAtomSpecRange(Map<Object, AtomSpecModel> map,
-          Object value,
-          String model, int startPos, int endPos, String chain)
+          Object value, String model, int startPos, int endPos,
+          String chain)
   {
     /*
      * Get/initialize map of data for the colour
@@ -1512,7 +1464,7 @@ public abstract class AAStructureBindingModel
       atomSpec = new AtomSpecModel();
       map.put(value, atomSpec);
     }
-  
+
     atomSpec.addRange(model, startPos, endPos, chain);
   }
 
@@ -1545,8 +1497,8 @@ public abstract class AAStructureBindingModel
       saveSession(f);
     } catch (IOException e)
     {
-      Cache.log.error(String.format("Error saving %s session: %s",
-              prefix, e.toString()));
+      Cache.log.error(String.format("Error saving %s session: %s", prefix,
+              e.toString()));
     }
 
     return f;
@@ -1559,11 +1511,439 @@ public abstract class AAStructureBindingModel
    */
   protected void saveSession(File f)
   {
-    StructureCommandI cmd = commandGenerator
-            .saveSession(f.getPath());
+    StructureCommandI cmd = commandGenerator.saveSession(f.getPath());
     if (cmd != null)
     {
       executeCommand(cmd, false);
     }
   }
+
+  /**
+   * Returns true if the viewer is an external structure viewer for which the
+   * process is still alive, else false (for Jmol, or an external viewer which
+   * the user has independently closed)
+   * 
+   * @return
+   */
+  public boolean isViewerRunning()
+  {
+    return false;
+  }
+
+  /**
+   * Closes Jalview's structure viewer panel and releases associated resources.
+   * If it is managing an external viewer program, and {@code forceClose} is
+   * true, also asks that program to close.
+   * 
+   * @param forceClose
+   */
+  public void closeViewer(boolean forceClose)
+  {
+    getSsm().removeStructureViewerListener(this, this.getStructureFiles());
+    releaseUIResources();
+
+    /*
+     * end the thread that closes this panel if the external viewer closes
+     */
+    if (externalViewerMonitor != null)
+    {
+      externalViewerMonitor.interrupt();
+      externalViewerMonitor = null;
+    }
+
+    stopListening();
+
+    if (forceClose)
+    {
+      StructureCommandI cmd = getCommandGenerator().closeViewer();
+      if (cmd != null)
+      {
+        executeCommand(cmd, false);
+      }
+    }
+  }
+
+  /**
+   * Returns the URL of a help page for the structure viewer, or null if none is
+   * known
+   * 
+   * @return
+   */
+  public String getHelpURL()
+  {
+    return null;
+  }
+
+  /**
+   * <pre>
+   * Helper method to build a map of 
+   *   { featureType, { feature value, AtomSpecModel } }
+   * </pre>
+   * 
+   * @param viewPanel
+   * @return
+   */
+  protected Map<String, Map<Object, AtomSpecModel>> buildFeaturesMap(
+          AlignmentViewPanel viewPanel)
+  {
+    Map<String, Map<Object, AtomSpecModel>> theMap = new LinkedHashMap<>();
+    String[] files = getStructureFiles();
+    if (files == null)
+    {
+      return theMap;
+    }
+
+    FeatureRenderer fr = viewPanel.getFeatureRenderer();
+    if (fr == null)
+    {
+      return theMap;
+    }
+
+    AlignViewportI viewport = viewPanel.getAlignViewport();
+    List<String> visibleFeatures = fr.getDisplayedFeatureTypes();
+
+    /*
+     * if alignment is showing features from complement, we also transfer
+     * these features to the corresponding mapped structure residues
+     */
+    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();
+    SequenceI[][] seqs = getSequence();
+
+    for (int pdbfnum = 0; pdbfnum < files.length; pdbfnum++)
+    {
+      String modelId = getModelIdForFile(files[pdbfnum]);
+      StructureMapping[] mapping = ssm.getMapping(files[pdbfnum]);
+
+      if (mapping == null || mapping.length < 1)
+      {
+        continue;
+      }
+
+      for (int seqNo = 0; seqNo < seqs[pdbfnum].length; seqNo++)
+      {
+        for (int m = 0; m < mapping.length; m++)
+        {
+          final SequenceI seq = seqs[pdbfnum][seqNo];
+          int sp = alignment.findIndex(seq);
+          StructureMapping structureMapping = mapping[m];
+          if (structureMapping.getSequence() == seq && sp > -1)
+          {
+            /*
+             * found a sequence with a mapping to a structure;
+             * now scan its features
+             */
+            if (!visibleFeatures.isEmpty())
+            {
+              scanSequenceFeatures(visibleFeatures, structureMapping, seq,
+                      theMap, modelId);
+            }
+            if (showLinkedFeatures)
+            {
+              scanComplementFeatures(complementRenderer, structureMapping,
+                      seq, theMap, modelId);
+            }
+          }
+        }
+      }
+    }
+    return theMap;
+  }
+
+  /**
+   * Ask the structure viewer to open a session file. Returns true if
+   * successful, else false (or not supported).
+   * 
+   * @param filepath
+   * @return
+   */
+  public boolean openSession(String filepath)
+  {
+    StructureCommandI cmd = getCommandGenerator().openSession(filepath);
+    if (cmd == null)
+    {
+      return false;
+    }
+    executeCommand(cmd, true);
+    // todo: test for failure - how?
+    return true;
+  }
+
+  /**
+   * 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,
+          String modelNumber)
+  {
+    /*
+     * for each sequence residue mapped to a structure position...
+     */
+    for (int seqPos : structureMapping.getMapping().keySet())
+    {
+      /*
+       * 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());
+            }
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * 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 theMap
+   * @param modelId
+   */
+  protected static void scanSequenceFeatures(List<String> visibleFeatures,
+          StructureMapping mapping, SequenceI seq,
+          Map<String, Map<Object, AtomSpecModel>> theMap, String modelId)
+  {
+    List<SequenceFeature> sfs = seq.getFeatures().getPositionalFeatures(
+            visibleFeatures.toArray(new String[visibleFeatures.size()]));
+    for (SequenceFeature sf : sfs)
+    {
+      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, modelId, range[0],
+                  range[1], mapping.getChain());
+        }
+      }
+    }
+  }
+
+  /**
+   * Returns the number of structure files in the structure viewer and mapped to
+   * Jalview. This may be zero if the files are still in the process of loading
+   * in the viewer.
+   * 
+   * @return
+   */
+  public int getMappedStructureCount()
+  {
+    String[] files = getStructureFiles();
+    return files == null ? 0 : files.length;
+  }
+
+  /**
+   * Starts a thread that waits for the external viewer program process to
+   * finish, so that we can then close the associated resources. This avoids
+   * leaving orphaned viewer panels in Jalview if the user closes the external
+   * viewer.
+   * 
+   * @param p
+   */
+  protected void startExternalViewerMonitor(Process p)
+  {
+    externalViewerMonitor = new Thread(new Runnable()
+    {
+
+      @Override
+      public void run()
+      {
+        try
+        {
+          p.waitFor();
+          JalviewStructureDisplayI display = getViewer();
+          if (display != null)
+          {
+            display.closeViewer(false);
+          }
+        } catch (InterruptedException e)
+        {
+          // exit thread if Chimera Viewer is closed in Jalview
+        }
+      }
+    });
+    externalViewerMonitor.start();
+  }
+
+  /**
+   * If supported by the external structure viewer, sends it commands to notify
+   * model or selection changes to the specified URL (where Jalview has started
+   * a listener)
+   * 
+   * @param uri
+   */
+  protected void startListening(String uri)
+  {
+    List<StructureCommandI> commands = getCommandGenerator()
+            .startNotifications(uri);
+    if (commands != null)
+    {
+      executeCommands(commands, false, null);
+    }
+  }
+
+  /**
+   * If supported by the external structure viewer, sends it commands to stop
+   * notifying model or selection changes
+   */
+  protected void stopListening()
+  {
+    List<StructureCommandI> commands = getCommandGenerator()
+            .stopNotifications();
+    if (commands != null)
+    {
+      executeCommands(commands, false, null);
+    }
+  }
+
+  /**
+   * If supported by the structure viewer, queries it for all residue attributes
+   * with the given attribute name, and creates features on corresponding
+   * residues of the alignment. Returns the number of features added.
+   * 
+   * @param attName
+   * @param alignmentPanel
+   * @return
+   */
+  public int copyStructureAttributesToFeatures(String attName,
+          AlignmentPanel alignmentPanel)
+  {
+    StructureCommandI cmd = getCommandGenerator()
+            .getResidueAttributes(attName);
+    if (cmd == null)
+    {
+      return 0;
+    }
+    List<String> residueAttributes = executeCommand(cmd, true);
+
+    int featuresAdded = createFeaturesForAttributes(attName,
+            residueAttributes);
+    if (featuresAdded > 0)
+    {
+      alignmentPanel.getFeatureRenderer().featuresAdded();
+    }
+    return featuresAdded;
+  }
+
+  /**
+   * Parses {@code residueAttributes} and creates sequence features on any
+   * mapped alignment residues. Returns the number of features created.
+   * <p>
+   * {@code residueAttributes} is the reply from the structure viewer to a
+   * command to list any residue attributes for the given attribute name. Syntax
+   * and parsing of this is viewer-specific.
+   * 
+   * @param attName
+   * @param residueAttributes
+   * @return
+   */
+  protected int createFeaturesForAttributes(String attName,
+          List<String> residueAttributes)
+  {
+    return 0;
+  }
 }