/* $RCSfile$ * $Author: hansonr $ * $Date: 2023-01-05 08:42:06 -0600 (Thu, 05 Jan 2023) $ * $Revision: 22500 $ * * Copyright (C) 2003-2005 The Jmol Development Team * * Contact: jmol-developers@lists.sf.net * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. */ package org.jmol.api; import java.io.BufferedReader; import java.util.Map; import javajs.util.PT; import org.jmol.util.Elements; import org.jmol.util.Edge; import org.jmol.viewer.Viewer; /**************************************************************** * The JmolAdapter interface defines the API used by the JmolViewer to * read external files and fetch atom properties necessary for rendering. * * A client of the JmolViewer implements this interface on top of their * existing molecular model representation. The JmolViewer then requests * information from the implementation using this API. * * Jmol will automatically calculate some atom properties if the client * is not capable or does not want to supply them. * * Note: If you are seeing pink atoms that have lots of bonds, then your * methods for getElementNumber(clientAtom) or getElementSymbol(clientAtom) * are probably returning stray values. Therefore, these atoms are getting * mapped to element 0 (Xx), which has color pink and a relatively large * covalent bonding radius. * @see org.jmol.api.JmolViewer * @see org.jmol.adapter.smarter.SmarterJmolAdapter ****************************************************************/ public abstract class JmolAdapter { public final static int ORDER_COVALENT_SINGLE = Edge.BOND_COVALENT_SINGLE; public final static int ORDER_COVALENT_DOUBLE = Edge.BOND_COVALENT_DOUBLE; public final static int ORDER_COVALENT_TRIPLE = Edge.BOND_COVALENT_TRIPLE; public final static int ORDER_COVALENT_QUAD = Edge.BOND_COVALENT_QUADRUPLE; public final static int ORDER_COVALENT_QUINT = Edge.BOND_COVALENT_QUINTUPLE; public final static int ORDER_COVALENT_HEX = Edge.BOND_COVALENT_sextuple; public final static int ORDER_AROMATIC = Edge.BOND_AROMATIC; public final static int ORDER_AROMATIC_SINGLE = Edge.BOND_AROMATIC_SINGLE; public final static int ORDER_AROMATIC_DOUBLE = Edge.BOND_AROMATIC_DOUBLE; public final static int ORDER_HBOND = Edge.BOND_H_REGULAR; public final static int ORDER_STEREO_NEAR = Edge.BOND_STEREO_NEAR; public final static int ORDER_STEREO_FAR = Edge.BOND_STEREO_FAR; public final static int ORDER_STEREO_EITHER = Edge.BOND_STEREO_EITHER; public final static int ORDER_PARTIAL01 = Edge.BOND_PARTIAL01; public final static int ORDER_PARTIAL12 = Edge.BOND_PARTIAL12; public final static int ORDER_PARTIAL23 = Edge.BOND_PARTIAL23; public final static int ORDER_PARTIAL32 = Edge.BOND_PARTIAL32; public final static int ORDER_UNSPECIFIED = Edge.BOND_ORDER_UNSPECIFIED; public final static int ORDER_PYMOL_SINGLE = Edge.BOND_PYMOL_NOMULT; public final static int ORDER_PYMOL_MULT = Edge.BOND_PYMOL_MULT; public static String getElementSymbol(int elementNumber) { return Elements.elementSymbolFromNumber(elementNumber); } public static int getElementNumber(String elementSymbol) { return Elements.elementNumberFromSymbol(elementSymbol, false); } public static int getNaturalIsotope(int elementNumber) { return Elements.getNaturalIsotope(elementNumber); } public static float getBondingRadius(int atomicNumberWithIsotope, int charge) { return Elements.getBondingRadius(atomicNumberWithIsotope, charge); } ////////////////////////////////////////////////////////////////// // file related ////////////////////////////////////////////////////////////////// final public static String[] cellParamNames = { "_cell_length_a", "_cell_length_b", "_cell_length_c", "_cell_angle_alpha", "_cell_angle_beta", "_cell_angle_gamma" }; /** * Read an atomSetCollection object from a bufferedReader and close the reader. * *

Given the BufferedReader, return an object which represents the file * contents. The parameter name is assumed to be the * file name or URL which is the source of reader. Note that this 'file' * may have been automatically decompressed. Also note that the name * may be 'String', representing a string constant. Therefore, few * assumptions should be made about the name parameter. * * The return value is an object which represents a atomSetCollection. * This atomSetCollection will be passed back in to other methods. * If the return value is instanceof String then it is * considered an error condition and the returned String is the error * message. * @param name File name, String or URL acting as the source of the reader * @param type File type, if known, or null * @param bufferedReader The BufferedReader * @param htParams a hash table containing parameter information * @return The atomSetCollection or String with an error message */ abstract public Object getAtomSetCollectionReader(String name, String type, Object bufferedReader, Map htParams); abstract public Object getAtomSetCollection(Object atomSetCollectionReader); /** * Associate an atomSetCollection object with an array of BufferedReader. * *

Given the array of BufferedReader, return an object which represents * the concatenation of every file contents. The parameter name * is assumed to be the file names or URL which are the source of each * reader. Note that each of this 'file' may have been automatically * decompressed. Also note that the name may be 'String', * representing a string constant. Therefore, few * assumptions should be made about the name parameter. * * The return value is an object which represents a atomSetCollection. * This atomSetCollection will be passed back in to other methods. * If the return value is instanceof String then it is * considered an error condition and the returned String is the error * message. * * @param fileReader the thread requesting a set of files if bufferedReaders is null * @param names File names, String or URL acting as the source of each reader * @param types File types, if known, or null * @param htParams The input parameters for each file to load * @param getReadersOnly * @return The atomSetCollection or String with an error message */ abstract public Object getAtomSetCollectionReaders(JmolFilesReaderInterface fileReader, String[] names, String[] types, Map htParams, boolean getReadersOnly); abstract public Object getAtomSetCollectionFromSet(Object readers, Object atomSets, Map htParams); abstract public Object getAtomSetCollectionFromReader(String fname, Object reader, Map htParams) throws Exception; /** * all in one -- for TestSmarterJmolAdapter * * @param name * @param type * @param bufferedReader * @param htParams * @return AtomSetCollection or error string */ public Object getAtomSetCollectionFromReaderType(String name, String type, Object bufferedReader, Map htParams) { // vwr is now needed for CIF and GenNBO file reading Object a = getAtomSetCollectionReader(name, type, bufferedReader, ((Viewer) JmolViewer.allocateViewer(null, this)).setLoadParameters( htParams, false)); if (a instanceof String) return a; return getAtomSetCollection(a); } // alternative settings, for posterity: public Object openBufferedReader(String name, BufferedReader bufferedReader) { return getAtomSetCollectionFromReaderType(name, null, bufferedReader, null); } public Object openBufferedReader(String name, BufferedReader bufferedReader, Map htParams) { return getAtomSetCollectionFromReaderType(name, null, bufferedReader, htParams); } public Object openBufferedReader(String name, String type, BufferedReader bufferedReader) { return getAtomSetCollectionFromReaderType(name, type, bufferedReader, null); } abstract public Object getAtomSetCollectionFromDOM(Object DOMNode, Map htParams); /** * @param atomSetCollection */ abstract public void finish(Object atomSetCollection); /** * Get the type of this file or molecular model, if known. * @param atomSetCollection The client file * @return The type of this file or molecular model, default * "unknown" */ abstract public String getFileTypeName(Object atomSetCollection); /** * Get the name of the atom set collection, if known. * *

Some file formats contain a formal name of the molecule in the file. * If this method returns null then the JmolViewer will * automatically supply the file/URL name as a default. * @param atomSetCollection * @return The atom set collection name or null */ abstract public String getAtomSetCollectionName(Object atomSetCollection); /** * Get the auxiliary information for this atomSetCollection. * *

Via the smarterJmolAdapter * @param atomSetCollection The client file * @return The auxiliaryInfo Hashtable that may be available for particular * filetypes for this atomSetCollection or null */ abstract public Map getAtomSetCollectionAuxiliaryInfo(Object atomSetCollection); /** * Get number of atomSets in the file or specific model index in file * * *

NOTE WARNING: *
Not yet implemented everywhere, it is in the smarterJmolAdapter * @param atomSetCollection The client file * @param modelIndex * @return The number of atomSets in the file */ abstract public int getAtomSetCount(Object atomSetCollection); /** * Get the number identifying each atomSet. * *

For a PDB file, this is is the model number. For others it is * a 1-based atomSet number. *

* Note that this is not currently implemented in PdbReader * @param atomSetCollection The client file * @param atomSetIndex The atom set's index for which to get * the atom set number * @return The number identifying each atom set. */ abstract public int getAtomSetNumber(Object atomSetCollection, int atomSetIndex); /** * Get the name of an atomSet. * * @param atomSetCollection The client file * @param atomSetIndex The atom set index * @return The name of the atom set, default the string representation * of atomSetIndex */ abstract public String getAtomSetName(Object atomSetCollection, int atomSetIndex); /** * Get the auxiliary information for a particular atomSet. * *

Via the smarterJmolAdapter * @param atomSetCollection The client file * @param atomSetIndex The atom set index * @return The auxiliaryInfo Hashtable that may be available for particular * filetypes for this atomSet or null */ abstract public Map getAtomSetAuxiliaryInfo(Object atomSetCollection, int atomSetIndex); /** * Get the number of atoms contained in the file. * * @param atomSetCollection The client file * @param atomSetIndex if -1, then count for the whole collection, else for this set * @return The estimated number of atoms in the file */ abstract public int getAtomCount(Object atomSetCollection, int atomSetIndex); /** * Get the hydrogen atom count -- for ligand files * * @param atomSetCollection * @return number of hydrogen atoms in this model */ abstract public int getHydrogenAtomCount(Object atomSetCollection); /** * * @param atomSetCollection * @return [ [atomName1 atomName2 order] ...] */ abstract public String[][] getBondList(Object atomSetCollection); /** * Get the boolean whether coordinates are fractional. * @param atomSetCollection The client file * @return true if the coordinates are fractional, default false */ abstract public boolean coordinatesAreFractional(Object atomSetCollection); /** * Get an AtomIterator for retrieval of all atoms in the file. * *

This method may not return null. * @param atomSetCollection The client file * @return An AtomIterator * @see JmolAdapterAtomIterator */ abstract public JmolAdapterAtomIterator getAtomIterator(Object atomSetCollection); /** * Get a BondIterator for retrieval of all bonds in the file. * *

If this method returns null and no * bonds are defined then the JmolViewer will automatically apply its * rebonding code to build bonds between atoms. * @param atomSetCollection The client file * @return A BondIterator or null * @see JmolAdapterBondIterator */ abstract public JmolAdapterBondIterator getBondIterator(Object atomSetCollection); /** * Get a StructureIterator. * @param atomSetCollection The client file * @return A StructureIterator or null */ abstract public JmolAdapterStructureIterator getStructureIterator(Object atomSetCollection); ////////////////////////////////////////////////////////////////// // range-checking routines ///////////////////////////////////////////////////////////////// private final static char canonizeAlphaDigit(char ch) { return (PT.isLetterOrDigit(ch) ? ch : '\0'); } // public final static char canonizeChainID(char chainID) { // return canonizeAlphaDigit(chainID); // } public final static char canonizeInsertionCode(char insertionCode) { return canonizeAlphaDigit(insertionCode); } public final static char canonizeAlternateLocationID(char altLoc) { // pdb altLoc return canonizeAlphaDigit(altLoc); } }