Saving and Opening Files in Jmol
This Jmol Training Guide was created with funding from NIH Grant #1 R25 RR022749-01 and NSF-DUE #1323414 and #1725940. Revised 4/2021.

This Jmol Exploration was created using the Jmol Exploration Webpage Creator from the MSOE Center for BioMolecular Modeling.

version 2.0
Exploration Content

Saving a Scene in Jmol

There are various ways to save your designs in Jmol. The method described here saves the file as a Jmol png file (pngj). This file may be used as an image (for instance, in a poster), but also embeds information from the PDB coordinates in the file. There are two advantages of saving in this format:

  • You don't have to keep a copy of the pdb file on your computer.

  • You can open the file in Jmol and resume your design.

To save a pngj file in Jmol, use the command:

write pngj filename.pngj
where filename is whatever you choose to name the file.

Best Practices for Saving Scenes in Jmol

  • Save early and often. Your early versions might just be named 1, 2, 3, etc.

  • Number each version you save: filename1, filename2, etc. When you are satisfied with your final version, you can delete earlier versions. You can then name the versions you want to keep with additional information that you can remember what the design is.

  • Don't include spaces in your filename. Underscores or upper vs. lower case letters can be used to distinguish words.

  • To increase resolution for scenes you want to use in a poster, make the Jmol Display Window as large as you can on your screen, then orient your design and zoom in to use as much space in the Display Window as possible. Your design will appear in the saved file just as it appears on the screen when you save it.

  • For scenes that might be used in a poster, we suggest a white background, or a very light background. Images with dark backgrounds often print with little stripes that are not aesthetically pleasing.

  • If you are using a number of PDB files, it is helpful to include the PDB ID in the filename, although this information will also appear at the top of the Jmol Display Window when you open the file.

Here are some sample filenames that demonstrate some naming conventions and formats.

  • 08-23-2020_human_insulin_hexamer_1aiy.pngj

  • 2020-03-15_1qha_hexokinase_ATP_activeSite.pngj

  • HbF_4mqj_backbone_v1.pngj

Opening a Saved Scene in Jmol

Open Jmol. Click and drag the pnjg file into the Jmol Display Window. Continue where you left off!

Saving a Script of Your Model Design

Saving a pngj file of your model design is useful, but it doesn't save a record of the commands you used to obtain the design.

Saving a pngj file of your model design is useful, but it doesn't save a record of the commands you used to obtain the design. Scripts allow you to create an exact record of your model design. This information will be helpful if you decide to create an electronic poster or Proteopedia page to accompany a model. It is also useful to have a record of the model design if you revisit it at a later date - either to modify the design, or to refresh your memory of Jmol commands.

After you have completed your model design, click 'history' on the Jmol Console. This will generate a list of all the commands you entered – without the $ prompt or any of the Jmol messages. Copy and paste this history into a word processor or text editor.

  • For PC users: Use CtrlC to copy and CtrlV to paste (right-clicking to copy and paste in Jmol will NOT work).

  • For Mac users: Select the script, then drag and drop into a word processor.

Be sure to include the following information in your Word document before saving:

  • Date

  • PDB file name

  • Name of file(s) containing your model design – and the path to the files (folder name, etc.)

  • Information about the features that are displayed in this particular model

Editing a Script in Jmol

These next steps 'clean up' your script and make it easier for you (and others) to interpret your script.

Editing a History

Taking a few minutes to edit your history immediately after completing a design will make it much easier to 'read' the script at a later date.

  • Remove any typos that occurred while you were designing your model.

  • Remove any 'blind alleys' that you took in your model design...and later decided to remove. For example, if you changed your backbone color multiple times, you no longer need the previous 'color backbone' commands for the colors you didn't like. You'll only need the final 'color backbone' command that has the actual color of your model.

Annotating a Script

  • Any line that begins with the symbol # is ignored by Jmol, so you can add comments to your script.

  • Insert comments throughout your script.

  • Use comments to indicate what features you are depicting in each of the blocks of commands. (We call these blocks 'cassettes'.)

Here is a sample script before and after annotating.

Testing a Script

After annotating your script, you should always run the script to make sure there aren't any errors. See the sections below on opening and running a script.

Opening a Script in Jmol

Once you have your script, run it as follows:

  • Open Jmol.

  • Drag and drop your PDB file into Jmol.

  • On the Jmol Console, click 'editor'.

  • On the Editor Box that pops up, click 'script' then click 'clear' so you have an empty window.

  • Copy and paste your script into the editor window.

  • Make sure there are no extra lines or spaces at the end of the script - these will prevent the script from executing properly.

  • Click 'run'.

  • If the script doesn't execute, look in the console for error messages; the console should direct to you the location of your error. Correct the script as needed.

  • If you can't find the error, you can click on 'step' instead of 'run' to execute the script line by line. Note that you will need to click the step button to execute each individual line.

  • Alternately, you can quickly narrow your search by removing the last half of the script, then running the first half. If the first part runs without problems, you can add additional chunks of script and run again. If the first part doesn't work, break it down into smaller chunks to isolate the problem.

After you've made a change to your script and want to test out the change, run the script on a fresh PDB file. If you type 'zap' in the console window, it will refresh your screen. Then click 'run' in the editor to test the revised script.

You can make changes to your script in the 'script' box of Jmol, and rerun the script to view the change, rather than typing it into the Jmol Console. Be sure you save your final revised script into a text editor or word processor.