JAL-4305 Isolate and unify the Jalview object from all the gubbins in jalview.bin...
[jalview.git] / src / jalview / project / Jalview2XML.java
index 8c3175f..cc20fce 100644 (file)
  */
 package jalview.project;
 
+import static jalview.math.RotatableMatrix.Axis.X;
+import static jalview.math.RotatableMatrix.Axis.Y;
+import static jalview.math.RotatableMatrix.Axis.Z;
+
+import java.awt.Color;
+import java.awt.Font;
+import java.awt.Rectangle;
+import java.io.BufferedReader;
+import java.io.ByteArrayInputStream;
+import java.io.File;
+import java.io.FileInputStream;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.io.OutputStream;
+import java.io.OutputStreamWriter;
+import java.io.PrintWriter;
+import java.lang.reflect.InvocationTargetException;
+import java.math.BigInteger;
+import java.net.MalformedURLException;
+import java.net.URL;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.BitSet;
+import java.util.Collections;
+import java.util.Enumeration;
+import java.util.GregorianCalendar;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Hashtable;
+import java.util.IdentityHashMap;
+import java.util.Iterator;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Map.Entry;
+import java.util.Set;
+import java.util.Vector;
+import java.util.jar.JarEntry;
+import java.util.jar.JarInputStream;
+import java.util.jar.JarOutputStream;
+
+import javax.swing.JInternalFrame;
+import javax.swing.SwingUtilities;
+import javax.xml.bind.JAXBContext;
+import javax.xml.bind.JAXBElement;
+import javax.xml.bind.Marshaller;
+import javax.xml.datatype.DatatypeConfigurationException;
+import javax.xml.datatype.DatatypeFactory;
+import javax.xml.datatype.XMLGregorianCalendar;
+import javax.xml.stream.XMLInputFactory;
+import javax.xml.stream.XMLStreamReader;
+
 import jalview.analysis.Conservation;
+import jalview.analysis.PCA;
+import jalview.analysis.scoremodels.ScoreModels;
+import jalview.analysis.scoremodels.SimilarityParams;
 import jalview.api.FeatureColourI;
 import jalview.api.ViewStyleI;
+import jalview.api.analysis.ScoreModelI;
+import jalview.api.analysis.SimilarityParamsI;
 import jalview.api.structures.JalviewStructureDisplayI;
 import jalview.bin.Cache;
+import jalview.bin.Console;
+import jalview.bin.Jalview;
 import jalview.datamodel.AlignedCodonFrame;
 import jalview.datamodel.Alignment;
 import jalview.datamodel.AlignmentAnnotation;
 import jalview.datamodel.AlignmentI;
+import jalview.datamodel.ContactMatrix;
+import jalview.datamodel.ContactMatrixI;
+import jalview.datamodel.DBRefEntry;
+import jalview.datamodel.GeneLocus;
 import jalview.datamodel.GraphLine;
+import jalview.datamodel.GroupSet;
 import jalview.datamodel.PDBEntry;
+import jalview.datamodel.Point;
 import jalview.datamodel.RnaViewerModel;
 import jalview.datamodel.SequenceFeature;
 import jalview.datamodel.SequenceGroup;
@@ -46,21 +114,23 @@ import jalview.gui.AlignFrame;
 import jalview.gui.AlignViewport;
 import jalview.gui.AlignmentPanel;
 import jalview.gui.AppVarna;
-import jalview.gui.ChimeraViewFrame;
 import jalview.gui.Desktop;
-import jalview.gui.FeatureRenderer;
-import jalview.gui.Jalview2XML_V1;
 import jalview.gui.JvOptionPane;
 import jalview.gui.OOMWarning;
+import jalview.gui.OverviewPanel;
+import jalview.gui.PCAPanel;
 import jalview.gui.PaintRefresher;
 import jalview.gui.SplitFrame;
 import jalview.gui.StructureViewer;
 import jalview.gui.StructureViewer.ViewerType;
 import jalview.gui.StructureViewerBase;
 import jalview.gui.TreePanel;
+import jalview.io.BackupFiles;
 import jalview.io.DataSourceType;
 import jalview.io.FileFormat;
 import jalview.io.NewickFile;
+import jalview.math.Matrix;
+import jalview.math.MatrixI;
 import jalview.renderer.ResidueShaderI;
 import jalview.schemes.AnnotationColourGradient;
 import jalview.schemes.ColourSchemeI;
@@ -71,15 +141,20 @@ import jalview.schemes.UserColourScheme;
 import jalview.structure.StructureSelectionManager;
 import jalview.structures.models.AAStructureBindingModel;
 import jalview.util.Format;
+import jalview.util.HttpUtils;
 import jalview.util.MessageManager;
 import jalview.util.Platform;
 import jalview.util.StringUtils;
 import jalview.util.jarInputStreamProvider;
 import jalview.util.matcher.Condition;
 import jalview.viewmodel.AlignmentViewport;
+import jalview.viewmodel.PCAModel;
 import jalview.viewmodel.ViewportRanges;
+import jalview.viewmodel.seqfeatures.FeatureRendererModel;
 import jalview.viewmodel.seqfeatures.FeatureRendererSettings;
 import jalview.viewmodel.seqfeatures.FeaturesDisplayed;
+import jalview.ws.datamodel.MappableContactMatrixI;
+import jalview.ws.datamodel.alphafold.PAEContactMatrix;
 import jalview.ws.jws2.Jws2Discoverer;
 import jalview.ws.jws2.dm.AAConSettings;
 import jalview.ws.jws2.jabaws2.Jws2Instance;
@@ -92,6 +167,8 @@ import jalview.xml.binding.jalview.Annotation;
 import jalview.xml.binding.jalview.Annotation.ThresholdLine;
 import jalview.xml.binding.jalview.AnnotationColourScheme;
 import jalview.xml.binding.jalview.AnnotationElement;
+import jalview.xml.binding.jalview.DoubleMatrix;
+import jalview.xml.binding.jalview.DoubleVector;
 import jalview.xml.binding.jalview.Feature;
 import jalview.xml.binding.jalview.Feature.OtherData;
 import jalview.xml.binding.jalview.FeatureMatcherSet.CompoundMatcher;
@@ -106,18 +183,27 @@ import jalview.xml.binding.jalview.JalviewModel.JSeq.Pdbids;
 import jalview.xml.binding.jalview.JalviewModel.JSeq.Pdbids.StructureState;
 import jalview.xml.binding.jalview.JalviewModel.JSeq.RnaViewer;
 import jalview.xml.binding.jalview.JalviewModel.JSeq.RnaViewer.SecondaryStructure;
+import jalview.xml.binding.jalview.JalviewModel.PcaViewer;
+import jalview.xml.binding.jalview.JalviewModel.PcaViewer.Axis;
+import jalview.xml.binding.jalview.JalviewModel.PcaViewer.SeqPointMax;
+import jalview.xml.binding.jalview.JalviewModel.PcaViewer.SeqPointMin;
+import jalview.xml.binding.jalview.JalviewModel.PcaViewer.SequencePoint;
 import jalview.xml.binding.jalview.JalviewModel.Tree;
 import jalview.xml.binding.jalview.JalviewModel.UserColours;
 import jalview.xml.binding.jalview.JalviewModel.Viewport;
 import jalview.xml.binding.jalview.JalviewModel.Viewport.CalcIdParam;
 import jalview.xml.binding.jalview.JalviewModel.Viewport.HiddenColumns;
+import jalview.xml.binding.jalview.JalviewModel.Viewport.Overview;
 import jalview.xml.binding.jalview.JalviewUserColours;
 import jalview.xml.binding.jalview.JalviewUserColours.Colour;
+import jalview.xml.binding.jalview.MapListType;
 import jalview.xml.binding.jalview.MapListType.MapListFrom;
 import jalview.xml.binding.jalview.MapListType.MapListTo;
 import jalview.xml.binding.jalview.Mapping;
+import jalview.xml.binding.jalview.MatrixType;
 import jalview.xml.binding.jalview.NoValueColour;
 import jalview.xml.binding.jalview.ObjectFactory;
+import jalview.xml.binding.jalview.PcaDataType;
 import jalview.xml.binding.jalview.Pdbentry.Property;
 import jalview.xml.binding.jalview.Sequence;
 import jalview.xml.binding.jalview.Sequence.DBRef;
@@ -126,54 +212,6 @@ import jalview.xml.binding.jalview.SequenceSet.SequenceSetProperties;
 import jalview.xml.binding.jalview.ThresholdType;
 import jalview.xml.binding.jalview.VAMSAS;
 
-import java.awt.Color;
-import java.awt.Font;
-import java.awt.Rectangle;
-import java.io.BufferedReader;
-import java.io.DataInputStream;
-import java.io.DataOutputStream;
-import java.io.File;
-import java.io.FileInputStream;
-import java.io.FileOutputStream;
-import java.io.IOException;
-import java.io.InputStreamReader;
-import java.io.OutputStreamWriter;
-import java.io.PrintWriter;
-import java.lang.reflect.InvocationTargetException;
-import java.math.BigInteger;
-import java.net.MalformedURLException;
-import java.net.URL;
-import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.Collections;
-import java.util.Enumeration;
-import java.util.GregorianCalendar;
-import java.util.HashMap;
-import java.util.HashSet;
-import java.util.Hashtable;
-import java.util.IdentityHashMap;
-import java.util.Iterator;
-import java.util.LinkedHashMap;
-import java.util.List;
-import java.util.Map;
-import java.util.Map.Entry;
-import java.util.Set;
-import java.util.Vector;
-import java.util.jar.JarEntry;
-import java.util.jar.JarInputStream;
-import java.util.jar.JarOutputStream;
-
-import javax.swing.JInternalFrame;
-import javax.swing.SwingUtilities;
-import javax.xml.bind.JAXBContext;
-import javax.xml.bind.JAXBElement;
-import javax.xml.bind.Marshaller;
-import javax.xml.datatype.DatatypeConfigurationException;
-import javax.xml.datatype.DatatypeFactory;
-import javax.xml.datatype.XMLGregorianCalendar;
-import javax.xml.stream.XMLInputFactory;
-import javax.xml.stream.XMLStreamReader;
-
 /**
  * Write out the current jalview desktop state as a Jalview XML stream.
  * 
@@ -186,6 +224,15 @@ import javax.xml.stream.XMLStreamReader;
  */
 public class Jalview2XML
 {
+
+  // BH 2018 we add the .jvp binary extension to J2S so that
+  // it will declare that binary when we do the file save from the browser
+
+  static
+  {
+    Platform.addJ2SBinaryType(".jvp?");
+  }
+
   private static final String VIEWER_PREFIX = "viewer_";
 
   private static final String RNA_PREFIX = "rna_";
@@ -193,6 +240,11 @@ public class Jalview2XML
   private static final String UTF_8 = "UTF-8";
 
   /**
+   * used in decision if quit confirmation should be issued
+   */
+  private static boolean stateSavedUpToDate = false;
+
+  /**
    * prefix for recovering datasets for alignments with multiple views where
    * non-existent dataset IDs were written for some views
    */
@@ -429,7 +481,7 @@ public class Jalview2XML
       public boolean isResolvable()
       {
         return super.isResolvable() && mp.getTo() != null;
-      };
+      }
 
       @Override
       boolean resolve()
@@ -468,7 +520,7 @@ public class Jalview2XML
           }
         } catch (Exception x)
         {
-          System.err.println(
+          jalview.bin.Console.errPrintln(
                   "IMPLEMENTATION ERROR: Failed to resolve forward reference for sequence "
                           + ref.getSref());
           x.printStackTrace();
@@ -482,29 +534,30 @@ public class Jalview2XML
     }
     if (unresolved > 0)
     {
-      System.err.println("Jalview Project Import: There were " + unresolved
+      jalview.bin.Console.errPrintln("Jalview Project Import: There were "
+              + unresolved
               + " forward references left unresolved on the stack.");
     }
     if (failedtoresolve > 0)
     {
-      System.err.println("SERIOUS! " + failedtoresolve
+      jalview.bin.Console.errPrintln("SERIOUS! " + failedtoresolve
               + " resolvable forward references failed to resolve.");
     }
     if (incompleteSeqs != null && incompleteSeqs.size() > 0)
     {
-      System.err.println(
+      jalview.bin.Console.errPrintln(
               "Jalview Project Import: There are " + incompleteSeqs.size()
                       + " sequences which may have incomplete metadata.");
       if (incompleteSeqs.size() < 10)
       {
         for (SequenceI s : incompleteSeqs.values())
         {
-          System.err.println(s.toString());
+          jalview.bin.Console.errPrintln(s.toString());
         }
       }
       else
       {
-        System.err.println(
+        jalview.bin.Console.errPrintln(
                 "Too many to report. Skipping output of incomplete sequences.");
       }
     }
@@ -529,24 +582,30 @@ public class Jalview2XML
   public void saveState(File statefile)
   {
     FileOutputStream fos = null;
+
     try
     {
+
       fos = new FileOutputStream(statefile);
+
       JarOutputStream jout = new JarOutputStream(fos);
       saveState(jout);
+      fos.close();
 
     } catch (Exception e)
     {
+      Console.error("Couln't write Jalview state to " + statefile, e);
       // TODO: inform user of the problem - they need to know if their data was
       // not saved !
       if (errorMessage == null)
       {
-        errorMessage = "Couldn't write Jalview Archive to output file '"
+        errorMessage = "Did't write Jalview Archive to output file '"
                 + statefile + "' - See console error log for details";
       }
       else
       {
-        errorMessage += "(output file was '" + statefile + "')";
+        errorMessage += "(Didn't write Jalview Archive to output file '"
+                + statefile + ")";
       }
       e.printStackTrace();
     } finally
@@ -572,7 +631,28 @@ public class Jalview2XML
    */
   public void saveState(JarOutputStream jout)
   {
-    AlignFrame[] frames = Desktop.getAlignFrames();
+    AlignFrame[] frames = Desktop.getDesktopAlignFrames();
+
+    setStateSavedUpToDate(true);
+
+    if (Cache.getDefault("DEBUG_DELAY_SAVE", false))
+    {
+      int n = debugDelaySave;
+      int i = 0;
+      while (i < n)
+      {
+        Console.debug("***** debugging save sleep " + i + "/" + n);
+        try
+        {
+          Thread.sleep(1000);
+        } catch (InterruptedException e)
+        {
+          // TODO Auto-generated catch block
+          e.printStackTrace();
+        }
+        i++;
+      }
+    }
 
     if (frames == null)
     {
@@ -655,7 +735,6 @@ public class Jalview2XML
       } catch (Exception foo)
       {
       }
-      ;
       jout.close();
     } catch (Exception ex)
     {
@@ -716,7 +795,31 @@ public class Jalview2XML
   {
     try
     {
-      FileOutputStream fos = new FileOutputStream(jarFile);
+      // create backupfiles object and get new temp filename destination
+      boolean doBackup = BackupFiles.getEnabled();
+      BackupFiles backupfiles = doBackup ? new BackupFiles(jarFile) : null;
+      FileOutputStream fos = new FileOutputStream(
+              doBackup ? backupfiles.getTempFilePath() : jarFile);
+
+      if (Cache.getDefault("DEBUG_DELAY_SAVE", false))
+      {
+        int n = debugDelaySave;
+        int i = 0;
+        while (i < n)
+        {
+          Console.debug("***** debugging save sleep " + i + "/" + n);
+          try
+          {
+            Thread.sleep(1000);
+          } catch (InterruptedException e)
+          {
+            // TODO Auto-generated catch block
+            e.printStackTrace();
+          }
+          i++;
+        }
+      }
+
       JarOutputStream jout = new JarOutputStream(fos);
       List<AlignFrame> frames = new ArrayList<>();
 
@@ -736,9 +839,16 @@ public class Jalview2XML
       } catch (Exception foo)
       {
       }
-      ;
       jout.close();
-      return true;
+      boolean success = true;
+
+      if (doBackup)
+      {
+        backupfiles.setWriteSuccess(success);
+        success = backupfiles.rollBackupsAndRenameTempFile();
+      }
+
+      return success;
     } catch (Exception ex)
     {
       errorMessage = "Couldn't Write alignment view to Jalview Archive - see error output for details";
@@ -827,10 +937,9 @@ public class Jalview2XML
       object.setCreationDate(now);
     } catch (DatatypeConfigurationException e)
     {
-      System.err.println("error writing date: " + e.toString());
+      jalview.bin.Console.errPrintln("error writing date: " + e.toString());
     }
-    object.setVersion(
-            jalview.bin.Cache.getDefault("VERSION", "Development Build"));
+    object.setVersion(Cache.getDefault("VERSION", "Development Build"));
 
     /**
      * rjal is full height alignment, jal is actual alignment with full metadata
@@ -895,19 +1004,19 @@ public class Jalview2XML
           // HAPPEN! (PF00072.15.stk does this)
           // JBPNote: Uncomment to debug writing out of files that do not read
           // back in due to ArrayOutOfBoundExceptions.
-          // System.err.println("vamsasSeq backref: "+id+"");
-          // System.err.println(jds.getName()+"
+          // jalview.bin.Console.errPrintln("vamsasSeq backref: "+id+"");
+          // jalview.bin.Console.errPrintln(jds.getName()+"
           // "+jds.getStart()+"-"+jds.getEnd()+" "+jds.getSequenceAsString());
-          // System.err.println("Hashcode: "+seqHash(jds));
+          // jalview.bin.Console.errPrintln("Hashcode: "+seqHash(jds));
           // SequenceI rsq = (SequenceI) seqRefIds.get(id + "");
-          // System.err.println(rsq.getName()+"
+          // jalview.bin.Console.errPrintln(rsq.getName()+"
           // "+rsq.getStart()+"-"+rsq.getEnd()+" "+rsq.getSequenceAsString());
-          // System.err.println("Hashcode: "+seqHash(rsq));
+          // jalview.bin.Console.errPrintln("Hashcode: "+seqHash(rsq));
         }
         else
         {
           vamsasSeq = createVamsasSequence(id, jds);
-//          vamsasSet.addSequence(vamsasSeq);
+          // vamsasSet.addSequence(vamsasSeq);
           vamsasSet.getSequence().add(vamsasSeq);
           vamsasSetIds.put(id, vamsasSeq);
           seqRefIds.put(id, jds);
@@ -1031,36 +1140,55 @@ public class Jalview2XML
            * only view *should* be coped with sensibly.
            */
           // This must have been loaded, is it still visible?
-          JInternalFrame[] frames = Desktop.desktop.getAllFrames();
-          String matchedFile = null;
-          for (int f = frames.length - 1; f > -1; f--)
+          List<JalviewStructureDisplayI> viewFrames = new ArrayList<>();
+          if (Desktop.desktop != null)
           {
-            if (frames[f] instanceof StructureViewerBase)
+            JInternalFrame[] jifs = Desktop.desktop.getAllFrames();
+            if (jifs != null)
             {
-              StructureViewerBase viewFrame = (StructureViewerBase) frames[f];
-              matchedFile = saveStructureState(ap, jds, pdb, entry, viewIds,
-                      matchedFile, viewFrame);
-              /*
-               * Only store each structure viewer's state once in the project
-               * jar. First time through only (storeDS==false)
-               */
-              String viewId = viewFrame.getViewId();
-              if (!storeDS && !viewIds.contains(viewId))
+              for (JInternalFrame jif : jifs)
               {
-                viewIds.add(viewId);
-                try
+                if (jif instanceof JalviewStructureDisplayI)
                 {
-                  String viewerState = viewFrame.getStateInfo();
-                  writeJarEntry(jout, getViewerJarEntryName(viewId),
-                          viewerState.getBytes());
-                } catch (IOException e)
-                {
-                  System.err.println(
-                          "Error saving viewer state: " + e.getMessage());
+                  viewFrames.add((JalviewStructureDisplayI) jif);
                 }
               }
             }
           }
+          else if (Jalview.isHeadlessMode()
+                  && Jalview.getInstance().getCommands() != null)
+          {
+            viewFrames.addAll(
+                    StructureViewerBase.getAllStructureViewerBases());
+          }
+
+          String matchedFile = null;
+          for (JalviewStructureDisplayI viewFrame : viewFrames)
+          {
+            matchedFile = saveStructureViewer(ap, jds, pdb, entry, viewIds,
+                    matchedFile, viewFrame);
+            /*
+             * Only store each structure viewer's state once in the project
+             * jar. First time through only (storeDS==false)
+             */
+            String viewId = viewFrame.getViewId();
+            String viewerType = viewFrame.getViewerType().toString();
+            if (!storeDS && !viewIds.contains(viewId))
+            {
+              viewIds.add(viewId);
+              File viewerState = viewFrame.saveSession();
+              if (viewerState != null)
+              {
+                copyFileToJar(jout, viewerState.getPath(),
+                        getViewerJarEntryName(viewId), viewerType);
+              }
+              else
+              {
+                Console.error(
+                        "Failed to save viewer state for " + viewerType);
+              }
+            }
+          }
 
           if (matchedFile != null || entry.getFile() != null)
           {
@@ -1078,7 +1206,7 @@ public class Jalview2XML
             if (!pdbfiles.contains(pdbId))
             {
               pdbfiles.add(pdbId);
-              copyFileToJar(jout, matchedFile, pdbId);
+              copyFileToJar(jout, matchedFile, pdbId, pdbId);
             }
           }
 
@@ -1215,6 +1343,16 @@ public class Jalview2XML
               tree.setXpos(tp.getX());
               tree.setYpos(tp.getY());
               tree.setId(makeHashCode(tp, null));
+              tree.setLinkToAllViews(
+                      tp.getTreeCanvas().isApplyToAllViews());
+
+              // columnWiseTree
+              if (tp.isColumnWise())
+              {
+                tree.setColumnWise(true);
+                String annId = tp.getAssocAnnotation().annotationId;
+                tree.setColumnReference(annId);
+              }
               // jms.addTree(tree);
               object.getTree().add(tree);
             }
@@ -1223,6 +1361,24 @@ public class Jalview2XML
       }
     }
 
+    /*
+     * save PCA viewers
+     */
+    if (!storeDS && Desktop.desktop != null)
+    {
+      for (JInternalFrame frame : Desktop.desktop.getAllFrames())
+      {
+        if (frame instanceof PCAPanel)
+        {
+          PCAPanel panel = (PCAPanel) frame;
+          if (panel.getAlignViewport().getAlignment() == jal)
+          {
+            savePCA(panel, object);
+          }
+        }
+      }
+    }
+
     // SAVE ANNOTATIONS
     /**
      * store forward refs from an annotationRow to any groups
@@ -1279,9 +1435,8 @@ public class Jalview2XML
 
             if (colourScheme instanceof jalview.schemes.UserColourScheme)
             {
-              jGroup.setColour(
-                      setUserColourScheme(colourScheme, userColours,
-                              object));
+              jGroup.setColour(setUserColourScheme(colourScheme,
+                      userColours, object));
             }
             else
             {
@@ -1327,7 +1482,7 @@ public class Jalview2XML
         }
       }
 
-      //jms.setJGroup(groups);
+      // jms.setJGroup(groups);
       Object group;
       for (JGroup grp : groups)
       {
@@ -1373,6 +1528,23 @@ public class Jalview2XML
       view.setStartRes(vpRanges.getStartRes());
       view.setStartSeq(vpRanges.getStartSeq());
 
+      OverviewPanel ov = ap.getOverviewPanel();
+      if (ov != null)
+      {
+        Overview overview = new Overview();
+        overview.setTitle(ov.getTitle());
+        Rectangle bounds = ov.getFrameBounds();
+        overview.setXpos(bounds.x);
+        overview.setYpos(bounds.y);
+        overview.setWidth(bounds.width);
+        overview.setHeight(bounds.height);
+        overview.setShowHidden(ov.isShowHiddenRegions());
+        overview.setGapColour(ov.getCanvas().getGapColour().getRGB());
+        overview.setResidueColour(
+                ov.getCanvas().getResidueColour().getRGB());
+        overview.setHiddenColour(ov.getCanvas().getHiddenColour().getRGB());
+        view.setOverview(overview);
+      }
       if (av.getGlobalColourScheme() instanceof jalview.schemes.UserColourScheme)
       {
         view.setBgColour(setUserColourScheme(av.getGlobalColourScheme(),
@@ -1413,6 +1585,8 @@ public class Jalview2XML
 
       view.setConservationSelected(av.getConservationSelected());
       view.setPidSelected(av.getAbovePIDThreshold());
+      view.setCharHeight(av.getCharHeight());
+      view.setCharWidth(av.getCharWidth());
       final Font font = av.getFont();
       view.setFontName(font.getName());
       view.setFontSize(font.getSize());
@@ -1441,11 +1615,14 @@ public class Jalview2XML
       view.setFollowHighlight(av.isFollowHighlight());
       view.setFollowSelection(av.followSelection);
       view.setIgnoreGapsinConsensus(av.isIgnoreGapsConsensus());
+      view.setShowComplementFeatures(av.isShowComplementFeatures());
+      view.setShowComplementFeaturesOnTop(
+              av.isShowComplementFeaturesOnTop());
       if (av.getFeaturesDisplayed() != null)
       {
         FeatureSettings fs = new FeatureSettings();
 
-        FeatureRenderer fr = ap.getSeqPanel().seqCanvas
+        FeatureRendererModel fr = ap.getSeqPanel().seqCanvas
                 .getFeatureRenderer();
         String[] renderOrder = fr.getRenderOrder().toArray(new String[0]);
 
@@ -1461,11 +1638,13 @@ public class Jalview2XML
              * save any filter for the feature type
              */
             FeatureMatcherSetI filter = fr.getFeatureFilter(featureType);
-            if (filter != null)  {
-              Iterator<FeatureMatcherI> filters = filter.getMatchers().iterator();
+            if (filter != null)
+            {
+              Iterator<FeatureMatcherI> filters = filter.getMatchers()
+                      .iterator();
               FeatureMatcherI firstFilter = filters.next();
-              setting.setMatcherSet(Jalview2XML.marshalFilter(
-                      firstFilter, filters, filter.isAnded()));
+              setting.setMatcherSet(Jalview2XML.marshalFilter(firstFilter,
+                      filters, filter.isAnded()));
             }
 
             /*
@@ -1514,8 +1693,7 @@ public class Jalview2XML
 
             setting.setDisplay(
                     av.getFeaturesDisplayed().isVisible(featureType));
-            float rorder = fr
-                    .getOrder(featureType);
+            float rorder = fr.getOrder(featureType);
             if (rorder > -1)
             {
               setting.setOrder(rorder);
@@ -1539,7 +1717,7 @@ public class Jalview2XML
           Group g = new Group();
           g.setName(grp);
           g.setDisplay(((Boolean) fr.checkGroupVisibility(grp, false))
-                          .booleanValue());
+                  .booleanValue());
           // fs.addGroup(g);
           fs.getGroup().add(g);
           groupsAdded.addElement(grp);
@@ -1554,7 +1732,8 @@ public class Jalview2XML
                 .getHiddenColumns();
         if (hidden == null)
         {
-          warn("REPORT BUG: avoided null columnselection bug (DMAM reported). Please contact Jim about this.");
+          Console.warn(
+                  "REPORT BUG: avoided null columnselection bug (DMAM reported). Please contact Jim about this.");
         }
         else
         {
@@ -1601,7 +1780,8 @@ public class Jalview2XML
       // using save and then load
       try
       {
-        System.out.println("Writing jar entry " + fileName);
+        fileName = fileName.replace('\\', '/');
+        jalview.bin.Console.outPrintln("Writing jar entry " + fileName);
         JarEntry entry = new JarEntry(fileName);
         jout.putNextEntry(entry);
         PrintWriter pout = new PrintWriter(
@@ -1622,7 +1802,7 @@ public class Jalview2XML
       } catch (Exception ex)
       {
         // TODO: raise error in GUI if marshalling failed.
-        System.err.println("Error writing Jalview project");
+        jalview.bin.Console.errPrintln("Error writing Jalview project");
         ex.printStackTrace();
       }
     }
@@ -1630,6 +1810,196 @@ public class Jalview2XML
   }
 
   /**
+   * Writes PCA viewer attributes and computed values to an XML model object and
+   * adds it to the JalviewModel. Any exceptions are reported by logging.
+   */
+  protected void savePCA(PCAPanel panel, JalviewModel object)
+  {
+    try
+    {
+      PcaViewer viewer = new PcaViewer();
+      viewer.setHeight(panel.getHeight());
+      viewer.setWidth(panel.getWidth());
+      viewer.setXpos(panel.getX());
+      viewer.setYpos(panel.getY());
+      viewer.setTitle(panel.getTitle());
+      PCAModel pcaModel = panel.getPcaModel();
+      viewer.setScoreModelName(pcaModel.getScoreModelName());
+      viewer.setXDim(panel.getSelectedDimensionIndex(X));
+      viewer.setYDim(panel.getSelectedDimensionIndex(Y));
+      viewer.setZDim(panel.getSelectedDimensionIndex(Z));
+      viewer.setBgColour(
+              panel.getRotatableCanvas().getBackgroundColour().getRGB());
+      viewer.setScaleFactor(panel.getRotatableCanvas().getScaleFactor());
+      float[] spMin = panel.getRotatableCanvas().getSeqMin();
+      SeqPointMin spmin = new SeqPointMin();
+      spmin.setXPos(spMin[0]);
+      spmin.setYPos(spMin[1]);
+      spmin.setZPos(spMin[2]);
+      viewer.setSeqPointMin(spmin);
+      float[] spMax = panel.getRotatableCanvas().getSeqMax();
+      SeqPointMax spmax = new SeqPointMax();
+      spmax.setXPos(spMax[0]);
+      spmax.setYPos(spMax[1]);
+      spmax.setZPos(spMax[2]);
+      viewer.setSeqPointMax(spmax);
+      viewer.setShowLabels(panel.getRotatableCanvas().isShowLabels());
+      viewer.setLinkToAllViews(
+              panel.getRotatableCanvas().isApplyToAllViews());
+      SimilarityParamsI sp = pcaModel.getSimilarityParameters();
+      viewer.setIncludeGaps(sp.includeGaps());
+      viewer.setMatchGaps(sp.matchGaps());
+      viewer.setIncludeGappedColumns(sp.includeGappedColumns());
+      viewer.setDenominateByShortestLength(sp.denominateByShortestLength());
+
+      /*
+       * sequence points on display
+       */
+      for (jalview.datamodel.SequencePoint spt : pcaModel
+              .getSequencePoints())
+      {
+        SequencePoint point = new SequencePoint();
+        point.setSequenceRef(seqHash(spt.getSequence()));
+        point.setXPos(spt.coord.x);
+        point.setYPos(spt.coord.y);
+        point.setZPos(spt.coord.z);
+        viewer.getSequencePoint().add(point);
+      }
+
+      /*
+       * (end points of) axes on display
+       */
+      for (Point p : panel.getRotatableCanvas().getAxisEndPoints())
+      {
+
+        Axis axis = new Axis();
+        axis.setXPos(p.x);
+        axis.setYPos(p.y);
+        axis.setZPos(p.z);
+        viewer.getAxis().add(axis);
+      }
+
+      /*
+       * raw PCA data (note we are not restoring PCA inputs here -
+       * alignment view, score model, similarity parameters)
+       */
+      PcaDataType data = new PcaDataType();
+      viewer.setPcaData(data);
+      PCA pca = pcaModel.getPcaData();
+
+      DoubleMatrix pm = new DoubleMatrix();
+      saveDoubleMatrix(pca.getPairwiseScores(), pm);
+      data.setPairwiseMatrix(pm);
+
+      DoubleMatrix tm = new DoubleMatrix();
+      saveDoubleMatrix(pca.getTridiagonal(), tm);
+      data.setTridiagonalMatrix(tm);
+
+      DoubleMatrix eigenMatrix = new DoubleMatrix();
+      data.setEigenMatrix(eigenMatrix);
+      saveDoubleMatrix(pca.getEigenmatrix(), eigenMatrix);
+
+      object.getPcaViewer().add(viewer);
+    } catch (Throwable t)
+    {
+      Console.error("Error saving PCA: " + t.getMessage());
+    }
+  }
+
+  /**
+   * Stores values from a matrix into an XML element, including (if present) the
+   * D or E vectors
+   * 
+   * @param m
+   * @param xmlMatrix
+   * @see #loadDoubleMatrix(DoubleMatrix)
+   */
+  protected void saveDoubleMatrix(MatrixI m, DoubleMatrix xmlMatrix)
+  {
+    xmlMatrix.setRows(m.height());
+    xmlMatrix.setColumns(m.width());
+    for (int i = 0; i < m.height(); i++)
+    {
+      DoubleVector row = new DoubleVector();
+      for (int j = 0; j < m.width(); j++)
+      {
+        row.getV().add(m.getValue(i, j));
+      }
+      xmlMatrix.getRow().add(row);
+    }
+    if (m.getD() != null)
+    {
+      DoubleVector dVector = new DoubleVector();
+      for (double d : m.getD())
+      {
+        dVector.getV().add(d);
+      }
+      xmlMatrix.setD(dVector);
+    }
+    if (m.getE() != null)
+    {
+      DoubleVector eVector = new DoubleVector();
+      for (double e : m.getE())
+      {
+        eVector.getV().add(e);
+      }
+      xmlMatrix.setE(eVector);
+    }
+  }
+
+  /**
+   * Loads XML matrix data into a new Matrix object, including the D and/or E
+   * vectors (if present)
+   * 
+   * @param mData
+   * @return
+   * @see Jalview2XML#saveDoubleMatrix(MatrixI, DoubleMatrix)
+   */
+  protected MatrixI loadDoubleMatrix(DoubleMatrix mData)
+  {
+    int rows = mData.getRows();
+    double[][] vals = new double[rows][];
+
+    for (int i = 0; i < rows; i++)
+    {
+      List<Double> dVector = mData.getRow().get(i).getV();
+      vals[i] = new double[dVector.size()];
+      int dvi = 0;
+      for (Double d : dVector)
+      {
+        vals[i][dvi++] = d;
+      }
+    }
+
+    MatrixI m = new Matrix(vals);
+
+    if (mData.getD() != null)
+    {
+      List<Double> dVector = mData.getD().getV();
+      double[] vec = new double[dVector.size()];
+      int dvi = 0;
+      for (Double d : dVector)
+      {
+        vec[dvi++] = d;
+      }
+      m.setD(vec);
+    }
+    if (mData.getE() != null)
+    {
+      List<Double> dVector = mData.getE().getV();
+      double[] vec = new double[dVector.size()];
+      int dvi = 0;
+      for (Double d : dVector)
+      {
+        vec[dvi++] = d;
+      }
+      m.setE(vec);
+    }
+
+    return m;
+  }
+
+  /**
    * Save any Varna viewers linked to this sequence. Writes an rnaViewer element
    * for each viewer, with
    * <ul>
@@ -1711,7 +2081,7 @@ public class Jalview2XML
 
                 String varnaStateFile = varna.getStateInfo(model.rna);
                 jarEntryName = RNA_PREFIX + viewId + "_" + nextCounter();
-                copyFileToJar(jout, varnaStateFile, jarEntryName);
+                copyFileToJar(jout, varnaStateFile, jarEntryName, "Varna");
                 rnaSessions.put(model, jarEntryName);
               }
               SecondaryStructure ss = new SecondaryStructure();
@@ -1735,58 +2105,48 @@ public class Jalview2XML
    * @param jout
    * @param infilePath
    * @param jarEntryName
+   * @param msg
+   *          additional identifying info to log to the console
    */
   protected void copyFileToJar(JarOutputStream jout, String infilePath,
-          String jarEntryName)
+          String jarEntryName, String msg)
   {
-    DataInputStream dis = null;
-    try
+    try (InputStream is = new FileInputStream(infilePath))
     {
       File file = new File(infilePath);
       if (file.exists() && jout != null)
       {
-        dis = new DataInputStream(new FileInputStream(file));
-        byte[] data = new byte[(int) file.length()];
-        dis.readFully(data);
-        writeJarEntry(jout, jarEntryName, data);
+        jalview.bin.Console.outPrintln(
+                "Writing jar entry " + jarEntryName + " (" + msg + ")");
+        jout.putNextEntry(new JarEntry(jarEntryName));
+        copyAll(is, jout);
+        jout.closeEntry();
+        // dis = new DataInputStream(new FileInputStream(file));
+        // byte[] data = new byte[(int) file.length()];
+        // dis.readFully(data);
+        // writeJarEntry(jout, jarEntryName, data);
       }
     } catch (Exception ex)
     {
       ex.printStackTrace();
-    } finally
-    {
-      if (dis != null)
-      {
-        try
-        {
-          dis.close();
-        } catch (IOException e)
-        {
-          // ignore
-        }
-      }
     }
   }
 
   /**
-   * Write the data to a new entry of given name in the output jar file
+   * Copies input to output, in 4K buffers; handles any data (text or binary)
    * 
-   * @param jout
-   * @param jarEntryName
-   * @param data
+   * @param in
+   * @param out
    * @throws IOException
    */
-  protected void writeJarEntry(JarOutputStream jout, String jarEntryName,
-          byte[] data) throws IOException
+  protected void copyAll(InputStream in, OutputStream out)
+          throws IOException
   {
-    if (jout != null)
+    byte[] buffer = new byte[4096];
+    int bytesRead = 0;
+    while ((bytesRead = in.read(buffer)) != -1)
     {
-      System.out.println("Writing jar entry " + jarEntryName);
-      jout.putNextEntry(new JarEntry(jarEntryName));
-      DataOutputStream dout = new DataOutputStream(jout);
-      dout.write(data, 0, data.length);
-      dout.flush();
-      jout.closeEntry();
+      out.write(buffer, 0, bytesRead);
     }
   }
 
@@ -1803,9 +2163,9 @@ public class Jalview2XML
    * @param viewFrame
    * @return
    */
-  protected String saveStructureState(AlignmentPanel ap, SequenceI jds,
+  protected String saveStructureViewer(AlignmentPanel ap, SequenceI jds,
           Pdbids pdb, PDBEntry entry, List<String> viewIds,
-          String matchedFile, StructureViewerBase viewFrame)
+          String matchedFile, JalviewStructureDisplayI viewFrame)
   {
     final AAStructureBindingModel bindingModel = viewFrame.getBinding();
 
@@ -1817,9 +2177,9 @@ public class Jalview2XML
     {
       final PDBEntry pdbentry = bindingModel.getPdbEntry(peid);
       final String pdbId = pdbentry.getId();
-      if (!pdbId.equals(entry.getId())
-              && !(entry.getId().length() > 4 && entry.getId().toLowerCase()
-                      .startsWith(pdbId.toLowerCase())))
+      if (!pdbId.equals(entry.getId()) && !(entry.getId().length() > 4
+              && entry.getId().toLowerCase(Locale.ROOT)
+                      .startsWith(pdbId.toLowerCase(Locale.ROOT))))
       {
         /*
          * not interested in a binding to a different PDB entry here
@@ -1832,7 +2192,7 @@ public class Jalview2XML
       }
       else if (!matchedFile.equals(pdbentry.getFile()))
       {
-        Cache.log.warn(
+        Console.warn(
                 "Probably lost some PDB-Sequence mappings for this structure file (which apparently has same PDB Entry code): "
                         + pdbentry.getFile());
       }
@@ -1850,14 +2210,14 @@ public class Jalview2XML
         {
           StructureState state = new StructureState();
           state.setVisible(true);
-          state.setXpos(viewFrame.getX());
+          state.setXpos(viewFrame.getY());
           state.setYpos(viewFrame.getY());
           state.setWidth(viewFrame.getWidth());
           state.setHeight(viewFrame.getHeight());
           final String viewId = viewFrame.getViewId();
           state.setViewId(viewId);
           state.setAlignwithAlignPanel(viewFrame.isUsedforaligment(ap));
-          state.setColourwithAlignPanel(viewFrame.isUsedforcolourby(ap));
+          state.setColourwithAlignPanel(viewFrame.isUsedForColourBy(ap));
           state.setColourByJmol(viewFrame.isColouredByViewer());
           state.setType(viewFrame.getViewerType().toString());
           // pdb.addStructureState(state);
@@ -1965,12 +2325,81 @@ public class Jalview2XML
           line.setColour(annotation.getThreshold().colour.getRGB());
           an.setThresholdLine(line);
         }
-      }
-      else
-      {
-        an.setGraph(false);
-      }
-
+        if (annotation.graph == AlignmentAnnotation.CONTACT_MAP)
+        {
+          if (annotation.sequenceRef.getContactMaps() != null)
+          {
+            ContactMatrixI cm = annotation.sequenceRef
+                    .getContactMatrixFor(annotation);
+            if (cm != null)
+            {
+              MatrixType xmlmat = new MatrixType();
+              xmlmat.setType(cm.getType());
+              xmlmat.setRows(BigInteger.valueOf(cm.getWidth()));
+              xmlmat.setCols(BigInteger.valueOf(cm.getHeight()));
+              // consider using an opaque to/from -> allow instance to control
+              // its representation ?
+              xmlmat.setElements(ContactMatrix.contactToFloatString(cm));
+              if (cm.hasGroups())
+              {
+                for (BitSet gp : cm.getGroups())
+                {
+                  xmlmat.getGroups().add(stringifyBitset(gp));
+                }
+              }
+              if (cm.hasTree())
+              {
+                // provenance object for tree ?
+                xmlmat.getNewick().add(cm.getNewick());
+                xmlmat.setTreeMethod(cm.getTreeMethod());
+              }
+              if (cm.hasCutHeight())
+              {
+                xmlmat.setCutHeight(cm.getCutHeight());
+              }
+              // set/get properties
+              if (cm instanceof MappableContactMatrixI)
+              {
+                jalview.util.MapList mlst = ((MappableContactMatrixI) cm)
+                        .getMapFor(annotation.sequenceRef);
+                if (mlst != null)
+                {
+                  MapListType mp = new MapListType();
+                  List<int[]> r = mlst.getFromRanges();
+                  for (int[] range : r)
+                  {
+                    MapListFrom mfrom = new MapListFrom();
+                    mfrom.setStart(range[0]);
+                    mfrom.setEnd(range[1]);
+                    // mp.addMapListFrom(mfrom);
+                    mp.getMapListFrom().add(mfrom);
+                  }
+                  r = mlst.getToRanges();
+                  for (int[] range : r)
+                  {
+                    MapListTo mto = new MapListTo();
+                    mto.setStart(range[0]);
+                    mto.setEnd(range[1]);
+                    // mp.addMapListTo(mto);
+                    mp.getMapListTo().add(mto);
+                  }
+                  mp.setMapFromUnit(
+                          BigInteger.valueOf(mlst.getFromRatio()));
+                  mp.setMapToUnit(BigInteger.valueOf(mlst.getToRatio()));
+                  xmlmat.setMapping(mp);
+                }
+              }
+              // and add to model
+              an.getContactmatrix().add(xmlmat);
+            }
+          }
+        }
+      }
+      else
+      {
+        an.setGraph(false);
+      }
+
       an.setLabel(annotation.label);
 
       if (annotation == av.getAlignmentQualityAnnot()
@@ -1995,10 +2424,9 @@ public class Jalview2XML
       {
         for (String pr : annotation.getProperties())
         {
-          jalview.xml.binding.jalview.Annotation.Property prop = new jalview.xml.binding.jalview.Annotation.Property();
+          jalview.xml.binding.jalview.Property prop = new jalview.xml.binding.jalview.Property();
           prop.setName(pr);
           prop.setValue(annotation.getProperty(pr));
-          // an.addProperty(prop);
           an.getProperty().add(prop);
         }
       }
@@ -2069,6 +2497,44 @@ public class Jalview2XML
 
   }
 
+  private String stringifyBitset(BitSet gp)
+  {
+    StringBuilder sb = new StringBuilder();
+    for (long val : gp.toLongArray())
+    {
+      if (sb.length() > 0)
+      {
+        sb.append(",");
+      }
+      sb.append(val);
+    }
+    return sb.toString();
+  }
+
+  private BitSet deStringifyBitset(String stringified)
+  {
+    if ("".equals(stringified) || stringified == null)
+    {
+      return new BitSet();
+    }
+    String[] longvals = stringified.split(",");
+    long[] newlongvals = new long[longvals.length];
+    for (int lv = 0; lv < longvals.length; lv++)
+    {
+      try
+      {
+        newlongvals[lv] = Long.valueOf(longvals[lv]);
+      } catch (Exception x)
+      {
+        errorMessage += "Couldn't destringify bitset from: '" + stringified
+                + "'";
+        newlongvals[lv] = 0;
+      }
+    }
+    return BitSet.valueOf(newlongvals);
+
+  }
+
   private CalcIdParam createCalcIdParam(String calcId, AlignViewport av)
   {
     AutoCalcSetting settings = av.getCalcIdSettingsFor(calcId);
@@ -2115,7 +2581,8 @@ public class Jalview2XML
   {
     if (calcIdParam.getVersion().equals("1.0"))
     {
-      final String[] calcIds = calcIdParam.getServiceURL().toArray(new String[0]);
+      final String[] calcIds = calcIdParam.getServiceURL()
+              .toArray(new String[0]);
       Jws2Instance service = Jws2Discoverer.getDiscoverer()
               .getPreferredServiceFor(calcIds);
       if (service != null)
@@ -2129,7 +2596,7 @@ public class Jalview2XML
                   calcIdParam.getParameters().replace("|\\n|", "\n"));
         } catch (IOException x)
         {
-          warn("Couldn't parse parameter data for "
+          Console.warn("Couldn't parse parameter data for "
                   + calcIdParam.getCalcId(), x);
           return false;
         }
@@ -2157,7 +2624,8 @@ public class Jalview2XML
       }
       else
       {
-        warn("Cannot resolve a service for the parameters used in this project. Try configuring a JABAWS server.");
+        Console.warn(
+                "Cannot resolve a service for the parameters used in this project. Try configuring a JABAWS server.");
         return false;
       }
     }
@@ -2201,7 +2669,8 @@ public class Jalview2XML
         return id.toString();
       }
       // give up and warn that something has gone wrong
-      warn("Cannot find ID for object in external mapping : " + jvobj);
+      Console.warn(
+              "Cannot find ID for object in external mapping : " + jvobj);
     }
     return altCode;
   }
@@ -2241,7 +2710,7 @@ public class Jalview2XML
     vamsasSeq.setName(jds.getName());
     vamsasSeq.setSequence(jds.getSequenceAsString());
     vamsasSeq.setDescription(jds.getDescription());
-    jalview.datamodel.DBRefEntry[] dbrefs = null;
+    List<DBRefEntry> dbrefs = null;
     if (jds.getDatasetSequence() != null)
     {
       vamsasSeq.setDsseqid(seqHash(jds.getDatasetSequence()));
@@ -2257,21 +2726,30 @@ public class Jalview2XML
         parentseq = jds;
       }
     }
+
+    /*
+     * save any dbrefs; special subclass GeneLocus is flagged as 'locus'
+     */
     if (dbrefs != null)
     {
-      for (int d = 0; d < dbrefs.length; d++)
+      for (int d = 0, nd = dbrefs.size(); d < nd; d++)
       {
         DBRef dbref = new DBRef();
-        dbref.setSource(dbrefs[d].getSource());
-        dbref.setVersion(dbrefs[d].getVersion());
-        dbref.setAccessionId(dbrefs[d].getAccessionId());
-        if (dbrefs[d].hasMap())
+        DBRefEntry ref = dbrefs.get(d);
+        dbref.setSource(ref.getSource());
+        dbref.setVersion(ref.getVersion());
+        dbref.setAccessionId(ref.getAccessionId());
+        dbref.setCanonical(ref.isCanonical());
+        if (ref instanceof GeneLocus)
+        {
+          dbref.setLocus(true);
+        }
+        if (ref.hasMap())
         {
-          Mapping mp = createVamsasMapping(dbrefs[d].getMap(), parentseq,
-                  jds, recurse);
+          Mapping mp = createVamsasMapping(ref.getMap(), parentseq, jds,
+                  recurse);
           dbref.setMapping(mp);
         }
-        // vamsasSeq.addDBRef(dbref);
         vamsasSeq.getDBRef().add(dbref);
       }
     }
@@ -2329,12 +2807,12 @@ public class Jalview2XML
         mp.setDseqFor(jmpid);
         if (!seqRefIds.containsKey(jmpid))
         {
-          jalview.bin.Cache.log.debug("creatign new DseqFor ID");
+          Console.debug("creatign new DseqFor ID");
           seqRefIds.put(jmpid, ps);
         }
         else
         {
-          jalview.bin.Cache.log.debug("reusing DseqFor ID");
+          Console.debug("reusing DseqFor ID");
         }
 
         // mp.setMappingChoice(mpc);
@@ -2377,7 +2855,7 @@ public class Jalview2XML
         for (int i = 0; i < colours.length; i++)
         {
           Colour col = new Colour();
-          col.setName(ResidueProperties.aa[i].toLowerCase());
+          col.setName(ResidueProperties.aa[i].toLowerCase(Locale.ROOT));
           col.setRGB(jalview.util.Format.getHexString(colours[i]));
           // jbucs.addColour(col);
           jbucs.getColour().add(col);
@@ -2393,12 +2871,12 @@ public class Jalview2XML
     return id;
   }
 
-  jalview.schemes.UserColourScheme getUserColourScheme(
-          JalviewModel jm, String id)
+  jalview.schemes.UserColourScheme getUserColourScheme(JalviewModel jm,
+          String id)
   {
     List<UserColours> uc = jm.getUserColours();
     UserColours colours = null;
-/*
+    /*
     for (int i = 0; i < uc.length; i++)
     {
       if (uc[i].getId().equals(id))
@@ -2407,7 +2885,7 @@ public class Jalview2XML
         break;
       }
     }
-*/
+    */
     for (UserColours c : uc)
     {
       if (c.getId().equals(id))
@@ -2435,10 +2913,9 @@ public class Jalview2XML
       newColours = new java.awt.Color[23];
       for (int i = 0; i < 23; i++)
       {
-        newColours[i] = new java.awt.Color(Integer.parseInt(
-                colours.getUserColourScheme().getColour().get(i + 24)
-                        .getRGB(),
-                16));
+        newColours[i] = new java.awt.Color(
+                Integer.parseInt(colours.getUserColourScheme().getColour()
+                        .get(i + 24).getRGB(), 16));
       }
       ucs.setLowerCaseColours(newColours);
     }
@@ -2463,7 +2940,7 @@ public class Jalview2XML
    * @param file
    *          - HTTP URL or filename
    */
-  public AlignFrame loadJalviewAlign(final String file)
+  public AlignFrame loadJalviewAlign(final Object file)
   {
 
     jalview.gui.AlignFrame af = null;
@@ -2497,53 +2974,82 @@ public class Jalview2XML
           public void run()
           {
             setLoadingFinishedForNewStructureViewers();
-          };
+          }
         });
       } catch (Exception x)
       {
-        System.err.println("Error loading alignment: " + x.getMessage());
+        jalview.bin.Console
+                .errPrintln("Error loading alignment: " + x.getMessage());
       }
     }
     return af;
   }
 
+  @SuppressWarnings("unused")
   private jarInputStreamProvider createjarInputStreamProvider(
-          final String file) throws MalformedURLException
+          final Object ofile) throws MalformedURLException
   {
-    URL url = null;
-    errorMessage = null;
-    uniqueSetSuffix = null;
-    seqRefIds = null;
-    viewportsAdded.clear();
-    frefedSequence = null;
 
-    if (file.startsWith("http://"))
-    {
-      url = new URL(file);
-    }
-    final URL _url = url;
-    return new jarInputStreamProvider()
+    // BH 2018 allow for bytes already attached to File object
+    try
     {
+      String file = (ofile instanceof File
+              ? ((File) ofile).getCanonicalPath()
+              : ofile.toString());
+      byte[] bytes = Platform.isJS() ? Platform.getFileBytes((File) ofile)
+              : null;
+      URL url = null;
+      errorMessage = null;
+      uniqueSetSuffix = null;
+      seqRefIds = null;
+      viewportsAdded.clear();
+      frefedSequence = null;
 
-      @Override
-      public JarInputStream getJarInputStream() throws IOException
+      if (HttpUtils.startsWithHttpOrHttps(file))
+      {
+        url = new URL(file);
+      }
+      final URL _url = url;
+      return new jarInputStreamProvider()
       {
-        if (_url != null)
+
+        @Override
+        public JarInputStream getJarInputStream() throws IOException
         {
-          return new JarInputStream(_url.openStream());
+          if (bytes != null)
+          {
+            // jalview.bin.Console.outPrintln("Jalview2XML: opening byte
+            // jarInputStream for
+            // bytes.length=" + bytes.length);
+            return new JarInputStream(new ByteArrayInputStream(bytes));
+          }
+          if (_url != null)
+          {
+            // jalview.bin.Console.outPrintln("Jalview2XML: opening url
+            // jarInputStream for "
+            // + _url);
+            return new JarInputStream(_url.openStream());
+          }
+          else
+          {
+            // jalview.bin.Console.outPrintln("Jalview2XML: opening file
+            // jarInputStream for
+            // " + file);
+            return new JarInputStream(new FileInputStream(file));
+          }
         }
-        else
+
+        @Override
+        public String getFilename()
         {
-          return new JarInputStream(new FileInputStream(file));
+          return file;
         }
-      }
-
-      @Override
-      public String getFilename()
-      {
-        return file;
-      }
-    };
+      };
+    } catch (IOException e)
+    {
+      e.printStackTrace();
+      return null;
+    }
   }
 
   /**
@@ -2586,23 +3092,15 @@ public class Jalview2XML
 
         if (jarentry != null && jarentry.getName().endsWith(".xml"))
         {
-          InputStreamReader in = new InputStreamReader(jin, UTF_8);
-          // JalviewModel object = new JalviewModel();
-
           JAXBContext jc = JAXBContext
                   .newInstance("jalview.xml.binding.jalview");
           XMLStreamReader streamReader = XMLInputFactory.newInstance()
                   .createXMLStreamReader(jin);
           javax.xml.bind.Unmarshaller um = jc.createUnmarshaller();
-          JAXBElement<JalviewModel> jbe = um
-                  .unmarshal(streamReader, JalviewModel.class);
+          JAXBElement<JalviewModel> jbe = um.unmarshal(streamReader,
+                  JalviewModel.class);
           JalviewModel object = jbe.getValue();
 
-          /*
-          Unmarshaller unmar = new Unmarshaller(object);
-          unmar.setValidation(false);
-          object = (JalviewModel) unmar.unmarshal(in);
-          */
           if (true) // !skipViewport(object))
           {
             _af = loadFromObject(object, file, true, jprovider);
@@ -2636,29 +3134,22 @@ public class Jalview2XML
           entryCount++;
         }
       } while (jarentry != null);
+      jin.close();
       resolveFrefedSequences();
     } catch (IOException ex)
     {
       ex.printStackTrace();
       errorMessage = "Couldn't locate Jalview XML file : " + file;
-      System.err.println(
+      jalview.bin.Console.errPrintln(
               "Exception whilst loading jalview XML file : " + ex + "\n");
     } catch (Exception ex)
     {
-      System.err.println("Parsing as Jalview Version 2 file failed.");
+      jalview.bin.Console
+              .errPrintln("Parsing as Jalview Version 2 file failed.");
       ex.printStackTrace(System.err);
       if (attemptversion1parse)
       {
-        // Is Version 1 Jar file?
-        try
-        {
-          af = new Jalview2XML_V1(raiseGUI).LoadJalviewAlign(jprovider);
-        } catch (Exception ex2)
-        {
-          System.err.println("Exception whilst loading as jalviewXMLV1:");
-          ex2.printStackTrace();
-          af = null;
-        }
+        // used to attempt to parse as V1 castor-generated xml
       }
       if (Desktop.instance != null)
       {
@@ -2666,18 +3157,19 @@ public class Jalview2XML
       }
       if (af != null)
       {
-        System.out.println("Successfully loaded archive file");
+        jalview.bin.Console.outPrintln("Successfully loaded archive file");
         return af;
       }
       ex.printStackTrace();
 
-      System.err.println(
+      jalview.bin.Console.errPrintln(
               "Exception whilst loading jalview XML file : " + ex + "\n");
     } catch (OutOfMemoryError e)
     {
       // Don't use the OOM Window here
       errorMessage = "Out of memory loading jalview XML file";
-      System.err.println("Out of memory whilst loading jalview XML file");
+      jalview.bin.Console
+              .errPrintln("Out of memory whilst loading jalview XML file");
       e.printStackTrace();
     }
 
@@ -2781,8 +3273,8 @@ public class Jalview2XML
         Desktop.addInternalFrame(af, view.getTitle(),
                 safeInt(view.getWidth()), safeInt(view.getHeight()));
         af.setMenusForViewport();
-        System.err.println("Failed to restore view " + view.getTitle()
-                + " to split frame");
+        jalview.bin.Console.errPrintln("Failed to restore view "
+                + view.getTitle() + " to split frame");
       }
     }
 
@@ -2860,7 +3352,8 @@ public class Jalview2XML
       }
       else
       {
-        System.err.println("Problem loading Jalview file: " + errorMessage);
+        jalview.bin.Console.errPrintln(
+                "Problem loading Jalview file: " + errorMessage);
       }
     }
     errorMessage = null;
@@ -2911,79 +3404,53 @@ public class Jalview2XML
    * @param prefix
    *          a prefix for the temporary file name, must be at least three
    *          characters long
-   * @param origFile
+   * @param suffixModel
    *          null or original file - so new file can be given the same suffix
    *          as the old one
    * @return
    */
   protected String copyJarEntry(jarInputStreamProvider jprovider,
-          String jarEntryName, String prefix, String origFile)
+          String jarEntryName, String prefix, String suffixModel)
   {
-    BufferedReader in = null;
-    PrintWriter out = null;
     String suffix = ".tmp";
-    if (origFile == null)
+    if (suffixModel == null)
     {
-      origFile = jarEntryName;
+      suffixModel = jarEntryName;
     }
-    int sfpos = origFile.lastIndexOf(".");
-    if (sfpos > -1 && sfpos < (origFile.length() - 3))
+    int sfpos = suffixModel.lastIndexOf(".");
+    if (sfpos > -1 && sfpos < (suffixModel.length() - 1))
     {
-      suffix = "." + origFile.substring(sfpos + 1);
+      suffix = "." + suffixModel.substring(sfpos + 1);
     }
-    try
-    {
-      JarInputStream jin = jprovider.getJarInputStream();
-      /*
-       * if (jprovider.startsWith("http://")) { jin = new JarInputStream(new
-       * URL(jprovider).openStream()); } else { jin = new JarInputStream(new
-       * FileInputStream(jprovider)); }
-       */
 
+    try (JarInputStream jin = jprovider.getJarInputStream())
+    {
       JarEntry entry = null;
       do
       {
         entry = jin.getNextJarEntry();
       } while (entry != null && !entry.getName().equals(jarEntryName));
+
       if (entry != null)
       {
-        in = new BufferedReader(new InputStreamReader(jin, UTF_8));
+        // in = new BufferedReader(new InputStreamReader(jin, UTF_8));
         File outFile = File.createTempFile(prefix, suffix);
         outFile.deleteOnExit();
-        out = new PrintWriter(new FileOutputStream(outFile));
-        String data;
-
-        while ((data = in.readLine()) != null)
+        try (OutputStream os = new FileOutputStream(outFile))
         {
-          out.println(data);
+          copyAll(jin, os);
         }
-        out.flush();
         String t = outFile.getAbsolutePath();
         return t;
       }
       else
       {
-        warn("Couldn't find entry in Jalview Jar for " + jarEntryName);
+        Console.warn(
+                "Couldn't find entry in Jalview Jar for " + jarEntryName);
       }
     } catch (Exception ex)
     {
       ex.printStackTrace();
-    } finally
-    {
-      if (in != null)
-      {
-        try
-        {
-          in.close();
-        } catch (IOException e)
-        {
-          // ignore
-        }
-      }
-      if (out != null)
-      {
-        out.close();
-      }
     }
 
     return null;
@@ -3024,7 +3491,8 @@ public class Jalview2XML
   AlignFrame loadFromObject(JalviewModel jalviewModel, String file,
           boolean loadTreesAndStructures, jarInputStreamProvider jprovider)
   {
-    SequenceSet vamsasSet = jalviewModel.getVamsasModel().getSequenceSet().get(0);
+    SequenceSet vamsasSet = jalviewModel.getVamsasModel().getSequenceSet()
+            .get(0);
     List<Sequence> vamsasSeqs = vamsasSet.getSequence();
 
     // JalviewModelSequence jms = object.getJalviewModelSequence();
@@ -3083,9 +3551,10 @@ public class Jalview2XML
           if (tmpSeq.getStart() != jseq.getStart()
                   || tmpSeq.getEnd() != jseq.getEnd())
           {
-            System.err.println(
-                    "Warning JAL-2154 regression: updating start/end for sequence "
-                            + tmpSeq.toString() + " to " + jseq);
+            jalview.bin.Console.errPrintln(String.format(
+                    "Warning JAL-2154 regression: updating start/end for sequence %s from %d/%d to %d/%d",
+                    tmpSeq.getName(), tmpSeq.getStart(), tmpSeq.getEnd(),
+                    jseq.getStart(), jseq.getEnd()));
           }
         }
         else
@@ -3368,8 +3837,8 @@ public class Jalview2XML
               else
               {
                 // defer to later
-                frefedSequence.add(
-                        newAlcodMapRef(map.getDnasq(), cf, mapping));
+                frefedSequence
+                        .add(newAlcodMapRef(map.getDnasq(), cf, mapping));
               }
             }
           }
@@ -3577,12 +4046,94 @@ public class Jalview2XML
         jaa.setCalcId(annotation.getCalcId());
         if (annotation.getProperty().size() > 0)
         {
-          for (Annotation.Property prop : annotation
+          for (jalview.xml.binding.jalview.Property prop : annotation
                   .getProperty())
           {
             jaa.setProperty(prop.getName(), prop.getValue());
           }
         }
+        if (jaa.graph == AlignmentAnnotation.CONTACT_MAP)
+        {
+          if (annotation.getContactmatrix() != null
+                  && annotation.getContactmatrix().size() > 0)
+          {
+            for (MatrixType xmlmat : annotation.getContactmatrix())
+            {
+              if (PAEContactMatrix.PAEMATRIX.equals(xmlmat.getType()))
+              {
+                if (!xmlmat.getRows().equals(xmlmat.getCols()))
+                {
+                  Console.error("Can't handle non square PAE Matrices");
+                }
+                else
+                {
+                  float[][] elements = ContactMatrix
+                          .fromFloatStringToContacts(xmlmat.getElements(),
+                                  xmlmat.getCols().intValue(),
+                                  xmlmat.getRows().intValue());
+                  jalview.util.MapList mapping = null;
+                  if (xmlmat.getMapping() != null)
+                  {
+                    MapListType m = xmlmat.getMapping();
+                    // Mapping m = dr.getMapping();
+                    int fr[] = new int[m.getMapListFrom().size() * 2];
+                    Iterator<MapListFrom> from = m.getMapListFrom()
+                            .iterator();// enumerateMapListFrom();
+                    for (int _i = 0; from.hasNext(); _i += 2)
+                    {
+                      MapListFrom mf = from.next();
+                      fr[_i] = mf.getStart();
+                      fr[_i + 1] = mf.getEnd();
+                    }
+                    int fto[] = new int[m.getMapListTo().size() * 2];
+                    Iterator<MapListTo> to = m.getMapListTo().iterator();// enumerateMapListTo();
+                    for (int _i = 0; to.hasNext(); _i += 2)
+                    {
+                      MapListTo mf = to.next();
+                      fto[_i] = mf.getStart();
+                      fto[_i + 1] = mf.getEnd();
+                    }
+
+                    mapping = new jalview.util.MapList(fr, fto,
+                            m.getMapFromUnit().intValue(),
+                            m.getMapToUnit().intValue());
+                  }
+                  List<BitSet> newgroups = new ArrayList<BitSet>();
+                  if (xmlmat.getGroups().size() > 0)
+                  {
+                    for (String sgroup : xmlmat.getGroups())
+                    {
+                      newgroups.add(deStringifyBitset(sgroup));
+                    }
+                  }
+                  String nwk = xmlmat.getNewick().size() > 0
+                          ? xmlmat.getNewick().get(0)
+                          : null;
+                  if (xmlmat.getNewick().size() > 1)
+                  {
+                    Console.log.info(
+                            "Ignoring additional clusterings for contact matrix");
+                  }
+                  String treeMethod = xmlmat.getTreeMethod();
+                  double thresh = xmlmat.getCutHeight() != null
+                          ? xmlmat.getCutHeight()
+                          : 0;
+                  GroupSet grpset = new GroupSet();
+                  grpset.restoreGroups(newgroups, treeMethod, nwk, thresh);
+                  PAEContactMatrix newpae = new PAEContactMatrix(
+                          jaa.sequenceRef, mapping, elements, grpset);
+                  jaa.sequenceRef.addContactListFor(jaa, newpae);
+                }
+              }
+              else
+              {
+                Console.error("Ignoring CONTACT_MAP annotation with type "
+                        + xmlmat.getType());
+              }
+            }
+          }
+        }
+
         if (jaa.autoCalculated)
         {
           autoAlan.add(new JvAnnotRow(i, jaa));
@@ -3620,7 +4171,7 @@ public class Jalview2XML
           }
           else
           {
-            cs = ColourSchemeProperty.getColourScheme(al,
+            cs = ColourSchemeProperty.getColourScheme(null, al,
                     jGroup.getColour());
           }
         }
@@ -3659,9 +4210,9 @@ public class Jalview2XML
         sg.setShowNonconserved(safeBoolean(jGroup.isShowUnconserved()));
         sg.thresholdTextColour = safeInt(jGroup.getTextColThreshold());
         // attributes with a default in the schema are never null
-          sg.setShowConsensusHistogram(jGroup.isShowConsensusHistogram());
-          sg.setshowSequenceLogo(jGroup.isShowSequenceLogo());
-          sg.setNormaliseSequenceLogo(jGroup.isNormaliseSequenceLogo());
+        sg.setShowConsensusHistogram(jGroup.isShowConsensusHistogram());
+        sg.setshowSequenceLogo(jGroup.isShowSequenceLogo());
+        sg.setNormaliseSequenceLogo(jGroup.isNormaliseSequenceLogo());
         sg.setIgnoreGapsConsensus(jGroup.isIgnoreGapsinConsensus());
         if (jGroup.getConsThreshold() != null
                 && jGroup.getConsThreshold().intValue() != 0)
@@ -3705,8 +4256,9 @@ public class Jalview2XML
         if (addAnnotSchemeGroup)
         {
           // reconstruct the annotation colourscheme
-          sg.setColourScheme(constructAnnotationColour(
-                  jGroup.getAnnotationColours(), null, al, jalviewModel, false));
+          sg.setColourScheme(
+                  constructAnnotationColour(jGroup.getAnnotationColours(),
+                          null, al, jalviewModel, false));
         }
       }
     }
@@ -3730,7 +4282,7 @@ public class Jalview2XML
       // XML.
       // and then recover its containing af to allow the settings to be applied.
       // TODO: fix for vamsas demo
-      System.err.println(
+      jalview.bin.Console.errPrintln(
               "About to recover a viewport for existing alignment: Sequence set ID is "
                       + uniqueSeqSetId);
       Object seqsetobj = retrieveExistingObj(uniqueSeqSetId);
@@ -3739,13 +4291,13 @@ public class Jalview2XML
         if (seqsetobj instanceof String)
         {
           uniqueSeqSetId = (String) seqsetobj;
-          System.err.println(
+          jalview.bin.Console.errPrintln(
                   "Recovered extant sequence set ID mapping for ID : New Sequence set ID is "
                           + uniqueSeqSetId);
         }
         else
         {
-          System.err.println(
+          jalview.bin.Console.errPrintln(
                   "Warning : Collision between sequence set ID string and existing jalview object mapping.");
         }
 
@@ -3792,21 +4344,59 @@ public class Jalview2XML
     }
 
     /*
-     * Load any trees, PDB structures and viewers
+     * Load any trees, PDB structures and viewers, Overview
      * 
      * Not done if flag is false (when this method is used for New View)
      */
     if (loadTreesAndStructures)
     {
       loadTrees(jalviewModel, view, af, av, ap);
+      loadPCAViewers(jalviewModel, ap);
       loadPDBStructures(jprovider, jseqs, af, ap);
       loadRnaViewers(jprovider, jseqs, ap);
+      loadOverview(view, jalviewModel.getVersion(), af);
     }
     // and finally return.
     return af;
   }
 
   /**
+   * Load Overview window, restoring colours, 'show hidden regions' flag, title
+   * and geometry as saved
+   * 
+   * @param view
+   * @param af
+   */
+  protected void loadOverview(Viewport view, String version, AlignFrame af)
+  {
+    if (!isVersionStringLaterThan("2.11.3", version)
+            && view.getOverview() == null)
+    {
+      return;
+    }
+    /*
+     * first close any Overview that was opened automatically
+     * (if so configured in Preferences) so that the view is
+     * restored in the same state as saved
+     */
+    af.alignPanel.closeOverviewPanel();
+
+    Overview overview = view.getOverview();
+    if (overview != null)
+    {
+      OverviewPanel overviewPanel = af
+              .openOverviewPanel(overview.isShowHidden());
+      overviewPanel.setTitle(overview.getTitle());
+      overviewPanel.setFrameBounds(overview.getXpos(), overview.getYpos(),
+              overview.getWidth(), overview.getHeight());
+      Color gap = new Color(overview.getGapColour());
+      Color residue = new Color(overview.getResidueColour());
+      Color hidden = new Color(overview.getHiddenColour());
+      overviewPanel.getCanvas().setColours(gap, residue, hidden);
+    }
+  }
+
+  /**
    * Instantiate and link any saved RNA (Varna) viewers. The state of the Varna
    * panel is restored from separate jar entries, two (gapped and trimmed) per
    * sequence and secondary structure.
@@ -3911,8 +4501,8 @@ public class Jalview2XML
    * @param av
    * @param ap
    */
-  protected void loadTrees(JalviewModel jm, Viewport view,
-          AlignFrame af, AlignViewport av, AlignmentPanel ap)
+  protected void loadTrees(JalviewModel jm, Viewport view, AlignFrame af,
+          AlignViewport av, AlignmentPanel ap)
   {
     // TODO result of automated refactoring - are all these parameters needed?
     try
@@ -3925,10 +4515,28 @@ public class Jalview2XML
         TreePanel tp = (TreePanel) retrieveExistingObj(tree.getId());
         if (tp == null)
         {
-          tp = af.showNewickTree(new NewickFile(tree.getNewick()),
-                  tree.getTitle(), safeInt(tree.getWidth()),
-                  safeInt(tree.getHeight()), safeInt(tree.getXpos()),
-                  safeInt(tree.getYpos()));
+          if (tree.isColumnWise())
+          {
+            AlignmentAnnotation aa = annotationIds
+                    .get(tree.getColumnReference());
+            if (aa == null)
+            {
+              Console.warn(
+                      "Null alignment annotation when restoring columnwise tree");
+            }
+            tp = af.showColumnWiseTree(new NewickFile(tree.getNewick()), aa,
+                    tree.getTitle(), safeInt(tree.getWidth()),
+                    safeInt(tree.getHeight()), safeInt(tree.getXpos()),
+                    safeInt(tree.getYpos()));
+
+          }
+          else
+          {
+            tp = af.showNewickTree(new NewickFile(tree.getNewick()),
+                    tree.getTitle(), safeInt(tree.getWidth()),
+                    safeInt(tree.getHeight()), safeInt(tree.getXpos()),
+                    safeInt(tree.getYpos()));
+          }
           if (tree.getId() != null)
           {
             // perhaps bind the tree id to something ?
@@ -3947,12 +4555,13 @@ public class Jalview2XML
           // TODO: verify 'associate with all views' works still
           tp.getTreeCanvas().setViewport(av); // af.viewport;
           tp.getTreeCanvas().setAssociatedPanel(ap); // af.alignPanel;
-
         }
+        tp.getTreeCanvas().setApplyToAllViews(tree.isLinkToAllViews());
         if (tp == null)
         {
-          warn("There was a problem recovering stored Newick tree: \n"
-                  + tree.getNewick());
+          Console.warn(
+                  "There was a problem recovering stored Newick tree: \n"
+                          + tree.getNewick());
           continue;
         }
 
@@ -4020,8 +4629,8 @@ public class Jalview2XML
           for (int s = 0; s < structureStateCount; s++)
           {
             // check to see if we haven't already created this structure view
-            final StructureState structureState = pdbid
-                    .getStructureState().get(s);
+            final StructureState structureState = pdbid.getStructureState()
+                    .get(s);
             String sviewid = (structureState.getViewId() == null) ? null
                     : structureState.getViewId() + uniqueSetSuffix;
             jalview.datamodel.PDBEntry jpdb = new jalview.datamodel.PDBEntry();
@@ -4051,10 +4660,15 @@ public class Jalview2XML
             }
             if (!structureViewers.containsKey(sviewid))
             {
+              String viewerType = structureState.getType();
+              if (viewerType == null) // pre Jalview 2.9
+              {
+                viewerType = ViewerType.JMOL.toString();
+              }
               structureViewers.put(sviewid,
                       new StructureViewerModel(x, y, width, height, false,
                               false, true, structureState.getViewId(),
-                              structureState.getType()));
+                              viewerType));
               // Legacy pre-2.7 conversion JAL-823 :
               // do not assume any view has to be linked for colour by
               // sequence
@@ -4084,8 +4698,8 @@ public class Jalview2XML
             colourByViewer &= structureState.isColourByJmol();
             jmoldat.setColourByViewer(colourByViewer);
 
-            if (jmoldat.getStateData().length() < structureState
-                    .getValue()/*Content()*/.length())
+            if (jmoldat.getStateData().length() < structureState.getValue()
+                    /*Content()*/.length())
             {
               jmoldat.setStateData(structureState.getValue());// Content());
             }
@@ -4108,7 +4722,7 @@ public class Jalview2XML
             else
             {
               errorMessage = ("The Jmol views in this project were imported\nfrom an older version of Jalview.\nPlease review the sequence colour associations\nin the Colour by section of the Jmol View menu.\n\nIn the case of problems, see note at\nhttp://issues.jalview.org/browse/JAL-747");
-              warn(errorMessage);
+              Console.warn(errorMessage);
             }
           }
         }
@@ -4123,7 +4737,7 @@ public class Jalview2XML
         createOrLinkStructureViewer(entry, af, ap, jprovider);
       } catch (Exception e)
       {
-        System.err.println(
+        jalview.bin.Console.errPrintln(
                 "Error loading structure viewer: " + e.getMessage());
         // failed - try the next one
       }
@@ -4155,300 +4769,70 @@ public class Jalview2XML
       return;
     }
 
-    /*
-     * From 2.9: stateData.type contains JMOL or CHIMERA, data is in jar entry
-     * "viewer_"+stateData.viewId
-     */
-    if (ViewerType.CHIMERA.toString().equals(stateData.getType()))
+    String type = stateData.getType();
+    try
     {
-      createChimeraViewer(viewerData, af, jprovider);
-    }
-    else
+      ViewerType viewerType = ViewerType.valueOf(type);
+      createStructureViewer(viewerType, viewerData, af, jprovider);
+    } catch (IllegalArgumentException | NullPointerException e)
     {
-      /*
-       * else Jmol (if pre-2.9, stateData contains JMOL state string)
-       */
-      createJmolViewer(viewerData, af, jprovider);
+      // TODO JAL-3619 show error dialog / offer an alternative viewer
+      Console.error("Invalid structure viewer type: " + type);
     }
   }
 
   /**
-   * Create a new Chimera viewer.
+   * Generates a name for the entry in the project jar file to hold state
+   * information for a structure viewer
    * 
-   * @param data
-   * @param af
-   * @param jprovider
+   * @param viewId
+   * @return
    */
-  protected void createChimeraViewer(
-          Entry<String, StructureViewerModel> viewerData, AlignFrame af,
-          jarInputStreamProvider jprovider)
+  protected String getViewerJarEntryName(String viewId)
   {
-    StructureViewerModel data = viewerData.getValue();
-    String chimeraSessionFile = data.getStateData();
-
-    /*
-     * Copy Chimera session from jar entry "viewer_"+viewId to a temporary file
-     * 
-     * NB this is the 'saved' viewId as in the project file XML, _not_ the
-     * 'uniquified' sviewid used to reconstruct the viewer here
-     */
-    String viewerJarEntryName = getViewerJarEntryName(data.getViewId());
-    chimeraSessionFile = copyJarEntry(jprovider, viewerJarEntryName,
-            "chimera", null);
-
-    Set<Entry<File, StructureData>> fileData = data.getFileData()
-            .entrySet();
-    List<PDBEntry> pdbs = new ArrayList<>();
-    List<SequenceI[]> allseqs = new ArrayList<>();
-    for (Entry<File, StructureData> pdb : fileData)
-    {
-      String filePath = pdb.getValue().getFilePath();
-      String pdbId = pdb.getValue().getPdbId();
-      // pdbs.add(new PDBEntry(filePath, pdbId));
-      pdbs.add(new PDBEntry(pdbId, null, PDBEntry.Type.PDB, filePath));
-      final List<SequenceI> seqList = pdb.getValue().getSeqList();
-      SequenceI[] seqs = seqList.toArray(new SequenceI[seqList.size()]);
-      allseqs.add(seqs);
-    }
-
-    boolean colourByChimera = data.isColourByViewer();
-    boolean colourBySequence = data.isColourWithAlignPanel();
-
-    // TODO use StructureViewer as a factory here, see JAL-1761
-    final PDBEntry[] pdbArray = pdbs.toArray(new PDBEntry[pdbs.size()]);
-    final SequenceI[][] seqsArray = allseqs
-            .toArray(new SequenceI[allseqs.size()][]);
-    String newViewId = viewerData.getKey();
-
-    ChimeraViewFrame cvf = new ChimeraViewFrame(chimeraSessionFile,
-            af.alignPanel, pdbArray, seqsArray, colourByChimera,
-            colourBySequence, newViewId);
-    cvf.setSize(data.getWidth(), data.getHeight());
-    cvf.setLocation(data.getX(), data.getY());
+    return VIEWER_PREFIX + viewId;
   }
 
   /**
-   * Create a new Jmol window. First parse the Jmol state to translate filenames
-   * loaded into the view, and record the order in which files are shown in the
-   * Jmol view, so we can add the sequence mappings in same order.
+   * Returns any open frame that matches given structure viewer data. The match
+   * is based on the unique viewId, or (for older project versions) the frame's
+   * geometry.
    * 
    * @param viewerData
-   * @param af
-   * @param jprovider
+   * @return
    */
-  protected void createJmolViewer(
-          final Entry<String, StructureViewerModel> viewerData,
-          AlignFrame af, jarInputStreamProvider jprovider)
+  protected StructureViewerBase findMatchingViewer(
+          Entry<String, StructureViewerModel> viewerData)
   {
+    final String sviewid = viewerData.getKey();
     final StructureViewerModel svattrib = viewerData.getValue();
-    String state = svattrib.getStateData();
-
-    /*
-     * Pre-2.9: state element value is the Jmol state string
-     * 
-     * 2.9+: @type is "JMOL", state data is in a Jar file member named "viewer_"
-     * + viewId
-     */
-    if (ViewerType.JMOL.toString().equals(svattrib.getType()))
-    {
-      state = readJarEntry(jprovider,
-              getViewerJarEntryName(svattrib.getViewId()));
-    }
-
-    List<String> pdbfilenames = new ArrayList<>();
-    List<SequenceI[]> seqmaps = new ArrayList<>();
-    List<String> pdbids = new ArrayList<>();
-    StringBuilder newFileLoc = new StringBuilder(64);
-    int cp = 0, ncp, ecp;
-    Map<File, StructureData> oldFiles = svattrib.getFileData();
-    while ((ncp = state.indexOf("load ", cp)) > -1)
+    StructureViewerBase comp = null;
+    JInternalFrame[] frames = getAllFrames();
+    for (JInternalFrame frame : frames)
     {
-      do
+      if (frame instanceof StructureViewerBase)
       {
-        // look for next filename in load statement
-        newFileLoc.append(state.substring(cp,
-                ncp = (state.indexOf("\"", ncp + 1) + 1)));
-        String oldfilenam = state.substring(ncp,
-                ecp = state.indexOf("\"", ncp));
-        // recover the new mapping data for this old filename
-        // have to normalize filename - since Jmol and jalview do
-        // filename
-        // translation differently.
-        StructureData filedat = oldFiles.get(new File(oldfilenam));
-        if (filedat == null)
+        /*
+         * Post jalview 2.4 schema includes structure view id
+         */
+        if (sviewid != null && ((StructureViewerBase) frame).getViewId()
+                .equals(sviewid))
         {
-          String reformatedOldFilename = oldfilenam.replaceAll("/", "\\\\");
-          filedat = oldFiles.get(new File(reformatedOldFilename));
+          comp = (StructureViewerBase) frame;
+          break; // break added in 2.9
         }
-        newFileLoc.append(Platform.escapeString(filedat.getFilePath()));
-        pdbfilenames.add(filedat.getFilePath());
-        pdbids.add(filedat.getPdbId());
-        seqmaps.add(filedat.getSeqList().toArray(new SequenceI[0]));
-        newFileLoc.append("\"");
-        cp = ecp + 1; // advance beyond last \" and set cursor so we can
-                      // look for next file statement.
-      } while ((ncp = state.indexOf("/*file*/", cp)) > -1);
-    }
-    if (cp > 0)
-    {
-      // just append rest of state
-      newFileLoc.append(state.substring(cp));
-    }
-    else
-    {
-      System.err.print("Ignoring incomplete Jmol state for PDB ids: ");
-      newFileLoc = new StringBuilder(state);
-      newFileLoc.append("; load append ");
-      for (File id : oldFiles.keySet())
-      {
-        // add this and any other pdb files that should be present in
-        // the viewer
-        StructureData filedat = oldFiles.get(id);
-        newFileLoc.append(filedat.getFilePath());
-        pdbfilenames.add(filedat.getFilePath());
-        pdbids.add(filedat.getPdbId());
-        seqmaps.add(filedat.getSeqList().toArray(new SequenceI[0]));
-        newFileLoc.append(" \"");
-        newFileLoc.append(filedat.getFilePath());
-        newFileLoc.append("\"");
-
-      }
-      newFileLoc.append(";");
-    }
-
-    if (newFileLoc.length() == 0)
-    {
-      return;
-    }
-    int histbug = newFileLoc.indexOf("history = ");
-    if (histbug > -1)
-    {
-      /*
-       * change "history = [true|false];" to "history = [1|0];"
-       */
-      histbug += 10;
-      int diff = histbug == -1 ? -1 : newFileLoc.indexOf(";", histbug);
-      String val = (diff == -1) ? null
-              : newFileLoc.substring(histbug, diff);
-      if (val != null && val.length() >= 4)
-      {
-        if (val.contains("e")) // eh? what can it be?
-        {
-          if (val.trim().equals("true"))
-          {
-            val = "1";
-          }
-          else
-          {
-            val = "0";
-          }
-          newFileLoc.replace(histbug, diff, val);
-        }
-      }
-    }
-
-    final String[] pdbf = pdbfilenames
-            .toArray(new String[pdbfilenames.size()]);
-    final String[] id = pdbids.toArray(new String[pdbids.size()]);
-    final SequenceI[][] sq = seqmaps
-            .toArray(new SequenceI[seqmaps.size()][]);
-    final String fileloc = newFileLoc.toString();
-    final String sviewid = viewerData.getKey();
-    final AlignFrame alf = af;
-    final Rectangle rect = new Rectangle(svattrib.getX(), svattrib.getY(),
-            svattrib.getWidth(), svattrib.getHeight());
-    try
-    {
-      javax.swing.SwingUtilities.invokeAndWait(new Runnable()
-      {
-        @Override
-        public void run()
-        {
-          JalviewStructureDisplayI sview = null;
-          try
-          {
-            sview = new StructureViewer(
-                    alf.alignPanel.getStructureSelectionManager())
-                            .createView(StructureViewer.ViewerType.JMOL,
-                                    pdbf, id, sq, alf.alignPanel, svattrib,
-                                    fileloc, rect, sviewid);
-            addNewStructureViewer(sview);
-          } catch (OutOfMemoryError ex)
-          {
-            new OOMWarning("restoring structure view for PDB id " + id,
-                    (OutOfMemoryError) ex.getCause());
-            if (sview != null && sview.isVisible())
-            {
-              sview.closeViewer(false);
-              sview.setVisible(false);
-              sview.dispose();
-            }
-          }
-        }
-      });
-    } catch (InvocationTargetException ex)
-    {
-      warn("Unexpected error when opening Jmol view.", ex);
-
-    } catch (InterruptedException e)
-    {
-      // e.printStackTrace();
-    }
-
-  }
-
-  /**
-   * Generates a name for the entry in the project jar file to hold state
-   * information for a structure viewer
-   * 
-   * @param viewId
-   * @return
-   */
-  protected String getViewerJarEntryName(String viewId)
-  {
-    return VIEWER_PREFIX + viewId;
-  }
-
-  /**
-   * Returns any open frame that matches given structure viewer data. The match
-   * is based on the unique viewId, or (for older project versions) the frame's
-   * geometry.
-   * 
-   * @param viewerData
-   * @return
-   */
-  protected StructureViewerBase findMatchingViewer(
-          Entry<String, StructureViewerModel> viewerData)
-  {
-    final String sviewid = viewerData.getKey();
-    final StructureViewerModel svattrib = viewerData.getValue();
-    StructureViewerBase comp = null;
-    JInternalFrame[] frames = getAllFrames();
-    for (JInternalFrame frame : frames)
-    {
-      if (frame instanceof StructureViewerBase)
-      {
-        /*
-         * Post jalview 2.4 schema includes structure view id
-         */
-        if (sviewid != null && ((StructureViewerBase) frame).getViewId()
-                .equals(sviewid))
-        {
-          comp = (StructureViewerBase) frame;
-          break; // break added in 2.9
-        }
-        /*
-         * Otherwise test for matching position and size of viewer frame
-         */
-        else if (frame.getX() == svattrib.getX()
-                && frame.getY() == svattrib.getY()
-                && frame.getHeight() == svattrib.getHeight()
-                && frame.getWidth() == svattrib.getWidth())
-        {
-          comp = (StructureViewerBase) frame;
-          // no break in faint hope of an exact match on viewId
-        }
-      }
+        /*
+         * Otherwise test for matching position and size of viewer frame
+         */
+        else if (frame.getX() == svattrib.getX()
+                && frame.getY() == svattrib.getY()
+                && frame.getHeight() == svattrib.getHeight()
+                && frame.getWidth() == svattrib.getWidth())
+        {
+          comp = (StructureViewerBase) frame;
+          // no break in faint hope of an exact match on viewId
+        }
+      }
     }
     return comp;
   }
@@ -4547,7 +4931,7 @@ public class Jalview2XML
    *          - minimum version we are comparing against
    * @param version
    *          - version of data being processsed
-   * @return
+   * @return true if version is equal to or later than supported
    */
   public static boolean isVersionStringLaterThan(String supported,
           String version)
@@ -4557,7 +4941,7 @@ public class Jalview2XML
             || version.equalsIgnoreCase("Test")
             || version.equalsIgnoreCase("AUTOMATED BUILD"))
     {
-      System.err.println("Assuming project file with "
+      jalview.bin.Console.errPrintln("Assuming project file with "
               + (version == null ? "null" : version)
               + " is compatible with Jalview version " + supported);
       return true;
@@ -4593,13 +4977,24 @@ public class Jalview2XML
   }
 
   AlignFrame loadViewport(String file, List<JSeq> JSEQ,
-          List<SequenceI> hiddenSeqs, AlignmentI al,
-          JalviewModel jm, Viewport view, String uniqueSeqSetId,
-          String viewId, List<JvAnnotRow> autoAlan)
+          List<SequenceI> hiddenSeqs, AlignmentI al, JalviewModel jm,
+          Viewport view, String uniqueSeqSetId, String viewId,
+          List<JvAnnotRow> autoAlan)
   {
     AlignFrame af = null;
     af = new AlignFrame(al, safeInt(view.getWidth()),
-            safeInt(view.getHeight()), uniqueSeqSetId, viewId);
+            safeInt(view.getHeight()), uniqueSeqSetId, viewId)
+    // {
+    //
+    // @Override
+    // protected void processKeyEvent(java.awt.event.KeyEvent e) {
+    // jalview.bin.Console.outPrintln("Jalview2XML AF " + e);
+    // super.processKeyEvent(e);
+    //
+    // }
+    //
+    // }
+    ;
 
     af.setFileName(file, FileFormat.Jalview);
 
@@ -4676,15 +5071,20 @@ public class Jalview2XML
 
     viewport.setColourText(safeBoolean(view.isShowColourText()));
 
-    viewport
-            .setConservationSelected(
-                    safeBoolean(view.isConservationSelected()));
+    viewport.setConservationSelected(
+            safeBoolean(view.isConservationSelected()));
     viewport.setIncrement(safeInt(view.getConsThreshold()));
     viewport.setShowJVSuffix(safeBoolean(view.isShowFullId()));
     viewport.setRightAlignIds(safeBoolean(view.isRightAlignIds()));
-    viewport.setFont(new Font(view.getFontName(),
-            safeInt(view.getFontStyle()), safeInt(view.getFontSize())),
-            true);
+    viewport.setFont(
+            new Font(view.getFontName(), safeInt(view.getFontStyle()),
+                    safeInt(view.getFontSize())),
+            (view.getCharWidth() != null) ? false : true);
+    if (view.getCharWidth() != null)
+    {
+      viewport.setCharWidth(view.getCharWidth());
+      viewport.setCharHeight(view.getCharHeight());
+    }
     ViewStyleI vs = viewport.getViewStyle();
     vs.setScaleProteinAsCdna(view.isScaleProteinAsCdna());
     viewport.setViewStyle(vs);
@@ -4731,30 +5131,31 @@ public class Jalview2XML
       }
       else
       {
-        cs = ColourSchemeProperty.getColourScheme(al, view.getBgColour());
+        cs = ColourSchemeProperty.getColourScheme(af.getViewport(), al,
+                view.getBgColour());
       }
     }
 
+    /*
+     * turn off 'alignment colour applies to all groups'
+     * while restoring global colour scheme
+     */
+    viewport.setColourAppliesToAllGroups(false);
     viewport.setGlobalColourScheme(cs);
     viewport.getResidueShading().setThreshold(pidThreshold,
             view.isIgnoreGapsinConsensus());
     viewport.getResidueShading()
             .setConsensus(viewport.getSequenceConsensusHash());
-    viewport.setColourAppliesToAllGroups(false);
-
     if (safeBoolean(view.isConservationSelected()) && cs != null)
     {
       viewport.getResidueShading()
               .setConservationInc(safeInt(view.getConsThreshold()));
     }
-
     af.changeColour(cs);
-
     viewport.setColourAppliesToAllGroups(true);
 
-    viewport
-            .setShowSequenceFeatures(
-                    safeBoolean(view.isShowSequenceFeatures()));
+    viewport.setShowSequenceFeatures(
+            safeBoolean(view.isShowSequenceFeatures()));
 
     viewport.setCentreColumnLabels(view.isCentreColumnLabels());
     viewport.setIgnoreGapsConsensus(view.isIgnoreGapsinConsensus(), null);
@@ -4767,21 +5168,24 @@ public class Jalview2XML
     viewport.setShowNPFeats(safeBoolean(view.isShowNPfeatureTooltip()));
     viewport.setShowGroupConsensus(view.isShowGroupConsensus());
     viewport.setShowGroupConservation(view.isShowGroupConservation());
+    viewport.setShowComplementFeatures(view.isShowComplementFeatures());
+    viewport.setShowComplementFeaturesOnTop(
+            view.isShowComplementFeaturesOnTop());
 
     // recover feature settings
     if (jm.getFeatureSettings() != null)
     {
-      FeatureRenderer fr = af.alignPanel.getSeqPanel().seqCanvas
+      FeatureRendererModel fr = af.alignPanel.getSeqPanel().seqCanvas
               .getFeatureRenderer();
       FeaturesDisplayed fdi;
       viewport.setFeaturesDisplayed(fdi = new FeaturesDisplayed());
-      String[] renderOrder = new String[jm.getFeatureSettings()
-              .getSetting().size()];
+      String[] renderOrder = new String[jm.getFeatureSettings().getSetting()
+              .size()];
       Map<String, FeatureColourI> featureColours = new Hashtable<>();
       Map<String, Float> featureOrder = new Hashtable<>();
 
-      for (int fs = 0; fs < jm.getFeatureSettings()
-              .getSetting().size(); fs++)
+      for (int fs = 0; fs < jm.getFeatureSettings().getSetting()
+              .size(); fs++)
       {
         Setting setting = jm.getFeatureSettings().getSetting().get(fs);
         String featureType = setting.getType();
@@ -4793,8 +5197,8 @@ public class Jalview2XML
                 .getMatcherSet();
         if (filters != null)
         {
-          FeatureMatcherSetI filter = Jalview2XML
-                  .parseFilter(featureType, filters);
+          FeatureMatcherSetI filter = Jalview2XML.parseFilter(featureType,
+                  filters);
           if (!filter.isEmpty())
           {
             fr.setFeatureFilter(featureType, filter);
@@ -4825,8 +5229,8 @@ public class Jalview2XML
           float min = safeFloat(safeFloat(setting.getMin()));
           float max = setting.getMax() == null ? 1f
                   : setting.getMax().floatValue();
-          FeatureColourI gc = new FeatureColour(minColour, maxColour,
-                  noValueColour, min, max);
+          FeatureColourI gc = new FeatureColour(maxColour, minColour,
+                  maxColour, noValueColour, min, max);
           if (setting.getAttributeName().size() > 0)
           {
             gc.setAttributeName(setting.getAttributeName().toArray(
@@ -4860,8 +5264,7 @@ public class Jalview2XML
         }
         else
         {
-          featureColours.put(featureType,
-                  new FeatureColour(maxColour));
+          featureColours.put(featureType, new FeatureColour(maxColour));
         }
         renderOrder[fs] = featureType;
         if (setting.getOrder() != null)
@@ -4870,7 +5273,7 @@ public class Jalview2XML
         }
         else
         {
-          featureOrder.put(featureType, new Float(
+          featureOrder.put(featureType, Float.valueOf(
                   fs / jm.getFeatureSettings().getSetting().size()));
         }
         if (safeBoolean(setting.isDisplay()))
@@ -4882,7 +5285,7 @@ public class Jalview2XML
       for (int gs = 0; gs < jm.getFeatureSettings().getGroup().size(); gs++)
       {
         Group grp = jm.getFeatureSettings().getGroup().get(gs);
-        fgtable.put(grp.getName(), new Boolean(grp.isDisplay()));
+        fgtable.put(grp.getName(), Boolean.valueOf(grp.isDisplay()));
       }
       // FeatureRendererSettings frs = new FeatureRendererSettings(renderOrder,
       // fgtable, featureColours, jms.getFeatureSettings().hasTransparency() ?
@@ -4912,7 +5315,7 @@ public class Jalview2XML
           }
           else
           {
-            warn("Couldn't recover parameters for "
+            Console.warn("Couldn't recover parameters for "
                     + calcIdParam.getCalcId());
           }
         }
@@ -4940,6 +5343,7 @@ public class Jalview2XML
     {
       splitFrameCandidates.put(view, af);
     }
+
     return af;
   }
 
@@ -4999,11 +5403,15 @@ public class Jalview2XML
     }
     if (matchedAnnotation == null)
     {
-      System.err.println("Failed to match annotation colour scheme for "
-              + annotationId);
+      jalview.bin.Console
+              .errPrintln("Failed to match annotation colour scheme for "
+                      + annotationId);
       return null;
     }
-    if (matchedAnnotation.getThreshold() == null)
+    // belt-and-braces create a threshold line if the
+    // colourscheme needs one but the matchedAnnotation doesn't have one
+    if (safeInt(viewAnnColour.getAboveThreshold()) != 0
+            && matchedAnnotation.getThreshold() == null)
     {
       matchedAnnotation.setThreshold(
               new GraphLine(safeFloat(viewAnnColour.getThreshold()),
@@ -5027,7 +5435,7 @@ public class Jalview2XML
     else
     {
       cs = new AnnotationColourGradient(matchedAnnotation,
-              ColourSchemeProperty.getColourScheme(al,
+              ColourSchemeProperty.getColourScheme(af.getViewport(), al,
                       viewAnnColour.getColourScheme()),
               safeInt(viewAnnColour.getAboveThreshold()));
     }
@@ -5188,10 +5596,7 @@ public class Jalview2XML
     String id = object.getViewport().get(0).getSequenceSetId();
     if (skipList.containsKey(id))
     {
-      if (Cache.log != null && Cache.log.isDebugEnabled())
-      {
-        Cache.log.debug("Skipping seuqence set id " + id);
-      }
+      Console.debug("Skipping seuqence set id " + id);
       return true;
     }
     return false;
@@ -5220,23 +5625,51 @@ public class Jalview2XML
   {
     jalview.datamodel.AlignmentI ds = getDatasetFor(
             vamsasSet.getDatasetId());
-    Vector dseqs = null;
-    if (ds == null)
+    AlignmentI xtant_ds = ds;
+    if (xtant_ds == null)
+    {
+      // good chance we are about to create a new dataset, but check if we've
+      // seen some of the dataset sequence IDs before.
+      // TODO: skip this check if we are working with project generated by
+      // version 2.11 or later
+      xtant_ds = checkIfHasDataset(vamsasSet.getSequence());
+      if (xtant_ds != null)
+      {
+        ds = xtant_ds;
+        addDatasetRef(vamsasSet.getDatasetId(), ds);
+      }
+    }
+    Vector<SequenceI> dseqs = null;
+    if (!ignoreUnrefed)
     {
-      if (!ignoreUnrefed)
+      // recovering an alignment View
+      AlignmentI seqSetDS = getDatasetFor(UNIQSEQSETID + uniqueSeqSetId);
+      if (seqSetDS != null)
       {
-        // try to resolve the dataset via uniqueSeqSetId
-        ds = getDatasetFor(UNIQSEQSETID + uniqueSeqSetId);
-        if (ds != null)
+        if (ds != null && ds != seqSetDS)
         {
-          addDatasetRef(vamsasSet.getDatasetId(), ds);
+          Console.warn(
+                  "JAL-3171 regression: Overwriting a dataset reference for an alignment"
+                          + " - CDS/Protein crossreference data may be lost");
+          if (xtant_ds != null)
+          {
+            // This can only happen if the unique sequence set ID was bound to a
+            // dataset that did not contain any of the sequences in the view
+            // currently being restored.
+            Console.warn(
+                    "JAL-3171 SERIOUS!  TOTAL CONFUSION - please consider contacting the Jalview Development team so they can investigate why your project caused this message to be displayed.");
+          }
         }
+        ds = seqSetDS;
+        addDatasetRef(vamsasSet.getDatasetId(), ds);
       }
     }
     if (ds == null)
     {
+      // try even harder to restore dataset
+      AlignmentI xtantDS = checkIfHasDataset(vamsasSet.getSequence());
       // create a list of new dataset sequences
-      dseqs = new Vector();
+      dseqs = new Vector<>();
     }
     for (int i = 0, iSize = vamsasSet.getSequence().size(); i < iSize; i++)
     {
@@ -5249,7 +5682,7 @@ public class Jalview2XML
       SequenceI[] dsseqs = new SequenceI[dseqs.size()];
       dseqs.copyInto(dsseqs);
       ds = new jalview.datamodel.Alignment(dsseqs);
-      debug("Created new dataset " + vamsasSet.getDatasetId()
+      Console.debug("Created new dataset " + vamsasSet.getDatasetId()
               + " for alignment " + System.identityHashCode(al));
       addDatasetRef(vamsasSet.getDatasetId(), ds);
     }
@@ -5260,6 +5693,53 @@ public class Jalview2XML
       // register dataset for the alignment's uniqueSeqSetId for legacy projects
       addDatasetRef(UNIQSEQSETID + uniqueSeqSetId, ds);
     }
+    updateSeqDatasetBinding(vamsasSet.getSequence(), ds);
+  }
+
+  /**
+   * XML dataset sequence ID to materialised dataset reference
+   */
+  HashMap<String, AlignmentI> seqToDataset = new HashMap<>();
+
+  /**
+   * @return the first materialised dataset reference containing a dataset
+   *         sequence referenced in the given view
+   * @param list
+   *          - sequences from the view
+   */
+  AlignmentI checkIfHasDataset(List<Sequence> list)
+  {
+    for (Sequence restoredSeq : list)
+    {
+      AlignmentI datasetFor = seqToDataset.get(restoredSeq.getDsseqid());
+      if (datasetFor != null)
+      {
+        return datasetFor;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Register ds as the containing dataset for the dataset sequences referenced
+   * by sequences in list
+   * 
+   * @param list
+   *          - sequences in a view
+   * @param ds
+   */
+  void updateSeqDatasetBinding(List<Sequence> list, AlignmentI ds)
+  {
+    for (Sequence restoredSeq : list)
+    {
+      AlignmentI prevDS = seqToDataset.put(restoredSeq.getDsseqid(), ds);
+      if (prevDS != null && prevDS != ds)
+      {
+        Console.warn("Dataset sequence appears in many datasets: "
+                + restoredSeq.getDsseqid());
+        // TODO: try to merge!
+      }
+    }
   }
 
   /**
@@ -5278,7 +5758,8 @@ public class Jalview2XML
    *          vamsasSeq array ordering, to preserve ordering of dataset
    */
   private void ensureJalviewDatasetSequence(Sequence vamsasSeq,
-          AlignmentI ds, Vector dseqs, boolean ignoreUnrefed, int vseqpos)
+          AlignmentI ds, Vector<SequenceI> dseqs, boolean ignoreUnrefed,
+          int vseqpos)
   {
     // JBP TODO: Check this is called for AlCodonFrames to support recovery of
     // xRef Codon Maps
@@ -5382,7 +5863,7 @@ public class Jalview2XML
         }
         // TODO: merges will never happen if we 'know' we have the real dataset
         // sequence - this should be detected when id==dssid
-        System.err.println(
+        jalview.bin.Console.errPrintln(
                 "DEBUG Notice:  Merged dataset sequence (if you see this often, post at http://issues.jalview.org/browse/JAL-1474)"); // ("
         // + (pre ? "prepended" : "") + " "
         // + (post ? "appended" : ""));
@@ -5460,7 +5941,8 @@ public class Jalview2XML
   {
     if (dataset.getDataset() != null)
     {
-      warn("Serious issue!  Dataset Object passed to getDatasetIdRef is not a Jalview DATASET alignment...");
+      Console.warn(
+              "Serious issue!  Dataset Object passed to getDatasetIdRef is not a Jalview DATASET alignment...");
     }
     String datasetId = makeHashCode(dataset, null);
     if (datasetId == null)
@@ -5483,17 +5965,34 @@ public class Jalview2XML
     return datasetId;
   }
 
+  /**
+   * Add any saved DBRefEntry's to the sequence. An entry flagged as 'locus' is
+   * constructed as a special subclass GeneLocus.
+   * 
+   * @param datasetSequence
+   * @param sequence
+   */
   private void addDBRefs(SequenceI datasetSequence, Sequence sequence)
   {
     for (int d = 0; d < sequence.getDBRef().size(); d++)
     {
       DBRef dr = sequence.getDBRef().get(d);
-      jalview.datamodel.DBRefEntry entry = new jalview.datamodel.DBRefEntry(
-              dr.getSource(), dr.getVersion(), dr.getAccessionId());
+      DBRefEntry entry;
+      if (dr.isLocus())
+      {
+        entry = new GeneLocus(dr.getSource(), dr.getVersion(),
+                dr.getAccessionId());
+      }
+      else
+      {
+        entry = new DBRefEntry(dr.getSource(), dr.getVersion(),
+                dr.getAccessionId());
+      }
       if (dr.getMapping() != null)
       {
         entry.setMap(addMapping(dr.getMapping()));
       }
+      entry.setCanonical(dr.isCanonical());
       datasetSequence.addDBRef(entry);
     }
   }
@@ -5521,15 +6020,16 @@ public class Jalview2XML
     jalview.datamodel.Mapping jmap = new jalview.datamodel.Mapping(dsto, fr,
             fto, m.getMapFromUnit().intValue(),
             m.getMapToUnit().intValue());
-    // if (m.getMappingChoice() != null)
-    // {
-    // MappingChoice mc = m.getMappingChoice();
+
+    /*
+     * (optional) choice of dseqFor or Sequence
+     */
     if (m.getDseqFor() != null)
     {
       String dsfor = m.getDseqFor();
       if (seqRefIds.containsKey(dsfor))
       {
-        /**
+        /*
          * recover from hash
          */
         jmap.setTo(seqRefIds.get(dsfor));
@@ -5539,9 +6039,9 @@ public class Jalview2XML
         frefedSequence.add(newMappingRef(dsfor, jmap));
       }
     }
-    else
+    else if (m.getSequence() != null)
     {
-      /**
+      /*
        * local sequence definition
        */
       Sequence ms = m.getSequence();
@@ -5556,7 +6056,7 @@ public class Jalview2XML
       }
       else
       {
-        System.err.println(
+        jalview.bin.Console.errPrintln(
                 "Warning - making up dataset sequence id for DbRef sequence map reference");
         sqid = ((Object) ms).toString(); // make up a new hascode for
         // undefined dataset sequence hash
@@ -5578,7 +6078,7 @@ public class Jalview2XML
         seqRefIds.put(sqid, djs);
 
       }
-      jalview.bin.Cache.log.debug("about to recurse on addDBRefs.");
+      Console.debug("about to recurse on addDBRefs.");
       addDBRefs(djs, ms);
 
     }
@@ -5631,62 +6131,6 @@ public class Jalview2XML
 
   private Hashtable jvids2vobj;
 
-  private void warn(String msg)
-  {
-    warn(msg, null);
-  }
-
-  private void warn(String msg, Exception e)
-  {
-    if (Cache.log != null)
-    {
-      if (e != null)
-      {
-        Cache.log.warn(msg, e);
-      }
-      else
-      {
-        Cache.log.warn(msg);
-      }
-    }
-    else
-    {
-      System.err.println("Warning: " + msg);
-      if (e != null)
-      {
-        e.printStackTrace();
-      }
-    }
-  }
-
-  private void debug(String string)
-  {
-    debug(string, null);
-  }
-
-  private void debug(String msg, Exception e)
-  {
-    if (Cache.log != null)
-    {
-      if (e != null)
-      {
-        Cache.log.debug(msg, e);
-      }
-      else
-      {
-        Cache.log.debug(msg);
-      }
-    }
-    else
-    {
-      System.err.println("Warning: " + msg);
-      if (e != null)
-      {
-        e.printStackTrace();
-      }
-    }
-  }
-
   /**
    * set the object to ID mapping tables used to write/recover objects and XML
    * ID strings for the jalview project. If external tables are provided then
@@ -5745,7 +6189,7 @@ public class Jalview2XML
         if (!jvann.annotationId.equals(anid))
         {
           // TODO verify that this is the correct behaviour
-          this.warn("Overriding Annotation ID for " + anid
+          Console.warn("Overriding Annotation ID for " + anid
                   + " from different id : " + jvann.annotationId);
           jvann.annotationId = anid;
         }
@@ -5760,7 +6204,7 @@ public class Jalview2XML
       }
       else
       {
-        Cache.log.debug("Ignoring " + jvobj.getClass() + " (ID = " + id);
+        Console.debug("Ignoring " + jvobj.getClass() + " (ID = " + id);
       }
     }
   }
@@ -5830,7 +6274,8 @@ public class Jalview2XML
       }
       else
       {
-        warn("Couldn't find entry in Jalview Jar for " + jarEntryName);
+        Console.warn(
+                "Couldn't find entry in Jalview Jar for " + jarEntryName);
       }
     } catch (Exception ex)
     {
@@ -5863,14 +6308,304 @@ public class Jalview2XML
   }
 
   /**
+   * Loads any saved PCA viewers
+   * 
+   * @param jms
+   * @param ap
+   */
+  protected void loadPCAViewers(JalviewModel model, AlignmentPanel ap)
+  {
+    try
+    {
+      List<PcaViewer> pcaviewers = model.getPcaViewer();
+      for (PcaViewer viewer : pcaviewers)
+      {
+        String modelName = viewer.getScoreModelName();
+        SimilarityParamsI params = new SimilarityParams(
+                viewer.isIncludeGappedColumns(), viewer.isMatchGaps(),
+                viewer.isIncludeGaps(),
+                viewer.isDenominateByShortestLength());
+
+        /*
+         * create the panel (without computing the PCA)
+         */
+        PCAPanel panel = new PCAPanel(ap, modelName, params);
+
+        panel.setTitle(viewer.getTitle());
+        panel.setBounds(new Rectangle(viewer.getXpos(), viewer.getYpos(),
+                viewer.getWidth(), viewer.getHeight()));
+
+        boolean showLabels = viewer.isShowLabels();
+        panel.setShowLabels(showLabels);
+        panel.getRotatableCanvas().setShowLabels(showLabels);
+        panel.getRotatableCanvas()
+                .setBgColour(new Color(viewer.getBgColour()));
+        panel.getRotatableCanvas()
+                .setApplyToAllViews(viewer.isLinkToAllViews());
+
+        /*
+         * load PCA output data
+         */
+        ScoreModelI scoreModel = ScoreModels.getInstance()
+                .getScoreModel(modelName, ap);
+        PCA pca = new PCA(null, scoreModel, params);
+        PcaDataType pcaData = viewer.getPcaData();
+
+        MatrixI pairwise = loadDoubleMatrix(pcaData.getPairwiseMatrix());
+        pca.setPairwiseScores(pairwise);
+
+        MatrixI triDiag = loadDoubleMatrix(pcaData.getTridiagonalMatrix());
+        pca.setTridiagonal(triDiag);
+
+        MatrixI result = loadDoubleMatrix(pcaData.getEigenMatrix());
+        pca.setEigenmatrix(result);
+
+        panel.getPcaModel().setPCA(pca);
+
+        /*
+         * we haven't saved the input data! (JAL-2647 to do)
+         */
+        panel.setInputData(null);
+
+        /*
+         * add the sequence points for the PCA display
+         */
+        List<jalview.datamodel.SequencePoint> seqPoints = new ArrayList<>();
+        for (SequencePoint sp : viewer.getSequencePoint())
+        {
+          String seqId = sp.getSequenceRef();
+          SequenceI seq = seqRefIds.get(seqId);
+          if (seq == null)
+          {
+            throw new IllegalStateException(
+                    "Unmatched seqref for PCA: " + seqId);
+          }
+          Point pt = new Point(sp.getXPos(), sp.getYPos(), sp.getZPos());
+          jalview.datamodel.SequencePoint seqPoint = new jalview.datamodel.SequencePoint(
+                  seq, pt);
+          seqPoints.add(seqPoint);
+        }
+        panel.getRotatableCanvas().setPoints(seqPoints, seqPoints.size());
+
+        /*
+         * set min-max ranges and scale after setPoints (which recomputes them)
+         */
+        panel.getRotatableCanvas().setScaleFactor(viewer.getScaleFactor());
+        SeqPointMin spMin = viewer.getSeqPointMin();
+        float[] min = new float[] { spMin.getXPos(), spMin.getYPos(),
+            spMin.getZPos() };
+        SeqPointMax spMax = viewer.getSeqPointMax();
+        float[] max = new float[] { spMax.getXPos(), spMax.getYPos(),
+            spMax.getZPos() };
+        panel.getRotatableCanvas().setSeqMinMax(min, max);
+
+        // todo: hold points list in PCAModel only
+        panel.getPcaModel().setSequencePoints(seqPoints);
+
+        panel.setSelectedDimensionIndex(viewer.getXDim(), X);
+        panel.setSelectedDimensionIndex(viewer.getYDim(), Y);
+        panel.setSelectedDimensionIndex(viewer.getZDim(), Z);
+
+        // is this duplication needed?
+        panel.setTop(seqPoints.size() - 1);
+        panel.getPcaModel().setTop(seqPoints.size() - 1);
+
+        /*
+         * add the axes' end points for the display
+         */
+        for (int i = 0; i < 3; i++)
+        {
+          Axis axis = viewer.getAxis().get(i);
+          panel.getRotatableCanvas().getAxisEndPoints()[i] = new Point(
+                  axis.getXPos(), axis.getYPos(), axis.getZPos());
+        }
+
+        Desktop.addInternalFrame(panel, MessageManager.formatMessage(
+                "label.calc_title", "PCA", modelName), 475, 450);
+      }
+    } catch (Exception ex)
+    {
+      Console.error("Error loading PCA: " + ex.toString());
+    }
+  }
+
+  /**
+   * Creates a new structure viewer window
+   * 
+   * @param viewerType
+   * @param viewerData
+   * @param af
+   * @param jprovider
+   */
+  protected void createStructureViewer(ViewerType viewerType,
+          final Entry<String, StructureViewerModel> viewerData,
+          AlignFrame af, jarInputStreamProvider jprovider)
+  {
+    final StructureViewerModel viewerModel = viewerData.getValue();
+    String sessionFilePath = null;
+
+    if (viewerType == ViewerType.JMOL)
+    {
+      sessionFilePath = rewriteJmolSession(viewerModel, jprovider);
+    }
+    else
+    {
+      String viewerJarEntryName = getViewerJarEntryName(
+              viewerModel.getViewId());
+      sessionFilePath = copyJarEntry(jprovider, viewerJarEntryName,
+              "viewerSession", ".tmp");
+    }
+    final String sessionPath = sessionFilePath;
+    final String sviewid = viewerData.getKey();
+    try
+    {
+      SwingUtilities.invokeAndWait(new Runnable()
+      {
+        @Override
+        public void run()
+        {
+          JalviewStructureDisplayI sview = null;
+          try
+          {
+            sview = StructureViewer.createView(viewerType, af.alignPanel,
+                    viewerModel, sessionPath, sviewid);
+            addNewStructureViewer(sview);
+          } catch (OutOfMemoryError ex)
+          {
+            new OOMWarning("Restoring structure view for " + viewerType,
+                    (OutOfMemoryError) ex.getCause());
+            if (sview != null && sview.isVisible())
+            {
+              sview.closeViewer(false);
+              sview.setVisible(false);
+              sview.dispose();
+            }
+          }
+        }
+      });
+    } catch (InvocationTargetException | InterruptedException ex)
+    {
+      Console.warn("Unexpected error when opening " + viewerType
+              + " structure viewer", ex);
+    }
+  }
+
+  /**
+   * Rewrites a Jmol session script, saves it to a temporary file, and returns
+   * the path of the file. "load file" commands are rewritten to change the
+   * original PDB file names to those created as the Jalview project is loaded.
+   * 
+   * @param svattrib
+   * @param jprovider
+   * @return
+   */
+  private String rewriteJmolSession(StructureViewerModel svattrib,
+          jarInputStreamProvider jprovider)
+  {
+    String state = svattrib.getStateData(); // Jalview < 2.9
+    if (state == null || state.isEmpty()) // Jalview >= 2.9
+    {
+      String jarEntryName = getViewerJarEntryName(svattrib.getViewId());
+      state = readJarEntry(jprovider, jarEntryName);
+    }
+    // TODO or simpler? for each key in oldFiles,
+    // replace key.getPath() in state with oldFiles.get(key).getFilePath()
+    // (allowing for different path escapings)
+    StringBuilder rewritten = new StringBuilder(state.length());
+    int cp = 0, ncp, ecp;
+    Map<File, StructureData> oldFiles = svattrib.getFileData();
+    while ((ncp = state.indexOf("load ", cp)) > -1)
+    {
+      do
+      {
+        // look for next filename in load statement
+        rewritten.append(state.substring(cp,
+                ncp = (state.indexOf("\"", ncp + 1) + 1)));
+        String oldfilenam = state.substring(ncp,
+                ecp = state.indexOf("\"", ncp));
+        // recover the new mapping data for this old filename
+        // have to normalize filename - since Jmol and jalview do
+        // filename translation differently.
+        StructureData filedat = oldFiles.get(new File(oldfilenam));
+        if (filedat == null)
+        {
+          String reformatedOldFilename = oldfilenam.replaceAll("/", "\\\\");
+          filedat = oldFiles.get(new File(reformatedOldFilename));
+        }
+        rewritten.append(Platform.escapeBackslashes(filedat.getFilePath()));
+        rewritten.append("\"");
+        cp = ecp + 1; // advance beyond last \" and set cursor so we can
+                      // look for next file statement.
+      } while ((ncp = state.indexOf("/*file*/", cp)) > -1);
+    }
+    if (cp > 0)
+    {
+      // just append rest of state
+      rewritten.append(state.substring(cp));
+    }
+    else
+    {
+      System.err.print("Ignoring incomplete Jmol state for PDB ids: ");
+      rewritten = new StringBuilder(state);
+      rewritten.append("; load append ");
+      for (File id : oldFiles.keySet())
+      {
+        // add pdb files that should be present in the viewer
+        StructureData filedat = oldFiles.get(id);
+        rewritten.append(" \"").append(filedat.getFilePath()).append("\"");
+      }
+      rewritten.append(";");
+    }
+
+    if (rewritten.length() == 0)
+    {
+      return null;
+    }
+    final String history = "history = ";
+    int historyIndex = rewritten.indexOf(history);
+    if (historyIndex > -1)
+    {
+      /*
+       * change "history = [true|false];" to "history = [1|0];"
+       */
+      historyIndex += history.length();
+      String val = rewritten.substring(historyIndex, historyIndex + 5);
+      if (val.startsWith("true"))
+      {
+        rewritten.replace(historyIndex, historyIndex + 4, "1");
+      }
+      else if (val.startsWith("false"))
+      {
+        rewritten.replace(historyIndex, historyIndex + 5, "0");
+      }
+    }
+
+    try
+    {
+      File tmp = File.createTempFile("viewerSession", ".tmp");
+      try (OutputStream os = new FileOutputStream(tmp))
+      {
+        InputStream is = new ByteArrayInputStream(
+                rewritten.toString().getBytes());
+        copyAll(is, os);
+        return tmp.getAbsolutePath();
+      }
+    } catch (IOException e)
+    {
+      Console.error("Error restoring Jmol session: " + e.toString());
+    }
+    return null;
+  }
+
+  /**
    * Populates an XML model of the feature colour scheme for one feature type
    * 
    * @param featureType
    * @param fcol
    * @return
    */
-  public static Colour marshalColour(
-          String featureType, FeatureColourI fcol)
+  public static Colour marshalColour(String featureType,
+          FeatureColourI fcol)
   {
     Colour col = new Colour();
     if (fcol.isSimpleColour())
@@ -5931,7 +6666,7 @@ public class Jalview2XML
           boolean and)
   {
     jalview.xml.binding.jalview.FeatureMatcherSet result = new jalview.xml.binding.jalview.FeatureMatcherSet();
-  
+
     if (filters.hasNext())
     {
       /*
@@ -5981,7 +6716,7 @@ public class Jalview2XML
       }
       result.setMatchCondition(matcherModel);
     }
-  
+
     return result;
   }
 
@@ -5992,8 +6727,7 @@ public class Jalview2XML
    * @param matcherSetModel
    * @return
    */
-  public static FeatureMatcherSetI parseFilter(
-          String featureType,
+  public static FeatureMatcherSetI parseFilter(String featureType,
           jalview.xml.binding.jalview.FeatureMatcherSet matcherSetModel)
   {
     FeatureMatcherSetI result = new FeatureMatcherSet();
@@ -6003,12 +6737,12 @@ public class Jalview2XML
     } catch (IllegalStateException e)
     {
       // mixing AND and OR conditions perhaps
-      System.err.println(
+      jalview.bin.Console.errPrintln(
               String.format("Error reading filter conditions for '%s': %s",
                       featureType, e.getMessage()));
       // return as much as was parsed up to the error
     }
-  
+
     return result;
   }
 
@@ -6023,8 +6757,7 @@ public class Jalview2XML
    * @throws IllegalStateException
    *           if AND and OR conditions are mixed
    */
-  protected static void parseFilterConditions(
-          FeatureMatcherSetI matcherSet,
+  protected static void parseFilterConditions(FeatureMatcherSetI matcherSet,
           jalview.xml.binding.jalview.FeatureMatcherSet matcherSetModel,
           boolean and)
   {
@@ -6046,7 +6779,7 @@ public class Jalview2XML
       else if (filterBy == FilterBy.BY_SCORE)
       {
         matchCondition = FeatureMatcher.byScore(cond, pattern);
-  
+
       }
       else if (filterBy == FilterBy.BY_ATTRIBUTE)
       {
@@ -6056,7 +6789,7 @@ public class Jalview2XML
         matchCondition = FeatureMatcher.byAttribute(cond, pattern,
                 attNames);
       }
-  
+
       /*
        * note this throws IllegalStateException if AND-ing to a 
        * previously OR-ed compound condition, or vice versa
@@ -6085,7 +6818,8 @@ public class Jalview2XML
       }
       else
       {
-        System.err.println("Malformed compound filter condition");
+        jalview.bin.Console
+                .errPrintln("Malformed compound filter condition");
       }
     }
   }
@@ -6099,22 +6833,22 @@ public class Jalview2XML
   public static FeatureColourI parseColour(Colour colourModel)
   {
     FeatureColourI colour = null;
-  
+
     if (colourModel.getMax() != null)
     {
       Color mincol = null;
       Color maxcol = null;
       Color noValueColour = null;
-  
+
       try
       {
         mincol = new Color(Integer.parseInt(colourModel.getMinRGB(), 16));
         maxcol = new Color(Integer.parseInt(colourModel.getRGB(), 16));
       } catch (Exception e)
       {
-        Cache.log.warn("Couldn't parse out graduated feature color.", e);
+        Console.warn("Couldn't parse out graduated feature color.", e);
       }
-  
+
       NoValueColour noCol = colourModel.getNoValueColour();
       if (noCol == NoValueColour.MIN)
       {
@@ -6124,8 +6858,8 @@ public class Jalview2XML
       {
         noValueColour = maxcol;
       }
-  
-      colour = new FeatureColour(mincol, maxcol, noValueColour,
+
+      colour = new FeatureColour(maxcol, mincol, maxcol, noValueColour,
               safeFloat(colourModel.getMin()),
               safeFloat(colourModel.getMax()));
       final List<String> attributeName = colourModel.getAttributeName();
@@ -6163,7 +6897,47 @@ public class Jalview2XML
       Color color = new Color(Integer.parseInt(colourModel.getRGB(), 16));
       colour = new FeatureColour(color);
     }
-  
+
     return colour;
   }
+
+  public static void setStateSavedUpToDate(boolean s)
+  {
+    Console.debug("Setting overall stateSavedUpToDate to " + s);
+    stateSavedUpToDate = s;
+  }
+
+  public static boolean stateSavedUpToDate()
+  {
+    Console.debug("Returning overall stateSavedUpToDate value: "
+            + stateSavedUpToDate);
+    return stateSavedUpToDate;
+  }
+
+  public static boolean allSavedUpToDate()
+  {
+    if (stateSavedUpToDate()) // nothing happened since last project save
+      return true;
+
+    AlignFrame[] frames = Desktop.getDesktopAlignFrames();
+    if (frames != null)
+    {
+      for (int i = 0; i < frames.length; i++)
+      {
+        if (frames[i] == null)
+          continue;
+        if (!frames[i].getViewport().savedUpToDate())
+          return false; // at least one alignment is not individually saved
+      }
+    }
+    return true;
+  }
+
+  // used for debugging and tests
+  private static int debugDelaySave = 20;
+
+  public static void setDebugDelaySave(int n)
+  {
+    debugDelaySave = n;
+  }
 }