Albert Lea Data Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Zenteknix Project Page: ztxcharts ======

===== Introduction =====
In searching, at one time, for an existing library for programmatically rendering chart graphics from data, I discovered that very little (nothing, really) existed.  This was especially true for the particular niche that I am interested in, which involves retaining simplicity and transparency of the solution's source code, as well as an approach to software engineering that reinforces portability (particularly within unix-like systems) and extensibility.

Therefore, the primary solution-level requirements (and goals) for ztxcharts have been:

  * Freedom-respecting (according to the [[http://www.fsf.org|FSF]] definition)
  * Programmatically transparent (access to all functionality programmatically)
  * Extensible via plugin-like architectural aspects
  * Performant, enabling real-time and heavy batch load operation
  * Portable, with emphasis on unix-like systems

The ztxcharts library seeks to provide all this, and more.

===== Design Overview =====
The basic design of ztxcharts is aimed at providing a programmer with capabilities to automate graphical chart generation, with a set of basic "canned" chart types, enhanced with some configurable attributes, that require minimal intervention to generate.  The design specifies a database schema for general storage/arrangement of chart data, which the programmer is expected to populate by any means convenient.  The programmer then writes a (hopefully) simple C program to set up the report's context and invoke the library's chart-drawing functionality.

An extension of the design has been made to provide a "plugin" section of the API, which will allow programmers to define their own chart types/attributes by writing a shared library providing the plugin's implementation according to the library's plugin specification.

==== Chart Type Overview ====

=== 1. Simple Bar Chart (CHART_TYPE_SIMPLEBAR1) ===
This chart is one set of bars representing one data set.  The data set lives in the "data1" column of the rows for the specified report (as indicated in the "rpt" column).  In its default form it charts the data as vertical bars, from left to right, with the X axis representing dates contained in the "period" column of rows.  The Y axis auto-scales according to the minimum and maximum values contained in the "data1" column of the rows.  The Y axis label is explicitly set on the chart via a function call.

=== 2. Simple Stacked Bar Chart (CHART_TYPE_SIMPLEBAR2) ===
This chart is two sets of bars, stacked one vertically on top of the other, representing two values out of one data set.  The two values live in the "data1" and "data3" colums of the rows for the specified report (as indicated in the "rpt" column).  In its default form, the X axis is treated similarly as with the CHART_TYPE_SIMPLEBAR1, and the Y axis auto-scales to the minimum and maximum of sums of the two values for each row, with each value then being charted as a bar, first on the bottom, and second continuing stacked on top of the first.  The Y axis label is explicitly set on the chart via a function call.

=== 3. Simple Pie Chart (CHART_TYPE_SIMPLEPIE1) ===
This chart consists of a circular pie graph, representing the values of each row of one data set.  The values are scaled as a percentage of the sum of all values in the set, and converted to the same percentage of the 360 degrees of the circle/pie.  The colors of the pie slices rotates through a (currently static) set of (currently 7) colors.

=== 4. Compound Bar/Line Chart (CHART_TYPE_BARLINE4) ===
This chart consists of one set of bars representing one data set, a line graph representing a delta of the bar graph data set to some threshold, and labels for the line graph data points that indicate the nature/magnitude of the delta.  The bar chart is created in a manner similar to the SIMPLEBAR chart types.

===== Design Detail =====
The current database schema expected by the library is represented
by a mysql table named "chartdata", defined with these fields:
<code>
+---------+---------------+------+-----+----------+----------------+
| Field   | Type          | Null | Key | Default  | Extra          |
+---------+---------------+------+-----+----------+----------------+
| id      | bigint(20)    | NO   | PRI | NULL     | auto_increment |
| rpt     | int(11)       | YES  |     | NULL     |                |
| created | datetime      | YES  |     | NULL     |                |
| opened  | datetime      | YES  |     | NULL     |                |
| period  | datetime      | YES  |     | NULL     |                |
| tag     | varchar(80)   | YES  |     | NULL     |                |
| org     | varchar(80)   | YES  |     | NULL     |                |
| app     | varchar(80)   | YES  |     |          |                |
| mag     | bigint(20)    | YES  |     | NULL     |                |
| idx     | bigint(20)    | YES  |     | NULL     |                |
| data1   | decimal(30,6) | YES  |     | 0.000000 |                |
| data2   | bigint(20)    | YES  |     | 0        |                |
| data3   | decimal(30,6) | YES  |     | 0.000000 |                |
| data4   | bigint(20)    | YES  |     | 0        |                |
| attr1   | int(11)       | YES  |     | 0        |                |
| attr2   | int(11)       | YES  |     | 0        |                |
| summary | text          | YES  |     | NULL     |                |
| brief   | text          | YES  |     | NULL     |                |
+---------+---------------+------+-----+----------+----------------+
</code>

=== Explanation of the fields: ===
^	Field Name	^Field Description  ^
|	id				|Unique row ID  |
|	rpt			|Report ID  |
|	created		|Creation  |
|	opened		|General date/time of initiation  |
|	period		|General date/time of relevant period  |
|	tag			|A chart-specific label  |
|	org			|A chart-specific origin  |
|	app			|Application name  |
|	mag			|A chart-specific scalar numeric value  |
|	idx			|A chart-specific index  |
|	data1			|A chart-specific large-range decimal data element  |
|	data2			|A chart-specific large-range numeric data element  |
|	data3			|A chart-specific large-range decimal data element  |
|	data4			|A chart-specific large-range numeric data element  |
|	attr1			|A chart-specific attribute  |
|	attr2			|A chart-specific attribute  |
|	summary		|A chart-specific freeform text content  |
|	brief			|A chart-specific freeform text content  |

... more specific purposes of the fields are relevant to and found in the chart type documentation:

==== CHART_TYPE_SIMPLEBAR1: Simple Bar Chart  ====
... under construction ...

==== CHART_TYPE_SIMPLEBAR2: Simple Stacked Bar Chart  ====
... under construction ...

==== CHART_TYPE_SIMPLEPIE1: Simple Pie Chart  ====
... under construction ...

==== CHART_TYPE_BARLINE4: Compound Bar/Line Chart  ====
... under construction ...

===== History/Evolution =====
A bit of historical background might be interesting/useful...

The "ztx" in ztxcharts is the short moniker/nickname for my company
"Zenteknix", which can be read about online at: \\
[[http://www.zenteknix.com]]

The product started out as an alternative to the "GDChart" product, which uses the popular GD graphics library, in its native C form, to draw simple charts.  While GDChart was the closest thing I could find to what I wanted/needed at the time, it didn't even come close to what I needed in diversity and flexibility of chart types and attributes.  After looking at the GDChart code, it quickly became clear to me that I could create what I needed fastest by just coding my own charting logic using the GD library itself.  So, I started out with that approach, creating a program that drew a couple of specific charts that I needed immediately.

As is typical, the need for more charts with new types and attributes came very quickly, with clear signs of more to be needed in the future.  This indicated to me that I needed to evolve the program into a "chart creation library" - a product similar to GDChart, but with the capabilities I needed.  Thus was born ztxcharts.

As new charting capabilities were added, they occupied contexts specific to the particular charts I needed at the time. With each new release, I've focused on generalizing those capabilities into more of a public charting API suitable for the kind of product ztxcharts has been (and is still) evolving into.

 \\

//Links: [[http://www.zenteknix.com/mantis|Zenteknix Mantis]] ... [[http://www.zenteknix.com|Zenteknix]]// \\
Albert Lea Data Wiki

User Tools

Site Tools

Page Tools
