git.cworth.org Git - acre/blob - acre.c

   1 /* acre - A cairo-based library for creating plots and charts.
   2  *
   3  * Copyright © 2009 Carl Worth <cworth@cworth.org>
   4  *
   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.
   9  *
  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.
  14  *
  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.
  18  */
  19
  20 #define _ISOC99_SOURCE /* for round() */
  21 #define _XOPEN_SOURCE 500
  22
  23 #include "acre.h"
  24 #include "xmalloc.h"
  25
  26 #include <string.h>
  27 #include <math.h>
  28
  29 typedef struct _acre_data_point_2d {
  30     double x;
  31     double y;
  32 } acre_data_point_2d_t;
  33
  34 struct _acre_data {
  35     char *name;
  36
  37     acre_data_point_2d_t *points;
  38     unsigned int points_size;
  39     unsigned int num_points;
  40 };
  41
  42 typedef struct _acre_axis {
  43     char *label;
  44     double min;
  45     double max;
  46 } acre_axis_t;
  47
  48 struct _acre {
  49     char *title;
  50     acre_axis_t x_axis;
  51     acre_axis_t y_axis;
  52
  53     acre_data_t **data;
  54     unsigned int data_size;
  55     unsigned int num_data;
  56
  57     /* Data for drawing. */
  58     cairo_t *cr;
  59
  60     /* Total size including labels. */
  61     int width;
  62     int height;
  63
  64     /* Position and size of chart alone. */
  65     PangoRectangle chart;
  66 };
  67
  68 /* Create a new, empty plot. */
  69 acre_t *
  70 acre_create (void)
  71 {
  72     acre_t *acre;
  73
  74     acre = xmalloc (sizeof (acre_t));
  75
  76     acre->title = NULL;
  77
  78     acre->x_axis.label = NULL;
  79     acre->x_axis.min = 0.0;
  80     acre->x_axis.max = 0.0;
  81
  82     acre->y_axis.label = NULL;
  83     acre->y_axis.min = 0.0;
  84     acre->y_axis.max = 0.0;
  85
  86     acre->data = NULL;
  87     acre->data_size = 0;
  88     acre->num_data = 0;
  89
  90     return acre;
  91 }
  92
  93 /* Destroy a plot. */
  94 void
  95 acre_destroy (acre_t *acre)
  96 {
  97     unsigned int i;
  98
  99     free (acre->title);
 100     free (acre->x_axis.label);
 101     free (acre->y_axis.label);
 102
 103     for (i = 0; i < acre->num_data; i++)
 104         acre_data_destroy (acre->data[i]);
 105
 106     free (acre->data);
 107
 108     free (acre);
 109 }
 110
 111 void
 112 acre_set_title (acre_t *acre, const char *title)
 113 {
 114     free (acre->title);
 115
 116     acre->title = strdup (title);
 117 }
 118
 119 void
 120 acre_set_x_axis_label (acre_t *acre, const char *label)
 121 {
 122     free (acre->x_axis.label);
 123
 124     acre->x_axis.label = strdup (label);
 125 }
 126
 127 void
 128 acre_set_y_axis_label (acre_t *acre, const char *label)
 129 {
 130     free (acre->y_axis.label);
 131
 132     acre->y_axis.label = strdup (label);
 133 }
 134
 135 /* Add a dataset to the plot. The plot assumes ownership of the
 136  * dataset so it is not necessary to call acre_data_destroy on it. */
 137 void
 138 acre_add_data (acre_t *acre, acre_data_t *data)
 139 {
 140     if (acre->num_data >= acre->data_size) {
 141         acre->data_size *= 2;
 142         if (acre->data_size == 0)
 143             acre->data_size = 1;
 144         acre->data = xrealloc_ab (acre->data,
 145                                   acre->data_size,
 146                                   sizeof (acre_data_t *));
 147     }
 148
 149     acre->data[acre->num_data] = data;
 150     acre->num_data++;
 151 }
 152
 153 #define ACRE_FONT_FAMILY "sans"
 154 #define ACRE_FONT_SIZE 12
 155 #define ACRE_TITLE_FONT_SIZE 32
 156 #define ACRE_PAD (ACRE_FONT_SIZE)
 157 #define ACRE_TICK_SIZE 6
 158
 159 static void
 160 _draw_title_and_labels (acre_t *acre)
 161 {
 162     cairo_t *cr = acre->cr;
 163     PangoFontDescription *acre_font, *title_font;
 164     PangoLayout *title_layout, *x_axis_layout, *y_axis_layout;
 165     int title_width, title_height;
 166     int x_axis_width, x_axis_height;
 167     int y_axis_width, y_axis_height;
 168     PangoRectangle new_chart;
 169
 170     cairo_save (cr);
 171
 172     acre_font = pango_font_description_new ();
 173     pango_font_description_set_family (acre_font, ACRE_FONT_FAMILY);
 174     pango_font_description_set_absolute_size (acre_font,
 175                                               ACRE_FONT_SIZE * PANGO_SCALE);
 176
 177     title_font = pango_font_description_new ();
 178     pango_font_description_set_family (title_font, ACRE_FONT_FAMILY);
 179     pango_font_description_set_absolute_size (title_font,
 180                                               ACRE_TITLE_FONT_SIZE * PANGO_SCALE);
 181
 182     title_layout = pango_cairo_create_layout (cr);
 183     pango_layout_set_font_description (title_layout, title_font);
 184     pango_layout_set_text (title_layout, acre->title, -1);
 185     pango_layout_set_alignment (title_layout, PANGO_ALIGN_CENTER);
 186
 187     x_axis_layout = pango_cairo_create_layout (cr);
 188     pango_layout_set_font_description (x_axis_layout, acre_font);
 189     pango_layout_set_text (x_axis_layout, acre->x_axis.label, -1);
 190     pango_layout_set_alignment (x_axis_layout, PANGO_ALIGN_CENTER);
 191
 192     y_axis_layout = pango_cairo_create_layout (cr);
 193     pango_layout_set_font_description (y_axis_layout, acre_font);
 194     pango_layout_set_text (y_axis_layout, acre->y_axis.label, -1);
 195     pango_layout_set_alignment (y_axis_layout, PANGO_ALIGN_CENTER);
 196
 197     /* Iterate with the layout of the title and axis labels until they
 198      * are stable, (this requires iteration since we don't know what
 199      * to set their widths to in advance due to the wrapping of the
 200      * other elements). */
 201     acre->chart.x = 0;
 202     acre->chart.y = 0;
 203     acre->chart.width = acre->width;
 204     acre->chart.height = acre->height;
 205     while (1) {
 206         pango_layout_set_width (title_layout, acre->chart.width * PANGO_SCALE);
 207         pango_layout_set_width (x_axis_layout, acre->chart.width * PANGO_SCALE);
 208         pango_layout_set_width (y_axis_layout, acre->chart.height * PANGO_SCALE);
 209
 210         pango_layout_get_pixel_size (title_layout, &title_width, &title_height);
 211         pango_layout_get_pixel_size (x_axis_layout, &x_axis_width, &x_axis_height);
 212         pango_layout_get_pixel_size (y_axis_layout, &y_axis_width, &y_axis_height);
 213
 214         new_chart.x = ACRE_PAD + y_axis_height +
 215             ACRE_PAD + ACRE_FONT_SIZE;
 216         new_chart.width = acre->width - acre->chart.x - ACRE_PAD;
 217
 218         new_chart.y = ACRE_PAD + title_height + ACRE_PAD;
 219         new_chart.height = acre->height - acre->chart.y - (ACRE_FONT_SIZE + ACRE_PAD + x_axis_height + ACRE_PAD);
 220
 221         if (new_chart.x == acre->chart.x &&
 222             new_chart.y == acre->chart.y &&
 223             new_chart.width == acre->chart.width &&
 224             new_chart.height == acre->chart.height)
 225         {
 226             break;
 227         }
 228
 229         acre->chart.x = new_chart.x;
 230         acre->chart.y = new_chart.y;
 231         acre->chart.width = new_chart.width;
 232         acre->chart.height = new_chart.height;
 233     }
 234
 235     cairo_set_source_rgb (cr, 0, 0, 0);
 236
 237     cairo_move_to (cr, acre->chart.x, ACRE_PAD);
 238     pango_cairo_show_layout (cr, title_layout);
 239
 240     cairo_save (cr);
 241     {
 242         cairo_translate (cr, ACRE_PAD, acre->chart.y + acre->chart.height);
 243         cairo_rotate (cr, - M_PI / 2.0);
 244         cairo_move_to (cr, 0, 0);
 245         pango_cairo_show_layout (cr, y_axis_layout);
 246     }
 247     cairo_restore (cr);
 248
 249     cairo_move_to (cr, acre->chart.x,
 250                    acre->chart.y + acre->chart.height +
 251                    ACRE_FONT_SIZE + ACRE_PAD);
 252     pango_cairo_show_layout (cr, x_axis_layout);
 253
 254     cairo_restore (cr);
 255 }
 256
 257 /* For a given axis range, compute a step size (in data space) to
 258  * generate a suitable number of ticks (5 or so). */
 259 static double
 260 _step_for_range (double range)
 261 {
 262     double step, scale_factor;
 263
 264     /* We want roughly 5 major ticks for the chart. */
 265     step = range / 5;
 266
 267     /* Normalize the step so we can easily snap it to a desirable
 268      * value. */
 269     scale_factor = pow (10.0, floor (log10 (step)));
 270     step /= scale_factor;
 271
 272     /* We want increments of 1, 2.5, 5, or 10 (times some power of
 273      * 10). The threshold values between these are computed
 274      * logarithmically. */
 275     if (step < 3.535533905932738) {
 276         if (step < 1.58113883008419)
 277             step = 1.0;
 278         else
 279             step = 2.5;
 280     } else {
 281         if (step < 7.071067811865475)
 282             step = 5.0;
 283         else
 284             step = 10.0;
 285     }
 286
 287     /* Un-normalize and we now have the data value that we want to
 288      * step at. */
 289     return step * scale_factor;
 290 }
 291
 292 /* Given an axis range, we can compute a desired data-space step
 293  * amount for the major ticks (see _step_for_range). To get
 294  * nice-looking pixel-snapped ticks we want to expand the range
 295  * slightly. */
 296 static double
 297 _expand_range (double data_range, int pixel_size)
 298 {
 299     double step, pixel_step;
 300
 301     step = _step_for_range (data_range);
 302     pixel_step = step * pixel_size / data_range;
 303
 304     /* We expand the range by the ratio of the pixel step to the floor
 305      * of the pixel_step.
 306      */
 307     return data_range * pixel_step / floor (pixel_step);
 308 }
 309
 310 /* Setup a transformation in acre->cr such that data values plotted
 311  * will appear where they should within the chart.
 312  */
 313 static void
 314 _set_transform_to_data_space (acre_t *acre)
 315 {
 316     cairo_t *cr = acre->cr;
 317
 318     cairo_translate (cr,
 319                      acre->chart.x,
 320                      acre->chart.y + acre->chart.height);
 321     cairo_scale (cr,
 322                  acre->chart.width / (acre->x_axis.max - acre->x_axis.min),
 323                  - acre->chart.height /(acre->y_axis.max - acre->y_axis.min));
 324     cairo_translate (cr, -acre->x_axis.min, -acre->y_axis.min);
 325 }
 326
 327 static void
 328 _compute_axis_ranges (acre_t *acre)
 329 {
 330     unsigned int d, i;
 331     acre_data_t *data;
 332     double x_range, new_x_range, x_adjust;
 333     double y_range, new_y_range, y_adjust;
 334     cairo_t *cr = acre->cr;
 335
 336     /* First, simply find the extrema of the data. */
 337     for (d = 0; d < acre->num_data; d++) {
 338         data = acre->data[d];
 339         for (i = 0; i < data->num_points; i++) {
 340             if (data->points[i].x < acre->x_axis.min)
 341                 acre->x_axis.min = data->points[i].x;
 342             if (data->points[i].x > acre->x_axis.max)
 343                 acre->x_axis.max = data->points[i].x;
 344
 345             if (data->points[i].y < acre->y_axis.min)
 346                 acre->y_axis.min = data->points[i].y;
 347             if (data->points[i].y > acre->y_axis.max)
 348                 acre->y_axis.max = data->points[i].y;
 349         }
 350     }
 351
 352     /* Next, increase the axis ranges just enough so that the step
 353      * sizes for the ticks will be integers.
 354      */
 355     x_range = acre->x_axis.max - acre->x_axis.min;
 356     new_x_range = _expand_range (x_range, acre->chart.width);
 357
 358     y_range = acre->y_axis.max - acre->y_axis.min;
 359     new_y_range = _expand_range (y_range, acre->chart.height);
 360
 361     /* And spread the increase out on either side of the range. */
 362     acre->x_axis.min -= (new_x_range - x_range) / 2.0;
 363     acre->x_axis.max += (new_x_range - x_range) / 2.0;
 364
 365     acre->y_axis.min -= (new_y_range - y_range) / 2.0;
 366     acre->y_axis.max += (new_y_range - y_range) / 2.0;
 367
 368     /* Finally, we also translate the axis ranges slightly so that the
 369      * ticks land on half-integer device-pixel positions.
 370      */
 371     cairo_save (cr);
 372     {
 373         _set_transform_to_data_space (acre);
 374
 375         x_adjust = 0.0;
 376         y_adjust = 0.0;
 377         cairo_user_to_device (cr, &x_adjust, &y_adjust);
 378         x_adjust = (round (x_adjust + 0.5) - 0.5) - x_adjust;
 379         y_adjust = (round (y_adjust + 0.5) - 0.5) - y_adjust;
 380         cairo_device_to_user_distance (cr, &x_adjust, &y_adjust);
 381
 382         acre->x_axis.min -= x_adjust;
 383         acre->x_axis.max -= x_adjust;
 384
 385         acre->y_axis.min -= y_adjust;
 386         acre->y_axis.max -= y_adjust;
 387     }
 388     cairo_restore (cr);
 389 }
 390
 391 static void
 392 _draw_data (acre_t *acre)
 393 {
 394     cairo_t *cr = acre->cr;
 395     unsigned int d, i;
 396     acre_data_t *data;
 397
 398     cairo_save (cr);
 399
 400     cairo_set_source_rgb (cr, 0, 0, 0);
 401
 402     _set_transform_to_data_space (acre);
 403
 404     for (d = 0; d < acre->num_data; d++) {
 405         data = acre->data[d];
 406         cairo_new_path (cr);
 407         for (i = 0; i < data->num_points; i++) {
 408             cairo_line_to (cr,
 409                            data->points[i].x,
 410                            data->points[i].y);
 411         }
 412         cairo_save (cr);
 413         {
 414             cairo_identity_matrix (cr);
 415             cairo_set_line_width (cr, 1.0);
 416             cairo_stroke (cr);
 417         }
 418         cairo_restore (cr);
 419     }
 420
 421     cairo_restore (cr);
 422 }
 423
 424 static void
 425 _draw_frame_and_ticks (acre_t *acre)
 426 {
 427     cairo_t *cr = acre->cr;
 428     double step, x, y;
 429
 430     cairo_save (cr);
 431
 432     cairo_set_source_rgb (cr, 0, 0, 0); /* black */
 433
 434     /* First the ticks within data space. */
 435     cairo_save (cr);
 436     {
 437         _set_transform_to_data_space (acre);
 438
 439         step = _step_for_range (acre->x_axis.max -acre->x_axis.min);
 440         x = (floor (acre->x_axis.min / step) + 1) * step;
 441         while (x <= acre->x_axis.max) {
 442             cairo_move_to (cr, x, acre->y_axis.min);
 443             cairo_save (cr);
 444             {
 445                 cairo_identity_matrix (cr);
 446                 cairo_rel_line_to (cr, 0, 0.5);
 447                 cairo_rel_line_to (cr, 0, -ACRE_TICK_SIZE-0.5);
 448                 cairo_set_line_width (cr, 1.0);
 449                 cairo_stroke (cr);
 450             }
 451             cairo_restore (cr);
 452             x += step;
 453         }
 454
 455         step = _step_for_range (acre->y_axis.max -acre->y_axis.min);
 456         y = (floor (acre->y_axis.min / step) + 1) * step;
 457         while (y <= acre->y_axis.max) {
 458             cairo_move_to (cr, acre->x_axis.min, y);
 459             cairo_save (cr);
 460             {
 461                 cairo_identity_matrix (cr);
 462                 cairo_rel_line_to (cr, -0.5, 0);
 463                 cairo_rel_line_to (cr, ACRE_TICK_SIZE+0.5, 0);
 464                 cairo_set_line_width (cr, 1.0);
 465                 cairo_stroke (cr);
 466             }
 467             cairo_restore (cr);
 468             y += step;
 469         }
 470     }
 471     cairo_restore (cr);
 472
 473     /* Then the frame drawn in pixel space. */
 474     cairo_rectangle (cr,
 475                      acre->chart.x - 0.5, acre->chart.y - 0.5,
 476                      acre->chart.width + 1.0, acre->chart.height + 1.0);
 477     cairo_set_line_width (cr, 1.0);
 478     cairo_stroke (cr);
 479
 480     cairo_restore (cr);
 481 }
 482
 483 /* Draw the plot to the given cairo context within a user-space
 484  * rectangle from (0, 0) to (width, height). This size includes all
 485  * space for extra-plot elements (such as the title, the axis labels,
 486  * etc.)
 487  */
 488 void
 489 acre_draw (acre_t *acre, cairo_t *cr, int width, int height)
 490 {
 491     acre->cr = cr;
 492     acre->width = width;
 493     acre->height = height;
 494
 495     cairo_save (cr);
 496
 497     cairo_set_source_rgb (cr, 1, 1, 1);
 498
 499     cairo_paint (cr);
 500
 501     _draw_title_and_labels (acre);
 502
 503     _compute_axis_ranges (acre);
 504
 505     _draw_data (acre);
 506
 507     _draw_frame_and_ticks (acre);
 508 }
 509
 510 /* Create a new dataset---a collection of (x, y) datapoints. A single
 511  * plot can contain multiple datasets, (see acre_add_data). */
 512 acre_data_t *
 513 acre_data_create (void)
 514 {
 515     acre_data_t *data;
 516
 517     data = xmalloc (sizeof (acre_data_t));
 518
 519     data->name = NULL;
 520
 521     data->points = NULL;
 522     data->points_size = 0;
 523     data->num_points = 0;
 524
 525     return data;
 526 }
 527
 528 /* Destroy an acre dataset. Do not call this function if the dataset
 529  * has been added to an acre_t plot with acre_add_data. */
 530 void
 531 acre_data_destroy (acre_data_t *data)
 532 {
 533     free (data->points);
 534
 535     free (data);
 536 }
 537
 538 /* Set the label for this dataset (to appear in the plot's key). */
 539 void
 540 acre_data_set_name (acre_data_t *data, const char *name)
 541 {
 542     free (data->name);
 543
 544     data->name = strdup (name);
 545 }
 546
 547 /* Add a datapoint to the given dataset. */
 548 void
 549 acre_data_add_point_2d (acre_data_t *data, double x, double y)
 550 {
 551     if (data->num_points >= data->points_size) {
 552         data->points_size *= 2;
 553         if (data->points_size == 0)
 554             data->points_size = 16;
 555         data->points = xrealloc_ab (data->points,
 556                                     data->points_size,
 557                                     sizeof (acre_data_point_2d_t));
 558     }
 559
 560     data->points[data->num_points].x = x;
 561     data->points[data->num_points].y = y;
 562     data->num_points++;
 563 }