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() */
33 typedef struct _acre_data_point_2d {
36 } acre_data_point_2d_t;
41 acre_data_point_2d_t min;
42 acre_data_point_2d_t max;
44 acre_data_point_2d_t *points;
45 unsigned int points_size;
46 unsigned int num_points;
49 typedef struct _acre_axis {
57 typedef struct _acre_color {
69 unsigned int data_size;
70 unsigned int num_data;
72 /* Data for drawing. */
74 PangoFontDescription *font;
79 /* Total size including labels. */
83 /* Position and size of chart alone. */
87 /* Create a new, empty plot. */
93 acre = xmalloc (sizeof (acre_t));
97 acre->x_axis.label = NULL;
98 acre->x_axis.data_min = 0.0;
99 acre->x_axis.data_max = 0.0;
100 acre->x_axis.view_min = 0.0;
101 acre->x_axis.view_max = 0.0;
103 acre->y_axis.label = NULL;
104 acre->y_axis.data_min = 0.0;
105 acre->y_axis.data_max = 0.0;
106 acre->y_axis.view_min = 0.0;
107 acre->y_axis.view_max = 0.0;
116 acre->num_colors = 0;
123 acre->chart.width = 0;
124 acre->chart.height = 0;
129 /* Destroy a plot. */
131 acre_destroy (acre_t *acre)
136 free (acre->x_axis.label);
137 free (acre->y_axis.label);
139 for (i = 0; i < acre->num_data; i++)
140 acre_data_destroy (acre->data[i]);
150 acre_set_title (acre_t *acre, const char *title)
154 acre->title = strdup (title);
158 acre_set_x_axis_label (acre_t *acre, const char *label)
160 free (acre->x_axis.label);
162 acre->x_axis.label = strdup (label);
166 acre_set_y_axis_label (acre_t *acre, const char *label)
168 free (acre->y_axis.label);
170 acre->y_axis.label = strdup (label);
173 /* Add a dataset to the plot. The plot assumes ownership of the
174 * dataset so it is not necessary to call acre_data_destroy on it. */
176 acre_add_data (acre_t *acre, acre_data_t *data)
178 if (acre->num_data >= acre->data_size) {
179 acre->data_size *= 2;
180 if (acre->data_size == 0)
182 acre->data = xrealloc_ab (acre->data,
184 sizeof (acre_data_t *));
187 acre->data[acre->num_data] = data;
189 if (acre->num_data == 0) {
190 acre->x_axis.data_min = data->min.x;
191 acre->y_axis.data_min = data->min.y;
193 acre->x_axis.data_max = data->max.x;
194 acre->y_axis.data_max = data->max.y;
196 if (data->min.x < acre->x_axis.data_min)
197 acre->x_axis.data_min = data->min.x;
198 if (data->min.y < acre->y_axis.data_min)
199 acre->y_axis.data_min = data->min.y;
201 if (data->max.x > acre->x_axis.data_max)
202 acre->x_axis.data_max = data->max.x;
203 if (data->max.y > acre->y_axis.data_max)
204 acre->y_axis.data_max = data->max.y;
210 #define ACRE_FONT_FAMILY "sans"
211 #define ACRE_FONT_SIZE 12
212 #define ACRE_TITLE_FONT_SIZE 20
213 #define ACRE_PAD (ACRE_FONT_SIZE)
214 #define ACRE_TICK_MAJOR_SIZE 6
215 #define ACRE_TICK_MINOR_SIZE 3
216 #define ACRE_X_TICK_VALUE_PAD 2
217 #define ACRE_Y_TICK_VALUE_PAD 4
218 #define ACRE_LEGEND_PAD 4
219 #define ACRE_LEGEND_LINE_SIZE 10
222 _create_layout (acre_t *acre, const char *text)
226 layout = pango_cairo_create_layout (acre->cr);
227 pango_layout_set_font_description (layout, acre->font);
228 pango_layout_set_text (layout, text, -1);
229 pango_layout_set_alignment (layout, PANGO_ALIGN_CENTER);
234 #define PRINTF_FORMAT(fmt_index, va_index) __attribute__ ((__format__(__printf__, fmt_index, va_index)))
237 _create_layout_vprintf (acre_t *acre, const char *fmt, va_list ap)
242 vasprintf (&text, fmt, ap);
244 layout = _create_layout (acre, text);
252 _create_layout_printf (acre_t *acre, const char *fmt, ...)
253 PRINTF_FORMAT (2, 3);
256 _create_layout_printf (acre_t *acre, const char *fmt, ...)
263 layout = _create_layout_vprintf (acre, fmt, ap);
271 _destroy_layout (PangoLayout *layout)
273 g_object_unref (layout);
277 _show_layout (cairo_t *cr, PangoLayout *layout)
279 pango_cairo_show_layout (cr, layout);
281 _destroy_layout (layout);
285 _draw_title_and_labels (acre_t *acre)
287 cairo_t *cr = acre->cr;
288 PangoFontDescription *title_font;
289 PangoLayout *title_layout, *x_axis_layout, *y_axis_layout;
290 PangoLayout *min_y, *max_y;
291 int min_y_width, max_y_width, y_axis_value_width;
292 int title_width, title_height;
293 int x_axis_width, x_axis_height;
294 int y_axis_width, y_axis_height;
295 PangoRectangle new_chart;
299 acre->font = pango_font_description_new ();
300 pango_font_description_set_family (acre->font, ACRE_FONT_FAMILY);
301 pango_font_description_set_absolute_size (acre->font,
302 ACRE_FONT_SIZE * PANGO_SCALE);
304 title_font = pango_font_description_new ();
305 pango_font_description_set_family (title_font, ACRE_FONT_FAMILY);
306 pango_font_description_set_absolute_size (title_font,
307 ACRE_TITLE_FONT_SIZE * PANGO_SCALE);
309 title_layout = _create_layout (acre, acre->title);
310 pango_layout_set_font_description (title_layout, title_font);
312 x_axis_layout = _create_layout (acre, acre->x_axis.label);
313 y_axis_layout = _create_layout (acre, acre->y_axis.label);
315 min_y = _create_layout_printf (acre, "%g",
316 round (acre->y_axis.view_min));
317 max_y = _create_layout_printf (acre, "%g",
318 round (acre->y_axis.view_max));
320 pango_layout_get_pixel_size (min_y, &min_y_width, NULL);
321 pango_layout_get_pixel_size (max_y, &max_y_width, NULL);
322 y_axis_value_width = MAX (min_y_width, max_y_width);
324 _destroy_layout (min_y);
325 _destroy_layout (max_y);
327 /* Iterate with the layout of the title and axis labels until they
328 * are stable, (this requires iteration since we don't know what
329 * to set their widths to in advance due to the wrapping of the
330 * other elements). */
332 pango_layout_set_width (title_layout, acre->chart.width * PANGO_SCALE);
333 pango_layout_set_width (x_axis_layout, acre->chart.width * PANGO_SCALE);
334 pango_layout_set_width (y_axis_layout, acre->chart.height * PANGO_SCALE);
336 pango_layout_get_pixel_size (title_layout, &title_width, &title_height);
337 pango_layout_get_pixel_size (x_axis_layout, &x_axis_width, &x_axis_height);
338 pango_layout_get_pixel_size (y_axis_layout, &y_axis_width, &y_axis_height);
340 new_chart.x = ACRE_PAD + y_axis_height +
341 ACRE_PAD + y_axis_value_width + ACRE_Y_TICK_VALUE_PAD;
342 new_chart.width = acre->width - acre->chart.x - ACRE_PAD;
344 new_chart.y = ACRE_PAD + title_height + ACRE_PAD;
345 new_chart.height = acre->height - acre->chart.y -
346 (ACRE_X_TICK_VALUE_PAD + ACRE_FONT_SIZE +
347 ACRE_PAD + x_axis_height + ACRE_PAD);
349 if (new_chart.x == acre->chart.x &&
350 new_chart.y == acre->chart.y &&
351 new_chart.width == acre->chart.width &&
352 new_chart.height == acre->chart.height)
357 acre->chart.x = new_chart.x;
358 acre->chart.y = new_chart.y;
359 acre->chart.width = new_chart.width;
360 acre->chart.height = new_chart.height;
363 cairo_set_source_rgb (cr, 0, 0, 0);
365 cairo_move_to (cr, acre->chart.x, ACRE_PAD);
366 _show_layout (cr, title_layout);
370 cairo_translate (cr, ACRE_PAD, acre->chart.y + acre->chart.height);
371 cairo_rotate (cr, - M_PI / 2.0);
372 cairo_move_to (cr, 0, 0);
373 _show_layout (cr, y_axis_layout);
377 cairo_move_to (cr, acre->chart.x,
378 acre->chart.y + acre->chart.height +
379 ACRE_FONT_SIZE + ACRE_PAD);
380 _show_layout (cr, x_axis_layout);
385 /* For a given axis range, compute a step size (in data space) to
386 * generate a suitable number of ticks (5 or so). */
388 _step_for_range (double range, int *minor_divisions)
390 double step, scale_factor;
392 /* We want roughly 5 major ticks for the chart. */
395 /* Normalize the step so we can easily snap it to a desirable
397 scale_factor = pow (10.0, floor (log10 (step)));
398 step /= scale_factor;
400 /* We want increments of 1, 2.5, 5, or 10 (times some power of
401 * 10). The threshold values between these are computed
402 * logarithmically. */
403 if (step < 3.535533905932738) {
404 if (step < 1.58113883008419) {
406 *minor_divisions = 4;
409 *minor_divisions = 5;
412 if (step < 7.071067811865475) {
414 *minor_divisions = 5;
417 *minor_divisions = 4;
421 /* Un-normalize and we now have the data value that we want to
423 return step * scale_factor;
426 /* Given an axis range, we can compute a desired data-space step
427 * amount for the major ticks (see _step_for_range). To get
428 * nice-looking pixel-snapped ticks we want to expand the range
431 _expand_range_for_width (double *axis_min, double *axis_max, int pixel_range)
433 double range, new_range, step, step_minor, pixel_step;
436 range = *axis_max - *axis_min;
438 step = _step_for_range (range, &minor_divisions);
439 step_minor = step / minor_divisions;
441 pixel_step = step_minor * (pixel_range / range);
443 /* We expand the range by the ratio of the pixel step to the floor
446 new_range = range * pixel_step / floor (pixel_step);
448 /* And spread the increase out on either side of the range. */
449 *axis_min -= (new_range - range) / 2.0;
450 *axis_max += (new_range - range) / 2.0;
453 /* Setup a transformation in acre->cr such that data values plotted
454 * will appear where they should within the chart.
457 _set_transform_to_data_space (acre_t *acre)
459 cairo_t *cr = acre->cr;
463 acre->chart.y + acre->chart.height);
465 acre->chart.width / (acre->x_axis.view_max - acre->x_axis.view_min),
466 - acre->chart.height /(acre->y_axis.view_max - acre->y_axis.view_min));
467 cairo_translate (cr, -acre->x_axis.view_min, -acre->y_axis.view_min);
471 _compute_axis_ranges (acre_t *acre)
473 double x_adjust, y_adjust;
474 cairo_t *cr = acre->cr;
476 /* First, simply set view ranges to data ranges. */
477 acre->x_axis.view_min = acre->x_axis.data_min;
478 acre->x_axis.view_max = acre->x_axis.data_max;
480 acre->y_axis.view_min = acre->y_axis.data_min;
481 acre->y_axis.view_max = acre->y_axis.data_max;
483 /* Next, we want to ensure that the data never collides with the
484 * ticks. So we expand each axis on its minimum side as needed. */
489 _set_transform_to_data_space (acre);
491 x = ACRE_TICK_MAJOR_SIZE + 2.0;
492 y = ACRE_TICK_MAJOR_SIZE + 2.0;
493 cairo_device_to_user_distance (cr, &x, &y);
495 acre->x_axis.view_min -= x;
496 acre->y_axis.view_min += y;
500 /* Then, increase the axis ranges just enough so that the step
501 * sizes for the ticks will be integers.
503 _expand_range_for_width (&acre->x_axis.view_min,
504 &acre->x_axis.view_max,
507 _expand_range_for_width (&acre->y_axis.view_min,
508 &acre->y_axis.view_max,
511 /* Finally, we also translate the axis ranges slightly so that the
512 * ticks land on half-integer device-pixel positions.
516 _set_transform_to_data_space (acre);
520 cairo_user_to_device (cr, &x_adjust, &y_adjust);
521 x_adjust = (round (x_adjust + 0.5) - 0.5) - x_adjust;
522 y_adjust = (round (y_adjust + 0.5) - 0.5) - y_adjust;
523 cairo_device_to_user_distance (cr, &x_adjust, &y_adjust);
525 acre->x_axis.view_min -= x_adjust;
526 acre->x_axis.view_max -= x_adjust;
528 acre->y_axis.view_min -= y_adjust;
529 acre->y_axis.view_max -= y_adjust;
535 _acre_color_from_hsv (acre_color_t *color,
543 hmod6 = (int) floor (hue / 60) % 6;
544 f = hue / 60 - floor (hue / 60);
545 p = value * (1 - saturation);
546 q = value * (1 - f * saturation);
547 t = value * (1 - (1 - f) * saturation);
557 color->green = value;
562 color->green = value;
584 _choose_colors (acre_t *acre)
586 cmsHPROFILE lab_profile, srgb_profile;
587 cmsHTRANSFORM lab_to_srgb;
589 double theta, radius, srgb[3];
592 lab_profile = cmsCreateLabProfile (NULL); /* D50 */
593 srgb_profile = cmsCreate_sRGBProfile ();
595 lab_to_srgb = cmsCreateTransform (lab_profile, TYPE_Lab_DBL,
596 srgb_profile, TYPE_RGB_DBL,
597 INTENT_PERCEPTUAL, 0);
599 acre->num_colors = acre->num_data;
601 if (acre->num_colors > acre->colors_size) {
602 acre->colors_size = acre->num_colors;
603 acre->colors = xrealloc (acre->colors,
604 acre->colors_size * sizeof (acre_color_t));
609 for (i = 0; i < acre->num_colors; i++) {
610 theta = 0.713 + 2 * M_PI * (double) i / acre->num_colors;
611 lab.a = radius * cos (theta);
612 lab.b = radius * sin (theta);
614 cmsDoTransform (lab_to_srgb, &lab, srgb, 1);
616 acre->colors[i].red = srgb[0];
617 acre->colors[i].green = srgb[1];
618 acre->colors[i].blue = srgb[2];
621 cmsDeleteTransform (lab_to_srgb);
622 cmsCloseProfile (lab_profile);
623 cmsCloseProfile (srgb_profile);
627 _draw_data (acre_t *acre)
629 cairo_t *cr = acre->cr;
635 cairo_set_source_rgb (cr, 0, 0, 0);
637 _set_transform_to_data_space (acre);
639 for (d = 0; d < acre->num_data; d++) {
640 int color = d % acre->num_colors;
641 cairo_set_source_rgb (cr,
642 acre->colors[color].red,
643 acre->colors[color].green,
644 acre->colors[color].blue);
645 data = acre->data[d];
647 for (i = 0; i < data->num_points; i++) {
654 cairo_identity_matrix (cr);
655 cairo_set_line_width (cr, 1.0);
664 typedef enum _ticks { ACRE_TICKS_X, ACRE_TICKS_Y } acre_ticks_t;
667 _draw_ticks (acre_t *acre,
668 double axis_min, double axis_max,
671 cairo_t *cr = acre->cr;
672 double t, step, sub_step;
677 _set_transform_to_data_space (acre);
679 step = _step_for_range (axis_max - axis_min, &minor_divisions);
680 sub_step = step / minor_divisions;
682 for (t = (floor (axis_min / sub_step) + 1) * sub_step;
687 if (fabs((t / step) - round (t / step)) < 0.5 * (sub_step / step))
688 tick_size = ACRE_TICK_MAJOR_SIZE;
690 tick_size = ACRE_TICK_MINOR_SIZE;
695 if (ticks == ACRE_TICKS_X)
696 cairo_move_to (cr, t, acre->y_axis.view_min);
698 cairo_move_to (cr, acre->x_axis.view_min, t);
700 cairo_identity_matrix (cr);
702 if (ticks == ACRE_TICKS_X) {
703 cairo_rel_line_to (cr, 0, 0.5);
704 cairo_rel_line_to (cr, 0, -tick_size - 0.5);
706 cairo_rel_line_to (cr, -0.5, 0);
707 cairo_rel_line_to (cr, tick_size + 0.5, 0);
710 cairo_set_line_width (cr, 1.0);
716 if (tick_size == ACRE_TICK_MAJOR_SIZE)
723 layout = _create_layout_printf (acre, "%g", t);
725 if (ticks == ACRE_TICKS_X)
726 cairo_move_to (cr, t, acre->y_axis.view_min);
728 cairo_move_to (cr, acre->x_axis.view_min, t);
730 cairo_identity_matrix (cr);
731 pango_layout_get_pixel_size (layout, &width, &height);
733 if (ticks == ACRE_TICKS_X)
734 cairo_rel_move_to (cr, -width / 2, ACRE_X_TICK_VALUE_PAD);
736 cairo_rel_move_to (cr, -width - ACRE_Y_TICK_VALUE_PAD,
739 _show_layout (cr, layout);
749 _draw_legend (acre_t *acre)
752 int label_width, max_label_width = 0;
755 cairo_t *cr = acre->cr;
759 for (i = 0; i < acre->num_data; i++) {
760 layout = _create_layout (acre, acre->data[i]->name);
761 pango_layout_get_pixel_size (layout, &label_width, NULL);
762 _destroy_layout (layout);
763 if (label_width > max_label_width)
764 max_label_width = label_width;
767 width = ACRE_LEGEND_PAD + ACRE_LEGEND_LINE_SIZE + ACRE_LEGEND_PAD +
768 max_label_width + ACRE_LEGEND_PAD;
769 height = ACRE_LEGEND_PAD +
770 acre->num_data * (ACRE_FONT_SIZE + ACRE_LEGEND_PAD);
772 cairo_translate (cr, acre->chart.x, acre->chart.y);
775 acre->chart.width - ACRE_LEGEND_PAD - width,
778 cairo_rectangle (cr, -0.5, -0.5, width + 1.0, height + 1.0);
779 cairo_set_source_rgb (cr, 0, 0, 0);
780 cairo_set_line_width (cr, 1.0);
783 cairo_translate (cr, ACRE_LEGEND_PAD, ACRE_LEGEND_PAD);
785 for (i = 0; i < acre->num_data; i++) {
787 0, ACRE_LEGEND_LINE_SIZE / 2,
788 ACRE_LEGEND_LINE_SIZE, ACRE_LEGEND_LINE_SIZE / 2);
789 cairo_set_source_rgb (cr,
790 acre->colors[i % acre->num_colors].red,
791 acre->colors[i % acre->num_colors].green,
792 acre->colors[i % acre->num_colors].blue);
795 layout = _create_layout (acre, acre->data[i]->name);
796 cairo_move_to (cr, ACRE_LEGEND_LINE_SIZE + ACRE_LEGEND_PAD, 0);
797 cairo_set_source_rgb (cr, 0, 0, 0);
798 _show_layout (cr, layout);
800 cairo_translate (cr, 0, ACRE_LEGEND_PAD + ACRE_FONT_SIZE);
807 _draw_frame_and_ticks (acre_t *acre)
809 cairo_t *cr = acre->cr;
813 cairo_set_source_rgb (cr, 0, 0, 0); /* black */
816 _draw_ticks (acre, acre->x_axis.view_min, acre->x_axis.view_max, ACRE_TICKS_X);
817 _draw_ticks (acre, acre->y_axis.view_min, acre->y_axis.view_max, ACRE_TICKS_Y);
821 acre->chart.x - 0.5, acre->chart.y - 0.5,
822 acre->chart.width + 1.0, acre->chart.height + 1.0);
823 cairo_set_line_width (cr, 1.0);
829 /* Draw the plot to the given cairo context within a user-space
830 * rectangle from (0, 0) to (width, height). This size includes all
831 * space for extra-plot elements (such as the title, the axis labels,
835 acre_draw (acre_t *acre, cairo_t *cr, int width, int height)
840 acre->height = height;
842 acre->chart.width = width;
843 acre->chart.height = height;
847 cairo_set_source_rgb (cr, 1, 1, 1);
849 _choose_colors (acre);
851 /* We compute the axis ranges before doing label layout so that we
852 * can account for the width of the y-axis value labels. */
853 _compute_axis_ranges (acre);
855 _draw_title_and_labels (acre);
857 /* And we recompute the axis ranges now that the title and axis
858 * label space is all measured and accounted for. */
859 _compute_axis_ranges (acre);
863 if (acre->num_data > 1)
866 _draw_frame_and_ticks (acre);
869 /* Create a new dataset---a collection of (x, y) datapoints. A single
870 * plot can contain multiple datasets, (see acre_add_data). */
872 acre_data_create (void)
876 data = xmalloc (sizeof (acre_data_t));
881 data->points_size = 0;
882 data->num_points = 0;
887 /* Destroy an acre dataset. Do not call this function if the dataset
888 * has been added to an acre_t plot with acre_add_data. */
890 acre_data_destroy (acre_data_t *data)
897 /* Set the label for this dataset (to appear in the plot's key). */
899 acre_data_set_name (acre_data_t *data, const char *name)
903 data->name = strdup (name);
906 /* Add a datapoint to the given dataset. */
908 acre_data_add_point_2d (acre_data_t *data, double x, double y)
910 if (data->num_points >= data->points_size) {
911 data->points_size *= 2;
912 if (data->points_size == 0)
913 data->points_size = 16;
914 data->points = xrealloc_ab (data->points,
916 sizeof (acre_data_point_2d_t));
919 data->points[data->num_points].x = x;
920 data->points[data->num_points].y = y;
922 if (data->num_points == 0) {