View source for Jmol Application

{{Running_Jmol_Sections}}
== 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 [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.png|Jmol Application window|center]]

Control of the molecular model is gained through several means:
# The mouse (documented in [[Mouse Manual]]).
# The application's menu and toolbar (at the top of the window), which offer
## File open, export, and print functionalities.
## A limited set of selection and rendering options, and several tools.
# 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.
# The [[Scripting|scripting language]] (same used by the applet); this is available through the <tt>File > Script...</tt> menu, which opens a "script console" or command-line environment.

== Installing Jmol Application ==
{{Installing_Jmol_Sections}}
{{clear}}
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.

To open the application, follow these instructions:

== Starting Jmol Application ==
Several ways:
* Double-click on {{File|Jmol.jar}} file. 
* Click on a previously created shortcut (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).
* 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.
* 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.

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. <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 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 '''-Xmx''size'' '''  -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:
<br><code>java '''-Xmx###m''' -jar Jmol.jar</code>
<br>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 [[Jmol_Applet#Giving_JmolApplet_more_memory_to_work_with|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'''

* 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 '''--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): <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 ''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|iso.spt}} contains:
    isosurface solvent;show isosurface
: 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:'''
  Jmol -ionx measure.spt myfile.xyz > measure.txt
: where {{file|measure.spt}} contains:
 measure allconnected (*) (*);show measurements
: which generates a list of measurements. The output file, {{file|measure.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|symmetry.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 ([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.
# 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)
# ''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=de -jar Jmol.jar   # forces German (Deutsch)</code>
::<code>java -Duser.language=en -jar Jmol.jar   # forces English</code>
::etc.

See also [[Jmol_Applet#Forcing_JmolApplet_to_open_in_a_certain_language|the procedure for the applet]].