11. Depict Toolkit

Back to Table of Contents

11.1 Introduction

On the surface, depictions and conformations seem similar: one contains (x,y) pairs, the other (x,y,z) triplets. However, there are significant differences between the two:

• A depiction is a schematic representation of a molecule. It is a visualization tool, but doesn't contain information about the molecule itself.

• A conformation contains measured or computed data about a molecule. Although it can be used for visualization, it can also be used to compute chemical properties, to uniquely identify a particular physical state a molecule might exhibit, and so forth. Conformations are even used as identifiers - see the Daylight Theory Manual for a complete discussion.

In spite of the fundamental difference in the information contained in these two objects, their representations are similar, so many of the functions that operate one also operate on the other.

There are two key differences in the way the Daylight Toolkit treats conformations and depictions:

1. A 2D depiction can be filled in directly from a molecule using a built-in algorithm that generates x,y coordinates for each atom. No such algorithm is available for 3D conformations. (Such algorithms are available from Daylight as separate programs. They are far more complex and computationally expensive than 2D depiction).

2. The many and varied uses of 3D conformations require flexibility and simplicity. The Daylight Toolkit provides access functions such that applications can perform their own custom operations on conformations. There are no facilities for displaying 3D conformations directly, hence no facilities for adding labels, setting graphics attributes, and so forth. However, functions are provided to rotate a conformation to an arbitrary orientation, and to transform a 3D conformation to a 2D depiction by projecting it on to the XY plane.

Although the units used for depictions and conformations can be considered arbitrary, the Toolkit assumes that they are in units of angstroms for the purposes of drawing atom labels in a depiction. If a depiction is made in which the bonds are longer, labels will be correspondingly smaller, and vice-versa.

11.2 Depictions

A depiction is a two-dimensional representation of a molecule. As such, it contains (x, y) coordinates for the the atoms in the molecule, and several attributes that control the graphical appearance of the depiction.

The Daylight Toolkit does not have any I/O capabilities built in. Instead, it relies on a Drawing Library consisting of about a dozen functions. Although several versions of the Drawing Library are available from Daylight, including one for serial graphics terminals and one for the X Window System, the Drawing Library is not considered part of the Toolkit per se: It is possible to write your own Drawing Library and attach it to the Toolkit. The specifications required by the Daylight Toolkit of the Drawing Library are given later in this chapter.

Each graphical attribute of a depiction is represented in the Toolkit by a unique integer value called a GA (Graphical Attribute). Each GA represents a complete specification of all graphical features such as color, line width, and line style. It is up to the Drawing Library and the application program to "agree" on the meaning of each GA; the Daylight Toolkit does not know or care about the meaning of a GA; the Toolkit associates GAs with objects (atoms, bonds, etc) and passes them along to the Drawing Library when a depiction is drawn.

The Drawing Library will always accept one special graphics attribute, named DX_GA_UNSPEC. It represents an unspecified graphics attribute; reasonable defaults are used for objects whose graphics attributes are unspecified. The following functions are used for depiction objects:

dt_alloc_depiction(molecule molec) => depiction

Creates and returns a depiction for the given molecule. Note that there is no theoretical limit to the number of pictorial representations that may be created for the same molecule, though an implementation may impose a practical limit. The initial properties of the depiction are as follows: All initial (x, y) coordinate values are 0; the isomeric, compressed, and schematic attributes are all initially FALSE.

Each depiction object has a base object: the molecule it represents (see dt_base()). If the base molecule is modified (i.e. if dt_mod_on() is invoked), the depiction will automatically be deallocated and its handle revoked.

dt_depict(depiction pic) => boolean

Draws a two-dimensional rendition of the underlying molecule using calls to the Drawing Library. The drawing uses the current coordinates and attributes of the given depiction.

dt_calcxy(depiction pic) => boolean

Sets the coordinates for the atoms of the given depiction (i.e. generates a 2D schematic representation), using an internal algorithm. Note that the coordinates are set according to the current attributes of the depiction (i.e. whether it is to be drawn in isomeric, compressed or schematic form) and the current attributes of the underlying molecule. If any of these attributes are changed, the coordinates may become outdated. It is the user's responsibility to recalculate them in this case.

dt_setbondstyles(depiction pic) => boolean

Sets the chiral bond styles of a depiction whose molecule contains chiral information. That is, attempts to determine a reasonable set of "in" and "out" wedges, cis and trans markings, and so forth, to accurately represent the chiral information present in the molecule. Note that this function must be applied after dt_calcxy() has been called or some other method of setting coordinates has been applied, as the bond styles depend on the particular layout of the depiction.

dt_bondstyle(dt_Handle deph, dt_Handle ah, dt_Handle bh) => integer

Returns the style of bond in depiction, relative to an atom. The values that are returned are symbolic constants defined in the Depict Toolkit's header file.

dt_ga(depiction pic, object ob) => integer

Returns the graphics attribute associated with object ob in the given depiction. If ob is an atom, the attribute is the one used when drawing the atomic symbol. If ob is a bond, the attribute is the one used when drawing the bond. If ob is an aromatic cycle, the attribute is the one used when drawing the circle indicating its aromaticity.

dt_setga(depiction pic, object ob, integer ga) => boolean

Set the graphical attribute associated with the given object in the given depiction.

dt_label1(depiction pic, object ob) => string
dt_label2(depiction pic, object ob) => string

Return the first and second string labels associated with the given object in the given depiction. If an error is detected returns the invalid string. String labels may be associated with any constituent of the underlying molecule, including the entire molecule itself. Depending on the type of the constituent, the label will be used in different ways. The first atom label is drawn to the lower left of the atomic symbol. The two bond labels are drawn above and below the bond. Cycle labels are unused. Labels for the whole molecule are placed above and below the depiction as a whole.

dt_setlabel1(depiction pic, object ob, string label) => boolean dt_setlabel2(depiction pic, object ob, string label) => boolean

Set the first and second string labels associated with the given object in the given depiction. Returns TRUE if no errors are detected.

dt_label1ga(depiction pic, object ob) => integer
dt_label2ga(depiction pic, object ob) => integer

Returns the graphic attribute of the first and second string labels of the given object in the given depiction.

dt_setlabel1ga(depiction pic, object ob, integer ga) => boolean
dt_setlabel2ga(depiction pic, object ob, integer ga) => boolean

Sets the graphical attributes of the first and second string labels of the given object in the given depiction. Returns TRUE if no errors are detected.

dt_isomeric(depiction pic) => boolean

Returns TRUE if the depiction includes isomeric information.

dt_setisomeric(depiction pic, boolean iso) => boolean

Sets the isomeric depiction status of the given depiction to the given value. (A value of TRUE means that isomeric information will be drawn.) Returns TRUE if no errors are detected.

dt_compressed(depiction pic) => boolean

Returns TRUE if chains of like atoms are compressed in the depiction.

dt_setcompressed(depiction pic, boolean comp) => boolean

Sets the compressed depiction status of the given depiction to the given value. (A value of TRUE means that chains of like atoms are compressed.)

dt_schematic(depiction pic) => boolean

Returns TRUE if the depiction is simplified to the point of a schema. (All normal carbons are suppressed, no circles in aromatic rings, etc.)

dt_setschematic(depiction pic, boolean schema) => boolean

Sets the schematic depiction status of the given depiction to the given value. (A value of TRUE means that the depiction is simplified to a schema.) Return TRUE if no errors are detected.

dt_orient(depiction pic) => integer

Returns the orient property of the depiction.

dt_setorient(depiction pic, integer value) => boolean

Sets the orient property of the depiction. The value controls the allowed orientations of the depiction.

11.3 Conformations

A conformation is an association of 3D Cartesian coordinates with the atoms of a molecule; there is an (x, y, z) coordinate for each atom. It is a "lower level" object than a 2D depiction: A 2D depiction is assumed to be useful only in that it can be shown to the user, whereas a 3D conformation might be the basis for chemical modeling, computing charge density, energy calculations, and so forth.

Unlike a depiction, there are no mechanisms for drawing conformations (e.g. no labels, graphics attributes, etc.), but a 3D conformation can be projected on to a 2D depiction.

dt_alloc_conformation(molecule molec) => conformation

Returns a conformation for the given molecule. All (x,y,z) coordinates in the conformation are set to 0. Note that there is no theoretical limit to the number of conformations that may be created for the same molecule, though there may be practical limits.

Each conformation object has a base object: the molecule it represents (see dt_base()). If the base molecule is deallocated the conformation will automatically be deallocated and its handle revoked. Note that, unlike depiction objects, conformation objects are not deallocated when the molecule is modified.

dt_project(depiction pic, conformation conf) => boolean

Sets the coordinates for the atoms of the given depiction by projecting the given conformation's atom coordinates to the x/y plane (i.e. ignore the z axis).

11.4 Modifying Depictions and Conformations

The following functions apply to both depictions and conformations.

dt_setcoord(object ob, atom at, real x, real y, real z) => boolean

Sets the (x,y) or (x,y,z) coordinates of the atom in the depiction or conformation, respectively. If ob is a depiction, z is ignored but must be present.

dt_zerocoord(object ob) => boolean

Zeros the (x,y) or (x,y,z) cartesian coordinates of the atom in the depiction or conformation, respectively.

dt_getcoord(object ob, atom at, RETURN real x, RETURN real y, RETURN real z) => boolean

Gets the (x,y) or (x,y,z) cartesian coordinates of the atom in the depiction or conformation, respectively. If ob is a depiction, z is not altered but must be present. Note that x, y, and z are return values (e.g. are modified by the function).

dt_rotate(object ob, real x, real y, real z, real theta) => boolean

If ob is a conformation, modifies the 3D coordinates associated with the atoms in the conformation ob, by rotating them by angle theta around an axis defined by x, y, and z.

The axis of rotation is the line from the origin to the point (x,y,z). Note that its length is irrelevant, only its direction is of interest; you can think of (x,y,z) as a vector. For this reason, at least one of x, y, and z must be nonzero. The angle of rotation is given by theta and is expressed in radians. The sense of the angle is given by the "right hand rule": if you curl the fingers of your right hand and extend your thumb outward as though hitchhiking, your fingers curl in the direction of positive theta when your thumb is pointing in the vector's direction.

If ob is a depiction this function modifies the 2D coordinates associated with the atoms in the depiction by rotating them through angle theta about the origin. Since points are rotated about the origin, the values x, y, and z are ignored. The angle of rotation given by theta, expressed in radians, is positive in the counterclockwise direction.

Returns TRUE if no errors are detected.

dt_translate(object ob, real dx, real dy, real dz) => boolean

Modifies the (x,y) or (x,y,z) coordinates associated with the atoms in the depiction or conformation, respectively, by adding dx, dy, and dz to the x, y, and z coordinates of each atom. If ob is a depiction, the parameter dz must be present but is ignored.

dt_scale(object ob, real cx, real cy, real cz) => boolean

Modify the (x,y) or (x,y,z) coordinates of a depiction or conformation, respectively, associated with the atoms in ob by multiplying their values by the given factors. If ob is a depiction, cz is ignored but must be present.

11.5 The Drawing Library

The Drawing Library provides all I/O for Daylight Toolkit depictions. All actual drawing (e.g. the results of calling the function dt_depict()) is done through calls to the Drawing Library. The Drawing Library is not an intrinsic part of the Daylight Toolkit, but rather is a replaceable module: Different versions can be attached to allow the Daylight Toolkit to work in a variety of environments, such as the X Window System, serial terminals, PostScript devices, and so forth.

Several example drawing libraries are supplied with the Daylight Depict Toolkit; they can be found in $DY_ROOT/contrib/src/depict. If you are writing a new Drawing Library, we suggest you begin with these functioning examples.

Back to Table of Contents
Go to previous chapter Fingerprint Toolkit
Go to next chapter Program Objects Toolkit.