RFC_Custom_Graphics_VizMapper

Status

3/9/2010 - KeiichiroOno: start working on actual design and implementation

Proposal

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.

Background

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

• A user wants to draw expression values as histogram on nodes (see the pictures above)
• A user wants a node shape that we don't supply by default.

• A user wants some non-standard graphic to be applied on or around a node (Like yEd. See the screenshot above).

• Draw complex graphics using multiple custom graphic objects.

Implementation Plan

• The general idea is to create a new NODE_CUSTOM_GRAPHIC visual property that would allow users to map specific images to nodes.

• This visual property would behave the same as other discrete properties like node shape or line type. This implies that most of the existing VizMapper GUI widgets could be used with minimal modification.

• We would provide a new menu option that would allow users to load image files and make them accessible to the VizMapper.

• We would need to consider I/O issues related to Session saving and loading.

  • One thought is to make a Custom Graphic a new type of CyAttribute. The advantage is that we could use the existing I/O mechanisms and we also allow passthrough mappings to point to the image. However, that might not buy us much as we'd need to add support in MANY places. It also doesn't make much sense to have graphics attached to specific nodes from the outset.

Specific Ideas

Mapping Problem

Simple use case is mapping to a static image.

 Attr value 1 = Image URL 1
 Attr value 2 = Image URL 2
 Attr value 3 = Image URL 1
 Attr value 4 = Image URL 3
 .
 .
 .

However, this is not efficient for the following case. Suppose a user has expression values as a list attribute. If there are N nodes in the network and he/she wants to map this attribute value to pi charts, the user needs to create N images and have to create a map like this:

 List 1 = Chart image URL 1
 List 2 = Chart image URL 2
 List 3 = Chart image URL 3
 
 .
 .
 .
 List N = Chart image URL N

In addition, in this case, images are bitmap and could not maintain the chart image quality when user export it as a vector image. To solve this issue, we can use CustomGraphicsBuilder interface.

   1 public interface CustomGraphicsBuilder<T> {
   2         public Collection<CustomGraphic> createCustomGraphics(final T constraint);
   3 }
   4 

And implementations look like the following:

   1 public class URLImageBuilder implements CustomGraphicsBuilder<URL> {
   2 
   3         @Override
   4         public Collection<CustomGraphic> createCustomGraphics(final URL constraint) {
   5                 
   6                 final Rectangle2D bound = new java.awt.geom.Rectangle2D.Double(-11.0, -15.0, 22.0, 30.0);
   7                 Paint paint = null;
   8                 try {
   9                         paint = new TexturePaint(ImageIO.read(constraint), bound);
  10                 } catch (IOException e) {
  11                         e.printStackTrace();
  12                 }
  13                 final List<CustomGraphic> graphics = new ArrayList<CustomGraphic>();
  14                 graphics.add(new CustomGraphic(bound, paint, NodeDetails.ANCHOR_WEST));
  15                 
  16                 return graphics;
  17         }
  18 }
  19 

   1 public class HistogramGraphicsBuilder implements CustomGraphicsBuilder<List<Double>> {
   2 
   3         @Override
   4         public Collection<CustomGraphic> createCustomGraphics(final List<Double> constraint) {
   5                 final List<CustomGraphic> graphics = new ArrayList<CustomGraphic>();
   6                 
   7                 // Draw histogram using double value here.
   8                 
   9                 return graphics;
  10         }
  11 }
  12 

This enables user maximum flexibility. They can mix multiple builders in a mapping when necessary.

By default, core provides URL image mapping and some very simple CustomGraphicsBuilder implementations. Plugin author can create their own builder if they need custom nodes.

In this design, mapping is attribute value to builder + constraint.

 Attr value 1 = (URLImageGraphicsBuilder, http://cytoscape.org/images/image1.png)

• Images could be specified using URLs or local files. This implies we'd use the Bookmarks API and the normal FileUtil for loading images into Cytoscape.

• We would use the session plugin file saving mechanism for storing loaded images.
• Write all UI functionality (menu items, etc.) as a plugin. Only touch the core for adding new visual properties.
• Setting custom images would simply use the existing custom graphic API in Ding.

CustomGraphicBuilder

   1 
   2 

Project Management

Project Dependencies

• This depends on the CustomGraphic API present in !DNodeView, something we might want to expose in GINY instead.

Issues

• What sort of image types will we support? PNG and JPG should be easy, but what about vector graphics like PDF or SVG?
• Would we want to provide facilities for scaling or other affine transforms for manipulating the images once they're loaded?

• We might want a separate visual property for setting custom graphic position. If not then we might need to extend current discrete VizMapper widgets to allow use to choose North/South/East/West positioning. Either way, this might be messy given the current API.

• What about background images?
  • Can we provide a minimal API that allows users to set background images?

  • How would this integrate with the VizMapper?

Comments