Title : RFC Custom Graphics in the VizMapper and Dynamic Mapping

Editor(s): Mike Smoot KeiichiroOno

Date: 2/12/2010

Status: init


3/9/2010 - KeiichiroOno: start working on actual design and implementation 4/9/2010 - KeiichiroOno: start designing dynamic graphics function. 4/13/2010 - KeiichiroOno: Static image custom graphics feature implemented in branch code. 6/15/2010 - KeiichiroOno: Code had been merged to trunk. Will be available as 2.8.0 feature.


We would like to provide some mechanism for allowing users to specify custom graphic images that can be applied to a network using the VizMapper. This includes new mapping from attributes to custom graphics.


The goal of this RFC is to explore ideas for bringing custom graphics out of the programmer-only domain and allow normal users to specify custom graphics for nodes using normal Cytoscape tools like the VizMapper.

Use Cases

Implementation Plan

Basic Mechanism

CyCustomGraphics Interface

To implement this function, I defined a new interface called CyCustomGraphics

   1 public interface CyCustomGraphics <T> {
   2         /**
   3          * Display name is a simple description of this image object.
   4          *
   5          * May not be unique.
   6          *
   7          * @return display name as String.
   8          */
   9         public String getDisplayName();
  10         public void setDisplayName(final String displayName);
  12         public Collection<T> getCustomGraphics();
  14         public Image getImage();
  15         public Image resizeImage(int width, int height);
  17                 /**
  18          * Map of properties, i.e., details of this object.
  19          * Key is the property name, and Value is prop object.
  20          *
  21          * @return
  22          */
  23         public Map<String, CustomGraphicsProperty<?>> getProps();
  25         public void update();
  26 }

and then we can define a new Visual Property NODE_CUSTOM_GRAPHICS:

NODE_CUSTOM_GRAPHICS("Node Custom Graphics", "nodeCustomGraphics",
                                         "node.customGraphics", "defaultNodeCustomGraphics",
                                         CyCustomGraphics.class, new NodeCustomGraphicsProp(),
                                         new GraphicsParser(), true, true)

By implementing CyCustomGraphics interface, plugin writers can use this framework to create their own version of Custom Graphics. In short, this is just a new Visual Property. Users can use current VizMap UI to map attributes to graphics.

Custom Graphics Types

There are two types of custom graphics.

Static image is just an mapping from an image object to custom graphics. However, a dynamic image is controlled by an associated node attribute. This requiers an additional layer to create CyCustomGraphics object on-the-fly (will be discussed later).

Static Custom Graphics Mapping

We can create discrete mapping from attribute value to URL image, but this type of mapping can be handled by an extended PassThroughMapping. Currently, Pass Through Mapping only supports String object to label. However, it can be extended to accept other objects including custom graphics. If a list of URL strings is mapped to NODE_CUSTOM_GRAPHICS, the Pass Through Mapping generates Image objects from the URL and wrap it with CyCustomGraphics.

Static Image Custom Graphics Pool

All Custom Graphics generated from static (bitmap) images will be stored in a manager object called CustomGraphicsPool. This collection of images will be saved to session or .cytoscape/images directory.

Dynamic Custom Graphics and Custom Mapping

Static images can be handled in the existing UI/framework of VizMapper. However, for graphics generated dynamically from attributes (Dynamic Graphics), we need an additional layer. This problem can be handled by adding new kind of Visual Mapping. Currently, we have three types of mappings: continuous, discrete, and passthrough. All of these implements the following interface:

If we need to add a new type of mapping, new editor component is necessary. To solve this problem, we can define a new mapping type called CustomMapping:

   1 public interface CustomMapping<V> {
   2         public Component getEditor();
   3 }

If the new mappings implement this interface AND ObjectMapping, then users can edit arbitrary many properties of the Custom Graphics objects.

Define How to Create Dynamic Custom Graphics (Custom Graphics Property)

To generate Custom Graphics dynamically, we need details about how to generate graphics from data. Suppose a user wants to create a histogram Custom Graphics from node attributes. In that case, Cytoscape needs the following information:

  1. Which node attribute is associated with the length of the bar?
  2. Appearance of the chart (width of the bars, bar color, etc.)
  3. Size of the histogram graphics (px)

These relationships will be encoded as CustomGraphicsProperty:

Basically, this is a sort of sub Visual Properties only for NODE_CUSTOM_GRAPHICS.

Sample Dynamic Custom Graphics

Custom Mapping Editor

Each custom mapping should have a GUI editor component.


Each editable field represents a CustomGraphicsProperty.

Custom Mapping Example

   1 public class SingleBarChartGeneratorMapping extends
   2                 AbstractMapping<CyCustomGraphics<?>> implements
   3                 CustomMapping {
   5         private final CustomGraphicsBuilder builder;
   7         public SingleBarChartGeneratorMapping(Class<CyCustomGraphics<?>> rangeClass,
   8                         final String controllingAttrName, final String targetPropertyName) {
   9                 super(rangeClass, controllingAttrName);
  10                 this.builder = new SimpleVectorBarBuilder(targetPropertyName);
  11                 // Create editor component here.
  12         }
  15         @Override
  16         public CyCustomGraphics<?> calculateRangeValue(Map<String, Object> attrBundle) {
  17                 if(attrBundle == null || attrBundle.get(controllingAttrName) == null)
  18                         return null;
  19                 final Object data = attrBundle.get(controllingAttrName);
  20                 return builder.getGraphics(data);
  21         }
  22  .
  23  .
  24  .
  26 }

   1 public class SimpleVectorBarBuilder implements CustomGraphicsBuilder {
   3         private final String targetPropName;
   5         public SimpleVectorBarBuilder(String targetPropName) {
   6                 this.targetPropName = targetPropName;
   7         }
   9         @Override
  10         public CyCustomGraphics<?> getGraphics(Object data) {
  11                 final CyCustomGraphics<?> graphics = new GradientRectangleCustomGraphics();
  12                 graphics.getProps().get(targetPropName).setValue(data);
  13                 graphics.update();
  15                 return graphics;
  16         }
  17 }

Project Management

Project Dependencies



RFC_Custom_Graphics_VizMapper (last edited 2010-06-15 20:25:34 by KeiichiroOno)

Funding for Cytoscape is provided by a federal grant from the U.S. National Institute of General Medical Sciences (NIGMS) of the Na tional Institutes of Health (NIH) under award number GM070743-01. Corporate funding is provided through a contract from Unilever PLC.

MoinMoin Appliance - Powered by TurnKey Linux