1 /* acre - A cairo-based library for creating plots and charts.
3 * Copyright © 2009 Carl Worth <cworth@cworth.org>
5 * This program is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU General Public License as
7 * published by the Free Software Foundation; either version 2 of the
8 * License, or (at your option) any later version.
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
20 #define _ISOC99_SOURCE /* for round() */
21 #define _XOPEN_SOURCE 500
22 #define _GNU_SOURCE /* for asprintf() */
31 typedef struct _acre_data_point_2d {
34 } acre_data_point_2d_t;
39 acre_data_point_2d_t *points;
40 unsigned int points_size;
41 unsigned int num_points;
44 typedef struct _acre_axis {
56 unsigned int data_size;
57 unsigned int num_data;
59 /* Data for drawing. */
61 PangoFontDescription *font;
62 struct { double r; double g; double b;} colors[3];
65 /* Total size including labels. */
69 /* Position and size of chart alone. */
73 /* Create a new, empty plot. */
79 acre = xmalloc (sizeof (acre_t));
83 acre->x_axis.label = NULL;
84 acre->x_axis.min = 0.0;
85 acre->x_axis.max = 0.0;
87 acre->y_axis.label = NULL;
88 acre->y_axis.min = 0.0;
89 acre->y_axis.max = 0.0;
97 acre->chart.width = 0;
98 acre->chart.height = 0;
103 /* Destroy a plot. */
105 acre_destroy (acre_t *acre)
110 free (acre->x_axis.label);
111 free (acre->y_axis.label);
113 for (i = 0; i < acre->num_data; i++)
114 acre_data_destroy (acre->data[i]);
122 acre_set_title (acre_t *acre, const char *title)
126 acre->title = strdup (title);
130 acre_set_x_axis_label (acre_t *acre, const char *label)
132 free (acre->x_axis.label);
134 acre->x_axis.label = strdup (label);
138 acre_set_y_axis_label (acre_t *acre, const char *label)
140 free (acre->y_axis.label);
142 acre->y_axis.label = strdup (label);
145 /* Add a dataset to the plot. The plot assumes ownership of the
146 * dataset so it is not necessary to call acre_data_destroy on it. */
148 acre_add_data (acre_t *acre, acre_data_t *data)
150 if (acre->num_data >= acre->data_size) {
151 acre->data_size *= 2;
152 if (acre->data_size == 0)
154 acre->data = xrealloc_ab (acre->data,
156 sizeof (acre_data_t *));
159 acre->data[acre->num_data] = data;
163 #define ACRE_FONT_FAMILY "sans"
164 #define ACRE_FONT_SIZE 12
165 #define ACRE_TITLE_FONT_SIZE 20
166 #define ACRE_PAD (ACRE_FONT_SIZE)
167 #define ACRE_TICK_MAJOR_SIZE 6
168 #define ACRE_TICK_MINOR_SIZE 3
169 #define ACRE_X_TICK_VALUE_PAD 2
170 #define ACRE_Y_TICK_VALUE_PAD 4
171 #define ACRE_LEGEND_PAD 4
172 #define ACRE_LEGEND_LINE_SIZE 10
175 _create_layout (acre_t *acre, const char *text)
179 layout = pango_cairo_create_layout (acre->cr);
180 pango_layout_set_font_description (layout, acre->font);
181 pango_layout_set_text (layout, text, -1);
182 pango_layout_set_alignment (layout, PANGO_ALIGN_CENTER);
187 #define PRINTF_FORMAT(fmt_index, va_index) __attribute__ ((__format__(__printf__, fmt_index, va_index)))
190 _create_layout_vprintf (acre_t *acre, const char *fmt, va_list ap)
195 vasprintf (&text, fmt, ap);
197 layout = _create_layout (acre, text);
205 _create_layout_printf (acre_t *acre, const char *fmt, ...)
206 PRINTF_FORMAT (2, 3);
209 _create_layout_printf (acre_t *acre, const char *fmt, ...)
216 layout = _create_layout_vprintf (acre, fmt, ap);
224 _destroy_layout (PangoLayout *layout)
226 g_object_unref (layout);
230 _show_layout (cairo_t *cr, PangoLayout *layout)
232 pango_cairo_show_layout (cr, layout);
234 _destroy_layout (layout);
238 _draw_title_and_labels (acre_t *acre)
240 cairo_t *cr = acre->cr;
241 PangoFontDescription *title_font;
242 PangoLayout *title_layout, *x_axis_layout, *y_axis_layout;
243 PangoLayout *min_y, *max_y;
244 int min_y_width, max_y_width, y_axis_value_width;
245 int title_width, title_height;
246 int x_axis_width, x_axis_height;
247 int y_axis_width, y_axis_height;
248 PangoRectangle new_chart;
252 acre->font = pango_font_description_new ();
253 pango_font_description_set_family (acre->font, ACRE_FONT_FAMILY);
254 pango_font_description_set_absolute_size (acre->font,
255 ACRE_FONT_SIZE * PANGO_SCALE);
257 title_font = pango_font_description_new ();
258 pango_font_description_set_family (title_font, ACRE_FONT_FAMILY);
259 pango_font_description_set_absolute_size (title_font,
260 ACRE_TITLE_FONT_SIZE * PANGO_SCALE);
262 title_layout = _create_layout (acre, acre->title);
263 pango_layout_set_font_description (title_layout, title_font);
265 x_axis_layout = _create_layout (acre, acre->x_axis.label);
266 y_axis_layout = _create_layout (acre, acre->y_axis.label);
268 min_y = _create_layout_printf (acre, "%g",
269 round (acre->y_axis.min));
270 max_y = _create_layout_printf (acre, "%g",
271 round (acre->y_axis.max));
273 pango_layout_get_pixel_size (min_y, &min_y_width, NULL);
274 pango_layout_get_pixel_size (max_y, &max_y_width, NULL);
275 y_axis_value_width = MAX (min_y_width, max_y_width);
277 _destroy_layout (min_y);
278 _destroy_layout (max_y);
280 /* Iterate with the layout of the title and axis labels until they
281 * are stable, (this requires iteration since we don't know what
282 * to set their widths to in advance due to the wrapping of the
283 * other elements). */
285 pango_layout_set_width (title_layout, acre->chart.width * PANGO_SCALE);
286 pango_layout_set_width (x_axis_layout, acre->chart.width * PANGO_SCALE);
287 pango_layout_set_width (y_axis_layout, acre->chart.height * PANGO_SCALE);
289 pango_layout_get_pixel_size (title_layout, &title_width, &title_height);
290 pango_layout_get_pixel_size (x_axis_layout, &x_axis_width, &x_axis_height);
291 pango_layout_get_pixel_size (y_axis_layout, &y_axis_width, &y_axis_height);
293 new_chart.x = ACRE_PAD + y_axis_height +
294 ACRE_PAD + y_axis_value_width + ACRE_Y_TICK_VALUE_PAD;
295 new_chart.width = acre->width - acre->chart.x - ACRE_PAD;
297 new_chart.y = ACRE_PAD + title_height + ACRE_PAD;
298 new_chart.height = acre->height - acre->chart.y -
299 (ACRE_X_TICK_VALUE_PAD + ACRE_FONT_SIZE +
300 ACRE_PAD + x_axis_height + ACRE_PAD);
302 if (new_chart.x == acre->chart.x &&
303 new_chart.y == acre->chart.y &&
304 new_chart.width == acre->chart.width &&
305 new_chart.height == acre->chart.height)
310 acre->chart.x = new_chart.x;
311 acre->chart.y = new_chart.y;
312 acre->chart.width = new_chart.width;
313 acre->chart.height = new_chart.height;
316 cairo_set_source_rgb (cr, 0, 0, 0);
318 cairo_move_to (cr, acre->chart.x, ACRE_PAD);
319 _show_layout (cr, title_layout);
323 cairo_translate (cr, ACRE_PAD, acre->chart.y + acre->chart.height);
324 cairo_rotate (cr, - M_PI / 2.0);
325 cairo_move_to (cr, 0, 0);
326 _show_layout (cr, y_axis_layout);
330 cairo_move_to (cr, acre->chart.x,
331 acre->chart.y + acre->chart.height +
332 ACRE_FONT_SIZE + ACRE_PAD);
333 _show_layout (cr, x_axis_layout);
338 /* For a given axis range, compute a step size (in data space) to
339 * generate a suitable number of ticks (5 or so). */
341 _step_for_range (double range, int *minor_divisions)
343 double step, scale_factor;
345 /* We want roughly 5 major ticks for the chart. */
348 /* Normalize the step so we can easily snap it to a desirable
350 scale_factor = pow (10.0, floor (log10 (step)));
351 step /= scale_factor;
353 /* We want increments of 1, 2.5, 5, or 10 (times some power of
354 * 10). The threshold values between these are computed
355 * logarithmically. */
356 if (step < 3.535533905932738) {
357 if (step < 1.58113883008419) {
359 *minor_divisions = 4;
362 *minor_divisions = 5;
365 if (step < 7.071067811865475) {
367 *minor_divisions = 5;
370 *minor_divisions = 4;
374 /* Un-normalize and we now have the data value that we want to
376 return step * scale_factor;
379 /* Given an axis range, we can compute a desired data-space step
380 * amount for the major ticks (see _step_for_range). To get
381 * nice-looking pixel-snapped ticks we want to expand the range
384 _expand_range_for_width (double *axis_min, double *axis_max, int pixel_range)
386 double range, new_range, step, step_minor, pixel_step;
389 range = *axis_max - *axis_min;
391 step = _step_for_range (range, &minor_divisions);
392 step_minor = step / minor_divisions;
394 pixel_step = step_minor * (pixel_range / range);
396 /* We expand the range by the ratio of the pixel step to the floor
399 new_range = range * pixel_step / floor (pixel_step);
401 /* And spread the increase out on either side of the range. */
402 *axis_min -= (new_range - range) / 2.0;
403 *axis_max += (new_range - range) / 2.0;
406 /* Setup a transformation in acre->cr such that data values plotted
407 * will appear where they should within the chart.
410 _set_transform_to_data_space (acre_t *acre)
412 cairo_t *cr = acre->cr;
416 acre->chart.y + acre->chart.height);
418 acre->chart.width / (acre->x_axis.max - acre->x_axis.min),
419 - acre->chart.height /(acre->y_axis.max - acre->y_axis.min));
420 cairo_translate (cr, -acre->x_axis.min, -acre->y_axis.min);
424 _compute_axis_ranges (acre_t *acre)
428 double x_adjust, y_adjust;
429 cairo_t *cr = acre->cr;
431 acre->x_axis.min = acre->data[0]->points[0].x;
432 acre->x_axis.max = acre->data[0]->points[0].x;
433 acre->y_axis.min = acre->data[0]->points[0].y;
434 acre->y_axis.min = acre->data[0]->points[0].y;
436 /* First, simply find the extrema of the data. */
437 for (d = 0; d < acre->num_data; d++) {
438 data = acre->data[d];
439 for (i = 0; i < data->num_points; i++) {
440 if (data->points[i].x < acre->x_axis.min)
441 acre->x_axis.min = data->points[i].x;
442 if (data->points[i].x > acre->x_axis.max)
443 acre->x_axis.max = data->points[i].x;
445 if (data->points[i].y < acre->y_axis.min)
446 acre->y_axis.min = data->points[i].y;
447 if (data->points[i].y > acre->y_axis.max)
448 acre->y_axis.max = data->points[i].y;
452 /* Next, we want to ensure that the data never collides with the
453 * ticks. So we expand each axis on its minimum side as needed. */
458 _set_transform_to_data_space (acre);
460 x = ACRE_TICK_MAJOR_SIZE + 2.0;
461 y = ACRE_TICK_MAJOR_SIZE + 2.0;
462 cairo_device_to_user_distance (cr, &x, &y);
464 acre->x_axis.min -= x;
465 acre->y_axis.min += y;
469 /* Then, increase the axis ranges just enough so that the step
470 * sizes for the ticks will be integers.
472 _expand_range_for_width (&acre->x_axis.min,
476 _expand_range_for_width (&acre->y_axis.min,
480 /* Finally, we also translate the axis ranges slightly so that the
481 * ticks land on half-integer device-pixel positions.
485 _set_transform_to_data_space (acre);
489 cairo_user_to_device (cr, &x_adjust, &y_adjust);
490 x_adjust = (round (x_adjust + 0.5) - 0.5) - x_adjust;
491 y_adjust = (round (y_adjust + 0.5) - 0.5) - y_adjust;
492 cairo_device_to_user_distance (cr, &x_adjust, &y_adjust);
494 acre->x_axis.min -= x_adjust;
495 acre->x_axis.max -= x_adjust;
497 acre->y_axis.min -= y_adjust;
498 acre->y_axis.max -= y_adjust;
504 _choose_colors (acre_t *acre)
506 /* XXX: Should choose N, equally-spaced colors from a perceptually
507 * linear space here. */
508 acre->num_colors = 3;
510 acre->colors[0].r = 1;
511 acre->colors[0].g = 0;
512 acre->colors[0].b = 0;
514 acre->colors[1].r = 0;
515 acre->colors[1].g = 1;
516 acre->colors[1].b = 0;
518 acre->colors[2].r = 0;
519 acre->colors[2].g = 0;
520 acre->colors[2].b = 1;
524 _draw_data (acre_t *acre)
526 cairo_t *cr = acre->cr;
532 cairo_set_source_rgb (cr, 0, 0, 0);
534 _set_transform_to_data_space (acre);
536 for (d = 0; d < acre->num_data; d++) {
537 int color = d % acre->num_colors;
538 cairo_set_source_rgb (cr,
539 acre->colors[color].r,
540 acre->colors[color].g,
541 acre->colors[color].b);
542 data = acre->data[d];
544 for (i = 0; i < data->num_points; i++) {
551 cairo_identity_matrix (cr);
552 cairo_set_line_width (cr, 1.0);
561 typedef enum _ticks { ACRE_TICKS_X, ACRE_TICKS_Y } acre_ticks_t;
564 _draw_ticks (acre_t *acre,
565 double axis_min, double axis_max,
568 cairo_t *cr = acre->cr;
569 double t, step, sub_step;
574 _set_transform_to_data_space (acre);
576 step = _step_for_range (axis_max - axis_min, &minor_divisions);
577 sub_step = step / minor_divisions;
579 for (t = (floor (axis_min / sub_step) + 1) * sub_step;
584 if (fabs((t / step) - round (t / step)) < 0.5 * (sub_step / step))
585 tick_size = ACRE_TICK_MAJOR_SIZE;
587 tick_size = ACRE_TICK_MINOR_SIZE;
592 if (ticks == ACRE_TICKS_X)
593 cairo_move_to (cr, t, acre->y_axis.min);
595 cairo_move_to (cr, acre->x_axis.min, t);
597 cairo_identity_matrix (cr);
599 if (ticks == ACRE_TICKS_X) {
600 cairo_rel_line_to (cr, 0, 0.5);
601 cairo_rel_line_to (cr, 0, -tick_size - 0.5);
603 cairo_rel_line_to (cr, -0.5, 0);
604 cairo_rel_line_to (cr, tick_size + 0.5, 0);
607 cairo_set_line_width (cr, 1.0);
613 if (tick_size == ACRE_TICK_MAJOR_SIZE)
620 layout = _create_layout_printf (acre, "%g", t);
622 if (ticks == ACRE_TICKS_X)
623 cairo_move_to (cr, t, acre->y_axis.min);
625 cairo_move_to (cr, acre->x_axis.min, t);
627 cairo_identity_matrix (cr);
628 pango_layout_get_pixel_size (layout, &width, &height);
630 if (ticks == ACRE_TICKS_X)
631 cairo_rel_move_to (cr, -width / 2, ACRE_X_TICK_VALUE_PAD);
633 cairo_rel_move_to (cr, -width - ACRE_Y_TICK_VALUE_PAD,
636 _show_layout (cr, layout);
646 _draw_legend (acre_t *acre)
649 int label_width, max_label_width = 0;
652 cairo_t *cr = acre->cr;
656 for (i = 0; i < acre->num_data; i++) {
657 layout = _create_layout (acre, acre->data[i]->name);
658 pango_layout_get_pixel_size (layout, &label_width, NULL);
659 _destroy_layout (layout);
660 if (label_width > max_label_width)
661 max_label_width = label_width;
664 width = ACRE_LEGEND_PAD + ACRE_LEGEND_LINE_SIZE + ACRE_LEGEND_PAD +
665 max_label_width + ACRE_LEGEND_PAD;
666 height = ACRE_LEGEND_PAD +
667 acre->num_data * (ACRE_FONT_SIZE + ACRE_LEGEND_PAD);
669 cairo_translate (cr, acre->chart.x, acre->chart.y);
672 acre->chart.width - ACRE_LEGEND_PAD - width,
675 cairo_rectangle (cr, -0.5, -0.5, width + 1.0, height + 1.0);
676 cairo_set_source_rgb (cr, 0, 0, 0);
677 cairo_set_line_width (cr, 1.0);
680 cairo_translate (cr, ACRE_LEGEND_PAD, ACRE_LEGEND_PAD);
682 for (i = 0; i < acre->num_data; i++) {
683 cairo_move_to (cr, 0, ACRE_FONT_SIZE / 2 + 0.5);
684 cairo_rel_line_to (cr, ACRE_LEGEND_LINE_SIZE, 0);
685 cairo_set_source_rgb (cr,
686 acre->colors[i % acre->num_colors].r,
687 acre->colors[i % acre->num_colors].g,
688 acre->colors[i % acre->num_colors].b);
691 layout = _create_layout (acre, acre->data[i]->name);
692 cairo_move_to (cr, ACRE_LEGEND_LINE_SIZE + ACRE_LEGEND_PAD, 0);
693 cairo_set_source_rgb (cr, 0, 0, 0);
694 _show_layout (cr, layout);
696 cairo_translate (cr, 0, ACRE_LEGEND_PAD + ACRE_FONT_SIZE);
703 _draw_frame_and_ticks (acre_t *acre)
705 cairo_t *cr = acre->cr;
709 cairo_set_source_rgb (cr, 0, 0, 0); /* black */
712 _draw_ticks (acre, acre->x_axis.min, acre->x_axis.max, ACRE_TICKS_X);
713 _draw_ticks (acre, acre->y_axis.min, acre->y_axis.max, ACRE_TICKS_Y);
717 acre->chart.x - 0.5, acre->chart.y - 0.5,
718 acre->chart.width + 1.0, acre->chart.height + 1.0);
719 cairo_set_line_width (cr, 1.0);
725 /* Draw the plot to the given cairo context within a user-space
726 * rectangle from (0, 0) to (width, height). This size includes all
727 * space for extra-plot elements (such as the title, the axis labels,
731 acre_draw (acre_t *acre, cairo_t *cr, int width, int height)
736 acre->height = height;
738 acre->chart.width = width;
739 acre->chart.height = height;
743 cairo_set_source_rgb (cr, 1, 1, 1);
745 _choose_colors (acre);
747 /* We compute the axis ranges before doing label layout so that we
748 * can account for the width of the y-axis value labels. */
749 _compute_axis_ranges (acre);
751 _draw_title_and_labels (acre);
753 /* And we recompute the axis ranges now that the title and axis
754 * label space is all measured and accounted for. */
755 _compute_axis_ranges (acre);
759 if (acre->num_data > 1)
762 _draw_frame_and_ticks (acre);
765 /* Create a new dataset---a collection of (x, y) datapoints. A single
766 * plot can contain multiple datasets, (see acre_add_data). */
768 acre_data_create (void)
772 data = xmalloc (sizeof (acre_data_t));
777 data->points_size = 0;
778 data->num_points = 0;
783 /* Destroy an acre dataset. Do not call this function if the dataset
784 * has been added to an acre_t plot with acre_add_data. */
786 acre_data_destroy (acre_data_t *data)
793 /* Set the label for this dataset (to appear in the plot's key). */
795 acre_data_set_name (acre_data_t *data, const char *name)
799 data->name = strdup (name);
802 /* Add a datapoint to the given dataset. */
804 acre_data_add_point_2d (acre_data_t *data, double x, double y)
806 if (data->num_points >= data->points_size) {
807 data->points_size *= 2;
808 if (data->points_size == 0)
809 data->points_size = 16;
810 data->points = xrealloc_ab (data->points,
812 sizeof (acre_data_point_2d_t));
815 data->points[data->num_points].x = x;
816 data->points[data->num_points].y = y;