What is ChartFactory?
ChartFactory is a quick, simple Java API for generating charts that can be saved as files or embedded in applications. It is free, open source, and easy to use. It can be used to generate simple, attractive bar charts (including bar charts with multiple rows of data), line charts and pie charts.

What is ChartFactory not?
ChartFactory is not a calculation graphing suite. If you are interested in creating hybrid, curve-fitted, high/low/open/close Pareto charts with multiple embossed secondary axes and gesture-based transformations, ChartFactory is not the tool you are looking for. We suggest you investigate another FLOSS package such as JFreeChart.

What version of Java does ChartFactory require?
ChartFactory requires Java 1.4 or higher. It uses javax.imageio and java.util.regex, which are only available in Java 1.4+.

I want to try ChartFactory out. What do I do?
Download the binary jar and add it to your classpath. Then write a simple class to draw your chart. You will find numerous examples in the TestChartFactory.java file included in the source jar. The simplest way to create a quick chart would be something like this:
// Make sure the ChartFactory binary jar is in your classpath
import org.corpstein.image.*;
public class Test
{
  public static void main(String args[])
  {
    try
    {
      ChartFactory factory = ChartFactory.getInstance();  // Get a ChartFactory object
      ChartData data = new ChartData();                   // Create a ChartData object
      data.setTitle("My Chart");                          // Set the chart title
      data.addPoint("foo", 1);                            // Add 2 values with labels
      data.addPoint("bar", 2);
      // Create the image and write it to a file
      factory.writeImage(factory.createBarChart(data), "MyChart.png"); 
    }
    catch(Exception e)
    {
      e.printStackTrace();
    }
  }
}
I want to customize the colors/gradients/fonts/keys/borders/transparency. I want to add image and text layers at different levels. I want to create bar/line/pie charts. I want to paint my chart image on a Swing/AWT/SWT object. I want to stream charts from a servlet/JSP. How do I do that?
Take a look at the TestChartFactory.java file for examples of how to do most things. You can also download the API docs or view them online. If you still have questions, try asking in one of the ChartFactory forums.

What are the key types? How can I use them?
The key types are defined in the ChartStyle class. They are
	public static final int KEY_TYPE_BAR_COLOR_ASSOCIATION = 0;
	public static final int KEY_TYPE_DIAGONAL_BAR_LABELS   = 1;
	public static final int KEY_TYPE_HORIZONTAL_BAR_LABELS = 2;
Single-row Bar charts can use any of the three key types. Line charts, multi-row bar charts, and pie charts always use the bar-color association key. In the case of line charts and multi-row bar charts, this is to define the different series and can have either diagonal or horizontal bar labels to define x-axis values.

Bar-color association draws labeled, color-coded boxes at the bottom of the chart that match the color of the associated bar/line/pie slice. Diagonal bar labels draw the label text under the bar or line at a 45 degree angle. This allows more and longer labels to fit into the chart image without overlapping. Horizontal bar labels are similar, but are drawn straight across the image and have tighter width limits.

To set the key type for a chart, use the setKeyType method in ChartStyle. For example, if you create a ChartStyle object named style and want to use diagonal bar labels, you would use style.setKeyType(ChartStyle.KEY_TYPE_DIAGONAL_BAR_LABELS). Don't forget to then pass the style object along with your ChartData object to ChartFactory.create[Bar|Line|Pie]Chart(data, style[, metrics]).

What is a multi-row chart?
Multi-row charts are charts that have multiple series. For example, a chart that shows the height of your son on each of his birthdays has only one y value (height) per x value (date). If you add the heights of your daughter on each of her birthdays to the same chart, you now have a multi-row chart with multiple y values for each x. In addition to x-axis labels (the dates), you now need a key that tells which y values correspond to the first series (your son) and which to the second (your daughter).

What is a "layer"? What is a z-index?
Layers are image elements that inherit from the Layer class. They have a number of properties such as location, color, font, border, etc. In addition, each layer contains a non-negative z-index which defines how layers overlap, which are on top of others, etc. All ChartFactory charts are created by defining standard layers for the background, scale, bars/lines/slices, key, title, etc. The standard layers have the following z-indexes defined in the ChartMetrics class:
	public static final int Z_INDEX_BACKGROUND = 10;
	public static final int Z_INDEX_BORDER     = 20;
	public static final int Z_INDEX_BACKDROP   = 30;
	public static final int Z_INDEX_SCALE      = 40;
	public static final int Z_INDEX_BARS       = 50;
	public static final int Z_INDEX_SLICES     = 60;
	public static final int Z_INDEX_LINES      = 70;
	public static final int Z_INDEX_AXIS_LABEL = 80;
	public static final int Z_INDEX_KEY        = 90;
	public static final int Z_INDEX_TITLE      = 100;
You can create different types of custom layers and add them to the chart before it is drawn. For example, suppose you have an image "Watermark.png" that you want to place in a bar chart behind the bars but on top of the backdrop and scale. The following code defines an ImageLayer and adds it at the correct z-index:
	ImageLayer layer = new ImageLayer("Watermark.png");  
	// Set the location somewhere in the middle of the chart
	layer.setX(160);    
	layer.setY(130);
	layer.setZ(ChartMetrics.Z_INDEX_SCALE + 1);  // place it under the bars

	ChartStyle style = new ChartStyle();  // define a custom style
	style.addLayer(layer);  // Add the layer to the chart
	ChartFactory factory = ChartFactory.getInstance();  
	Image image = factory.createBarChart(data, style);  // Create the chart
	factory.writeImage(image, "myChart.png");  // Save the image to a file
Or suppose you want to add some text in the bottom left of a chart:
	TextLayer layer = new TextLayer("Generated 24 April 2005");  
	// Set the font to blue 12pt bold SansSerif
	layer.setFont(new Font("SansSerif"), Font.BOLD, 12);
	layer.setFontColor(Color.BLUE);
	// Set the location in the bottom left corner
	layer.setX(10);    
	layer.setY(460);
	layer.setZ(ChartMetrics.Z_INDEX_TITLE + 1);  // place it on top of everything

	ChartStyle style = new ChartStyle();  // define a custom style
	style.addLayer(layer);  // Add the layer to the chart
	ChartFactory factory = ChartFactory.getInstance();  
	Image image = factory.createBarChart(data, style);  // Create the chart
	factory.writeImage(image, "myChart.png");  // Save the image to a file
You can also create your own custom classes that inherit from Layer and override the draw method:
import org.corpstein.image.*;
public class Smiley extends Layer
{
	public Smiley(ChartStyle style)
	{
		this.style = style;
		setHeight(20);
		setWidth(20);
		setZ(ChartMetrics.Z_INDEX_TITLE + 1);  // topmost layer
	}

	public void draw(Graphics g)
	{
		super.draw(g);
		g.setColor(Color.BLUE);
		g.drawOval(0,  0, 19, 19);  // head
		g.drawLine(8,  5,  8,  7);  // left eye
		g.drawLine(11, 5, 11,  7);  // right eye
		g.drawArc(0, -5, 19, 19, 230, 80); // smile
	}
}
How do I embed an image into a chart?
To embed an image, create an ImageLayer with either a filename (String), java.awt.Image, or a URI. You can use any image format for which an ImageReader has been registered (we suggest PNG; see the javax.imageio.ImageReader class for more details). Images that contain transparent sections are supported. You can control the z-index of any layer in order to place your layer above or below any element.

How do I customize chart colors? How do I use transparency and gradients?
All chart elements have customizable java.awt.Paint's. Most elements can be customized by using the ChartStyle setPaint(ChartStyle.ITEM, paint) method where ITEM is one of COLOR_LABEL, COLOR_SHADOW, COLOR_BACKGROUND, COLOR_WALL, or COLOR_EDGE and paint is a Color or GradientPaint object. Bars (lines for line charts, slices for pie charts) can be customized by using the ChartStyle setBarPaint([index, ] paint) method. The following code snippet contains examples for changing various paints.
public void createChart() throws IOException
{
  ChartStyle style = new ChartStyle();  // used to customize the colors

  style.setColor(ChartStyle.COLOR_LABEL, Color.WHITE); // key text, axis labels, title
  style.setColor(ChartStyle.COLOR_SHADOW, Color.GRAY); // shadow under title text
  style.setColor(ChartStyle.COLOR_WALL, new Color(0.8f, 0.8f, 1.0f)); // light blue backdrop
  style.setColor(ChartStyle.COLOR_EDGE, Color.BLACK); // outline of bars, key, scale, etc.   
  style.setColor
  (
    ChartStyle.COLOR_BACKGROUND,  // Background of the entire chart image
    new GradientPaint  // Use a paint that fades from one color to another
    (
      0, 0,       // Start in the top left
      Color.BLUE, // with blue
      640, 480,                         // Go to the bottom right
      new Color(1.0f, 0.0f, 0.0f, 0.9f) // with 90% opaque Red
    )
  );
		
  style.setBarColor(Color.WHITE); // all bars are white
  style.setBarColor(0, Color.YELLOW); // the first bar is now yellow
  style.setBarColor(1, 1.0f, 0.0f, 0.0f); // 2nd bar is red
  style.setBarColor(2, 0.0f, 1.0f, 0.0f, 0.3f); // 3rd bar is green and very transparent
	
  ChartData data = new ChartData();
  data.setTitle("My Chart");
  data.addLabel("one"); // first bar
  data.addValue(1);
  data.addPoint("two", 2); // second bar
  data.addPoint("three", 3);
  data.addPoint("four", 4);  // color still white, as are all subsequent bars

  ChartFactory factory = ChartFactory.getInstance();
  Image image = factory.createBarChart(data, style); // pass data and style
  factory.writeImage(image, "MyChart.png"); // save the image to a file
}
For more examples, see the TestChartFactory.java file included in the source jar. Also see the ChartStyle class in the API docs.

What are chart borders?
Chart borders are a 3 pixel wide color gradient based on the the background color of the chart (lighter if the background is dark; darker if the background is light). They are drawn around the edges of the chart image. They are disabled by default but can be enabled by calling ChartStyle.setBorderEnabled(true).

What are value labels? How do I control them?
Value labels are numbers drawn on colored rectangles at the top of the value bar in a single-row bar chart. You can enable/disable them by calling ChartStyle.setValueLabelsEnabled(boolean). Value bars are not available for line charts or multi-row bar charts. The are planned for pie charts but not yet implemented.

What are point marks? How do I control them?
Point marks are the small squares drawn on the line chart lines where values are defined. Point marks are disabled by default but can set by calling ChartStyle.setShowPointMarks(boolean).

How does ChartFactory.createChart differ from createBarChart, createLineChart, and createPieChart?
If you call createChart, the ChartStyle object will determine whether to create a bar, line or pie chart. ChartStyle defaults to bar charts.

What is a "wall"? What does ChartStyle.setColor(ChartStyle.COLOR_WALL, Color) do?
The "walls" are the 3 planes behind the bars/lines of a bar or line chart that have the scale drawn on them. The side and bottom walls are shaded based on the wall color. You can customize the color used to draw the wall by creating a ChartStyle object, calling myChartStyle.setColor(ChartStyle.COLOR_WALL, <Color|float,float,float>), and passing your ChartStyle object along with the ChartData (and, optionally, a ChartMetrics) to ChartFactory.create[Bar|Line|Pie]Chart.

What else will be added to ChartFactory?
For a list of things planned in future releases, read the TODO file included with the source jar. Some features are already in the planning or implementation stage while other features (such as Pareto charts, Gantt charts, etc.) have been considered and rejected.

Can I improve ChartFactory itself?
You bet! ChartFactory is licensed under the GNU General Public License, which is designed to "guarantee your freedom to share and change free software". The best thing to do is to join the ChartFactory project and put your ideas into motion right away. You contribute; we all benefit.

I have a great idea for ChartFactory but don't have the time or inclination to implement it. Can I request a feature?
You sure can! Submit your request and the ChartFactory developers will evaluate it. Most developers create features they need or predict, but can't think of everything.
"The next best thing to having good ideas is recognizing good ideas from your users. Sometimes the latter is better."  -Eric S. Raymond, The Cathedral and the Bazaar

Can I incorporate ChartFactory in my own project?
You bet! The GNU General Public License gives you as much freedom as possible without trampling on the freedom of everyone else that wants to use, modify, or distribute the software. Go ahead and innovate, collaborate, or contribute any way you can. Share and enjoy.

Hey! Your example charts do not support my opinion! Don't you realize <insert opinion here>? Let me flame you on topics unrelated to the quality of ChartFactory. All your bases are belong to us!
Besides production use, we exercise the API during unit and regression testing with example data from various sources. In addition to typos, it might even have been deliberately altered in order to stress one feature or another. Nevertheless, see the TestChartFactory.java file for detailed reference citations. These are not the droids you are looking for. Move along.


SourceForge.net Logo