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_12-0.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 [[The Toolbar|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.

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:

== 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 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 [[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/Osx|Support/OS X]], [[Support/Windows]], for example how to [[Support/Osx | create a Mac OSX native installer]].

=== 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 ====
* 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:
:# 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:
 Jmol.jar '''-g  ''WIDTHxHEIGHT'' '''
 Jmol.jar '''--geometry  ''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 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:
 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:
 <code>java '''-Xmx###m''' -jar Jmol.jar</code>
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 [[Jmol_Applet#Giving_JmolApplet_more_memory_to_work_with|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): <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: 
 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 <code>-J</code> or <code>-j</code> to set <code>nioContentPath</code> and <code>nioTerminatorMessage</code> 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|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.jar -ionx myfile.xyz measure.spt > 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.jar -ionx myfile.cif symmetry.spt > 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 [[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
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, 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
::<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]].