Difference between revisions of "Jmol Application"

From Jmol
Jump to navigation Jump to search
(Starting Jmol Application)
(remove languages template (not being used))
 
(21 intermediate revisions by 4 users not shown)
Line 3: Line 3:
 
"Jmol Application" is the version of Jmol that runs as a standalone program, in its own window. The program code is written using the [http://en.wikipedia.org/wiki/Java_programming_language Java programming language], therefore to be run it needs an installed ''Java Virtual Machine'' (a runtime version of Java, or ''JRE''); this ''JVM'' is available for all major operating systems, including Windows, MacOS and Linux.  
 
"Jmol Application" is the version of Jmol that runs as a standalone program, in its own window. The program code is written using the [http://en.wikipedia.org/wiki/Java_programming_language Java programming language], therefore to be run it needs an installed ''Java Virtual Machine'' (a runtime version of Java, or ''JRE''); this ''JVM'' is available for all major operating systems, including Windows, MacOS and Linux.  
  
[[Image:JmolApplication_11-6.png|Jmol Application window|center]]
+
[[Image:JmolApplication_12-0.png|Jmol Application window|center]]
  
 
Control of the molecular model is gained through several means:
 
Control of the molecular model is gained through several means:
 
# The mouse (documented in [[Mouse Manual]]).
 
# The mouse (documented in [[Mouse Manual]]).
# The application's menu and toolbar (at the top of the window), which offer
+
# The application's menu and [[The Toolbar|toolbar]] (at the top of the window), which offer
 
## File open, export, and print functionalities.
 
## File open, export, and print functionalities.
 
## A limited set of selection and rendering options, and several tools.
 
## A limited set of selection and rendering options, and several tools.
Line 18: Line 18:
 
Download the Jmol package (either <code>.zip</code> or <code>tar.gz</code> format) and extract/uncompress '''only the {{File|Jmol.jar}} file''' to the folder of your choice.
 
Download the Jmol package (either <code>.zip</code> or <code>tar.gz</code> format) and extract/uncompress '''only the {{File|Jmol.jar}} file''' to the folder of your choice.
  
It is also possible to [[Support/Osx | create a Mac OSX native installer]].
+
See also specific tips in [[Support/Linux]], [[Support/Osx|Support/OS X]], [[Support/Windows]], for example how to [[Support/Osx | create a Mac OSX native installer]].
  
 
To open the application, follow these instructions:
 
To open the application, follow these instructions:
Line 28: Line 28:
 
* Click on a previously created Start menu entry (Windows terminology - [[Support/Windows#Creating_shortcuts_to_Jmol_application|HowTo]]).
 
* Click on a previously created Start menu entry (Windows terminology - [[Support/Windows#Creating_shortcuts_to_Jmol_application|HowTo]]).
 
* Execute one of the [[Files_Description#jmol|batch files/shell scripts]] that are part of Jmol distribution (Windows, MacOS, Linux, Unix).
 
* Execute one of the [[Files_Description#jmol|batch files/shell scripts]] that are part of Jmol distribution (Windows, MacOS, Linux, Unix).
* From the command line: <code>java -jar Jmol.jar</code>  (of course, issued from the folder/directory where Jmol.jar is, or else pointing to it with a full path). See memory options below.
+
* From the command line: <code>java -jar Jmol.jar</code>  (of course, issued from the folder/directory where Jmol.jar is, or else pointing to it with a full path). See options below.
 
* Double-click on a molecular coordinates file whose extension has been previously associated to Jmol ([[Support/Windows#Associating_molecular_files_.28e.g._PDB.29_in_hard_disk_with_Jmol_application|HowTo]]).
 
* Double-click on a molecular coordinates file whose extension has been previously associated to Jmol ([[Support/Windows#Associating_molecular_files_.28e.g._PDB.29_in_hard_disk_with_Jmol_application|HowTo]]).
 +
<!--
 
* ''only for Macs'', Fernanda Foertter has packed Jmol application into a clickable icon / .app type icon that opens up Jmol. This makes it look like a regular 'ol app without all of the exposed jar files. It is available at her site as a dmg file. Instructions: 1) download [http://www.advancedphysics.org/Jmol/Jmol.dmg dmg file]; 2) double-click to open; 3) drag Jmol icon to you Applications folder to install; 4) eject dmg; 5) trash dmg file; 6) double-click Jmol icon to open application, or 6a) click and drag to dock to have ready whenever needed.
 
* ''only for Macs'', Fernanda Foertter has packed Jmol application into a clickable icon / .app type icon that opens up Jmol. This makes it look like a regular 'ol app without all of the exposed jar files. It is available at her site as a dmg file. Instructions: 1) download [http://www.advancedphysics.org/Jmol/Jmol.dmg dmg file]; 2) double-click to open; 3) drag Jmol icon to you Applications folder to install; 4) eject dmg; 5) trash dmg file; 6) double-click Jmol icon to open application, or 6a) click and drag to dock to have ready whenever needed.
 +
-->
  
 
If you have trouble running the application, see also [[Troubleshooting]].  
 
If you have trouble running the application, see also [[Troubleshooting]].  
  
 
If you want to attach a Jmol icon to your preferred method of opening Jmol, you can get one from the [[Recycling Corner]].
 
If you want to attach a Jmol icon to your preferred method of opening Jmol, you can get one from the [[Recycling Corner]].
 +
 +
See also specific tips in [[Support/Linux]], [[Support/Osx|Support/OS X]], [[Support/Windows]], for example how to [[Support/Osx | create a Mac OSX native installer]].
  
 
=== Command line options ===
 
=== Command line options ===
 +
 +
'''''Note:'''''
 +
For all the following, calling directly
 +
<code>Jmol.jar</code> ''(some options)''
 +
will only work as long as the {{file|.jar}} files are associated with Java. Otherwise, the general syntax for all cases is
 +
<code>java -jar Jmol.jar</code> ''(some options)''
 +
but the 'java -jar' part will be omitted for simplicity (except where it is unavoidable).
 +
 +
In fact, you can also just use
 +
<code>Jmol</code> ''(some options)''
 +
provided you have in the same folder/directory the batch file or shell script adequate for your OS (included with Jmol distribution).
  
 
==== Basic options ====
 
==== Basic options ====
Line 42: Line 57:
 
  java -jar Jmol.jar '''-h'''
 
  java -jar Jmol.jar '''-h'''
 
  java -jar Jmol.jar '''--help'''
 
  java -jar Jmol.jar '''--help'''
* To load a molecular file immediately after opening Jmol, use either of these:
+
 
 +
===== Loading files and running scripts =====
 +
* To load a molecular file immediately after opening Jmol, use:
 
  Jmol.jar ''' ''fileName'' '''
 
  Jmol.jar ''' ''fileName'' '''
java -jar Jmol.jar ''' ''fileName'' '''
+
 
* To run a script or a script file immediately after opening Jmol, use either of these:
+
* To run a script file immediately after opening Jmol, use:
  Jmol.jar ''' ''script_fileName'' '''
+
  Jmol.jar ''' ''scriptFileName'' '''
java -jar Jmol.jar  '''''script_fileName'''''
+
 
  Jmol.jar '''-J ''script_commands''  -s ''script_fileName''  -j ''script_commands'' '''
+
* You can combine loading a molecular file, running a script file and running script commands (only Jmol 11.7.x and later):
  java -jar Jmol.jar '''-J ''script_commands''  -s ''script_fileName''  -j ''script_commands'' '''
+
  Jmol.jar ''' ''fileName''  -J ''scriptCommands''  -s ''scriptFileName''  -j ''scriptCommands'' '''
: The "-J" and "-j" switches are only valid in Jmol 11.7.x, and case of the "J" is significant when combined with "-s". Either of the 3 switches may be omitted; if several are present, they will be executed in that order: first J, then s, then j.  
+
: irrespective of their actual order in the command line, they will always be run in this order:
 +
:# the file will be loaded
 +
:# the commands written after uppercase "-J"
 +
:# the commands inside the <code>scriptFileName</code> text file (file extension is irrelevant, but we like to use <code>.spt</code> as a hint)
 +
:# the commands written after lowercase "-j"
 +
: Either of the 4 may be omitted. File names and commands may need to be enclosed in quotes when they are not simple (it is safe to always use quotes).
 +
 
 +
===== Interface =====
 
* To set the application's window size, use either of these:
 
* To set the application's window size, use either of these:
 
  Jmol.jar '''-g  ''WIDTHxHEIGHT'' '''
 
  Jmol.jar '''-g  ''WIDTHxHEIGHT'' '''
 
  Jmol.jar '''--geometry  ''WIDTHxHEIGHT'' '''
 
  Jmol.jar '''--geometry  ''WIDTHxHEIGHT'' '''
java -jar Jmol.jar  '''-g  ''WIDTHxHEIGHT'' '''
 
 
: using lowercase 'x' and no spaces, e.g. <code>Jmol.jar -g 500x250</code>. By default, size is the last size used or else 500x500.
 
: using lowercase 'x' and no spaces, e.g. <code>Jmol.jar -g 500x250</code>. By default, size is the last size used or else 500x500.
* To set the language to be used for the interface (default is language of the operating system; [http://wiki.jmol.org/index.php/User:AngelHerraez#Forcing_Jmol_to_open_in_a_certain_language see also]) use:
+
 
  java '''-Duser.language=ca|cs|de|en|es|et|fr|nl|pt|tr'''  -jar Jmol.jar
+
* To run in [[kiosk mode]]
 +
Jmol.jar '''-k'''
 +
This mode displays a borderless window (no top menu, button bar or status bar); it's more like the applet, but with an optional banner across the top. By default it opens in full screen, but you can use the '''<code>-g</code>''' option above to set a certain window size. Communication with the application in kiosk mode uses ports with JSON commands (see {{ScriptingDoc}}misc/appsync.txt).
 +
''Note: you need Jmol 12.2.0 or later to use this feature''.
 +
 
 +
* To use a [[Custom_Menus|custom pop-up menu]], defined in a file, use either of these:  
 +
Jmol.jar '''-m ''fileName'' '''
 +
Jmol.jar '''--menu  ''fileName'' '''
 +
 
 +
* To set the language to be used for the interface, use:
 +
  java '''-Duser.language=ca|cs|de|en_GB|en_US|es|fr|hu|it|ko|nl|pt_BR|tr|zh_TW'''  -jar Jmol.jar
 +
:(default is the language of the operating system or else, if that is not available, en_US; [[Jmol_Application#Forcing_Jmol_to_open_in_a_certain_language|see also]]).
 +
 
 +
===== Miscellaneous =====
 
* To report the display speed in either frames per second or milliseconds per frame (the default), use:
 
* To report the display speed in either frames per second or milliseconds per frame (the default), use:
 
  java '''-Ddisplay.speed=fps|ms'''  -jar Jmol.jar
 
  java '''-Ddisplay.speed=fps|ms'''  -jar Jmol.jar
 +
 
* To set a path where to look for plugins for Jmol, use:
 
* To set a path where to look for plugins for Jmol, use:
 
  java '''-Dplugin.dir=''/path/to/plugins'' '''  -jar Jmol.jar
 
  java '''-Dplugin.dir=''/path/to/plugins'' '''  -jar Jmol.jar
 +
 
* To specify memory use (see below):
 
* To specify memory use (see below):
 
  java '''-Xmx''size'' '''  -jar Jmol.jar
 
  java '''-Xmx''size'' '''  -jar Jmol.jar
Line 67: Line 105:
 
==== Giving Jmol more memory to work with ====
 
==== Giving Jmol more memory to work with ====
 
Memory available to Jmol is determined by Java. Less or more memory can be allocated by using:
 
Memory available to Jmol is determined by Java. Less or more memory can be allocated by using:
<br><code>java '''-Xmx###m''' -jar Jmol.jar</code>
+
<code>java '''-Xmx###m''' -jar Jmol.jar</code>
<br>where the ### must be substituted by a number in megabytes (hence the "m" after it).
+
where the ### must be substituted by a number in megabytes (hence the "m" after it).
  
 
Technically:  
 
Technically:  
 
* -Xmx sets the maximum memory heap size.
 
* -Xmx sets the maximum memory heap size.
 
* -Xms sets the minimum memory heap size.
 
* -Xms sets the minimum memory heap size.
Batch files and shell scripts included with Jmol distribution are written to give -Xmx512m (512 MB maximum).
+
Batch files and shell scripts included with Jmol distribution are written to give -Xmx512m (i.e. 512 MB maximum).
 +
See also [[Jmol_Applet#Giving_JmolApplet_more_memory_to_work_with|the procedure for the applet]].
 +
 
 +
=====Mac OS X=====
  
See also [[Jmol_Applet#Giving_JmolApplet_more_memory_to_work_with|the procedure for the applet]].
+
The above command may be executed in a Terminal window (Applications, Utilities, Terminal.app). Either you need to specify a complete filepath with ''Jmol.jar'', or else you need to change the default Terminal directory to one containing a copy of Jmol.jar. Example of a filepath:
 +
java -Xmx512m -jar /Users/your_account/Downloads/jmol-12.0.26/Jmol.jar
 +
 
 +
=====Windows=====
 +
 
 +
The above command may be executed in a Command Prompt window (Start, Programs, Accessories, Command Prompt). Either you need to specify a complete filepath with ''Jmol.jar'', or else you need to change the default Terminal directory to one containing a copy of Jmol.jar. Example of a filepath:
 +
java -Xmx512m -jar c:\jmol\jmol-12.0.26\Jmol.jar
 +
 
 +
==== Advanced options ====
 +
 
 +
* To avoid the splash screen from being displayed, use either of these:
 +
Jmol.jar '''-L'''
 +
Jmol.jar '''--nosplash'''
 +
 
 +
* To open the app with a transparent background (may not function, use at your own risk), use either of these:
 +
Jmol.jar '''-b'''
 +
Jmol.jar '''--backgroundtransparent'''
  
==== Advanced options (Jmol v.11) ====
+
* To have Jmol export a snapshot of the rendered model to an image file, use either of these:
 +
Jmol.jar ''fileNameToLoad'' '''-w ''imageFormat'':''imageFileName'' '''
 +
Jmol.jar ''fileNameToLoad'' '''--write ''imageFormat'':''imageFileName'' '''
 +
Jmol.jar -s ''scriptFileNameToLoad'' '''-w ''imageFormat'':''imageFileName'' '''
 +
Jmol.jar --script ''scriptFileNameToLoad'' '''--write ''imageFormat'':''imageFileName'' '''
 +
: Where ''imageFormat'' may be one of these (and must be followed by a colon): <code>JPG</code> , <code>JPEG</code> , <code>JPG64</code> , <code>PNG</code> , <code>PPM</code> , or <code>CLIP</code> for copying the image to the clipboard instead of writing to a file.
  
''(Some of these need testing to confirm this is the proper syntax)''
+
* To set the quality of images written to file, use either of these:
 +
Jmol.jar ''fileNameToLoad'' '''-q##''' -w ''imageFormat'':''imageFileName''
 +
Jmol.jar ''fileNameToLoad'' '''--quality##''' --write ''imageFormat'':''imageFileName''
 +
Jmol.jar -s ''scriptFileNameToLoad'' '''-q##''' -w ''imageFormat'':''imageFileName''
 +
Jmol.jar --script ''scriptFileNameToLoad'' '''--quality##''' --write ''imageFormat'':''imageFileName''
 +
: Where the ''##'' may be a number from 1 to 100, meaning quality of JPG (75 by default), or a number from 0 to 9, meaning compression of PNG (2 by default, 9 maximum compression).
  
 
* To have the syntax of scripts checked, without actually executing them, use either of these:  
 
* To have the syntax of scripts checked, without actually executing them, use either of these:  
  java -jar Jmol.jar '''-c'''
+
  Jmol.jar '''-c'''
  java -jar Jmol.jar '''--check'''
+
  Jmol.jar '''--check'''
 +
 
 +
* To have the syntax of scripts checked and also execute them, use either of these:
 +
Jmol.jar '''-C'''
 +
Jmol.jar '''--checkload'''
  
 
* To have the script commands listed while running them, use either of these:  
 
* To have the script commands listed while running them, use either of these:  
  java -jar Jmol.jar '''-l'''
+
  Jmol.jar '''-l'''
  java -jar Jmol.jar '''--list'''
+
  Jmol.jar '''--list'''
  
 
* To get a silent startup operation, use either of these:  
 
* To get a silent startup operation, use either of these:  
  java -jar Jmol.jar '''-i'''
+
  Jmol.jar '''-i'''
  java -jar Jmol.jar '''--silent'''
+
  Jmol.jar '''--silent'''
  
 
* To have output messages put to the standard system output (e.g. the terminal), instead of to the internal Jmol Java console, use either of these:  
 
* To have output messages put to the standard system output (e.g. the terminal), instead of to the internal Jmol Java console, use either of these:  
  java -jar Jmol.jar '''-o'''
+
  Jmol.jar '''-o'''
  java -jar Jmol.jar '''--noconsole'''
+
  Jmol.jar '''--noconsole'''
  
 
* To avoid the use of the screen display (all rendering done only in memory, hence accelerating Jmol), use either of these:  
 
* To avoid the use of the screen display (all rendering done only in memory, hence accelerating Jmol), use either of these:  
  java -jar Jmol.jar '''-n'''
+
  Jmol.jar '''-n'''
  java -jar Jmol.jar '''--nodisplay'''  
+
  Jmol.jar '''--nodisplay'''  
 
: Normally, this should be used together with other switches like -x (see below).
 
: Normally, this should be used together with other switches like -x (see below).
  
 
* To have the application exit once finished (e.g. after running a script), use either of these:  
 
* To have the application exit once finished (e.g. after running a script), use either of these:  
  java -jar Jmol.jar '''-x'''
+
  Jmol.jar '''-x'''
  java -jar Jmol.jar '''--exit'''
+
  Jmol.jar '''--exit'''
 +
 
 +
* To start in debug mode, use either of these:
 +
Jmol.jar '''-d'''
 +
Jmol.jar '''--debug'''
  
* To use a [[Custom_Menus|custom pop-up menu]], defined in a file, use either of these:  
+
* To use an independent thread, use either of these:  
  java -jar Jmol.jar '''-m ''fileName'' '''
+
  Jmol.jar '''-t'''
  java -jar Jmol.jar '''--menu  ''fileName'' '''
+
  Jmol.jar '''--threaded'''
  
* To have Jmol export a snapshot of the rendered model to an image file, use either of these:  
+
* To run in JSON NIO client mode:
  java -jar Jmol.jar ''fileNameToLoad'' '''-w ''imageFormat'':''imageFileName'' '''
+
  Jmol.jar '''-P''' ''portNumber''
java -jar Jmol.jar ''fileNameToLoad'' '''--write ''imageFormat'':''imageFileName'' '''
+
You should use <code>-J</code> or <code>-j</code> to set <code>nioContentPath</code> and <code>nioTerminatorMessage</code> to the desired values. For example:
java -jar Jmol.jar -s ''scriptFileNameToLoad'' '''-w ''imageFormat'':''imageFileName'' '''
+
Jmol -k -P 31461 -j "nioContentPath='./%ID%/%ID%.json';nioTerminatorMessage='SCRIPT_DONE'"
java -jar Jmol.jar --script ''scriptFileNameToLoad'' '''--write ''imageFormat'':''imageFileName'' '''
 
: Where ''imageFormat'' may be one of these (and must be followed by a colon): <code>JPG</code> , <code>JPEG</code> , <code>JPG64</code> , <code>PNG</code> , <code>PPM</code> , or <code>CLIP</code> for copying the image to the clipboard instead of writing to a file.
 
  
* To set the quality of images written to file, use either of these:
 
java -jar Jmol.jar ''fileNameToLoad'' '''-q##''' -w ''imageFormat'':''imageFileName''
 
java -jar Jmol.jar ''fileNameToLoad'' '''--quality##''' --write ''imageFormat'':''imageFileName''
 
java -jar Jmol.jar -s ''scriptFileNameToLoad'' '''-q##''' -w ''imageFormat'':''imageFileName''
 
java -jar Jmol.jar --script ''scriptFileNameToLoad'' '''--quality##''' --write ''imageFormat'':''imageFileName''
 
: Where the ''##'' may be a number from 1 to 100, meaning quality of JPG (75 by default), or a number from 0 to 9, meaning compression of PNG (2 by default, 9 maximum compression).
 
  
 
'''Examples:'''
 
'''Examples:'''
Line 128: Line 195:
 
'''Create a JVXL file directly:'''
 
'''Create a JVXL file directly:'''
  
   Jmol -ionx iso.spt myfile.xyz > myfile.jvxl
+
   Jmol.jar -ionx myfile.xyz iso.spt > myfile.jvxl
 
: where {{file|iso.spt}} contains:
 
: where {{file|iso.spt}} contains:
    isosurface solvent;show isosurface
+
isosurface solvent; show isosurface
 
: will create a {{file|myfile.jvxl}} file containing data for a solvent surface in Jmol isosurface format (<code>JVXL</code>).
 
: will create a {{file|myfile.jvxl}} file containing data for a solvent surface in Jmol isosurface format (<code>JVXL</code>).
  
 
'''Create a list of measurements:'''
 
'''Create a list of measurements:'''
   Jmol -ionx measure.spt myfile.xyz > measure.txt
+
   Jmol.jar -ionx myfile.xyz measure.spt > measure.txt
 
: where {{file|measure.spt}} contains:
 
: where {{file|measure.spt}} contains:
  measure allconnected (*) (*);show measurements
+
  measure allconnected (*) (*); show measurements
 
: which generates a list of measurements. The output file, {{file|measure.txt}}, will contain (tab-separated):
 
: which generates a list of measurements. The output file, {{file|measure.txt}}, will contain (tab-separated):
 
  Measurement Information
 
  Measurement Information
Line 145: Line 212:
  
 
'''Check CIF file symmetry:'''
 
'''Check CIF file symmetry:'''
   Jmol -ionx symmetry.spt myfile.cif > symmetry.txt
+
   Jmol.jar -ionx myfile.cif symmetry.spt > symmetry.txt
 
: where {{file|symmetry.spt}} contains:
 
: where {{file|symmetry.spt}} contains:
 
     show unitcell;show symmetry;show spacegroup;
 
     show unitcell;show symmetry;show spacegroup;
Line 153: Line 220:
  
 
===  Forcing Jmol to open in a certain language ===
 
===  Forcing Jmol to open in a certain language ===
Jmol includes several languages (technically called localizations) for the user interface (top menu and pop-up menu).
+
Jmol [[Internationalisation/Current_Status|includes several languages]] (technically called localizations) for the user interface (top menu and pop-up menu).
 
Jmol will open by default with the interface using the language
 
Jmol will open by default with the interface using the language
 
of your operating system ([http://java.sun.com/j2se/corejava/intl/reference/faqs/index.html#set-default-locale ref.]). However, if you need to change this:
 
of your operating system ([http://java.sun.com/j2se/corejava/intl/reference/faqs/index.html#set-default-locale ref.]). However, if you need to change this:
  
 
# Starting Jmol 11.1.30, the language in application can be switched anytime, from the pop-up  menu, "Language" item near the bottom.
 
# Starting Jmol 11.1.30, the language in application can be switched anytime, from the pop-up  menu, "Language" item near the bottom.
# Or, using the scripting language: <code> language = "de" </code> (you must use the keyword "language" and the two-letter language code: ca, cs, de, en, es, et, fr, nl, pt, tr)
+
# Or, using the scripting language: <code> language = "de" </code> (you must use the keyword "language" and the two-letter language code: ca, cs, de, en, es, et, fr, nl, pt, tr, or four-letter code: en_GB, en_US, pt_BR, zh_TW)
 
# ''This is an old method, only needed for versions below 11.1.30:'' If you want to force a certain language, you must start Jmol with
 
# ''This is an old method, only needed for versions below 11.1.30:'' If you want to force a certain language, you must start Jmol with
 
::<code>java -Duser.language=es -jar Jmol.jar  # forces Spanish (Español)</code>
 
::<code>java -Duser.language=es -jar Jmol.jar  # forces Spanish (Español)</code>

Latest revision as of 10:20, 14 August 2021

Running Jmol / JSmol

Jmol Application

"Jmol Application" is the version of Jmol that runs as a standalone program, in its own window. The program code is written using the Java programming language, therefore to be run it needs an installed Java Virtual Machine (a runtime version of Java, or JRE); this JVM is available for all major operating systems, including Windows, MacOS and Linux.

Jmol Application window

Control of the molecular model is gained through several means:

  1. The mouse (documented in Mouse Manual).
  2. The application's menu and toolbar (at the top of the window), which offer
    1. File open, export, and print functionalities.
    2. A limited set of selection and rendering options, and several tools.
  3. The pop-up menu (or context menu, opened by right-click or Ctrl+click on the model's panel), which offers most funcionality available and is identical to the applet menu.
  4. The scripting language (same used by the applet); this is available through the File > Script... menu, which opens a "script console" or command-line environment.

Installing Jmol Application

Installing Jmol / JSmol

Download the Jmol package (either .zip or tar.gz format) and extract/uncompress only the File icon.gifJmol.jar file to the folder of your choice.

See also specific tips in Support/Linux, Support/OS X, Support/Windows, for example how to create a Mac OSX native installer.

To open the application, follow these instructions:

Starting Jmol Application

Several ways:

  • Double-click on File icon.gifJmol.jar file.
  • Click on a previously created shortcut (Windows terminology - HowTo).
  • Click on a previously created Start menu entry (Windows terminology - HowTo).
  • Execute one of the batch files/shell scripts that are part of Jmol distribution (Windows, MacOS, Linux, Unix).
  • From the command line: java -jar Jmol.jar (of course, issued from the folder/directory where Jmol.jar is, or else pointing to it with a full path). See options below.
  • Double-click on a molecular coordinates file whose extension has been previously associated to Jmol (HowTo).

If you have trouble running the application, see also Troubleshooting.

If you want to attach a Jmol icon to your preferred method of opening Jmol, you can get one from the Recycling Corner.

See also specific tips in Support/Linux, Support/OS X, Support/Windows, for example how to create a Mac OSX native installer.

Command line options

Note: For all the following, calling directly

Jmol.jar (some options)

will only work as long as the File icon.gif.jar files are associated with Java. Otherwise, the general syntax for all cases is

java -jar Jmol.jar (some options)

but the 'java -jar' part will be omitted for simplicity (except where it is unavoidable).

In fact, you can also just use

Jmol (some options)

provided you have in the same folder/directory the batch file or shell script adequate for your OS (included with Jmol distribution).

Basic options

  • To show help for command-line options, use either of these:
java -jar Jmol.jar -h
java -jar Jmol.jar --help
Loading files and running scripts
  • To load a molecular file immediately after opening Jmol, use:
Jmol.jar  fileName 
  • To run a script file immediately after opening Jmol, use:
Jmol.jar  scriptFileName 
  • You can combine loading a molecular file, running a script file and running script commands (only Jmol 11.7.x and later):
Jmol.jar  fileName  -J scriptCommands  -s scriptFileName  -j scriptCommands 
irrespective of their actual order in the command line, they will always be run in this order:
  1. the file will be loaded
  2. the commands written after uppercase "-J"
  3. the commands inside the scriptFileName text file (file extension is irrelevant, but we like to use .spt as a hint)
  4. the commands written after lowercase "-j"
Either of the 4 may be omitted. File names and commands may need to be enclosed in quotes when they are not simple (it is safe to always use quotes).
Interface
  • To set the application's window size, use either of these:
Jmol.jar -g  WIDTHxHEIGHT 
Jmol.jar --geometry  WIDTHxHEIGHT 
using lowercase 'x' and no spaces, e.g. Jmol.jar -g 500x250. By default, size is the last size used or else 500x500.
Jmol.jar -k

This mode displays a borderless window (no top menu, button bar or status bar); it's more like the applet, but with an optional banner across the top. By default it opens in full screen, but you can use the -g option above to set a certain window size. Communication with the application in kiosk mode uses ports with JSON commands (see https://chemapps.stolaf.edu/jmol/docs/misc/appsync.txt). Note: you need Jmol 12.2.0 or later to use this feature.

Jmol.jar -m fileName 
Jmol.jar --menu  fileName 
  • To set the language to be used for the interface, use:
java -Duser.language=ca|cs|de|en_GB|en_US|es|fr|hu|it|ko|nl|pt_BR|tr|zh_TW  -jar Jmol.jar
(default is the language of the operating system or else, if that is not available, en_US; see also).
Miscellaneous
  • To report the display speed in either frames per second or milliseconds per frame (the default), use:
java -Ddisplay.speed=fps|ms  -jar Jmol.jar
  • To set a path where to look for plugins for Jmol, use:
java -Dplugin.dir=/path/to/plugins   -jar Jmol.jar
  • To specify memory use (see below):
java -Xmxsize   -jar Jmol.jar

Giving Jmol more memory to work with

Memory available to Jmol is determined by Java. Less or more memory can be allocated by using:

java -Xmx###m -jar Jmol.jar

where the ### must be substituted by a number in megabytes (hence the "m" after it).

Technically:

  • -Xmx sets the maximum memory heap size.
  • -Xms sets the minimum memory heap size.

Batch files and shell scripts included with Jmol distribution are written to give -Xmx512m (i.e. 512 MB maximum). See also the procedure for the applet.

Mac OS X

The above command may be executed in a Terminal window (Applications, Utilities, Terminal.app). Either you need to specify a complete filepath with Jmol.jar, or else you need to change the default Terminal directory to one containing a copy of Jmol.jar. Example of a filepath:

java -Xmx512m -jar /Users/your_account/Downloads/jmol-12.0.26/Jmol.jar
Windows

The above command may be executed in a Command Prompt window (Start, Programs, Accessories, Command Prompt). Either you need to specify a complete filepath with Jmol.jar, or else you need to change the default Terminal directory to one containing a copy of Jmol.jar. Example of a filepath:

java -Xmx512m -jar c:\jmol\jmol-12.0.26\Jmol.jar

Advanced options

  • To avoid the splash screen from being displayed, use either of these:
Jmol.jar -L
Jmol.jar --nosplash
  • To open the app with a transparent background (may not function, use at your own risk), use either of these:
Jmol.jar -b
Jmol.jar --backgroundtransparent
  • To have Jmol export a snapshot of the rendered model to an image file, use either of these:
Jmol.jar fileNameToLoad -w imageFormat:imageFileName 
Jmol.jar fileNameToLoad --write imageFormat:imageFileName 
Jmol.jar -s scriptFileNameToLoad -w imageFormat:imageFileName 
Jmol.jar --script scriptFileNameToLoad --write imageFormat:imageFileName 
Where imageFormat may be one of these (and must be followed by a colon): JPG , JPEG , JPG64 , PNG , PPM , or CLIP for copying the image to the clipboard instead of writing to a file.
  • To set the quality of images written to file, use either of these:
Jmol.jar fileNameToLoad -q## -w imageFormat:imageFileName
Jmol.jar fileNameToLoad --quality## --write imageFormat:imageFileName
Jmol.jar -s scriptFileNameToLoad -q## -w imageFormat:imageFileName
Jmol.jar --script scriptFileNameToLoad --quality## --write imageFormat:imageFileName
Where the ## may be a number from 1 to 100, meaning quality of JPG (75 by default), or a number from 0 to 9, meaning compression of PNG (2 by default, 9 maximum compression).
  • To have the syntax of scripts checked, without actually executing them, use either of these:
Jmol.jar -c
Jmol.jar --check
  • To have the syntax of scripts checked and also execute them, use either of these:
Jmol.jar -C
Jmol.jar --checkload
  • To have the script commands listed while running them, use either of these:
Jmol.jar -l
Jmol.jar --list
  • To get a silent startup operation, use either of these:
Jmol.jar -i
Jmol.jar --silent
  • To have output messages put to the standard system output (e.g. the terminal), instead of to the internal Jmol Java console, use either of these:
Jmol.jar -o
Jmol.jar --noconsole
  • To avoid the use of the screen display (all rendering done only in memory, hence accelerating Jmol), use either of these:
Jmol.jar -n
Jmol.jar --nodisplay 
Normally, this should be used together with other switches like -x (see below).
  • To have the application exit once finished (e.g. after running a script), use either of these:
Jmol.jar -x
Jmol.jar --exit
  • To start in debug mode, use either of these:
Jmol.jar -d
Jmol.jar --debug
  • To use an independent thread, use either of these:
Jmol.jar -t
Jmol.jar --threaded
  • To run in JSON NIO client mode:
Jmol.jar -P portNumber

You should use -J or -j to set nioContentPath and nioTerminatorMessage to the desired values. For example:

Jmol -k -P 31461 -j "nioContentPath='./%ID%/%ID%.json';nioTerminatorMessage='SCRIPT_DONE'"


Examples:

Create a JVXL file directly:

 Jmol.jar -ionx myfile.xyz iso.spt > myfile.jvxl
where File icon.gifiso.spt contains:
isosurface solvent; show isosurface
will create a File icon.gifmyfile.jvxl file containing data for a solvent surface in Jmol isosurface format (JVXL).

Create a list of measurements:

 Jmol.jar -ionx myfile.xyz measure.spt > measure.txt
where File icon.gifmeasure.spt contains:
measure allconnected (*) (*); show measurements
which generates a list of measurements. The output file, File icon.gifmeasure.txt, will contain (tab-separated):
Measurement Information
distance     1.1217928     0.112 nm     H 1 #1     C 10 #10
distance     1.4158994     0.142 nm     N 2 #2     C 6 #6
distance     1.3865448     0.139 nm     N 2 #2     C 7 #7
...

Check CIF file symmetry:

 Jmol.jar -ionx myfile.cif symmetry.spt > symmetry.txt
where File icon.gifsymmetry.spt contains:
   show unitcell;show symmetry;show spacegroup;

Anything that can be "shown" can be dumped to a file this way. And anything you can get from getProperty will do the same.

Forcing Jmol to open in a certain language

Jmol includes several languages (technically called localizations) for the user interface (top menu and pop-up menu). Jmol will open by default with the interface using the language of your operating system (ref.). However, if you need to change this:

  1. Starting Jmol 11.1.30, the language in application can be switched anytime, from the pop-up menu, "Language" item near the bottom.
  2. Or, using the scripting language: language = "de" (you must use the keyword "language" and the two-letter language code: ca, cs, de, en, es, et, fr, nl, pt, tr, or four-letter code: en_GB, en_US, pt_BR, zh_TW)
  3. This is an old method, only needed for versions below 11.1.30: If you want to force a certain language, you must start Jmol with
java -Duser.language=es -jar Jmol.jar # forces Spanish (Español)
java -Duser.language=de -jar Jmol.jar # forces German (Deutsch)
java -Duser.language=en -jar Jmol.jar # forces English
etc.

See also the procedure for the applet.