Package 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 Details

    • AUTOMATIC

      public static final double AUTOMATIC
      Magic value for indicating automatic parameters. These can be overridden by a caller.
      See Also:

    • DEFAULT_MM_MARGIN

      public static final double DEFAULT_MM_MARGIN
      Default margin for vector graphics formats.
      See Also:

    • DEFAULT_PX_MARGIN

      public static final double DEFAULT_PX_MARGIN
      Default margin for raster graphics formats.
      See Also:

  • Constructor Details

    • 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 Details

    • 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

      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

    • depict

      public Depiction depict(IReactionSet rxns) throws CDKException
      Throws:
      CDKException

    • 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:

    • withAtomColors

      public DepictionGenerator withAtomColors(IAtomColorer colorer)
      Color atom symbols using provided colorer.
      Returns:
      new generator for method chaining
      See Also:

    • withBackgroundColor

      public DepictionGenerator withBackgroundColor(Color color)
      Change the background color.
      Parameters:
      color - background color
      Returns:
      new generator for method chaining
      See Also:

    • 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:

    • 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:

    • 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:

    • withBondNumbers

      public DepictionGenerator withBondNumbers()
      Display bond numbers on the molecule or reaction. The numbers are based on the ordering of bonds 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:

    • 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

      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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • withTerminalCarbons

      public DepictionGenerator withTerminalCarbons()
      Display atom symbols for terminal carbons (i.e. Methyl) groups.
      Returns:
      new generator for method chaining
      See Also:

    • withCarbonSymbols

      public DepictionGenerator withCarbonSymbols()
      Display atom symbols for all atoms in the molecule.
      Returns:
      new generator for method chaining
      See Also:

    • 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:

    • 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:

    • withMargin

      public DepictionGenerator withMargin(double m)
      Specify a desired size of margin, this margin is a minimum amount of space around the depiction and the edge of the draw area. If you have specified withSize(double, double) larger than required the margin will grow to center the molecule/reaction. If you specify a margin you should also specify withPadding(double) which will default to a multiple of the margin amount.
      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:

    • 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:

    • 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:

    • 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 and for publication quality work all bond lengths should be the same size.
      Returns:
      new generator for method chaining
      See Also:

    • 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:

    • withDeuteriumSymbol

      public DepictionGenerator withDeuteriumSymbol(boolean v)
      Indicate whether 2H 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

    • withParams

      public DepictionGenerator withParams(RendererModel model)