Difference between revisions of "Jmol Application"

From Jmol
Jump to navigation Jump to search
(more command line options)
(more descriptive wording)
Line 35: Line 35:
  
 
==== Basic options ====
 
==== Basic options ====
* Show help for command-line options: use either of these:
+
* To show help for command-line options, use either of these:
 
  java -jar Jmol.jar '''-h'''
 
  java -jar Jmol.jar '''-h'''
 
  java -jar Jmol.jar '''--help'''
 
  java -jar Jmol.jar '''--help'''
* Load a molecular file: use either of these:
+
* To load a molecular file immediately after opening Jmol, use either of these:
 
  Jmol.jar  ''' ''fileName'' '''
 
  Jmol.jar  ''' ''fileName'' '''
 
  java -jar Jmol.jar  ''' ''fileName'' '''
 
  java -jar Jmol.jar  ''' ''fileName'' '''
* Run a script: use either of these:
+
* To run a script immediately after opening Jmol, use either of these:
 
  Jmol.jar -s  ''' ''script_fileName'' '''
 
  Jmol.jar -s  ''' ''script_fileName'' '''
 
  Jmol.jar  ''' ''script_fileName'' '''
 
  Jmol.jar  ''' ''script_fileName'' '''
 
  java -jar Jmol.jar  ''' ''script_fileName'' '''
 
  java -jar Jmol.jar  ''' ''script_fileName'' '''
* Set the 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'' '''
 
  java -jar Jmol.jar  '''-g  ''WIDTHxHEIGHT'' '''
using lowercase 'x' and no spaces, e.g. <code>Jmol.jar -g 500x250</code>.
+
: 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.
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:
* 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]:
 
 
  java '''-Duser.language=ca|cs|de|en|es|et|fr|nl|pt|tr'''  -jar Jmol.jar
 
  java '''-Duser.language=ca|cs|de|en|es|et|fr|nl|pt|tr'''  -jar Jmol.jar
* Report the display speed in either frames per second or milliseconds per frame (the default):
+
* 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
* Set a path where to look for plugins for Jmol:
+
* 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
* Set memory use (see below):
+
* To specify memory use (see below):
 
  java '''-Xmx''size'' '''  -jar Jmol.jar
 
  java '''-Xmx''size'' '''  -jar Jmol.jar
  
Line 74: Line 73:
 
==== Advanced options (Jmol v.11) ====
 
==== Advanced options (Jmol v.11) ====
  
''(Some of these need testign to confirm this is the proper syntax)''
+
''(Some of these need testing to confirm this is the proper syntax)''
  
* Just check the syntax of scripts, without running 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'''
 
  java -jar Jmol.jar '''-c'''
 
  java -jar Jmol.jar '''--check'''
 
  java -jar Jmol.jar '''--check'''
  
* List script commands 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'''
 
  java -jar Jmol.jar '''-l'''
 
  java -jar Jmol.jar '''--list'''
 
  java -jar Jmol.jar '''--list'''
  
* Silent startup operation: use either of these:  
+
* To get a silent startup operation, use either of these:  
 
  java -jar Jmol.jar '''-i'''
 
  java -jar Jmol.jar '''-i'''
 
  java -jar Jmol.jar '''--silent'''
 
  java -jar Jmol.jar '''--silent'''
  
* Output is not put into console, but goes to the standard sysyout: 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'''
 
  java -jar Jmol.jar '''-o'''
 
  java -jar Jmol.jar '''--noconsole'''
 
  java -jar Jmol.jar '''--noconsole'''
  
* Do not use the graphic display (runs Jmol much faster): 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'''
 
  java -jar Jmol.jar '''-n'''
 
  java -jar Jmol.jar '''--nodisplay'''  
 
  java -jar 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).
  
* Exit the application 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'''
 
  java -jar Jmol.jar '''-x'''
 
  java -jar Jmol.jar '''--exit'''
 
  java -jar Jmol.jar '''--exit'''
  
* Use a custom pop-up menu, defined in a file: use either of these:  
+
* To use a [[Custom_Menus|custom pop-up menu]], defined in a file, use either of these:  
 
  java -jar Jmol.jar '''-m ''fileName'' '''
 
  java -jar Jmol.jar '''-m ''fileName'' '''
 
  java -jar Jmol.jar '''--menu  ''fileName'' '''
 
  java -jar Jmol.jar '''--menu  ''fileName'' '''
  
* Write an image file: use either of these:  
+
* To have Jmol export a snapshot of the rendered model to an image file, use either of these:  
 
  java -jar Jmol.jar ''fileName'' '''-w ''imageFormat'':''imageFileName'' '''
 
  java -jar Jmol.jar ''fileName'' '''-w ''imageFormat'':''imageFileName'' '''
 
  java -jar Jmol.jar ''fileName'' '''--write ''imageFormat'':''imageFileName'' '''
 
  java -jar Jmol.jar ''fileName'' '''--write ''imageFormat'':''imageFileName'' '''
 
  java -jar Jmol.jar -s ''scriptFileName'' '''-w ''imageFormat'':''imageFileName'' '''
 
  java -jar Jmol.jar -s ''scriptFileName'' '''-w ''imageFormat'':''imageFileName'' '''
 
  java -jar Jmol.jar --script ''scriptFileName'' '''--write ''imageFormat'':''imageFileName'' '''
 
  java -jar Jmol.jar --script ''scriptFileName'' '''--write ''imageFormat'':''imageFileName'' '''
Where ''imageFormat'' may be one of these (and must be followed by a colon):
+
: 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.
<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.
 
  
* Set the quality of images written to file: use either of these:  
+
* To set the quality of images written to file, use either of these:  
 
  java -jar Jmol.jar ''fileName'' '''-q##''' -w ''imageFormat'':''imageFileName''
 
  java -jar Jmol.jar ''fileName'' '''-q##''' -w ''imageFormat'':''imageFileName''
 
  java -jar Jmol.jar ''fileName'' '''--quality##''' --write ''imageFormat'':''imageFileName''
 
  java -jar Jmol.jar ''fileName'' '''--quality##''' --write ''imageFormat'':''imageFileName''
 
  java -jar Jmol.jar -s ''scriptFileName'' '''-q##''' -w ''imageFormat'':''imageFileName''
 
  java -jar Jmol.jar -s ''scriptFileName'' '''-q##''' -w ''imageFormat'':''imageFileName''
 
  java -jar Jmol.jar --script ''scriptFileName'' '''--quality##''' --write ''imageFormat'':''imageFileName''
 
  java -jar Jmol.jar --script ''scriptFileName'' '''--quality##''' --write ''imageFormat'':''imageFileName''
Where the ''##'' may be a number for JPG from 1 to 100, meaning quality (75 by default), or a number from 0 to 9 for PNG, meaning compression (2 by default, 9 maximum compression).
+
: 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:'''
  
 
'''Create a JVXL file directly:'''
 
'''Create a JVXL file directly:'''
  
 
   Jmol -ionx iso.spt myfile.xyz > myfile.jvxl
 
   Jmol -ionx iso.spt myfile.xyz > myfile.jvxl
 
+
: where {{file|iso.spt}} contains:
where:
 
* -i,--silent          silent startup operation
 
* -o,--noconsole        no console -- all output to sysout
 
* -n,--nodisplay        no display (much faster)
 
* -x,--exit            run script and exit
 
 
 
and iso.spt is:
 
 
     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>).
creates a JVXL solvent surface file.
 
  
 
'''Create a list of measurements:'''
 
'''Create a list of measurements:'''
 
   Jmol -ionx measure.spt myfile.xyz > measure.txt
 
   Jmol -ionx measure.spt myfile.xyz > measure.txt
 
+
: where {{file|measure.spt}} contains:
where measure.spt is:
 
 
  measure allconnected (*) (*);show measurements
 
  measure allconnected (*) (*);show measurements
 
+
: which generates a list of measurements. The output file, {{file|measure.txt}}, will contain (tab-separated):
generates a list of measurements.
+
Measurement Information
 
+
distance    1.1217928    0.112 nm    H 1 #1    C 10 #10
measure.txt now contains (tab-separated):
+
distance    1.4158994    0.142 nm    N 2 #2    C 6 #6
 
+
distance    1.3865448    0.139 nm    N 2 #2    C 7 #7
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:'''
 
'''Check CIF file symmetry:'''
 
   Jmol -ionx symmetry.spt myfile.cif > symmetry.txt
 
   Jmol -ionx symmetry.spt myfile.cif > symmetry.txt
 
+
: where {{file|symmetry.spt}} contains:
where symmetry.spt is:
 
 
     show unitcell;show symmetry;show spacegroup;
 
     show unitcell;show symmetry;show spacegroup;
  

Revision as of 13:34, 22 October 2008

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.

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 memory options below.
  • Double-click on a molecular coordinates file whose extension has been previously associated to Jmol (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 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 Solving Java Problems.

Command line options

Basic options

  • To show help for command-line options, use either of these:
java -jar Jmol.jar -h
java -jar Jmol.jar --help
  • To load a molecular file immediately after opening Jmol, use either of these:
Jmol.jar   fileName 
java -jar Jmol.jar   fileName 
  • To run a script immediately after opening Jmol, use either of these:
Jmol.jar -s   script_fileName 
Jmol.jar   script_fileName 
java -jar Jmol.jar   script_fileName 
  • To set the application's window size, use either of these:
Jmol.jar -g  WIDTHxHEIGHT 
Jmol.jar --geometry  WIDTHxHEIGHT 
java -jar Jmol.jar  -g  WIDTHxHEIGHT 
using lowercase 'x' and no spaces, e.g. Jmol.jar -g 500x250. 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; see also) use:
java -Duser.language=ca|cs|de|en|es|et|fr|nl|pt|tr  -jar Jmol.jar
  • 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 (512 MB maximum).

See also the procedure for the applet.

Advanced options (Jmol v.11)

(Some of these need testing to confirm this is the proper syntax)

  • To have the syntax of scripts checked, without actually executing them, use either of these:
java -jar Jmol.jar -c
java -jar Jmol.jar --check
  • To have the script commands listed while running them, use either of these:
java -jar Jmol.jar -l
java -jar Jmol.jar --list
  • To get a silent startup operation, use either of these:
java -jar Jmol.jar -i
java -jar 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:
java -jar Jmol.jar -o
java -jar Jmol.jar --noconsole
  • 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
java -jar 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:
java -jar Jmol.jar -x
java -jar Jmol.jar --exit
java -jar Jmol.jar -m fileName 
java -jar Jmol.jar --menu  fileName 
  • To have Jmol export a snapshot of the rendered model to an image file, use either of these:
java -jar Jmol.jar fileName -w imageFormat:imageFileName 
java -jar Jmol.jar fileName --write imageFormat:imageFileName 
java -jar Jmol.jar -s scriptFileName -w imageFormat:imageFileName 
java -jar Jmol.jar --script scriptFileName --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:
java -jar Jmol.jar fileName -q## -w imageFormat:imageFileName
java -jar Jmol.jar fileName --quality## --write imageFormat:imageFileName
java -jar Jmol.jar -s scriptFileName -q## -w imageFormat:imageFileName
java -jar Jmol.jar --script scriptFileName --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:

Create a JVXL file directly:

 Jmol -ionx iso.spt myfile.xyz > 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 -ionx measure.spt myfile.xyz > 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 -ionx symmetry.spt myfile.cif > 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)
  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.