+
+ /**
+ * Returns true if the viewer is an external structure viewer for which the
+ * process is still alive, else false (for Jmol, or an external viewer which
+ * the user has independently closed)
+ *
+ * @return
+ */
+ public boolean isViewerRunning()
+ {
+ return false;
+ }
+
+ /**
+ * Closes Jalview's structure viewer panel and releases associated resources.
+ * If it is managing an external viewer program, and {@code forceClose} is
+ * true, also asks that program to close.
+ *
+ * @param forceClose
+ */
+ public void closeViewer(boolean forceClose)
+ {
+ getSsm().removeStructureViewerListener(this, this.getStructureFiles());
+ releaseUIResources();
+
+ /*
+ * end the thread that closes this panel if the external viewer closes
+ */
+ if (externalViewerMonitor != null)
+ {
+ externalViewerMonitor.interrupt();
+ externalViewerMonitor = null;
+ }
+
+ stopListening();
+
+ if (forceClose)
+ {
+ StructureCommandI cmd = getCommandGenerator().closeViewer();
+ if (cmd != null)
+ {
+ executeCommand(cmd, false);
+ }
+ }
+ }
+
+ /**
+ * Returns the URL of a help page for the structure viewer, or null if none is
+ * known
+ *
+ * @return
+ */
+ public String getHelpURL()
+ {
+ return null;
+ }
+
+ /**
+ * <pre>
+ * Helper method to build a map of
+ * { featureType, { feature value, AtomSpecModel } }
+ * </pre>
+ *
+ * @param viewPanel
+ * @return
+ */
+ protected Map<String, Map<Object, AtomSpecModel>> buildFeaturesMap(
+ AlignmentViewPanel viewPanel)
+ {
+ Map<String, Map<Object, AtomSpecModel>> theMap = new LinkedHashMap<>();
+ String[] files = getStructureFiles();
+ if (files == null)
+ {
+ return theMap;
+ }
+
+ FeatureRenderer fr = viewPanel.getFeatureRenderer();
+ if (fr == null)
+ {
+ return theMap;
+ }
+
+ AlignViewportI viewport = viewPanel.getAlignViewport();
+ List<String> visibleFeatures = fr.getDisplayedFeatureTypes();
+
+ /*
+ * if alignment is showing features from complement, we also transfer
+ * these features to the corresponding mapped structure residues
+ */
+ boolean showLinkedFeatures = viewport.isShowComplementFeatures();
+ List<String> complementFeatures = new ArrayList<>();
+ FeatureRenderer complementRenderer = null;
+ if (showLinkedFeatures)
+ {
+ AlignViewportI comp = fr.getViewport().getCodingComplement();
+ if (comp != null)
+ {
+ complementRenderer = Desktop.getAlignFrameFor(comp)
+ .getFeatureRenderer();
+ complementFeatures = complementRenderer.getDisplayedFeatureTypes();
+ }
+ }
+ if (visibleFeatures.isEmpty() && complementFeatures.isEmpty())
+ {
+ return theMap;
+ }
+
+ AlignmentI alignment = viewPanel.getAlignment();
+ SequenceI[][] seqs = getSequence();
+
+ for (int pdbfnum = 0; pdbfnum < files.length; pdbfnum++)
+ {
+ String modelId = getModelIdForFile(files[pdbfnum]);
+ StructureMapping[] mapping = ssm.getMapping(files[pdbfnum]);
+
+ if (mapping == null || mapping.length < 1)
+ {
+ continue;
+ }
+
+ for (int seqNo = 0; seqNo < seqs[pdbfnum].length; seqNo++)
+ {
+ for (int m = 0; m < mapping.length; m++)
+ {
+ final SequenceI seq = seqs[pdbfnum][seqNo];
+ int sp = alignment.findIndex(seq);
+ StructureMapping structureMapping = mapping[m];
+ if (structureMapping.getSequence() == seq && sp > -1)
+ {
+ /*
+ * found a sequence with a mapping to a structure;
+ * now scan its features
+ */
+ if (!visibleFeatures.isEmpty())
+ {
+ scanSequenceFeatures(visibleFeatures, structureMapping, seq,
+ theMap, modelId);
+ }
+ if (showLinkedFeatures)
+ {
+ scanComplementFeatures(complementRenderer, structureMapping,
+ seq, theMap, modelId);
+ }
+ }
+ }
+ }
+ }
+ return theMap;
+ }
+
+ /**
+ * Ask the structure viewer to open a session file. Returns true if
+ * successful, else false (or not supported).
+ *
+ * @param filepath
+ * @return
+ */
+ public boolean openSession(String filepath)
+ {
+ StructureCommandI cmd = getCommandGenerator().openSession(filepath);
+ if (cmd == null)
+ {
+ return false;
+ }
+ executeCommand(cmd, true);
+ // todo: test for failure - how?
+ return true;
+ }
+
+ /**
+ * Scans visible features in mapped positions of the CDS/peptide complement,
+ * and adds any found to the map of attribute values/structure positions
+ *
+ * @param complementRenderer
+ * @param structureMapping
+ * @param seq
+ * @param theMap
+ * @param modelNumber
+ */
+ protected static void scanComplementFeatures(
+ FeatureRenderer complementRenderer,
+ StructureMapping structureMapping, SequenceI seq,
+ Map<String, Map<Object, AtomSpecModel>> theMap,
+ String modelNumber)
+ {
+ /*
+ * for each sequence residue mapped to a structure position...
+ */
+ for (int seqPos : structureMapping.getMapping().keySet())
+ {
+ /*
+ * find visible complementary features at mapped position(s)
+ */
+ MappedFeatures mf = complementRenderer
+ .findComplementFeaturesAtResidue(seq, seqPos);
+ if (mf != null)
+ {
+ for (SequenceFeature sf : mf.features)
+ {
+ String type = sf.getType();
+
+ /*
+ * Don't copy features which originated from Chimera
+ */
+ if (JalviewChimeraBinding.CHIMERA_FEATURE_GROUP
+ .equals(sf.getFeatureGroup()))
+ {
+ continue;
+ }
+
+ /*
+ * record feature 'value' (score/description/type) as at the
+ * corresponding structure position
+ */
+ List<int[]> mappedRanges = structureMapping
+ .getPDBResNumRanges(seqPos, seqPos);
+
+ if (!mappedRanges.isEmpty())
+ {
+ String value = sf.getDescription();
+ if (value == null || value.length() == 0)
+ {
+ value = type;
+ }
+ float score = sf.getScore();
+ if (score != 0f && !Float.isNaN(score))
+ {
+ value = Float.toString(score);
+ }
+ Map<Object, AtomSpecModel> featureValues = theMap.get(type);
+ if (featureValues == null)
+ {
+ featureValues = new HashMap<>();
+ theMap.put(type, featureValues);
+ }
+ for (int[] range : mappedRanges)
+ {
+ addAtomSpecRange(featureValues, value, modelNumber, range[0],
+ range[1], structureMapping.getChain());
+ }
+ }
+ }
+ }
+ }
+ }
+
+ /**
+ * Inspect features on the sequence; for each feature that is visible,
+ * determine its mapped ranges in the structure (if any) according to the
+ * given mapping, and add them to the map.
+ *
+ * @param visibleFeatures
+ * @param mapping
+ * @param seq
+ * @param theMap
+ * @param modelId
+ */
+ protected static void scanSequenceFeatures(List<String> visibleFeatures,
+ StructureMapping mapping, SequenceI seq,
+ Map<String, Map<Object, AtomSpecModel>> theMap, String modelId)
+ {
+ List<SequenceFeature> sfs = seq.getFeatures().getPositionalFeatures(
+ visibleFeatures.toArray(new String[visibleFeatures.size()]));
+ for (SequenceFeature sf : sfs)
+ {
+ String type = sf.getType();
+
+ /*
+ * Don't copy features which originated from Chimera
+ */
+ if (JalviewChimeraBinding.CHIMERA_FEATURE_GROUP
+ .equals(sf.getFeatureGroup()))
+ {
+ continue;
+ }
+
+ List<int[]> mappedRanges = mapping.getPDBResNumRanges(sf.getBegin(),
+ sf.getEnd());
+
+ if (!mappedRanges.isEmpty())
+ {
+ String value = sf.getDescription();
+ if (value == null || value.length() == 0)
+ {
+ value = type;
+ }
+ float score = sf.getScore();
+ if (score != 0f && !Float.isNaN(score))
+ {
+ value = Float.toString(score);
+ }
+ Map<Object, AtomSpecModel> featureValues = theMap.get(type);
+ if (featureValues == null)
+ {
+ featureValues = new HashMap<>();
+ theMap.put(type, featureValues);
+ }
+ for (int[] range : mappedRanges)
+ {
+ addAtomSpecRange(featureValues, value, modelId, range[0],
+ range[1], mapping.getChain());
+ }
+ }
+ }
+ }
+
+ /**
+ * Returns the number of structure files in the structure viewer and mapped to
+ * Jalview. This may be zero if the files are still in the process of loading
+ * in the viewer.
+ *
+ * @return
+ */
+ public int getMappedStructureCount()
+ {
+ String[] files = getStructureFiles();
+ return files == null ? 0 : files.length;
+ }
+
+ /**
+ * Starts a thread that waits for the external viewer program process to
+ * finish, so that we can then close the associated resources. This avoids
+ * leaving orphaned viewer panels in Jalview if the user closes the external
+ * viewer.
+ *
+ * @param p
+ */
+ protected void startExternalViewerMonitor(Process p)
+ {
+ externalViewerMonitor = new Thread(new Runnable()
+ {
+
+ @Override
+ public void run()
+ {
+ try
+ {
+ p.waitFor();
+ JalviewStructureDisplayI display = getViewer();
+ if (display != null)
+ {
+ display.closeViewer(false);
+ }
+ } catch (InterruptedException e)
+ {
+ // exit thread if Chimera Viewer is closed in Jalview
+ }
+ }
+ });
+ externalViewerMonitor.start();
+ }
+
+ /**
+ * If supported by the external structure viewer, sends it commands to notify
+ * model or selection changes to the specified URL (where Jalview has started
+ * a listener)
+ *
+ * @param uri
+ */
+ protected void startListening(String uri)
+ {
+ List<StructureCommandI> commands = getCommandGenerator()
+ .startNotifications(uri);
+ if (commands != null)
+ {
+ executeCommands(commands, false, null);
+ }
+ }
+
+ /**
+ * If supported by the external structure viewer, sends it commands to stop
+ * notifying model or selection changes
+ */
+ protected void stopListening()
+ {
+ List<StructureCommandI> commands = getCommandGenerator()
+ .stopNotifications();
+ if (commands != null)
+ {
+ executeCommands(commands, false, null);
+ }
+ }
+
+ /**
+ * If supported by the structure viewer, queries it for all residue attributes
+ * with the given attribute name, and creates features on corresponding
+ * residues of the alignment. Returns the number of features added.
+ *
+ * @param attName
+ * @param alignmentPanel
+ * @return
+ */
+ public int copyStructureAttributesToFeatures(String attName,
+ AlignmentPanel alignmentPanel)
+ {
+ StructureCommandI cmd = getCommandGenerator()
+ .getResidueAttributes(attName);
+ if (cmd == null)
+ {
+ return 0;
+ }
+ List<String> residueAttributes = executeCommand(cmd, true);
+
+ int featuresAdded = createFeaturesForAttributes(attName,
+ residueAttributes);
+ if (featuresAdded > 0)
+ {
+ alignmentPanel.getFeatureRenderer().featuresAdded();
+ }
+ return featuresAdded;
+ }
+
+ /**
+ * Parses {@code residueAttributes} and creates sequence features on any
+ * mapped alignment residues. Returns the number of features created.
+ * <p>
+ * {@code residueAttributes} is the reply from the structure viewer to a
+ * command to list any residue attributes for the given attribute name. Syntax
+ * and parsing of this is viewer-specific.
+ *
+ * @param attName
+ * @param residueAttributes
+ * @return
+ */
+ protected int createFeaturesForAttributes(String attName,
+ List<String> residueAttributes)
+ {
+ return 0;
+ }