src/jalview/structures/models/AAStructureBindingModel.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.structures.models;
  22
  23 import java.awt.Color;
  24 import java.io.File;
  25 import java.io.IOException;
  26 import java.util.ArrayList;
  27 import java.util.Arrays;
  28 import java.util.BitSet;
  29 import java.util.HashMap;
  30 import java.util.LinkedHashMap;
  31 import java.util.List;
  32 import java.util.Map;
  33
  34 import javax.swing.SwingUtilities;
  35
  36 import jalview.api.AlignViewportI;
  37 import jalview.api.AlignmentViewPanel;
  38 import jalview.api.FeatureRenderer;
  39 import jalview.api.SequenceRenderer;
  40 import jalview.api.StructureSelectionManagerProvider;
  41 import jalview.api.structures.JalviewStructureDisplayI;
  42 import jalview.bin.Cache;
  43 import jalview.datamodel.AlignmentI;
  44 import jalview.datamodel.HiddenColumns;
  45 import jalview.datamodel.MappedFeatures;
  46 import jalview.datamodel.PDBEntry;
  47 import jalview.datamodel.SequenceFeature;
  48 import jalview.datamodel.SequenceI;
  49 import jalview.ext.rbvi.chimera.JalviewChimeraBinding;
  50 import jalview.gui.AlignmentPanel;
  51 import jalview.gui.Desktop;
  52 import jalview.gui.StructureViewer.ViewerType;
  53 import jalview.io.DataSourceType;
  54 import jalview.io.StructureFile;
  55 import jalview.renderer.seqfeatures.FeatureColourFinder;
  56 import jalview.schemes.ColourSchemeI;
  57 import jalview.schemes.ResidueProperties;
  58 import jalview.structure.AtomSpec;
  59 import jalview.structure.AtomSpecModel;
  60 import jalview.structure.StructureCommandI;
  61 import jalview.structure.StructureCommandsI;
  62 import jalview.structure.StructureListener;
  63 import jalview.structure.StructureMapping;
  64 import jalview.structure.StructureSelectionManager;
  65 import jalview.util.Comparison;
  66 import jalview.util.MessageManager;
  67
  68 /**
  69  *
  70  * A base class to hold common function for protein structure model binding.
  71  * Initial version created by refactoring JMol and Chimera binding models, but
  72  * other structure viewers could in principle be accommodated in future.
  73  *
  74  * @author gmcarstairs
  75  *
  76  */
  77 public abstract class AAStructureBindingModel
  78         extends SequenceStructureBindingModel
  79         implements StructureListener, StructureSelectionManagerProvider
  80 {
  81   /**
  82    * Data bean class to simplify parameterisation in superposeStructures
  83    */
  84   public static class SuperposeData
  85   {
  86     public String filename;
  87
  88     public String pdbId;
  89
  90     public String chain = "";
  91
  92     public boolean isRna;
  93
  94     /*
  95      * The pdb residue number (if any) mapped to columns of the alignment
  96      */
  97     public int[] pdbResNo; // or use SparseIntArray?
  98
  99     public String modelId;
 100
 101     /**
 102      * Constructor
 103      *
 104      * @param width
 105      *          width of alignment (number of columns that may potentially
 106      *          participate in superposition)
 107      * @param model
 108      *          structure viewer model number
 109      */
 110     public SuperposeData(int width, String model)
 111     {
 112       pdbResNo = new int[width];
 113       modelId = model;
 114     }
 115   }
 116
 117   private static final int MIN_POS_TO_SUPERPOSE = 4;
 118
 119   private static final String COLOURING_STRUCTURES = MessageManager
 120           .getString("status.colouring_structures");
 121
 122   /*
 123    * the Jalview panel through which the user interacts
 124    * with the structure viewer
 125    */
 126   private JalviewStructureDisplayI viewer;
 127
 128   /*
 129    * helper that generates command syntax
 130    */
 131   private StructureCommandsI commandGenerator;
 132
 133   private StructureSelectionManager ssm;
 134
 135   /*
 136    * modelled chains, formatted as "pdbid:chainCode"
 137    */
 138   private List<String> chainNames;
 139
 140   /*
 141    * lookup of pdb file name by key "pdbid:chainCode"
 142    */
 143   private Map<String, String> chainFile;
 144
 145   /*
 146    * distinct PDB entries (pdb files) associated
 147    * with sequences
 148    */
 149   private PDBEntry[] pdbEntry;
 150
 151   /*
 152    * sequences mapped to each pdbentry
 153    */
 154   private SequenceI[][] sequence;
 155
 156   /*
 157    * array of target chains for sequences - tied to pdbentry and sequence[]
 158    */
 159   private String[][] chains;
 160
 161   /*
 162    * datasource protocol for access to PDBEntrylatest
 163    */
 164   DataSourceType protocol = null;
 165
 166   protected boolean colourBySequence = true;
 167
 168   private boolean nucleotide;
 169
 170   private boolean finishedInit = false;
 171
 172   /**
 173    * current set of model filenames loaded in the viewer
 174    */
 175   protected String[] modelFileNames = null;
 176
 177   public String fileLoadingError;
 178
 179   protected Thread externalViewerMonitor;
 180
 181   /**
 182    * Constructor
 183    *
 184    * @param ssm
 185    * @param seqs
 186    */
 187   public AAStructureBindingModel(StructureSelectionManager ssm,
 188           SequenceI[][] seqs)
 189   {
 190     this.ssm = ssm;
 191     this.sequence = seqs;
 192     chainNames = new ArrayList<>();
 193     chainFile = new HashMap<>();
 194   }
 195
 196   /**
 197    * Constructor
 198    *
 199    * @param ssm
 200    * @param pdbentry
 201    * @param sequenceIs
 202    * @param protocol
 203    */
 204   public AAStructureBindingModel(StructureSelectionManager ssm,
 205           PDBEntry[] pdbentry, SequenceI[][] sequenceIs,
 206           DataSourceType protocol)
 207   {
 208     this(ssm, sequenceIs);
 209     this.nucleotide = Comparison.isNucleotide(sequenceIs);
 210     this.pdbEntry = pdbentry;
 211     this.protocol = protocol;
 212     resolveChains();
 213   }
 214
 215   private boolean resolveChains()
 216   {
 217     /**
 218      * final count of chain mappings discovered
 219      */
 220     int chainmaps = 0;
 221     // JBPNote: JAL-2693 - this should be a list of chain mappings per
 222     // [pdbentry][sequence]
 223     String[][] newchains = new String[pdbEntry.length][];
 224     int pe = 0;
 225     for (PDBEntry pdb : pdbEntry)
 226     {
 227       SequenceI[] seqsForPdb = sequence[pe];
 228       if (seqsForPdb != null)
 229       {
 230         newchains[pe] = new String[seqsForPdb.length];
 231         int se = 0;
 232         for (SequenceI asq : seqsForPdb)
 233         {
 234           String chain = (chains != null && chains[pe] != null)
 235                   ? chains[pe][se]
 236                   : null;
 237           SequenceI sq = (asq.getDatasetSequence() == null) ? asq
 238                   : asq.getDatasetSequence();
 239           if (sq.getAllPDBEntries() != null)
 240           {
 241             for (PDBEntry pdbentry : sq.getAllPDBEntries())
 242             {
 243               if (pdb.getFile() != null && pdbentry.getFile() != null
 244                       && pdb.getFile().equals(pdbentry.getFile()))
 245               {
 246                 String chaincode = pdbentry.getChainCode();
 247                 if (chaincode != null && chaincode.length() > 0)
 248                 {
 249                   chain = chaincode;
 250                   chainmaps++;
 251                   break;
 252                 }
 253               }
 254             }
 255           }
 256           newchains[pe][se] = chain;
 257           se++;
 258         }
 259         pe++;
 260       }
 261     }
 262
 263     chains = newchains;
 264     return chainmaps > 0;
 265   }
 266
 267   public StructureSelectionManager getSsm()
 268   {
 269     return ssm;
 270   }
 271
 272   /**
 273    * Returns the i'th PDBEntry (or null)
 274    *
 275    * @param i
 276    * @return
 277    */
 278   public PDBEntry getPdbEntry(int i)
 279   {
 280     return (pdbEntry != null && pdbEntry.length > i) ? pdbEntry[i] : null;
 281   }
 282
 283   /**
 284    * Answers true if this binding includes the given PDB id, else false
 285    *
 286    * @param pdbId
 287    * @return
 288    */
 289   public boolean hasPdbId(String pdbId)
 290   {
 291     if (pdbEntry != null)
 292     {
 293       for (PDBEntry pdb : pdbEntry)
 294       {
 295         if (pdb.getId().equals(pdbId))
 296         {
 297           return true;
 298         }
 299       }
 300     }
 301     return false;
 302   }
 303
 304   /**
 305    * Returns the number of modelled PDB file entries.
 306    *
 307    * @return
 308    */
 309   public int getPdbCount()
 310   {
 311     return pdbEntry == null ? 0 : pdbEntry.length;
 312   }
 313
 314   public SequenceI[][] getSequence()
 315   {
 316     return sequence;
 317   }
 318
 319   public String[][] getChains()
 320   {
 321     return chains;
 322   }
 323
 324   public DataSourceType getProtocol()
 325   {
 326     return protocol;
 327   }
 328
 329   // TODO may remove this if calling methods can be pulled up here
 330   protected void setPdbentry(PDBEntry[] pdbentry)
 331   {
 332     this.pdbEntry = pdbentry;
 333   }
 334
 335   protected void setSequence(SequenceI[][] sequence)
 336   {
 337     this.sequence = sequence;
 338   }
 339
 340   protected void setChains(String[][] chains)
 341   {
 342     this.chains = chains;
 343   }
 344
 345   /**
 346    * Construct a title string for the viewer window based on the data Jalview
 347    * knows about
 348    *
 349    * @param viewerName
 350    *          TODO
 351    * @param verbose
 352    *
 353    * @return
 354    */
 355   public String getViewerTitle(String viewerName, boolean verbose)
 356   {
 357     if (getSequence() == null || getSequence().length < 1
 358             || getPdbCount() < 1 || getSequence()[0].length < 1)
 359     {
 360       return ("Jalview " + viewerName + " Window");
 361     }
 362     // TODO: give a more informative title when multiple structures are
 363     // displayed.
 364     StringBuilder title = new StringBuilder(64);
 365     final PDBEntry pdbe = getPdbEntry(0);
 366     title.append(viewerName + " view for " + getSequence()[0][0].getName()
 367             + ":" + pdbe.getId());
 368
 369     if (verbose)
 370     {
 371       String method = (String) pdbe.getProperty("method");
 372       if (method != null)
 373       {
 374         title.append(" Method: ").append(method);
 375       }
 376       String chain = (String) pdbe.getProperty("chains");
 377       if (chain != null)
 378       {
 379         title.append(" Chain:").append(chain);
 380       }
 381     }
 382     return title.toString();
 383   }
 384
 385   /**
 386    * Called by after closeViewer is called, to release any resources and
 387    * references so they can be garbage collected. Override if needed.
 388    */
 389   protected void releaseUIResources()
 390   {
 391   }
 392
 393   @Override
 394   public void releaseReferences(Object svl)
 395   {
 396   }
 397
 398   public boolean isColourBySequence()
 399   {
 400     return colourBySequence;
 401   }
 402
 403   /**
 404    * Called when the binding thinks the UI needs to be refreshed after a
 405    * structure viewer state change. This could be because structures were
 406    * loaded, or because an error has occurred. Default does nothing, override as
 407    * required.
 408    */
 409   public void refreshGUI()
 410   {
 411   }
 412
 413   /**
 414    * Instruct the Jalview binding to update the pdbentries vector if necessary
 415    * prior to matching the jmol view's contents to the list of structure files
 416    * Jalview knows about. By default does nothing, override as required.
 417    */
 418   public void refreshPdbEntries()
 419   {
 420   }
 421
 422   public void setColourBySequence(boolean colourBySequence)
 423   {
 424     this.colourBySequence = colourBySequence;
 425   }
 426
 427   protected void addSequenceAndChain(int pe, SequenceI[] seq,
 428           String[] tchain)
 429   {
 430     if (pe < 0 || pe >= getPdbCount())
 431     {
 432       throw new Error(MessageManager.formatMessage(
 433               "error.implementation_error_no_pdbentry_from_index",
 434               new Object[]
 435               { Integer.valueOf(pe).toString() }));
 436     }
 437     final String nullChain = "TheNullChain";
 438     List<SequenceI> s = new ArrayList<>();
 439     List<String> c = new ArrayList<>();
 440     if (getChains() == null)
 441     {
 442       setChains(new String[getPdbCount()][]);
 443     }
 444     if (getSequence()[pe] != null)
 445     {
 446       for (int i = 0; i < getSequence()[pe].length; i++)
 447       {
 448         s.add(getSequence()[pe][i]);
 449         if (getChains()[pe] != null)
 450         {
 451           if (i < getChains()[pe].length)
 452           {
 453             c.add(getChains()[pe][i]);
 454           }
 455           else
 456           {
 457             c.add(nullChain);
 458           }
 459         }
 460         else
 461         {
 462           if (tchain != null && tchain.length > 0)
 463           {
 464             c.add(nullChain);
 465           }
 466         }
 467       }
 468     }
 469     for (int i = 0; i < seq.length; i++)
 470     {
 471       if (!s.contains(seq[i]))
 472       {
 473         s.add(seq[i]);
 474         if (tchain != null && i < tchain.length)
 475         {
 476           c.add(tchain[i] == null ? nullChain : tchain[i]);
 477         }
 478       }
 479     }
 480     SequenceI[] tmp = s.toArray(new SequenceI[s.size()]);
 481     getSequence()[pe] = tmp;
 482     if (c.size() > 0)
 483     {
 484       String[] tch = c.toArray(new String[c.size()]);
 485       for (int i = 0; i < tch.length; i++)
 486       {
 487         if (tch[i] == nullChain)
 488         {
 489           tch[i] = null;
 490         }
 491       }
 492       getChains()[pe] = tch;
 493     }
 494     else
 495     {
 496       getChains()[pe] = null;
 497     }
 498   }
 499
 500   /**
 501    * add structures and any known sequence associations
 502    *
 503    * @returns the pdb entries added to the current set.
 504    */
 505   public synchronized PDBEntry[] addSequenceAndChain(PDBEntry[] pdbe,
 506           SequenceI[][] seq, String[][] chns)
 507   {
 508     List<PDBEntry> v = new ArrayList<>();
 509     List<int[]> rtn = new ArrayList<>();
 510     for (int i = 0; i < getPdbCount(); i++)
 511     {
 512       v.add(getPdbEntry(i));
 513     }
 514     for (int i = 0; i < pdbe.length; i++)
 515     {
 516       int r = v.indexOf(pdbe[i]);
 517       if (r == -1 || r >= getPdbCount())
 518       {
 519         rtn.add(new int[] { v.size(), i });
 520         v.add(pdbe[i]);
 521       }
 522       else
 523       {
 524         // just make sure the sequence/chain entries are all up to date
 525         addSequenceAndChain(r, seq[i], chns[i]);
 526       }
 527     }
 528     pdbe = v.toArray(new PDBEntry[v.size()]);
 529     setPdbentry(pdbe);
 530     if (rtn.size() > 0)
 531     {
 532       // expand the tied sequence[] and string[] arrays
 533       SequenceI[][] sqs = new SequenceI[getPdbCount()][];
 534       String[][] sch = new String[getPdbCount()][];
 535       System.arraycopy(getSequence(), 0, sqs, 0, getSequence().length);
 536       System.arraycopy(getChains(), 0, sch, 0, this.getChains().length);
 537       setSequence(sqs);
 538       setChains(sch);
 539       pdbe = new PDBEntry[rtn.size()];
 540       for (int r = 0; r < pdbe.length; r++)
 541       {
 542         int[] stri = (rtn.get(r));
 543         // record the pdb file as a new addition
 544         pdbe[r] = getPdbEntry(stri[0]);
 545         // and add the new sequence/chain entries
 546         addSequenceAndChain(stri[0], seq[stri[1]], chns[stri[1]]);
 547       }
 548     }
 549     else
 550     {
 551       pdbe = null;
 552     }
 553     return pdbe;
 554   }
 555
 556   /**
 557    * Add sequences to the pe'th pdbentry's sequence set.
 558    *
 559    * @param pe
 560    * @param seq
 561    */
 562   public void addSequence(int pe, SequenceI[] seq)
 563   {
 564     addSequenceAndChain(pe, seq, null);
 565   }
 566
 567   /**
 568    * add the given sequences to the mapping scope for the given pdb file handle
 569    *
 570    * @param pdbFile
 571    *          - pdbFile identifier
 572    * @param seq
 573    *          - set of sequences it can be mapped to
 574    */
 575   public void addSequenceForStructFile(String pdbFile, SequenceI[] seq)
 576   {
 577     for (int pe = 0; pe < getPdbCount(); pe++)
 578     {
 579       if (getPdbEntry(pe).getFile().equals(pdbFile))
 580       {
 581         addSequence(pe, seq);
 582       }
 583     }
 584   }
 585
 586   @Override
 587   public abstract void highlightAtoms(List<AtomSpec> atoms);
 588
 589   protected boolean isNucleotide()
 590   {
 591     return this.nucleotide;
 592   }
 593
 594   /**
 595    * Returns a readable description of all mappings for the wrapped pdbfile to
 596    * any mapped sequences
 597    *
 598    * @param pdbfile
 599    * @param seqs
 600    * @return
 601    */
 602   public String printMappings()
 603   {
 604     if (pdbEntry == null)
 605     {
 606       return "";
 607     }
 608     StringBuilder sb = new StringBuilder(128);
 609     for (int pdbe = 0; pdbe < getPdbCount(); pdbe++)
 610     {
 611       String pdbfile = getPdbEntry(pdbe).getFile();
 612       List<SequenceI> seqs = Arrays.asList(getSequence()[pdbe]);
 613       sb.append(getSsm().printMappings(pdbfile, seqs));
 614     }
 615     return sb.toString();
 616   }
 617
 618   /**
 619    * Returns the mapped structure position for a given aligned column of a given
 620    * sequence, or -1 if the column is gapped, beyond the end of the sequence, or
 621    * not mapped to structure.
 622    *
 623    * @param seq
 624    * @param alignedPos
 625    * @param mapping
 626    * @return
 627    */
 628   protected int getMappedPosition(SequenceI seq, int alignedPos,
 629           StructureMapping mapping)
 630   {
 631     if (alignedPos >= seq.getLength())
 632     {
 633       return -1;
 634     }
 635
 636     if (Comparison.isGap(seq.getCharAt(alignedPos)))
 637     {
 638       return -1;
 639     }
 640     int seqPos = seq.findPosition(alignedPos);
 641     int pos = mapping.getPDBResNum(seqPos);
 642     return pos;
 643   }
 644
 645   /**
 646    * Helper method to identify residues that can participate in a structure
 647    * superposition command. For each structure, identify a sequence in the
 648    * alignment which is mapped to the structure. Identify non-gapped columns in
 649    * the sequence which have a mapping to a residue in the structure. Returns
 650    * the index of the first structure that has a mapping to the alignment.
 651    *
 652    * @param alignment
 653    *          the sequence alignment which is the basis of structure
 654    *          superposition
 655    * @param matched
 656    *          a BitSet, where bit j is set to indicate that every structure has
 657    *          a mapped residue present in column j (so the column can
 658    *          participate in structure alignment)
 659    * @param structures
 660    *          an array of data beans corresponding to pdb file index
 661    * @return
 662    */
 663   protected int findSuperposableResidues(AlignmentI alignment,
 664           BitSet matched,
 665           AAStructureBindingModel.SuperposeData[] structures)
 666   {
 667     int refStructure = -1;
 668     String[] files = getStructureFiles();
 669     if (files == null)
 670     {
 671       return -1;
 672     }
 673     for (int pdbfnum = 0; pdbfnum < files.length; pdbfnum++)
 674     {
 675       StructureMapping[] mappings = getSsm().getMapping(files[pdbfnum]);
 676       int lastPos = -1;
 677
 678       /*
 679        * Find the first mapped sequence (if any) for this PDB entry which is in
 680        * the alignment
 681        */
 682       final int seqCountForPdbFile = getSequence()[pdbfnum].length;
 683       for (int s = 0; s < seqCountForPdbFile; s++)
 684       {
 685         for (StructureMapping mapping : mappings)
 686         {
 687           final SequenceI theSequence = getSequence()[pdbfnum][s];
 688           if (mapping.getSequence() == theSequence
 689                   && alignment.findIndex(theSequence) > -1)
 690           {
 691             if (refStructure < 0)
 692             {
 693               refStructure = pdbfnum;
 694             }
 695             for (int r = 0; r < alignment.getWidth(); r++)
 696             {
 697               if (!matched.get(r))
 698               {
 699                 continue;
 700               }
 701               int pos = getMappedPosition(theSequence, r, mapping);
 702               if (pos < 1 || pos == lastPos)
 703               {
 704                 matched.clear(r);
 705                 continue;
 706               }
 707               lastPos = pos;
 708               structures[pdbfnum].pdbResNo[r] = pos;
 709             }
 710             String chain = mapping.getChain();
 711             if (chain != null && chain.trim().length() > 0)
 712             {
 713               structures[pdbfnum].chain = chain;
 714             }
 715             structures[pdbfnum].pdbId = mapping.getPdbId();
 716             structures[pdbfnum].isRna = theSequence.getRNA() != null;
 717
 718             /*
 719              * move on to next pdb file (ignore sequences for other chains
 720              * for the same structure)
 721              */
 722             s = seqCountForPdbFile;
 723             break; // fixme break out of two loops here!
 724           }
 725         }
 726       }
 727     }
 728     return refStructure;
 729   }
 730
 731   /**
 732    * Returns true if the structure viewer has loaded all of the files of
 733    * interest (identified by the file mapping having been set up), or false if
 734    * any are still not loaded after a timeout interval.
 735    *
 736    * @param files
 737    */
 738   protected boolean waitForFileLoad(String[] files)
 739   {
 740     /*
 741      * give up after 10 secs plus 1 sec per file
 742      */
 743     long starttime = System.currentTimeMillis();
 744     long endTime = 10000 + 1000 * files.length + starttime;
 745     String notLoaded = null;
 746
 747     boolean waiting = true;
 748     while (waiting && System.currentTimeMillis() < endTime)
 749     {
 750       waiting = false;
 751       for (String file : files)
 752       {
 753         notLoaded = file;
 754         if (file == null)
 755         {
 756           continue;
 757         }
 758         try
 759         {
 760           StructureMapping[] sm = getSsm().getMapping(file);
 761           if (sm == null || sm.length == 0)
 762           {
 763             waiting = true;
 764           }
 765         } catch (Throwable x)
 766         {
 767           waiting = true;
 768         }
 769       }
 770     }
 771
 772     if (waiting)
 773     {
 774       System.err.println(
 775               "Timed out waiting for structure viewer to load file "
 776                       + notLoaded);
 777       return false;
 778     }
 779     return true;
 780   }
 781
 782   @Override
 783   public boolean isListeningFor(SequenceI seq)
 784   {
 785     if (sequence != null)
 786     {
 787       for (SequenceI[] seqs : sequence)
 788       {
 789         if (seqs != null)
 790         {
 791           for (SequenceI s : seqs)
 792           {
 793             if (s == seq || (s.getDatasetSequence() != null
 794                     && s.getDatasetSequence() == seq.getDatasetSequence()))
 795             {
 796               return true;
 797             }
 798           }
 799         }
 800       }
 801     }
 802     return false;
 803   }
 804
 805   public boolean isFinishedInit()
 806   {
 807     return finishedInit;
 808   }
 809
 810   public void setFinishedInit(boolean fi)
 811   {
 812     this.finishedInit = fi;
 813   }
 814
 815   /**
 816    * Returns a list of chains mapped in this viewer, formatted as
 817    * "pdbid:chainCode"
 818    *
 819    * @return
 820    */
 821   public List<String> getChainNames()
 822   {
 823     return chainNames;
 824   }
 825
 826   /**
 827    * Returns the Jalview panel hosting the structure viewer (if any)
 828    *
 829    * @return
 830    */
 831   public JalviewStructureDisplayI getViewer()
 832   {
 833     return viewer;
 834   }
 835
 836   public void setViewer(JalviewStructureDisplayI v)
 837   {
 838     viewer = v;
 839   }
 840
 841   /**
 842    * Constructs and sends a command to align structures against a reference
 843    * structure, based on one or more sequence alignments. May optionally return
 844    * an error or warning message for the alignment command(s).
 845    *
 846    * @param alignWith
 847    *          an array of one or more alignment views to process
 848    * @return
 849    */
 850   public String superposeStructures(List<AlignmentViewPanel> alignWith)
 851   {
 852     String error = "";
 853     String[] files = getStructureFiles();
 854
 855     if (!waitForFileLoad(files))
 856     {
 857       return null;
 858     }
 859     refreshPdbEntries();
 860
 861     for (AlignmentViewPanel view : alignWith)
 862     {
 863       AlignmentI alignment = view.getAlignment();
 864       HiddenColumns hiddenCols = alignment.getHiddenColumns();
 865
 866       /*
 867        * 'matched' bit i will be set for visible alignment columns i where
 868        * all sequences have a residue with a mapping to their PDB structure
 869        */
 870       BitSet matched = new BitSet();
 871       final int width = alignment.getWidth();
 872       for (int m = 0; m < width; m++)
 873       {
 874         if (hiddenCols == null || hiddenCols.isVisible(m))
 875         {
 876           matched.set(m);
 877         }
 878       }
 879
 880       AAStructureBindingModel.SuperposeData[] structures = new AAStructureBindingModel.SuperposeData[files.length];
 881       for (int f = 0; f < files.length; f++)
 882       {
 883         structures[f] = new AAStructureBindingModel.SuperposeData(width,
 884                 getModelIdForFile(files[f]));
 885       }
 886
 887       /*
 888        * Calculate the superposable alignment columns ('matched'), and the
 889        * corresponding structure residue positions (structures.pdbResNo)
 890        */
 891       int refStructure = findSuperposableResidues(alignment, matched,
 892               structures);
 893
 894       /*
 895        * require at least 4 positions to be able to execute superposition
 896        */
 897       int nmatched = matched.cardinality();
 898       if (nmatched < MIN_POS_TO_SUPERPOSE)
 899       {
 900         String msg = MessageManager
 901                 .formatMessage("label.insufficient_residues", nmatched);
 902         error += view.getViewName() + ": " + msg + "; ";
 903         continue;
 904       }
 905
 906       /*
 907        * get a model of the superposable residues in the reference structure
 908        */
 909       AtomSpecModel refAtoms = getAtomSpec(structures[refStructure],
 910               matched);
 911
 912       /*
 913        * Show all as backbone before doing superposition(s)
 914        * (residues used for matching will be shown as ribbon)
 915        */
 916       // todo better way to ensure synchronous than setting getReply true!!
 917       executeCommands(commandGenerator.showBackbone(), true, null);
 918
 919       /*
 920        * superpose each (other) structure to the reference in turn
 921        */
 922       for (int i = 0; i < structures.length; i++)
 923       {
 924         if (i != refStructure)
 925         {
 926           AtomSpecModel atomSpec = getAtomSpec(structures[i], matched);
 927           List<StructureCommandI> commands = commandGenerator
 928                   .superposeStructures(refAtoms, atomSpec);
 929           List<String> replies = executeCommands(commands, true, null);
 930           for (String reply : replies)
 931           {
 932             // return this error (Chimera only) to the user
 933             if (reply.toLowerCase().contains("unequal numbers of atoms"))
 934             {
 935               error += "; " + reply;
 936             }
 937           }
 938         }
 939       }
 940     }
 941
 942     return error;
 943   }
 944
 945   private AtomSpecModel getAtomSpec(
 946           AAStructureBindingModel.SuperposeData superposeData,
 947           BitSet matched)
 948   {
 949     AtomSpecModel model = new AtomSpecModel();
 950     int nextColumnMatch = matched.nextSetBit(0);
 951     while (nextColumnMatch != -1)
 952     {
 953       int pdbResNum = superposeData.pdbResNo[nextColumnMatch];
 954       model.addRange(superposeData.modelId, pdbResNum, pdbResNum,
 955               superposeData.chain);
 956       nextColumnMatch = matched.nextSetBit(nextColumnMatch + 1);
 957     }
 958
 959     return model;
 960   }
 961
 962   /**
 963    * returns the current sequenceRenderer that should be used to colour the
 964    * structures
 965    *
 966    * @param alignment
 967    *
 968    * @return
 969    */
 970   public abstract SequenceRenderer getSequenceRenderer(
 971           AlignmentViewPanel alignment);
 972
 973   /**
 974    * Sends a command to the structure viewer to colour each chain with a
 975    * distinct colour (to the extent supported by the viewer)
 976    */
 977   public void colourByChain()
 978   {
 979     colourBySequence = false;
 980
 981     // TODO: JAL-628 colour chains distinctly across all visible models
 982
 983     executeCommand(false, COLOURING_STRUCTURES,
 984             commandGenerator.colourByChain());
 985   }
 986
 987   /**
 988    * Sends a command to the structure viewer to colour each chain with a
 989    * distinct colour (to the extent supported by the viewer)
 990    */
 991   public void colourByCharge()
 992   {
 993     colourBySequence = false;
 994
 995     executeCommands(commandGenerator.colourByCharge(), false,
 996             COLOURING_STRUCTURES);
 997   }
 998
 999   /**
1000    * Sends a command to the structure to apply a colour scheme (defined in
1001    * Jalview but not necessarily applied to the alignment), which defines a
1002    * colour per residue letter. More complex schemes (e.g. that depend on
1003    * consensus) cannot be used here and are ignored.
1004    *
1005    * @param cs
1006    */
1007   public void colourByJalviewColourScheme(ColourSchemeI cs)
1008   {
1009     colourBySequence = false;
1010
1011     if (cs == null || !cs.isSimple())
1012     {
1013       return;
1014     }
1015
1016     /*
1017      * build a map of {Residue3LetterCode, Color}
1018      */
1019     Map<String, Color> colours = new HashMap<>();
1020     List<String> residues = ResidueProperties.getResidues(isNucleotide(),
1021             false);
1022     for (String resName : residues)
1023     {
1024       char res = resName.length() == 3
1025               ? ResidueProperties.getSingleCharacterCode(resName)
1026               : resName.charAt(0);
1027       Color colour = cs.findColour(res, 0, null, null, 0f);
1028       colours.put(resName, colour);
1029     }
1030
1031     /*
1032      * pass to the command constructor, and send the command
1033      */
1034     List<StructureCommandI> cmd = commandGenerator
1035             .colourByResidues(colours);
1036     executeCommands(cmd, false, COLOURING_STRUCTURES);
1037   }
1038
1039   public void setBackgroundColour(Color col)
1040   {
1041     StructureCommandI cmd = commandGenerator.setBackgroundColour(col);
1042     executeCommand(false, null, cmd);
1043   }
1044
1045   /**
1046    * Execute one structure viewer command. If {@code getReply} is true, may
1047    * optionally return one or more reply messages, else returns null.
1048    *
1049    * @param cmd
1050    * @param getReply
1051    */
1052   protected abstract List<String> executeCommand(StructureCommandI cmd,
1053           boolean getReply);
1054
1055   /**
1056    * Executes one or more structure viewer commands
1057    *
1058    * @param commands
1059    * @param getReply
1060    * @param msg
1061    */
1062   protected List<String> executeCommands(List<StructureCommandI> commands,
1063           boolean getReply, String msg)
1064   {
1065     return executeCommand(getReply, msg,
1066             commands.toArray(new StructureCommandI[commands.size()]));
1067   }
1068
1069   /**
1070    * Executes one or more structure viewer commands, optionally returning the
1071    * reply, and optionally showing a status message while the command is being
1072    * executed.
1073    * <p>
1074    * If a reply is wanted, the execution is done synchronously (waits),
1075    * otherwise it is done in a separate thread (doesn't wait).
1076    *
1077    * @param getReply
1078    * @param msg
1079    * @param cmds
1080    * @return
1081    */
1082   protected List<String> executeCommand(boolean getReply, String msg,
1083           StructureCommandI... cmds)
1084   {
1085     JalviewStructureDisplayI theViewer = getViewer();
1086     final long handle = msg == null ? 0 : theViewer.startProgressBar(msg);
1087
1088     if (getReply)
1089     {
1090       /*
1091        * execute and wait for reply
1092        */
1093       List<String> response = new ArrayList<>();
1094       try
1095       {
1096         for (StructureCommandI cmd : cmds)
1097         {
1098           List<String> replies = executeCommand(cmd, true);
1099           if (replies != null)
1100           {
1101             response.addAll(replies);
1102           }
1103         }
1104         return response;
1105       } finally
1106       {
1107         if (msg != null)
1108         {
1109           theViewer.stopProgressBar(null, handle);
1110         }
1111       }
1112     }
1113
1114     /*
1115      * fire and forget
1116      */
1117     String threadName = msg == null ? "StructureCommand" : msg;
1118     new Thread(new Runnable()
1119     {
1120       @Override
1121       public void run()
1122       {
1123         try
1124         {
1125           for (StructureCommandI cmd : cmds)
1126           {
1127             executeCommand(cmd, false);
1128           }
1129         } finally
1130         {
1131           if (msg != null)
1132           {
1133             SwingUtilities.invokeLater(new Runnable()
1134             {
1135               @Override
1136               public void run()
1137               {
1138                 theViewer.stopProgressBar(null, handle);
1139               }
1140             });
1141           }
1142         }
1143       }
1144     }, threadName).start();
1145     return null;
1146   }
1147
1148   /**
1149    * Colours any structures associated with sequences in the given alignment as
1150    * coloured in the alignment view, provided colourBySequence is enabled
1151    */
1152   public void colourBySequence(AlignmentViewPanel alignmentv)
1153   {
1154     if (!colourBySequence || !isLoadingFinished() || getSsm() == null)
1155     {
1156       return;
1157     }
1158     Map<Object, AtomSpecModel> colourMap = buildColoursMap(ssm, sequence,
1159             alignmentv);
1160
1161     List<StructureCommandI> colourBySequenceCommands = commandGenerator
1162             .colourBySequence(colourMap);
1163     executeCommands(colourBySequenceCommands, false, COLOURING_STRUCTURES);
1164   }
1165
1166   /**
1167    * Centre the display in the structure viewer
1168    */
1169   public void focusView()
1170   {
1171     executeCommand(false, null, commandGenerator.focusView());
1172   }
1173
1174   /**
1175    * Generates and executes a command to show only specified chains in the
1176    * structure viewer. The list of chains to show should contain entries
1177    * formatted as "pdbid:chaincode".
1178    *
1179    * @param toShow
1180    */
1181   public void showChains(List<String> toShow)
1182   {
1183     // todo or reformat toShow list entries as modelNo:pdbId:chainCode ?
1184
1185     /*
1186      * Reformat the pdbid:chainCode values as modelNo:chainCode
1187      * since this is what is needed to construct the viewer command
1188      * todo: find a less messy way to do this
1189      */
1190     List<String> showThese = new ArrayList<>();
1191     for (String chainId : toShow)
1192     {
1193       String[] tokens = chainId.split("\\:");
1194       if (tokens.length == 2)
1195       {
1196         String pdbFile = getFileForChain(chainId);
1197         String model = getModelIdForFile(pdbFile);
1198         showThese.add(model + ":" + tokens[1]);
1199       }
1200     }
1201     executeCommands(commandGenerator.showChains(showThese), false, null);
1202   }
1203
1204   /**
1205    * Answers the structure viewer's model id given a PDB file name. Returns an
1206    * empty string if model id is not found.
1207    *
1208    * @param chainId
1209    * @return
1210    */
1211   protected abstract String getModelIdForFile(String chainId);
1212
1213   public boolean hasFileLoadingError()
1214   {
1215     return fileLoadingError != null && fileLoadingError.length() > 0;
1216   }
1217
1218   /**
1219    * Returns the FeatureRenderer for the given alignment view
1220    *
1221    * @param avp
1222    * @return
1223    */
1224   public FeatureRenderer getFeatureRenderer(AlignmentViewPanel avp)
1225   {
1226     AlignmentViewPanel ap = (avp == null) ? getViewer().getAlignmentPanel()
1227             : avp;
1228     if (ap == null)
1229     {
1230       return null;
1231     }
1232     return ap.getFeatureRenderer();
1233   }
1234
1235   protected void setStructureCommands(StructureCommandsI cmd)
1236   {
1237     commandGenerator = cmd;
1238   }
1239
1240   /**
1241    * Records association of one chain id (formatted as "pdbid:chainCode") with
1242    * the corresponding PDB file name
1243    *
1244    * @param chainId
1245    * @param fileName
1246    */
1247   public void addChainFile(String chainId, String fileName)
1248   {
1249     chainFile.put(chainId, fileName);
1250   }
1251
1252   /**
1253    * Returns the PDB filename for the given chain id (formatted as
1254    * "pdbid:chainCode"), or null if not found
1255    *
1256    * @param chainId
1257    * @return
1258    */
1259   protected String getFileForChain(String chainId)
1260   {
1261     return chainFile.get(chainId);
1262   }
1263
1264   @Override
1265   public void updateColours(Object source)
1266   {
1267     AlignmentViewPanel ap = (AlignmentViewPanel) source;
1268     // ignore events from panels not used to colour this view
1269     if (!getViewer().isUsedForColourBy(ap))
1270     {
1271       return;
1272     }
1273     if (!isLoadingFromArchive())
1274     {
1275       colourBySequence(ap);
1276     }
1277   }
1278
1279   public StructureCommandsI getCommandGenerator()
1280   {
1281     return commandGenerator;
1282   }
1283
1284   protected abstract ViewerType getViewerType();
1285
1286   /**
1287    * Builds a data structure which records mapped structure residues for each
1288    * colour. From this we can easily generate the viewer commands for colour by
1289    * sequence. Constructs and returns a map of {@code Color} to
1290    * {@code AtomSpecModel}, where the atomspec model holds
1291    *
1292    * <pre>
1293    *   Model ids
1294    *     Chains
1295    *       Residue positions
1296    * </pre>
1297    *
1298    * Ordering is by order of addition (for colours), natural ordering (for
1299    * models and chains)
1300    *
1301    * @param ssm
1302    * @param sequence
1303    * @param viewPanel
1304    * @return
1305    */
1306   protected Map<Object, AtomSpecModel> buildColoursMap(
1307           StructureSelectionManager ssm, SequenceI[][] sequence,
1308           AlignmentViewPanel viewPanel)
1309   {
1310     String[] files = getStructureFiles();
1311     SequenceRenderer sr = getSequenceRenderer(viewPanel);
1312     FeatureRenderer fr = viewPanel.getFeatureRenderer();
1313     FeatureColourFinder finder = new FeatureColourFinder(fr);
1314     AlignViewportI viewport = viewPanel.getAlignViewport();
1315     HiddenColumns cs = viewport.getAlignment().getHiddenColumns();
1316     AlignmentI al = viewport.getAlignment();
1317     Map<Object, AtomSpecModel> colourMap = new LinkedHashMap<>();
1318     Color lastColour = null;
1319
1320     for (int pdbfnum = 0; pdbfnum < files.length; pdbfnum++)
1321     {
1322       final String modelId = getModelIdForFile(files[pdbfnum]);
1323       StructureMapping[] mapping = ssm.getMapping(files[pdbfnum]);
1324
1325       if (mapping == null || mapping.length < 1)
1326       {
1327         continue;
1328       }
1329
1330       int startPos = -1, lastPos = -1;
1331       String lastChain = "";
1332       for (int s = 0; s < sequence[pdbfnum].length; s++)
1333       {
1334         for (int sp, m = 0; m < mapping.length; m++)
1335         {
1336           final SequenceI seq = sequence[pdbfnum][s];
1337           if (mapping[m].getSequence() == seq
1338                   && (sp = al.findIndex(seq)) > -1)
1339           {
1340             SequenceI asp = al.getSequenceAt(sp);
1341             for (int r = 0; r < asp.getLength(); r++)
1342             {
1343               // no mapping to gaps in sequence
1344               if (Comparison.isGap(asp.getCharAt(r)))
1345               {
1346                 continue;
1347               }
1348               int pos = mapping[m].getPDBResNum(asp.findPosition(r));
1349
1350               if (pos < 1 || pos == lastPos)
1351               {
1352                 continue;
1353               }
1354
1355               Color colour = sr.getResidueColour(seq, r, finder);
1356
1357               /*
1358                * darker colour for hidden regions
1359                */
1360               if (!cs.isVisible(r))
1361               {
1362                 colour = Color.GRAY;
1363               }
1364
1365               final String chain = mapping[m].getChain();
1366
1367               /*
1368                * Just keep incrementing the end position for this colour range
1369                * _unless_ colour, PDB model or chain has changed, or there is a
1370                * gap in the mapped residue sequence
1371                */
1372               final boolean newColour = !colour.equals(lastColour);
1373               final boolean nonContig = lastPos + 1 != pos;
1374               final boolean newChain = !chain.equals(lastChain);
1375               if (newColour || nonContig || newChain)
1376               {
1377                 if (startPos != -1)
1378                 {
1379                   addAtomSpecRange(colourMap, lastColour, modelId, startPos,
1380                           lastPos, lastChain);
1381                 }
1382                 startPos = pos;
1383               }
1384               lastColour = colour;
1385               lastPos = pos;
1386               lastChain = chain;
1387             }
1388             // final colour range
1389             if (lastColour != null)
1390             {
1391               addAtomSpecRange(colourMap, lastColour, modelId, startPos,
1392                       lastPos, lastChain);
1393             }
1394             // break;
1395           }
1396         }
1397       }
1398     }
1399     return colourMap;
1400   }
1401
1402   /**
1403    * todo better refactoring (map lookup or similar to get viewer structure id)
1404    *
1405    * @param pdbfnum
1406    * @param file
1407    * @return
1408    */
1409   protected String getModelId(int pdbfnum, String file)
1410   {
1411     return String.valueOf(pdbfnum);
1412   }
1413
1414   /**
1415    * Saves chains, formatted as "pdbId:chainCode", and lookups from this to the
1416    * full PDB file path
1417    *
1418    * @param pdb
1419    * @param file
1420    */
1421   public void stashFoundChains(StructureFile pdb, String file)
1422   {
1423     for (int i = 0; i < pdb.getChains().size(); i++)
1424     {
1425       String chid = pdb.getId() + ":" + pdb.getChains().elementAt(i).id;
1426       addChainFile(chid, file);
1427       getChainNames().add(chid);
1428     }
1429   }
1430
1431   /**
1432    * Helper method to add one contiguous range to the AtomSpec model for the
1433    * given value (creating the model if necessary). As used by Jalview,
1434    * {@code value} is
1435    * <ul>
1436    * <li>a colour, when building a 'colour structure by sequence' command</li>
1437    * <li>a feature value, when building a 'set Chimera attributes from features'
1438    * command</li>
1439    * </ul>
1440    *
1441    * @param map
1442    * @param value
1443    * @param model
1444    * @param startPos
1445    * @param endPos
1446    * @param chain
1447    */
1448   public static final void addAtomSpecRange(Map<Object, AtomSpecModel> map,
1449           Object value, String model, int startPos, int endPos,
1450           String chain)
1451   {
1452     /*
1453      * Get/initialize map of data for the colour
1454      */
1455     AtomSpecModel atomSpec = map.get(value);
1456     if (atomSpec == null)
1457     {
1458       atomSpec = new AtomSpecModel();
1459       map.put(value, atomSpec);
1460     }
1461
1462     atomSpec.addRange(model, startPos, endPos, chain);
1463   }
1464
1465   /**
1466    * Returns the file extension (including '.' separator) to use for a saved
1467    * viewer session file. Default is to return null (not supported), override as
1468    * required.
1469    *
1470    * @return
1471    */
1472   public String getSessionFileExtension()
1473   {
1474     return null;
1475   }
1476
1477   /**
1478    * If supported, saves the state of the structure viewer to a temporary file
1479    * and returns the file. Returns null and logs an error on any failure.
1480    *
1481    * @return
1482    */
1483   public File saveSession()
1484   {
1485     String prefix = getViewerType().toString();
1486     String suffix = getSessionFileExtension();
1487     File f = null;
1488     try
1489     {
1490       f = File.createTempFile(prefix, suffix);
1491       saveSession(f);
1492     } catch (IOException e)
1493     {
1494       Cache.log.error(String.format("Error saving %s session: %s", prefix,
1495               e.toString()));
1496     }
1497
1498     return f;
1499   }
1500
1501   /**
1502    * Saves the structure viewer session to the given file
1503    *
1504    * @param f
1505    */
1506   protected void saveSession(File f)
1507   {
1508     StructureCommandI cmd = commandGenerator.saveSession(f.getPath());
1509     if (cmd != null)
1510     {
1511       executeCommand(cmd, false);
1512     }
1513   }
1514
1515   /**
1516    * Returns true if the viewer is an external structure viewer for which the
1517    * process is still alive, else false (for Jmol, or an external viewer which
1518    * the user has independently closed)
1519    *
1520    * @return
1521    */
1522   public boolean isViewerRunning()
1523   {
1524     return false;
1525   }
1526
1527   /**
1528    * Closes Jalview's structure viewer panel and releases associated resources.
1529    * If it is managing an external viewer program, and {@code forceClose} is
1530    * true, also asks that program to close.
1531    *
1532    * @param forceClose
1533    */
1534   public void closeViewer(boolean forceClose)
1535   {
1536     getSsm().removeStructureViewerListener(this, this.getStructureFiles());
1537     releaseUIResources();
1538
1539     /*
1540      * end the thread that closes this panel if the external viewer closes
1541      */
1542     if (externalViewerMonitor != null)
1543     {
1544       externalViewerMonitor.interrupt();
1545       externalViewerMonitor = null;
1546     }
1547
1548     stopListening();
1549
1550     if (forceClose)
1551     {
1552       StructureCommandI cmd = getCommandGenerator().closeViewer();
1553       if (cmd != null)
1554       {
1555         executeCommand(cmd, false);
1556       }
1557     }
1558   }
1559
1560   /**
1561    * Returns the URL of a help page for the structure viewer, or null if none is
1562    * known
1563    *
1564    * @return
1565    */
1566   public String getHelpURL()
1567   {
1568     return null;
1569   }
1570
1571   /**
1572    * <pre>
1573    * Helper method to build a map of
1574    *   { featureType, { feature value, AtomSpecModel } }
1575    * </pre>
1576    *
1577    * @param viewPanel
1578    * @return
1579    */
1580   protected Map<String, Map<Object, AtomSpecModel>> buildFeaturesMap(
1581           AlignmentViewPanel viewPanel)
1582   {
1583     Map<String, Map<Object, AtomSpecModel>> theMap = new LinkedHashMap<>();
1584     String[] files = getStructureFiles();
1585     if (files == null)
1586     {
1587       return theMap;
1588     }
1589
1590     FeatureRenderer fr = viewPanel.getFeatureRenderer();
1591     if (fr == null)
1592     {
1593       return theMap;
1594     }
1595
1596     AlignViewportI viewport = viewPanel.getAlignViewport();
1597     List<String> visibleFeatures = fr.getDisplayedFeatureTypes();
1598
1599     /*
1600      * if alignment is showing features from complement, we also transfer
1601      * these features to the corresponding mapped structure residues
1602      */
1603     boolean showLinkedFeatures = viewport.isShowComplementFeatures();
1604     List<String> complementFeatures = new ArrayList<>();
1605     FeatureRenderer complementRenderer = null;
1606     if (showLinkedFeatures)
1607     {
1608       AlignViewportI comp = fr.getViewport().getCodingComplement();
1609       if (comp != null)
1610       {
1611         complementRenderer = Desktop.getAlignFrameFor(comp)
1612                 .getFeatureRenderer();
1613         complementFeatures = complementRenderer.getDisplayedFeatureTypes();
1614       }
1615     }
1616     if (visibleFeatures.isEmpty() && complementFeatures.isEmpty())
1617     {
1618       return theMap;
1619     }
1620
1621     AlignmentI alignment = viewPanel.getAlignment();
1622     SequenceI[][] seqs = getSequence();
1623
1624     for (int pdbfnum = 0; pdbfnum < files.length; pdbfnum++)
1625     {
1626       String modelId = getModelIdForFile(files[pdbfnum]);
1627       StructureMapping[] mapping = ssm.getMapping(files[pdbfnum]);
1628
1629       if (mapping == null || mapping.length < 1)
1630       {
1631         continue;
1632       }
1633
1634       for (int seqNo = 0; seqNo < seqs[pdbfnum].length; seqNo++)
1635       {
1636         for (int m = 0; m < mapping.length; m++)
1637         {
1638           final SequenceI seq = seqs[pdbfnum][seqNo];
1639           int sp = alignment.findIndex(seq);
1640           StructureMapping structureMapping = mapping[m];
1641           if (structureMapping.getSequence() == seq && sp > -1)
1642           {
1643             /*
1644              * found a sequence with a mapping to a structure;
1645              * now scan its features
1646              */
1647             if (!visibleFeatures.isEmpty())
1648             {
1649               scanSequenceFeatures(visibleFeatures, structureMapping, seq,
1650                       theMap, modelId);
1651             }
1652             if (showLinkedFeatures)
1653             {
1654               scanComplementFeatures(complementRenderer, structureMapping,
1655                       seq, theMap, modelId);
1656             }
1657           }
1658         }
1659       }
1660     }
1661     return theMap;
1662   }
1663
1664   /**
1665    * Ask the structure viewer to open a session file. Returns true if
1666    * successful, else false (or not supported).
1667    *
1668    * @param filepath
1669    * @return
1670    */
1671   public boolean openSession(String filepath)
1672   {
1673     StructureCommandI cmd = getCommandGenerator().openSession(filepath);
1674     if (cmd == null)
1675     {
1676       return false;
1677     }
1678     executeCommand(cmd, true);
1679     // todo: test for failure - how?
1680     return true;
1681   }
1682
1683   /**
1684    * Scans visible features in mapped positions of the CDS/peptide complement,
1685    * and adds any found to the map of attribute values/structure positions
1686    *
1687    * @param complementRenderer
1688    * @param structureMapping
1689    * @param seq
1690    * @param theMap
1691    * @param modelNumber
1692    */
1693   protected static void scanComplementFeatures(
1694           FeatureRenderer complementRenderer,
1695           StructureMapping structureMapping, SequenceI seq,
1696           Map<String, Map<Object, AtomSpecModel>> theMap,
1697           String modelNumber)
1698   {
1699     /*
1700      * for each sequence residue mapped to a structure position...
1701      */
1702     for (int seqPos : structureMapping.getMapping().keySet())
1703     {
1704       /*
1705        * find visible complementary features at mapped position(s)
1706        */
1707       MappedFeatures mf = complementRenderer
1708               .findComplementFeaturesAtResidue(seq, seqPos);
1709       if (mf != null)
1710       {
1711         for (SequenceFeature sf : mf.features)
1712         {
1713           String type = sf.getType();
1714
1715           /*
1716            * Don't copy features which originated from Chimera
1717            */
1718           if (JalviewChimeraBinding.CHIMERA_FEATURE_GROUP
1719                   .equals(sf.getFeatureGroup()))
1720           {
1721             continue;
1722           }
1723
1724           /*
1725            * record feature 'value' (score/description/type) as at the
1726            * corresponding structure position
1727            */
1728           List<int[]> mappedRanges = structureMapping
1729                   .getPDBResNumRanges(seqPos, seqPos);
1730
1731           if (!mappedRanges.isEmpty())
1732           {
1733             String value = sf.getDescription();
1734             if (value == null || value.length() == 0)
1735             {
1736               value = type;
1737             }
1738             float score = sf.getScore();
1739             if (score != 0f && !Float.isNaN(score))
1740             {
1741               value = Float.toString(score);
1742             }
1743             Map<Object, AtomSpecModel> featureValues = theMap.get(type);
1744             if (featureValues == null)
1745             {
1746               featureValues = new HashMap<>();
1747               theMap.put(type, featureValues);
1748             }
1749             for (int[] range : mappedRanges)
1750             {
1751               addAtomSpecRange(featureValues, value, modelNumber, range[0],
1752                       range[1], structureMapping.getChain());
1753             }
1754           }
1755         }
1756       }
1757     }
1758   }
1759
1760   /**
1761    * Inspect features on the sequence; for each feature that is visible,
1762    * determine its mapped ranges in the structure (if any) according to the
1763    * given mapping, and add them to the map.
1764    *
1765    * @param visibleFeatures
1766    * @param mapping
1767    * @param seq
1768    * @param theMap
1769    * @param modelId
1770    */
1771   protected static void scanSequenceFeatures(List<String> visibleFeatures,
1772           StructureMapping mapping, SequenceI seq,
1773           Map<String, Map<Object, AtomSpecModel>> theMap, String modelId)
1774   {
1775     List<SequenceFeature> sfs = seq.getFeatures().getPositionalFeatures(
1776             visibleFeatures.toArray(new String[visibleFeatures.size()]));
1777     for (SequenceFeature sf : sfs)
1778     {
1779       String type = sf.getType();
1780
1781       /*
1782        * Don't copy features which originated from Chimera
1783        */
1784       if (JalviewChimeraBinding.CHIMERA_FEATURE_GROUP
1785               .equals(sf.getFeatureGroup()))
1786       {
1787         continue;
1788       }
1789
1790       List<int[]> mappedRanges = mapping.getPDBResNumRanges(sf.getBegin(),
1791               sf.getEnd());
1792
1793       if (!mappedRanges.isEmpty())
1794       {
1795         String value = sf.getDescription();
1796         if (value == null || value.length() == 0)
1797         {
1798           value = type;
1799         }
1800         float score = sf.getScore();
1801         if (score != 0f && !Float.isNaN(score))
1802         {
1803           value = Float.toString(score);
1804         }
1805         Map<Object, AtomSpecModel> featureValues = theMap.get(type);
1806         if (featureValues == null)
1807         {
1808           featureValues = new HashMap<>();
1809           theMap.put(type, featureValues);
1810         }
1811         for (int[] range : mappedRanges)
1812         {
1813           addAtomSpecRange(featureValues, value, modelId, range[0],
1814                   range[1], mapping.getChain());
1815         }
1816       }
1817     }
1818   }
1819
1820   /**
1821    * Returns the number of structure files in the structure viewer and mapped to
1822    * Jalview. This may be zero if the files are still in the process of loading
1823    * in the viewer.
1824    *
1825    * @return
1826    */
1827   public int getMappedStructureCount()
1828   {
1829     String[] files = getStructureFiles();
1830     return files == null ? 0 : files.length;
1831   }
1832
1833   /**
1834    * Starts a thread that waits for the external viewer program process to
1835    * finish, so that we can then close the associated resources. This avoids
1836    * leaving orphaned viewer panels in Jalview if the user closes the external
1837    * viewer.
1838    *
1839    * @param p
1840    */
1841   protected void startExternalViewerMonitor(Process p)
1842   {
1843     externalViewerMonitor = new Thread(new Runnable()
1844     {
1845
1846       @Override
1847       public void run()
1848       {
1849         try
1850         {
1851           p.waitFor();
1852           JalviewStructureDisplayI display = getViewer();
1853           if (display != null)
1854           {
1855             display.closeViewer(false);
1856           }
1857         } catch (InterruptedException e)
1858         {
1859           // exit thread if Chimera Viewer is closed in Jalview
1860         }
1861       }
1862     });
1863     externalViewerMonitor.start();
1864   }
1865
1866   /**
1867    * If supported by the external structure viewer, sends it commands to notify
1868    * model or selection changes to the specified URL (where Jalview has started
1869    * a listener)
1870    *
1871    * @param uri
1872    */
1873   protected void startListening(String uri)
1874   {
1875     List<StructureCommandI> commands = getCommandGenerator()
1876             .startNotifications(uri);
1877     if (commands != null)
1878     {
1879       executeCommands(commands, false, null);
1880     }
1881   }
1882
1883   /**
1884    * If supported by the external structure viewer, sends it commands to stop
1885    * notifying model or selection changes
1886    */
1887   protected void stopListening()
1888   {
1889     List<StructureCommandI> commands = getCommandGenerator()
1890             .stopNotifications();
1891     if (commands != null)
1892     {
1893       executeCommands(commands, false, null);
1894     }
1895   }
1896
1897   /**
1898    * If supported by the structure viewer, queries it for all residue attributes
1899    * with the given attribute name, and creates features on corresponding
1900    * residues of the alignment. Returns the number of features added.
1901    *
1902    * @param attName
1903    * @param alignmentPanel
1904    * @return
1905    */
1906   public int copyStructureAttributesToFeatures(String attName,
1907           AlignmentPanel alignmentPanel)
1908   {
1909     StructureCommandI cmd = getCommandGenerator()
1910             .getResidueAttributes(attName);
1911     if (cmd == null)
1912     {
1913       return 0;
1914     }
1915     List<String> residueAttributes = executeCommand(cmd, true);
1916
1917     int featuresAdded = createFeaturesForAttributes(attName,
1918             residueAttributes);
1919     if (featuresAdded > 0)
1920     {
1921       alignmentPanel.getFeatureRenderer().featuresAdded();
1922     }
1923     return featuresAdded;
1924   }
1925
1926   /**
1927    * Parses {@code residueAttributes} and creates sequence features on any
1928    * mapped alignment residues. Returns the number of features created.
1929    * <p>
1930    * {@code residueAttributes} is the reply from the structure viewer to a
1931    * command to list any residue attributes for the given attribute name. Syntax
1932    * and parsing of this is viewer-specific.
1933    *
1934    * @param attName
1935    * @param residueAttributes
1936    * @return
1937    */
1938   protected int createFeaturesForAttributes(String attName,
1939           List<String> residueAttributes)
1940   {
1941     return 0;
1942   }
1943 }