Difference between revisions of "Jmol JavaScript Object/JSV"

From Jmol
Jump to navigation Jump to search
(Integration of JSpecView into Jmol-JSO)
(Creating and inserting the JSpecView applet)
 
(8 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
= JSpecView =
 +
[http://jspecview.sourceforge.net/ JSpecView] is a graphical viewer for spectral data in the [http://www.jcamp-dx.org/ JCAMP-DX format].
 +
It was initially developed as a Java application and Java applet, at the Department of Chemistry of the University of the West Indies, Mona, Jamaica.
 +
 +
It was later integrated into Jmol distribution and converted, to avoid Java, as a JavaScript-HTML5 version. This page documents this latter version.
 +
 
= Integration of JSpecView into Jmol-JSO =
 
= Integration of JSpecView into Jmol-JSO =
  
Extensive work in 2012 integrated [http://jspecview.sourceforge.net JSpecView] into Jmol 13.  
+
Extensive work in 2012 integrated JSpecView into Jmol 13 thanks to the [[Jmol JavaScript Object|JSO]] infrastructure (the same used for '''JSmol''').  
 
* The '''Jmol application''' now includes a new <code>tools</code> menu item that opens a frame for JSpecView.
 
* The '''Jmol application''' now includes a new <code>tools</code> menu item that opens a frame for JSpecView.
* The '''Jmol applet''' can communicate to and from a JSpecView applet in the same page, using the Jmol <code>sync</code> command. '''Jmol-JSO''' brokers this transaction and allows coordinated applet start-up so that one applet does not send a command to the other before both are ready.  
+
* The '''JSmol object''' can communicate to and from a JSpecView object in the same page, using the Jmol <code>sync</code> command. The JSmol object syntax (Jmol-JSO) brokers this transaction and allows coordinated start-up of both kind of objects so that one does not send a command to the other before both are ready.  
  
 
This makes it possible to tie 3D models to IR, NMR, UV/VIS, GC, and GC/MS spectra, using the JCAMP-DX Version 6 standard.
 
This makes it possible to tie 3D models to IR, NMR, UV/VIS, GC, and GC/MS spectra, using the JCAMP-DX Version 6 standard.
Line 9: Line 15:
 
Associated with this integration, we have designed a [{{StOlaf}}docs/misc/Jmol-JSpecView-specs.pdf specification] for an extension of the JCAMP-DX format that allows one JDX file to contain both Jmol-readable 3D models and peak information, allowing the user to click on, for example, a carbon atom in Jmol and have the <sup>13</sup>C-NMR spectrum automatically display and highlight the associated peak in JSpecView.  
 
Associated with this integration, we have designed a [{{StOlaf}}docs/misc/Jmol-JSpecView-specs.pdf specification] for an extension of the JCAMP-DX format that allows one JDX file to contain both Jmol-readable 3D models and peak information, allowing the user to click on, for example, a carbon atom in Jmol and have the <sup>13</sup>C-NMR spectrum automatically display and highlight the associated peak in JSpecView.  
  
For a demonstration of the Jmol <-> JSpecView connection, see the [{{StOlaf}}jspecview JSpecView subdirectory] at St.Olaf or the demo pages at [http://wwwchem.uwimona.edu.jm/spectra/JSpecView/ the University of the West Indies].
+
:''Note: this needs updating, StOlaf pages are broken at UWI pages use old Java versions, not JSmol.''
 +
:For a demonstration of the Jmol <-> JSpecView connection, see the [{{StOlaf}}jspecview JSpecView subdirectory] at St.Olaf or the demo pages at [http://wwwchem.uwimona.edu.jm/spectra/JSpecView/ the University of the West Indies].
 +
 
 +
== Initialization ==
 +
Add this in the <code>head</code> section of your page:
 +
<pre>
 +
<script src="somePath/JSmol.min.js" type="text/javascript"></script>
 +
<script src="somePath/js/JSmolJSV.js" type="text/javascript"></script>
 +
</pre>
 +
 
 +
And also define <tt>jsvInfo</tt> (''you can use whatever name for this variable'') which is an associative array (a set of key+value pairs) indicating all the desired characteristics of the JSpecView object. The keys that may be used and their default values are given below:
 +
* '''use''' <code>html5</code>
 +
* '''height''' <code>300</code>
 +
* '''width''' <code>800</code>
 +
* '''color''' <code>#A0A0A0</code>  (background around the spectrum box)
 +
* '''j2sPath''' <code>j2s</code>
 +
* '''jarPath''' <code>java</code>
 +
* '''jarFile''' <code>JSpecViewApplet.jar</code>
 +
* '''isSigned''' <code>false</code>
 +
* '''initParams''' <empty>
 +
* '''readyFunction''' <empty>
 +
* '''script''' <empty>
 +
 
 +
Example:
 +
<pre>
 +
var jsvInfo = {
 +
  j2sPath: 'somePath/j2s',
 +
  height: 300,
 +
  width: 300,
 +
  script: 'load "acetophenone.jdx"'
 +
};
 +
</pre>
  
 
== Creating and inserting the JSpecView applet ==  
 
== Creating and inserting the JSpecView applet ==  
To create a JSpecView applet, use for example:
+
To create a JSpecView applet and insert it into the htm page, use for example:
  var myJSV = Jmol.getJSVApplet("myJSV", Info)
+
  Jmol.getJSVApplet("myJSV", jsvInfo)
 +
 
 +
This will create a <tt>myJSV</tt> global variable in JavaScript that holds the JSpecView object and is also the unique ID for that object in all functions and methods described below.
  
Parameters making the <code>Info</code> variable (with default values shown between angular brackets):
+
If you prefer to insert the JSpecView object later after page creation, you can use:
* '''Info.height''' <<code>500</code>>
+
Jmol.getJSVAppletHtml("myJSV", jsvInfo)
* '''Info.width''' <<code>300</code>>
 
* '''Info.debug''' <<code>false</code>>
 
* '''Info.jarPath''' <<code>.</code>>
 
* '''Info.jarFile''' <<code>JSpecViewApplet.jar</code>>
 
* '''Info.isSigned''' <<code>false</code>>
 
* '''Info.initParams''' <empty>
 
* '''Info.readyFunction''' <empty>
 
* '''Info.script''' <empty>
 
  
 +
For example like this:
 +
$("#myPlace").html( Jmol.getJSVAppletHtml("myJSV", jsvInfo) )
 +
 +
You can visit an [http://jsmol.000webhostapp.com/test_JSV.htm example page] that load spectra from files or from inline data.
  
 
== JSpecView-specific methods ==
 
== JSpecView-specific methods ==
  
 
All these functions must be applied to the unique '''<code>Jmol</code>''' object (this name is literal, cannot be changed):
 
All these functions must be applied to the unique '''<code>Jmol</code>''' object (this name is literal, cannot be changed):
Jmol.jsvAddHightlight(myJSV, x1, x2, r, g, b, a)
+
 
Jmol.jsvExport(myJSV, exportType, n)
+
Handling files and scripting:
Jmol.jsvGetCoordinate(myJSV)  
+
* <code>Jmol.jsvLoadInline(myJSV, data, params)</code> Loads JCAMP-DX data from a string variable.
Jmol.jsvGetPropertyAsJavaObject(myJSV, key)  
+
* <code>Jmol.jsvRunScript(myJSV, script)</code> Uses a queue, possibly waiting until the viewer object has been loaded.
Jmol.jsvGetPropertyAsJSON(myJSV, key)  
+
* <code>Jmol.jsvRunScriptNow(myJSV, script)</code> Runs a script without queuing it, and returns only after completion.
Jmol.jsvGetSolnColour(myJSV)  
+
* <code>Jmol.jsvSyncScript(myJSV, peakScript)</code>
 +
* <code>Jmol.jsvExport(myJSV, exportType, n)</code> Delivers the spectrum in one of these formats:
 +
** exportType: PDF, JDX, XY, SQZ, PAC, DIF, DIFDUP, FIX, AML, CML, PNG, JPG (apparently only PDF is functional)
 +
** n: zero-based index of spectra available; -1 for the current one
 +
* <code>Jmol.jsvSetFilePath(myJSV, tmpFilePath)</code>
 +
 
 +
Configuration:
 
  Jmol.jsvIsPro(myJSV)  
 
  Jmol.jsvIsPro(myJSV)  
 
  Jmol.jsvIsSigned(myJSV)  
 
  Jmol.jsvIsSigned(myJSV)  
  Jmol.jsvLoadInline(myJSV, data, params)
+
 
 +
Interface:
 +
  Jmol.jsvAddHighlight(myJSV, x1, x2, r, g, b, a) // Adds a highlight to a portion of the plot area.
 +
Jmol.jsvRemoveHighlight(myJSV, x1, x2)
 
  Jmol.jsvRemoveAllHighlights(myJSV)  
 
  Jmol.jsvRemoveAllHighlights(myJSV)  
  Jmol.jsvRemoveHighlight(myJSV, x1, x2)
+
  Jmol.jsvToggleCoordinate(myJSV) // Toggles display of coordinate.
  Jmol.jsvReversePlot(myJSV)  
+
Jmol.jsvToggleGrid(myJSV)  
  Jmol.jsvRunScript(myJSV, script)
+
 
  Jmol.jsvRunScriptNow(myJSV, script)  
+
Other features:
  Jmol.jsvSetFilePath(myJSV, tmpFilePath)  
+
  Jmol.jsvGetCoordinate(myJSV) // returns the coordinate of clicked point in the plot area
 +
  Jmol.jsvGetPropertyAsJavaObject(myJSV, key)  
 +
  Jmol.jsvGetPropertyAsJSON(myJSV, key)
 +
Jmol.jsvGetSolnColour(myJSV) // Returns the calculated colour of a visible spectrum.
 +
  Jmol.jsvReversePlot(myJSV) // Inverts the direction of the X axis (chemical shift, ppm)
 
  Jmol.jsvSetSpectrumNumber(myJSV, n)  
 
  Jmol.jsvSetSpectrumNumber(myJSV, n)  
 
  Jmol.jsvSetVisible(myJSV, true/false)
 
  Jmol.jsvSetVisible(myJSV, true/false)
Jmol.jsvSyncScript(myJSV, peakScript)
+
  Jmol.jsvToggleIntegration(myJSV) // Toggles display of he integration plot
Jmol.jsvToggleCoordinate(myJSV)
+
  Jmol.jsvWriteStatus(myJSV, message) // Writes a message to the status label.
Jmol.jsvToggleGrid(myJSV)
 
  Jmol.jsvToggleIntegration(myJSV)
 
  Jmol.jsvWriteStatus(myJSV, message)
 

Latest revision as of 18:51, 28 April 2019

JSpecView

JSpecView is a graphical viewer for spectral data in the JCAMP-DX format. It was initially developed as a Java application and Java applet, at the Department of Chemistry of the University of the West Indies, Mona, Jamaica.

It was later integrated into Jmol distribution and converted, to avoid Java, as a JavaScript-HTML5 version. This page documents this latter version.

Integration of JSpecView into Jmol-JSO

Extensive work in 2012 integrated JSpecView into Jmol 13 thanks to the JSO infrastructure (the same used for JSmol).

  • The Jmol application now includes a new tools menu item that opens a frame for JSpecView.
  • The JSmol object can communicate to and from a JSpecView object in the same page, using the Jmol sync command. The JSmol object syntax (Jmol-JSO) brokers this transaction and allows coordinated start-up of both kind of objects so that one does not send a command to the other before both are ready.

This makes it possible to tie 3D models to IR, NMR, UV/VIS, GC, and GC/MS spectra, using the JCAMP-DX Version 6 standard.

Associated with this integration, we have designed a specification for an extension of the JCAMP-DX format that allows one JDX file to contain both Jmol-readable 3D models and peak information, allowing the user to click on, for example, a carbon atom in Jmol and have the 13C-NMR spectrum automatically display and highlight the associated peak in JSpecView.

Note: this needs updating, StOlaf pages are broken at UWI pages use old Java versions, not JSmol.
For a demonstration of the Jmol <-> JSpecView connection, see the JSpecView subdirectory at St.Olaf or the demo pages at the University of the West Indies.

Initialization

Add this in the head section of your page:

<script src="somePath/JSmol.min.js" type="text/javascript"></script>
<script src="somePath/js/JSmolJSV.js" type="text/javascript"></script>

And also define jsvInfo (you can use whatever name for this variable) which is an associative array (a set of key+value pairs) indicating all the desired characteristics of the JSpecView object. The keys that may be used and their default values are given below:

  • use html5
  • height 300
  • width 800
  • color #A0A0A0 (background around the spectrum box)
  • j2sPath j2s
  • jarPath java
  • jarFile JSpecViewApplet.jar
  • isSigned false
  • initParams <empty>
  • readyFunction <empty>
  • script <empty>

Example:

var jsvInfo = {
  j2sPath: 'somePath/j2s',
  height: 300,
  width: 300,
  script: 'load "acetophenone.jdx"'
};

Creating and inserting the JSpecView applet

To create a JSpecView applet and insert it into the htm page, use for example:

Jmol.getJSVApplet("myJSV", jsvInfo)

This will create a myJSV global variable in JavaScript that holds the JSpecView object and is also the unique ID for that object in all functions and methods described below.

If you prefer to insert the JSpecView object later after page creation, you can use:

Jmol.getJSVAppletHtml("myJSV", jsvInfo)

For example like this:

$("#myPlace").html( Jmol.getJSVAppletHtml("myJSV", jsvInfo) )

You can visit an example page that load spectra from files or from inline data.

JSpecView-specific methods

All these functions must be applied to the unique Jmol object (this name is literal, cannot be changed):

Handling files and scripting:

  • Jmol.jsvLoadInline(myJSV, data, params) Loads JCAMP-DX data from a string variable.
  • Jmol.jsvRunScript(myJSV, script) Uses a queue, possibly waiting until the viewer object has been loaded.
  • Jmol.jsvRunScriptNow(myJSV, script) Runs a script without queuing it, and returns only after completion.
  • Jmol.jsvSyncScript(myJSV, peakScript)
  • Jmol.jsvExport(myJSV, exportType, n) Delivers the spectrum in one of these formats:
    • exportType: PDF, JDX, XY, SQZ, PAC, DIF, DIFDUP, FIX, AML, CML, PNG, JPG (apparently only PDF is functional)
    • n: zero-based index of spectra available; -1 for the current one
  • Jmol.jsvSetFilePath(myJSV, tmpFilePath)

Configuration:

Jmol.jsvIsPro(myJSV) 
Jmol.jsvIsSigned(myJSV) 

Interface:

Jmol.jsvAddHighlight(myJSV, x1, x2, r, g, b, a) // Adds a highlight to a portion of the plot area.
Jmol.jsvRemoveHighlight(myJSV, x1, x2)
Jmol.jsvRemoveAllHighlights(myJSV) 
Jmol.jsvToggleCoordinate(myJSV) // Toggles display of coordinate.
Jmol.jsvToggleGrid(myJSV) 

Other features:

Jmol.jsvGetCoordinate(myJSV) // returns the coordinate of clicked point in the plot area
Jmol.jsvGetPropertyAsJavaObject(myJSV, key) 
Jmol.jsvGetPropertyAsJSON(myJSV, key) 
Jmol.jsvGetSolnColour(myJSV) // Returns the calculated colour of a visible spectrum.
Jmol.jsvReversePlot(myJSV) // Inverts the direction of the X axis (chemical shift, ppm)
Jmol.jsvSetSpectrumNumber(myJSV, n) 
Jmol.jsvSetVisible(myJSV, true/false)
Jmol.jsvToggleIntegration(myJSV) // Toggles display of he integration plot
Jmol.jsvWriteStatus(myJSV, message) // Writes a message to the status label.

Contributors

AngelHerraez