# &app; manual

# &app; Manual V&manrevision;

2006-2012
Jean Bréfort

&legal;

GNOME Documentation Project
Jean
Bréfort

     jean.brefort@normalesup.org

&app; Manual V&manrevision;
&date;

Jean Bréfort jean.brefort@normalesup.org

GNOME Documentation Project

&app; Manual V0.3
April 2010

Jean Bréfort jean.brefort@normalesup.org

GNOME Documentation Project

&app; Manual V0.2
September 2008

Jean Bréfort jean.brefort@normalesup.org

GNOME Documentation Project

&app; Manual V0.1
February 2006

Jean Bréfort jean.brefort@normalesup.org

GNOME Documentation Project

This manual describes version &appversion; of &app;.

## Feedback

To report a bug or make a suggestion regarding the &app; application or this manual, go to the &app; home page.

&app; allows you to display molecular structures.

## Introduction

The &app; application is a simple molecular structures visualizer.

## Getting started

### To Start &app;

You can start &app; in the following ways:

Applications list

  Choose Molecules Viewer. It might be listed either in the Education or Science category.

Command line

  Type `gchem3d`, then press Return.

### When You Start &app;

When you start &app;, the following window is displayed:

#### &app; main window

Screenshot of the &app; main window.

The &app; window contains the following elements:

Menubar

  The menus on the menubar contain all of the commands you need to work with files in &app;.

Display area

  The display area contains the contents of an opened file if any.

### To Open a File

To open a file, choose File Open to display the Open File dialog. Select the file that you want to open, then click OK. The file is displayed in the &app; main window.

&app; can open files on a distant server.

&app; can open several file formats. Available formats are:

- ChemML files (*.cml)

- MDL MOL files, MDL Structure Data files (*.mol;*.sd;*.sdf)

- PDB files (*.pdb;*.ent)

- XYZ Coordinate Format files (*.xyz)

You can open multiple files in &app;. The application displays each file in its own window.

Recently opened file appear in the File Open recent sub-menu.

A molecule can also be loaded from it's InChI or a SMILES representation as described in the To Load a Molecule from a String section.

### To Open Multiple Files from a Command Line

You can run &app; from a command line and open a single file or multiple files. To open multiple files from a command line, type the following command, then press Return:

`gchem3d file1 file2 file3`

## Usage

### To Save the View as an Image

To open a file, choose File Save as Image... to display the Save as image dialog. Select a file name and, if wanted, a file type and a size, then click OK. Default image size is 300 pixels wide and 300 pixels high.

Supported types are VRML, Postscript, Encapsulated Postscript, PDF, and all types that GdkPixbuf can export. You'll find an exact list in the drop-down file type menu.

If no file type is specified, &app; tries to determine the type from the file name. If it does not succeed, the default type (VRML) will be used.

An appropriate extension will be added to the file name if none is found.

PostScript and PDF files can also be obtained with the Print command.

### To Load a molecule from an InChI or a SMILES

To import a molecule from a string, choose Tools Import molecule... . A dialog box pops up:

#### The string input dialog box.

Screenshot of the empty string input dialog box.

You need to input a valid string such as this SMILES:

#### The string input dialog box with a SMILES inside.

Screenshot of the string input dialog box with the SMILES for toluene.

Please note that if you use an InChI as input, you must not skip the InChI= prefix.

After activating the Apply button you get:

#### The 3D View.

Screenshot of the 3d view corresponding to the input SIMLES.

### To Use the Tools Menu with a molecule.

When a molecule is displayed, several menu items appear in the Tools menu:

Open in GChemPaint

  Opens the 2D editor GChemPaint with a copy of the molecule. The molecule has been converted to a 2D representation using the OpenBabel library.

  With the trans-1,2-dimethylcyclohexane molecule, you get:

  #### Initial view in GChem3D.

  Screenshot of the initial view in GChem3D.

  And after conversion in GChemPaint:

  #### The molecule in GChemPaint.

  Screenshot of the 2D-model of trans-1,2-cyclohexane molecule after conversion.

Open in GChemCalc

  Opens the chemical calculator GChemCalc with a copy of the molecule formula and performs the available calculations. With the same molecule as above, you get:

  #### The molecule in GChemCalc.

  Screenshot of trans-1,2-cyclohexane molecule in GChemCalc.

Generate InChI

  Generates the InChI for the molecule and displays it in a popup window.

Generate InChIKey

  Generates the InChIKey for the molecule and displays it in a popup window.

Generate SMILES

  Generates the SMILES for the molecule and displays it in a popup window.

Search in an online database

  The molecule can be searched for in online databases, either predefined or user defined.

  To add custom databases, you need to create an xml file listing them. The file must be named .gchemutils/databases.xml in you home directory.

  Entries inside the file must be inside a databases top node, each entry being a database node with children name, uri, and class, like for the NIST webbook (which is predefined):

        <database>
          <name>NIST webbook</name>
          <uri>http://webbook.nist.gov/cgi/cbook.cgi?Name=%K&Units=SI"</uri>
          <class>molecule</class>
        </database>

  where %K will be replaced by the InChIKey. Tou use the InChI, the code is %I and for the SMILES, %S.

  The class node is for future usages and must contain molecule.

### To Print the View

To print a file, choose File Print... .

&app; uses a 300 dpi resolution when printing.

You might want to change the background color before printing.

File Preview opens a window with a preview of the printed output.

To tune the printed output, choose File Page setup... as explained below.

#### The page setup dialog.

the first tab of the dialog concerns the paper and margins setup. Headers and footers are not supported in the version of &app;

##### The Page Setup tab.

Screenshot of page setup dialog.

The second tab allows you to choose the scale of the output. With no scaling or scaling at 100%, the output will have the same size in points as the size in pixels on the screen. If you choose automatic scaling, you can make the output fill the available space either horizontally, vertically, or both (none of the options is equivalent to no scaling).

Printing to more than one page is not supported in this version of &app;

##### The Print Scale tab.

Screenshot of the printing scale page.

### To Change the Model Options

&app; is able to display a molecule using four model types: the ball and stick model, the compact model, the cylinders model, and the wireframe model. The first one is the default. Multiple bonds are displayed as such in the ball and stick model.

#### The Balls and Sticks model.

Screenshot of the balls and sticks model.

#### The Spacefill model.

Screenshot of the spacefill model.

#### The Cylinders model.

Screenshot of the cylinders model.

#### The Wireframe model.

Screenshot of the wireframe model.

To change the mode, choose either View Balls and sticks , View Space filling , View Cylinders , or View Wireframe .

The model can also be selected from the command line: `gchem3d --display3d=cylinders` or `gchem3d -d cylinders` will open &app; with the cylinders model active. The other models are entered as ball&stick, spacefill, and wireframe.

You can also change the orientation. Just click somewhere in the view and drag the mouse until you get the wanted orientation.

### To Change the Background Color

To change the backgound color, choose View Background color and select the appropriate color in the palette, or choose a custom color.

The background color can also be selected from the command line: `gchem3d --bgcolor=white` or `gchem3d -b white` will open &app; with a white background in windows. Recognized strings are black (the default), white, and #rrggbb where r, g, and b are hexadecimal digits.

### To Ask a Question

If you choose Help Ask a question, your mail agent should pop up with a new message to the Gnome Chemistry Utils mailing list.

Another way to get some help is to connect on the #gchemutils channel at irc.gimp.net and ask your question there (if you are not alone on the channel).

### To Find the Gnome Chemistry Utils on the Web.

If you choose Help Gnome Chemistry Utils on the web, the default web browser should pop up and display the main page for the Gnome Chemsitry Utils.

The main page is http://gchemutils.nongnu.org and the project page at savannah http://savannah.nongnu.org/projects/gchemutils.

### To Report a Bug

To report a bug, you must use the bug page for the Gnome Chemistry Utils at Savannah. You can access it by choosing Help Report Bugs (hopefully you'll have only one at once to report).

You can also type the bug report page address directly in the browser. The bug repository is at https://savannah.nongnu.org/bugs/?group=gchemutils

## License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A copy of the GNU General Public License is included as an appendix to the GNOME Users Guide. You may also obtain a copy of the GNU General Public License from the Free Software Foundation by visiting their Web site or by writing to

        Free Software Foundation, Inc.
        51 Franklin St - Fifth Floor
        Boston, MA 02111-1307
        USA