Package chemaxon.marvin.space

Class SurfaceColoring

  • @PublicAPI
public class SurfaceColoring
extends Object
    SurfaceColoring is an easy-to-use tool to map different properties as colors onto surfaces.
    Examples of typical usages: 
     
      
      
    • Mapping simple float values from a property grid (for example Gaussian Cube grid) to a surface.
      
      
      SurfaceColoring sc = new SurfaceColoring(surface);
      
      sc.setPropertyObject(myGrid);
      
      sc.setPropertyMethod(myGrid.getClass().getMethod("get",
              new Class[] {float.class, float.class, float.class} ));
      
      sc.addColors( blue, cyan, green, yellow, red );
      
      
      • 
      
    • Mapping own atom properties.
      
      
      SurfaceColoring sc = new SurfaceColoring(molecules, surface);
      
      sc.setPropertyMethod( myMolecule.getClass().getMethod("getAtomType", new Class[] {int.class}) );
      
          // it has to have 1 int argument
      
          // it will be called through getAtomProperty() of MoleculeInterface:
      
          // ((MoleculeInterface)molecules.get(i)).getAtomProperty().getAtomType(atomIndex);
      
      sc.setPropertyColorMapperMethod( getMethod( "getAtomColor", new Class[] {float.class} ) );
            
      
      • 
 
    

 See also SurfaceColoringInUse.html for more examples.

    • Field Detail

      • RADIUS_VDW

        public static final int RADIUS_VDW
        Is the atom property range the van der Waals radius
        See Also:
        Constant Field Values

      • RADIUS_VDW_EXTENDED

        public static final int RADIUS_VDW_EXTENDED
        Is the atom property range the van der Waals radius plus a fix value (for example the probe radius)
        See Also:
        Constant Field Values

      • RADIUS_CONSTANT

        public static final int RADIUS_CONSTANT
        Is the atom property range a fix value
        See Also:
        Constant Field Values

      • NEAREST_VALUE

        public static final int NEAREST_VALUE
        Will only the property of the nearest atom be mapped onto the surface.
        See Also:
        Constant Field Values

      • SUM_OF_VALUES

        public static final int SUM_OF_VALUES
        Will the sum of the affecting properties be mapped onto the surface.
        See Also:
        Constant Field Values

      • MEAN_VALUE

        public static final int MEAN_VALUE
        Will the mean of the affecting properties be mapped onto the surface.
        See Also:
        Constant Field Values

      • DISTANCE_WEIGHTED

        public static final int DISTANCE_WEIGHTED
        Will all affecting properties be mapped onto the surface weighted by atom distances.
        See Also:
        Constant Field Values

      • DISTANCE_FROM_VDW

        public static final int DISTANCE_FROM_VDW
        In case of distance weighted property mapping is the distance measured from the atom center extended by the van der Waals radius. Example:
        A surface vertex is affected by 2 atoms, a hydrogen and a carbon. The vertex lies exactly where the two atom spheres intersect. Thus it is nearer to the H, but the 2 atoms have to effect equally. If the distance is computed as the distance from the van der Walls radius, it will be 0 to both atoms getting equal weight properly.
        See Also:
        Constant Field Values

      • DISTANCE_FROM_VDW_EXTENDED

        public static final int DISTANCE_FROM_VDW_EXTENDED
        Is the distance measured from the atom center extended by the van der Waals radius plus a constant, typically the probe radius.
        See Also:
        Constant Field Values

      • DISTANCE_CONSTANT

        public static final int DISTANCE_CONSTANT
        Is the distance measured from the atom center extended by a constant value.
        See Also:
        Constant Field Values

      • BUILT_IN_CPK_MAPPING

        public static final int BUILT_IN_CPK_MAPPING
        Coloring by built-in cpk colors.
        See Also:
        Constant Field Values

      • BUILT_IN_RESIDUE_MAPPING

        public static final int BUILT_IN_RESIDUE_MAPPING
        Coloring by built-in residue colors.
        See Also:
        Constant Field Values

      • BUILT_IN_CHAIN_MAPPING

        public static final int BUILT_IN_CHAIN_MAPPING
        Coloring by built-in chain colors.
        See Also:
        Constant Field Values

      • BUILT_IN_SECONDARY_STRUCTURE_MAPPING

        public static final int BUILT_IN_SECONDARY_STRUCTURE_MAPPING
        Coloring by built-in secondary structure colors.
        See Also:
        Constant Field Values

      • BUILT_IN_RAINBOW_MAPPING

        public static final int BUILT_IN_RAINBOW_MAPPING
        Coloring by built-in rainbow colors.
        See Also:
        Constant Field Values

      • ATOM_PROPERTY_MAPPING

        public static final int ATOM_PROPERTY_MAPPING
        Coloring by mapping atom based property values to the surface.
        See Also:
        Constant Field Values

      • GRID_MAPPING

        public static final int GRID_MAPPING
        Coloring by mapping values form a grid to the surface.
        See Also:
        Constant Field Values

      • NO_DECREASE

        public static final int NO_DECREASE
        The property values will not decrease when getting farther from the atom center.
        See Also:
        Constant Field Values

      • DECREASE_LINEAR

        public static final int DECREASE_LINEAR
        The property values will decrease when getting farther from the atom center.
        See Also:
        Constant Field Values

      • DECREASE_SQUARE

        public static final int DECREASE_SQUARE
        The property values will decrease when getting farther from the atom center.
        See Also:
        Constant Field Values

      • DECREASE_RECIPROCAL_SQUARE

        public static final int DECREASE_RECIPROCAL_SQUARE
        The property values will decrease when getting farther from the atom center.
        See Also:
        Constant Field Values

      • COLOR_MAPPER_RAINBOW

        public static final int COLOR_MAPPER_RAINBOW
        Built-in rainbow palette will be used.
        See Also:
        Constant Field Values

      • COLOR_MAPPER_REVERSE_RAINBOW

        public static final int COLOR_MAPPER_REVERSE_RAINBOW
        Built-in reverse rainbow palette will be used.
        See Also:
        Constant Field Values

      • COLOR_MAPPER_RED_TO_BLUE

        public static final int COLOR_MAPPER_RED_TO_BLUE
        Built-in red-lightgray-blue palette will be used.
        See Also:
        Constant Field Values

      • COLOR_MAPPER_BLUE_TO_RED

        public static final int COLOR_MAPPER_BLUE_TO_RED
        Built-in blue-lightgray-red palette will be used.
        See Also:
        Constant Field Values

      • COLOR_MAPPER_GREEN_TO_BLUE

        public static final int COLOR_MAPPER_GREEN_TO_BLUE
        Built-in green-cyan-blue palette will be used.
        See Also:
        Constant Field Values

      • COLOR_MAPPER_BLUE_TO_GREEN

        public static final int COLOR_MAPPER_BLUE_TO_GREEN
        Built-in blue-cyan-green palette will be used.
        See Also:
        Constant Field Values

      • COLOR_MAPPER_FIRE

        public static final int COLOR_MAPPER_FIRE
        Built-in "fire" palette will be used.
        See Also:
        Constant Field Values

    • Constructor Detail

      • SurfaceColoring

        public SurfaceColoring​(SurfaceComponent surface)
        The given surface is to be colored after the parametrization.
        Parameters:
        surface - surface to be colored

      • SurfaceColoring

        public SurfaceColoring​(ArrayList molecules,
                       SurfaceComponent surface)
        The given surface of the given molecules is to be colored after the parametrization.
        Parameters:
        molecules - set of MoleculeInterfaces
        surface - surface to be colored

      • SurfaceColoring

        public SurfaceColoring​(ArrayList molecules,
                       SurfaceComponent surface,
                       float step)
        The given surface of the given molecules is to be colored after the parametrization.
        Parameters:
        molecules - set of MoleculeInterfaces
        surface - surface to be colored
        step - precision value, it is an approximate value of distances between surface vertices

    • Method Detail

      • setProgressBar

        public void setProgressBar​(chemaxon.marvin.space.ProgressBarInterface progressBar)

      • setSurface

        public void setSurface​(SurfaceComponent surface)
        Sets the surface for coloring. This is useful when the surface has been changed, but the grid and molecules are the same, especially in case of isosurfaces.
        Parameters:
        surface -

      • reset

        public void reset()
        Resets all parameters to the default. Useful when coloring the same surface multiple times by different parameters.

      • setPropertyObject

        public void setPropertyObject​(Object o,
                              int mappingMode)
        Atom properties will be get from this object. Typically it can be a grid.
        Parameters:
        o - object that has the property method
        mappingMode - either GRID_MAPPING or ATOM_PROPERTY_MAPPING indicating {int} or {float, float, float} arguments to the property method

      • setPropertyMethod

        public void setPropertyMethod​(Method m)
                       throws Exception
        Atom properties will be got by this method. The method will get atom type or atom index or x-y-z values as argument, depending the mapping mode was a built-in mapping or ATOM_PROPERTY_MAPPING or GRID_MAPPING. By default the parameter will be atom type. It has to return a property value.
        Parameters:
        m - custom method that computes the atom properties
        Throws:
        Exception - in case of illegal method or illegal arguments

      • setBuiltInColorMapperMethod

        public void setBuiltInColorMapperMethod​(int mode)
                                 throws Exception
        Selection of built-in color palettes through their identifier.
        Parameters:
        mode - See {#COLOR_MAPPER_RAINBOW}, {#COLOR_MAPPER_RED_AND_BLUE}.
        Throws:
        Exception

      • setBuiltInColorMapperMethod

        public void setBuiltInColorMapperMethod​(int mode,
                                        boolean twoPolePalette)
                                 throws Exception
        Selection of built-in color palettes through their identifier.
        Parameters:
        mode - See {#COLOR_MAPPER_RAINBOW}, {#COLOR_MAPPER_RED_AND_BLUE}. "param twoPolePalette if the palette should handle negative and positive values separately
        Throws:
        Exception

      • changeColorMapperColors

        public void changeColorMapperColors​(int mode)
        Switches to another built-in color palette and leaves minimum, maximum and cutoff values unchanged.
        Parameters:
        mode - internal id of the newly set color palette

      • setPropertyColorMapperRange

        public void setPropertyColorMapperRange​(double min,
                                        double max)
        Sets the range of the built-in palette.
        Parameters:
        min - Sets the minimum value the palette assignes color to.
        max - Sets the maximum value the palette assignes color to.

      • setPropertyColorMapperMethod

        public void setPropertyColorMapperMethod​(Method m)
                                  throws Exception
        Colors will be got by this method. The method will get atom properties as an argument and has to return byte[] colors.
        Parameters:
        m - custom method that returns a color to an atom property
        Throws:
        Exception - in case of illegal method or illegal arguments

      • setPropertyColorObject

        public void setPropertyColorObject​(Object o)
        Colors will be got from this object. Typically it can be a custom pelette.
        Parameters:
        o - object that has the color mapper method

      • doColoring

        public void doColoring()
                throws Exception
        This function has to be called after proper parametrization of the SurfaceColoring object in case of custom properties.
        Throws:
        Exception

      • doColoring

        public void doColoring​(int mappingMode)
                throws Exception
        This function has to be called after proper parametrization of the SurfaceColoring object in case of built-in properties.
        Parameters:
        mappingMode - identifier of the built-in method, see {#BUILT_IN_CPK_MAPPING}, {#BUILT_IN_RESIDUE_MAPPING}, {#BUILT_IN_CHAIN_MAPPING}
        Throws:
        Exception

      • setEnrtyRadiusMode

        public void setEnrtyRadiusMode​(int pvs)
        Atom properties will effect surface vertices being closer than a certain radius. The mode of getting this radius can be set here, namely van der Waals radius of the atoms, van der Waals radius plus a constant value (e.g. probe radius), or a constant radius.
        Parameters:
        pvs - See {#RADIUS_VDW}, {#RADIUS_VDW_EXTENDED}, {#RADIUS_CONSTANT}.

      • setAtomRadiusExtension

        public void setAtomRadiusExtension​(float r)
        In case of {#RADIUS_VDW_EXTENDED} mode the extension can be set.
        Parameters:
        r - radius extension in angstroms

      • setConstantAtomRadius

        public void setConstantAtomRadius​(float r)
        In case of {#RADIUS_CONSTANT} mode the constant radius can be set.
        Parameters:
        r - radius in angstroms

      • setDistanceRadiusMode

        public void setDistanceRadiusMode​(int pvs)
        In case of distance weighted property values the distance computation can be set differently from the property radius but in the same way. Example: "I would like to set 1.0 weight if the distance of the surface vertex and the atom center is the van der Waals radius, though the atom still has effect farther from the atom center."
        Parameters:
        pvs - mode as distance is computed, see {#DISTANCE_FROM_VDW}, {#DISTANCE_FROM_VDW_EXTENDED}, {#DISTANCE_CONSTANT}.

      • setDistanceRadiusExtension

        public void setDistanceRadiusExtension​(float r)
        In case of distance weighted property values radius extension can be set.
        Parameters:
        r - distance radius extension in angstroms

      • setConstantDistanceRadius

        public void setConstantDistanceRadius​(float r)
        In case of distance weighted property values constant radius can be set.
        Parameters:
        r - constant distance radius in angstroms

      • setPropertyValueDecreasement

        public void setPropertyValueDecreasement​(int pvd)
        Atom property values can decrease when getting farhter from the atom center. The way of decreasement can be set here.
        Parameters:
        pvd - See {#NO_DECREASE}, {#DECREASE_LINEAR}, {#DECREASE_SQUARE}, {#DECREASE_RECIPROCAL_SQUARE}.

      • setReciprocalConstant

        public void setReciprocalConstant​(double c)
        Atom property values will decrease by (1.0/(4*PI*c)) * (v/(d*d)).
        Parameters:
        c -

      • setWeightMode

        public void setWeightMode​(int mode)
        Way of handling values when multiple atoms have effect on one surface vertex.
        Parameters:
        mode - See {#NEAREST_VALUE}, {#SUM_OF_VALUES}, {#MEAN_VALUE}, {#DISTANCE_WEIGHTED}.

      • setHomogeneousPaletteColors

        public void setHomogeneousPaletteColors​(byte[][] colorArray)
        This is an easy way to create a homogenous palette and use it as a color mapper. There is no need to call {#setPropertyColorMapperMethod()} or {#setPropertyColorObject()}.
        Parameters:
        colorArray - array of byte[] colors.

      • getBuiltInPalettes

        public static String[] getBuiltInPalettes()
        Returns the string identifiers of the built-in palettes.
        Returns:
        array of palette names

      • getBuiltInPalette

        public static byte[][] getBuiltInPalette​(int paletteId)
        Returns the colors of a built-in palette. See {#COLOR_MAPPER_RAINBOW}, {#COLOR_MAPPER_RED_AND_BLUE}, etc.
        Parameters:
        paletteId - int identifier of a built-in palette
        Returns:
        array of the rgb colors represented as byte arrays

      • getBuiltInPalette

        public static byte[][] getBuiltInPalette​(Object paletteId)
        Returns the colors of a built-in palette.
        Parameters:
        paletteId - string identifier of a built-in palette
        Returns:
        array of the rgb colors represented as byte arrays

      • getMinimumValue

        public double getMinimumValue()
        Returns the lowest property value of the surface vertices.
        Returns:
        minimum weighted value

      • getMaximumValue

        public double getMaximumValue()
        Returns the greatest property value of the surface vertices.
        Returns:
        maximum weighted value

      • setMinimumValue

        public void setMinimumValue​(double v)
        Sets the lowest property value of the surface vertices considered.
        Parameters:
        v - minimum weighted value

      • setMaximumValue

        public void setMaximumValue​(double v)
        Sets the greatest property value of the surface vertices considered.
        Parameters:
        v - maximum weighted value

      • setLowerCutoffValue

        public void setLowerCutoffValue​(double v)
        Cutoff values can be set to the built-in two pole palettes. Values greater than the lower cutoff value and lesser than the upper cutoff value are uniformly colored.
        Parameters:
        v - lower cutoff value

      • setUpperCutoffValue

        public void setUpperCutoffValue​(double v)
        Cutoff values can be set to the built-in two pole palettes. Values greater than the lower cutoff value and lesser than the upper cutoff value are uniformly colored.
        Parameters:
        v - upper cutoff value

      • setSmoothColoringToCutoffValues

        public void setSmoothColoringToCutoffValues​(boolean b)
        See Palette.smoothColorToCutoffValues(boolean).
        Parameters:
        b -

      • updateColors

        public void updateColors()
                  throws Exception
        Useful fast updating method when the atom properties have not changed, but there is a change in the way of coloring. Typically when setting a new palette, setting cutoff values, etc.
        Throws:
        Exception