Package org.openscience.cdk.depict

Class 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 Detail

      • AUTOMATIC

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

      • DEFAULT_MM_MARGIN

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

      • DEFAULT_PX_MARGIN

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

    • 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​(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

      • 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

      • 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()

      • 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

      • 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

      • 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

      • 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