org.openscience.cdk.depict

Class DepictionGenerator

java.lang.Object

org.openscience.cdk.depict.DepictionGenerator

public final class DepictionGenerator
extends Object

A high-level API for depicting molecules and reactions.
General Usage Create a generator and reuse it for multiple depictions. Configure how the depiction will look using with...() methods.

 DepictionGenerator dg = new DepictionGenerator().withSize(512, 512)
                                                 .withAtomColors();
 for (IAtomContainer mol : mols) {
   dg.depict(mol).writeTo("~/mol.png");
 }
 

One Line Quick Use For simplified use we can create a generator and use it once for a single depiction.

 new DepictionGenerator().depict(mol)
                         .writeTo("~/mol.png");
 

The intermediate Depiction object can write to many different formats through a variety of API calls.

 Depiction depiction = new DepictionGenerator().depict(mol);
 
 // quick use, format determined by name by path
 depiction.writeTo("~/mol.png");
 depiction.writeTo("~/mol.svg");
 depiction.writeTo("~/mol.pdf");
 depiction.writeTo("~/mol.jpg");
 
 // manually specify the format
 depiction.writeTo(Depiction.SVG_FMT, "~/mol");
 
 // convert to a Java buffered image
 BufferedImage img = depiction.toImg();
 
 // get the SVG XML string
 String svg = depiction.toSvgStr();
 

Author:

John may

Field Summary

Fields

Modifier and Type	Field and Description
static double	AUTOMATIC Magic value for indicating automatic parameters.
static double	DEFAULT_MM_MARGIN Default margin for vector graphics formats.
static double	DEFAULT_PX_MARGIN Default margin for raster graphics formats.

Constructor Summary

Constructors

Constructor and Description
DepictionGenerator() Create a depiction generator using the standard sans-serif system font.
DepictionGenerator(Font font) Create a depiction generator that will render atom labels using the specified AWT font.

Method Summary

Modifier and Type	Method and Description
Depiction	depict(IAtomContainer mol) Depict a single molecule.
Depiction	depict(IReaction rxn) Depict a reaction.
Depiction	depict(Iterable<IAtomContainer> mols) Depict a set of molecules, they will be depicted in a grid.
Depiction	depict(Iterable<IAtomContainer> mols, int nrow, int ncol) Depict a set of molecules, they will be depicted in a grid with the specified number of rows and columns.
DepictionGenerator	withAnnotationColor(Color color) Set the color annotations (e.g.
DepictionGenerator	withAnnotationScale(double scale) Set the size of annotations relative to atom symbols.
DepictionGenerator	withAromaticDisplay() When aromaticity is set on bonds, display this in the diagram.
DepictionGenerator	withAtomColors() Color atom symbols using typical colors, oxygens are red, nitrogens are blue, etc.
DepictionGenerator	withAtomColors(IAtomColorer colorer) Color atom symbols using provided colorer.
DepictionGenerator	withAtomMapHighlight() Adds to the highlight the coloring of reaction atom-maps.
DepictionGenerator	withAtomMapHighlight(Color[] colors) Adds to the highlight the coloring of reaction atom-maps.
DepictionGenerator	withAtomMapNumbers() Display atom-atom mapping numbers on a reaction.
DepictionGenerator	withAtomNumbers() Display atom numbers on the molecule or reaction.
DepictionGenerator	withAtomValues() Display atom values on the molecule or reaction.
DepictionGenerator	withBackgroundColor(Color color) Change the background color.
DepictionGenerator	withCarbonSymbols() Display atom symbols for all atoms in the molecule.
DepictionGenerator	withDeuteriumSymbol(boolean v) Indicate whether 2H should be rendered as 'D'.
DepictionGenerator	withFillToFit() Resize depictions to fill all available space (only if a size is specified).
DepictionGenerator	withHighlight(Iterable<? extends IChemObject> chemObjs, Color color) Highlight the provided set of atoms and bonds in the depiction in the specified color.
DepictionGenerator	withMappedRxnAlign(boolean val) Specifies that reactions with atom-atom mappings should have their reactants/product coordinates aligned.
DepictionGenerator	withMargin(double m) Specify a desired size of margin.
DepictionGenerator	withMolTitle() Display a molecule title with each depiction.
DepictionGenerator	withOuterGlowHighlight() Highlights are shown as an outer glow around the atom symbols and bonds rather than recoloring.
DepictionGenerator	withOuterGlowHighlight(double width) Highlights are shown as an outer glow around the atom symbols and bonds rather than recoloring.
DepictionGenerator	withPadding(double p) Specify a desired size of padding for molecule sets and reactions.
<T extends IGeneratorParameter<S>,S,U extends S> DepictionGenerator	withParam(Class<T> key, U value) Low-level option method to set a rendering model parameter.
DepictionGenerator	withRxnTitle() Display a reaction title with the depiction.
DepictionGenerator	withSize(double w, double h) Specify a desired size of depiction.
DepictionGenerator	withTerminalCarbons() Display atom symbols for terminal carbons (i.e.
DepictionGenerator	withTitleColor(Color color) Set the color titles will appear in.
DepictionGenerator	withTitleScale(double scale) Set the size of titles compared to atom symbols.
DepictionGenerator	withZoom(double zoom) Specify a desired zoom factor - this changes the base size of a depiction and is used for uniformly making depictions bigger.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

AUTOMATIC

public static double AUTOMATIC

Magic value for indicating automatic parameters. These can be overridden by a caller.

DEFAULT_MM_MARGIN

public static double DEFAULT_MM_MARGIN

Default margin for vector graphics formats.

DEFAULT_PX_MARGIN

public static double DEFAULT_PX_MARGIN

Default margin for raster graphics formats.

Constructor Detail

DepictionGenerator

public DepictionGenerator()

Create a depiction generator using the standard sans-serif system font.

DepictionGenerator

public DepictionGenerator(Font font)

Create a depiction generator that will render atom labels using the specified AWT font.

Parameters:

font - the font to use to display

Method Detail

depict

public Depiction depict(IAtomContainer mol)
                 throws CDKException

Depict a single molecule.

Parameters:

mol - molecule

Returns:

depiction instance

Throws:

CDKException - a depiction could not be generated

depict

public Depiction depict(Iterable<IAtomContainer> mols)
                 throws CDKException

Depict a set of molecules, they will be depicted in a grid. The grid size (nrow x ncol) is determined automatically based on the number molecules.

Parameters:

mols - molecules

Returns:

depiction

Throws:

CDKException - a depiction could not be generated

See Also:

depict(Iterable, int, int)

depict

public Depiction depict(Iterable<IAtomContainer> mols,
                        int nrow,
                        int ncol)
                 throws CDKException

Depict a set of molecules, they will be depicted in a grid with the specified number of rows and columns. Rows are filled first and then columns.

Parameters:

mols - molecules

nrow - number of rows

ncol - number of columns

Returns:

depiction

Throws:

CDKException - a depiction could not be generated

depict

public Depiction depict(IReaction rxn)
                 throws CDKException

Depict a reaction.

Parameters:

rxn - reaction instance

Returns:

depiction

Throws:

CDKException - a depiction could not be generated

withAtomColors

public DepictionGenerator withAtomColors()

Color atom symbols using typical colors, oxygens are red, nitrogens are blue, etc.

Returns:

new generator for method chaining

See Also:

StandardGenerator.AtomColor, StandardGenerator.Highlighting, StandardGenerator.HighlightStyle, CDK2DAtomColors

withAtomColors

public DepictionGenerator withAtomColors(IAtomColorer colorer)

Color atom symbols using provided colorer.

Returns:

new generator for method chaining

See Also:

StandardGenerator.AtomColor, StandardGenerator.Highlighting, StandardGenerator.HighlightStyle, CDK2DAtomColors, UniColor

withBackgroundColor

public DepictionGenerator withBackgroundColor(Color color)

Change the background color.

Parameters:

color - background color

Returns:

new generator for method chaining

See Also:

BasicSceneGenerator.BackgroundColor

withOuterGlowHighlight

public DepictionGenerator withOuterGlowHighlight()

Highlights are shown as an outer glow around the atom symbols and bonds rather than recoloring. The width of the glow can be set but defaults to 4x the stroke width.

Returns:

new generator for method chaining

See Also:

StandardGenerator.Highlighting, StandardGenerator.HighlightStyle

withOuterGlowHighlight

public DepictionGenerator withOuterGlowHighlight(double width)

Highlights are shown as an outer glow around the atom symbols and bonds rather than recoloring.

Parameters:

width - width of the outer glow relative to the bond stroke

Returns:

new generator for method chaining

See Also:

StandardGenerator.Highlighting, StandardGenerator.HighlightStyle

withAtomNumbers

public DepictionGenerator withAtomNumbers()

Display atom numbers on the molecule or reaction. The numbers are based on the ordering of atoms in the molecule data structure and not a systematic system such as IUPAC numbering. Note: A depiction can not have both atom numbers and atom maps visible (but this can be achieved by manually setting the annotation).

Returns:

new generator for method chaining

See Also:

withAtomMapNumbers(), StandardGenerator.ANNOTATION_LABEL

withAtomValues

public DepictionGenerator withAtomValues()

Display atom values on the molecule or reaction. The values need to be assigned by

 atom.setProperty(CDKConstants.COMMENT, myValueToBeDisplayedNextToAtom);
 

Note: A depiction can not have both atom numbers and atom maps visible (but this can be achieved by manually setting the annotation).

Returns:

new generator for method chaining

See Also:

withAtomMapNumbers(), StandardGenerator.ANNOTATION_LABEL

withAtomMapNumbers

public DepictionGenerator withAtomMapNumbers()

Display atom-atom mapping numbers on a reaction. Each atom map index is loaded from the property CDKConstants.ATOM_ATOM_MAPPING. Note: A depiction can not have both atom numbers and atom maps visible (but this can be achieved by manually setting the annotation).

Returns:

new generator for method chaining

See Also:

withAtomNumbers(), CDKConstants.ATOM_ATOM_MAPPING, StandardGenerator.ANNOTATION_LABEL

withAtomMapHighlight

public DepictionGenerator withAtomMapHighlight()

Adds to the highlight the coloring of reaction atom-maps. The optional color array is used as the pallet with which to highlight. If none is provided a set of high-contrast colors will be used.

Returns:

new generator for method chaining

See Also:

withAtomMapNumbers(), withAtomMapHighlight()

withAtomMapHighlight

public DepictionGenerator withAtomMapHighlight(Color[] colors)

Adds to the highlight the coloring of reaction atom-maps. The optional color array is used as the pallet with which to highlight. If none is provided a set of high-contrast colors will be used.

Parameters:

colors - array of colors

Returns:

new generator for method chaining

See Also:

withAtomMapNumbers(), withAtomMapHighlight()

withMolTitle

public DepictionGenerator withMolTitle()

Display a molecule title with each depiction. The title is specified by setting the CDKConstants.TITLE property. For reactions only the main components have their title displayed.

Returns:

new generator for method chaining

See Also:

BasicSceneGenerator.ShowMoleculeTitle

withRxnTitle

public DepictionGenerator withRxnTitle()

Display a reaction title with the depiction. The title is specified by setting the CDKConstants.TITLE property on the IReaction instance.

Returns:

new generator for method chaining

See Also:

BasicSceneGenerator.ShowReactionTitle

withMappedRxnAlign

public DepictionGenerator withMappedRxnAlign(boolean val)

Specifies that reactions with atom-atom mappings should have their reactants/product coordinates aligned. Default: true.

Parameters:

val - setting value

Returns:

new generator for method chaining

withAnnotationColor

public DepictionGenerator withAnnotationColor(Color color)

Set the color annotations (e.g. atom-numbers) will appear in.

Parameters:

color - the color of annotations

Returns:

new generator for method chaining

See Also:

StandardGenerator.AnnotationColor

withAnnotationScale

public DepictionGenerator withAnnotationScale(double scale)

Set the size of annotations relative to atom symbols.

Parameters:

scale - the scale of annotations

Returns:

new generator for method chaining

See Also:

StandardGenerator.AnnotationFontScale

withTitleColor

public DepictionGenerator withTitleColor(Color color)

Set the color titles will appear in.

Parameters:

color - the color of titles

Returns:

new generator for method chaining

See Also:

RendererModel.TitleColor

withTitleScale

public DepictionGenerator withTitleScale(double scale)

Set the size of titles compared to atom symbols.

Parameters:

scale - the scale of titles

Returns:

new generator for method chaining

See Also:

RendererModel.TitleFontScale

withTerminalCarbons

public DepictionGenerator withTerminalCarbons()

Display atom symbols for terminal carbons (i.e. Methyl) groups.

Returns:

new generator for method chaining

See Also:

StandardGenerator.Visibility

withCarbonSymbols

public DepictionGenerator withCarbonSymbols()

Display atom symbols for all atoms in the molecule.

Returns:

new generator for method chaining

See Also:

StandardGenerator.Visibility

withHighlight

public DepictionGenerator withHighlight(Iterable<? extends IChemObject> chemObjs,
                                        Color color)

Highlight the provided set of atoms and bonds in the depiction in the specified color. Calling this methods appends to the current highlight buffer. The buffer is cleared after each depiction is generated (e.g. depict(IAtomContainer)).

Parameters:

chemObjs - set of atoms and bonds

color - the color to highlight

Returns:

new generator for method chaining

See Also:

StandardGenerator.HIGHLIGHT_COLOR

withSize

public DepictionGenerator withSize(double w,
                                   double h)

Specify a desired size of depiction. The units depend on the output format with raster images using pixels and vector graphics using millimeters. By default depictions are only ever made smaller if you would also like to make depictions fill all available space use the withFillToFit() option. Currently the size must either both be precisely specified (e.g. 256x256) or automatic (e.g. AUTOMATICxAUTOMATIC) you cannot for example specify a fixed height and automatic width.

Parameters:

w - max width

h - max height

Returns:

new generator for method chaining

See Also:

withFillToFit()

withMargin

public DepictionGenerator withMargin(double m)

Specify a desired size of margin. The units depend on the output format with raster images using pixels and vector graphics using millimeters.

Parameters:

m - margin

Returns:

new generator for method chaining

See Also:

BasicSceneGenerator.Margin

withPadding

public DepictionGenerator withPadding(double p)

Specify a desired size of padding for molecule sets and reactions. The units depend on the output format with raster images using pixels and vector graphics using millimeters.

Parameters:

p - padding

Returns:

new generator for method chaining

See Also:

RendererModel.Padding

withZoom

public DepictionGenerator withZoom(double zoom)

Specify a desired zoom factor - this changes the base size of a depiction and is used for uniformly making depictions bigger. If you would like to simply fill all available space (not recommended) use withFillToFit(). The zoom is a scaling factor, specifying a zoom of 2 is double size, 0.5 half size, etc.

Parameters:

zoom - zoom factor

Returns:

new generator for method chaining

See Also:

BasicSceneGenerator.ZoomFactor

withFillToFit

public DepictionGenerator withFillToFit()

Resize depictions to fill all available space (only if a size is specified). This generally isn't wanted as very small molecules (e.g. acetaldehyde) may become huge.

Returns:

new generator for method chaining

See Also:

BasicSceneGenerator.FitToScreen

withAromaticDisplay

public DepictionGenerator withAromaticDisplay()

When aromaticity is set on bonds, display this in the diagram. IUPAC recommends depicting kekulé structures to avoid ambiguity but it's common practice to render delocalised rings "donuts" or "life buoys". With fused rings this can be somewhat confusing as you end up with three lines at the fusion point.
By default small rings are renders as donuts with dashed bonds used otherwise. You can use dashed bonds always by turning off the StandardGenerator.DelocalisedDonutsBondDisplay.

Returns:

new generator for method chaining

See Also:

StandardGenerator.ForceDelocalisedBondDisplay, StandardGenerator.DelocalisedDonutsBondDisplay

withDeuteriumSymbol

public DepictionGenerator withDeuteriumSymbol(boolean v)

Indicate whether ²H should be rendered as 'D'. Default: true.

Parameters:

v - the value

Returns:

new generator for method chaining

withParam

public <T extends IGeneratorParameter<S>,S,U extends S> DepictionGenerator withParam(Class<T> key,
                                                                                     U value)

Low-level option method to set a rendering model parameter.

Type Parameters:

T - option key type

U - option value type

Parameters:

key - option key

value - option value

Returns:

new generator for method chaining