Jmol Application

From Jmol

You do not have permission to edit this page, for the following reasons:

• The action you have requested is limited to users in the group: Users.
• You must confirm your e-mail address before editing pages. Please set and validate your e-mail address through your user preferences.

You can view and copy the source of this page:

{{Lang: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 ''script_commands'' -s ''scriptFileName'' -j ''script_commands'' ''' : which will be run in that order irrespective of their actual order in the command line. Either of the 4 may be omitted. Case of the "-J" is significant when combined with "-s". ===== 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]].

Return to Jmol Application.