proj/mag/harp/libs/matlab/mfile-mex/standalone/text_on_image_font_helper.c

#include "mex.h"  /* must appear first */
#include <math.h>
#include <unistd.h>
#include "mexhead.h" /* my mex defines */
#include "Doc/text_on_image_font_helper_docstring.h"  /* autogenerated */

/******************************************

%text_on_image_font_helper: render characters of a font for use later
%
% [bm,cpos] = text_on_image_font_helper(fontfile, dict, height, width)
% * Renders a set of characters, dict, into a 3d stack of bitmaps bm,
% using a given TrueType font file, and a given height and width.
% The per-character positions (start and end) are given in cpos.
% * The font file name is given in `fontfile'.  Reasonable 
% truetype (.ttf) files work, and some truetype collections (.ttc/.ttfc)
% work.  Some truetype collections (e.g., Apple's Menlo) do not work.
% However, ordinary .ttf files can be extracted from .ttc's.
% * The list of characters to convert is given in `dict'.
% * The dimensions of each output character are the same (which might
% be undesirable sometimes).  This can be addressed using the wid output.
% * The height argument is in this format:
%    [char_height allow_space_for_descenders top_pad bottom_pad]
% char_height is in pixels.  By default, the highest ascender and lowest 
% descender in the font fit into char_height.  If allow_space_for_descenders
% is false, room is made for ascenders only, which is useful for, e.g., 
% maximizing compactness in digit-only text.  The last two entries give
% top and bottom padding, respectively.  They can be negative, which 
% is helpful if, for example, too much space is being left for 
% ascenders.
% * The width of each bitmap is enough to accommodate the character
% width(1) (which is an integer value supplied as a double, but 
% representing a unicode character).  Additionally, extra padding
% to the left and right can be given in width(2) and width(3), which
% can again be negative to soak up extra space.
% * The default height is 32 pixels, accommodating both ascenders
% and descenders, and no extra padding.  The height entries can be
% cut off at any point, so [], [32], [32 1], [32 1 -1], and [32 1 -1 -2]
% are all legal inputs.
% * The default character-width is that of `0', and no extra padding.
% As with height, the entries may be cut off at any point.
% * The bitmap is in raster scan order (left -> right, top -> bottom).
% To display in matlab, use image(bm(:,:,nchar)').
% * The character positions can be used to extract the original character
% bitmap within the TrueType font from its embedding into a standard-size
% bitmap.  It is offset by 1 and clipped to the valid range, so you can
% use: bm(cpos(1,nchar):cpos(2,nchar),:,nchar).  
% 
% Inputs:
%  string font
%  string dict(n)
%  opt int height(0, 1, 2, 3, or 4) = [32 1 0 0]
%  opt int width(0, 1, 2, or 3) = [double('0') 0 0]
% 
% Outputs:
%  uint8 bm(wd,ht,n)
%  opt real cpos(2,n)
% 
% See Also:  text_on_image
%
******************************************/
 
/* constants and globals used for error checking */

#define NARGIN_MIN  2       /* number of inputs */
#define NARGIN_MAX  4       /* number of inputs */
#define NARGOUT_MIN 0       /* number of output args */
#define NARGOUT_MAX 2       /* number of output args */

#define ARG_font   0 
#define ARG_dict   1
#define ARG_height 2
#define ARG_width  3

#define ARG_bm     0
#define ARG_cpos   1

static const char *progname = "text_on_image_font_helper";
#define PROGNAME text_on_image_font_helper
static const char *in_specs[NARGIN_MAX] = {
  "SV",
  "SV",
  "IM(0,0)|IV(1)|IV(2)|IV(3)|IV(4)",  // IM(0,0) permits []
  "IM(0,0)|IV(1)|IV(2)|IV(3)",
};
static const char *in_names[NARGIN_MAX] = {
  "font",
  "dict",
  "height",
  "width",
};
static const char *out_names[NARGOUT_MAX] = {
  "bm", "cw" };


/*******************************************************************
 * Computational routines
 *******************************************************************/

// This expands the actual implementation into this file
#define STB_TRUETYPE_IMPLEMENTATION
#include "stb_truetype.h"

/*
 * Note on coordinate systems for the truetype library
 *  Using the coords returned by stbtt_GetCodepointBitmapBox, the
 *  bitmap of a char extends from x0..x1 (width) and y0..y1 (height)
 *  The bitmaps are presented in raster order, scanning fastest along width.
 *
 *  For instance, in Consolas.ttf at a scale of 16 pixels in height, the char Q 
 *  extends in this range:
 *  X:   0 ..   9
 *  Y: -11 ..   3
 *  The char "." at the same scale has:
 *  X:   3 ..   6
 *  Y:  -3 ..   1
 *
 *  The width in pixels is just x1-x0; similarly for the height.
 *  The x numbers are straightforward offsets, in the rightward direction,
 *  from the left edge.  For instance, "Q" has an offset of 0 (it is up
 *  against the left edge), while "." has an offset of +3.
 *  The y numbers are best thought of as an offset from the baseline (i.e.,
 *  the bottom edge of, for instance, the capital X).  y0 is the number you
 *  would add to an array position, which is at the baseline, to obtain the 
 *  top edge of the character.  So, the above y0 for Q of -11 means Q starts
 *  11 pixels above the baseline.  The y1 of +3 means Q extends 3 pixels
 *  below the baseline.
 *
 *       x
 *    |---->
 *  y |
 *    |  (negative y is up here)
 *    |
 *    | --+--  <-- baseline in (-), and origin at (+)
 *    | 
 *    V
 *
 *  These are the two bitmaps returned as ascii art.
 *
 *       "Q"                 "."
 *   +---------+            +---+
 *   |   .:.   |            |.i |
 *   |  V@@@V  |            |M@i|
 *   | V@. .@o |          + |V@:| <---- baseline (-); origin (+)
 *   |.@:   i@ |            | . | 
 *   |:@    .@.|            +---+
 *   |i@     @:|
 *   |i@     @:|
 *   |i@    :@.|
 *   |.@:   oM |
 *   | V@:.i@: |
 *   |+ V@@@:  |  <---- baseline (-); origin (+)
 *   |   .@.   |
 *   |    MMioi|
 *   |     oMV.|
 *   +---------+
 */


/*
 * Opens the font, returns the font buffer and the font structure
 * through two pointer arguments.
 * If trouble, returns a non-NULL error message.  The outputs in this
 * case are NULL and do not need to be freed.
 * If OK, returns NULL, and both outputs are valid and must be freed
 * by the caller.
 */
static 
char *
open_font(char *fontfile,
      stbtt_fontinfo **fontP,    // output: must be freed by caller
      unsigned char **ttf_bufP   // output: must be freed by caller
      )
{
  FILE *fp;
  const size_t BlockSize = 1<<20; // gets most .ttf files in one slurp
  int blocks;
  int offset;
  // used within, assigned to outputs upon exit
  unsigned char *ttf_buf;
  stbtt_fontinfo *font;

  // in case of error, both outputs will be left as null
  *fontP = NULL;
  *ttf_bufP = NULL;

  // Read truetype file
  if ((fp = fopen(fontfile, "rb")) == NULL) {
    return "Could not open font file";
  }
  if ((ttf_buf = malloc(1 * BlockSize)) == NULL)
    return "Failed to allocate buffer for file";
  for (blocks = 0; !feof(fp); blocks++)
    fread(ttf_buf, BlockSize, 1, fp);
  if (blocks > 1) {
    // older and wiser, we start over
    rewind(fp); // clears eof
    free(ttf_buf);
    if ((ttf_buf = malloc(blocks*BlockSize)) == NULL)
      return "Failed to reallocate buffer for file";
    fread(ttf_buf, BlockSize, (size_t) blocks, fp);
  }
  fclose(fp);

  // Find the particular font
  if ((offset = stbtt_GetFontOffsetForIndex(ttf_buf, 0)) < 0) {
    free(ttf_buf);
    return "Truetype problem: FontOffset (weird ttc?)";
  }
  // Load the font
  if ((font = malloc(sizeof(stbtt_fontinfo))) == NULL) {
    free(ttf_buf);
    return "Failed to allocate font object";
  }    
  if (stbtt_InitFont(font, ttf_buf, offset) == 0) {
    free(font);
    free(ttf_buf);
    return "Truetype problem: InitFont";
  }
  
  // assign outputs and return OK
  *fontP = font;
  *ttf_bufP = ttf_buf;
  return NULL;
}
      

/* 
 * find_scale: determine bitmap dims and font scale based on height and width information
 */
static char *
find_scale(stbtt_fontinfo *font,
       // outputs
       int *height_dimP,   // height of bitmaps with all padding, pixels
       int *width_dimP,    // width of bitmaps with all padding, pixels
       int *baselineP,     // distance of baseline (bottom of "X") below bitmap top
       float *scaleP,      // font scale factor
       // height info
       int height_char, 
       int add_descenders, 
       int height_pad_top, 
       int height_pad_bot,
       // width info
       int width_reference, 
       int width_pad_left, 
       int width_pad_right)
{
  // convenient place to put outputs
  int height_dim, width_dim, baseline;
  float scale;
  // other vars
  int ascent, descent;
  int advanceWidth, leftSideBearing;
  int width_char;

  // Height scaling
  // Below: ascent is the coordinate above the baseline the font extends; descent
  // is the coordinate below the baseline the font extends (i.e. it is typically negative)
  stbtt_GetFontVMetrics(font, &ascent, &descent, NULL);
  if (add_descenders) {
    scale = (float) height_char / (ascent - descent);
    baseline = height_pad_top + ceil(scale * ascent);
  } else {
    scale = (float) height_char / ascent;
    baseline = height_pad_top + height_char;
  }
  // full bitmap height: character height plus padding
  height_dim = height_char + height_pad_top + height_pad_bot;
  // error check
  if (height_dim <= 0 || baseline < 0)
    return "Error finding height dimensions";

  // Width scaling
  stbtt_GetCodepointHMetrics(font, width_reference, &advanceWidth, &leftSideBearing);
  if (0)
    printf("advanceWidth = %d, lsb = %d, scale = %f\n", 
       advanceWidth, leftSideBearing, scale);
  width_char = (int) ceil(advanceWidth * scale); // width of the reference char in scaled units
  // full bitmap height: character width plus padding
  width_dim = width_char + width_pad_left + width_pad_right;
  if (0)
    printf("Width computed from `%c': char %d, total dim %d\n", 
       width_reference, width_char, width_dim);
  // error check
  if (width_dim <= 0)
    return "Error finding width dimensions";

  if (0)
    printf("Desired character height = %d pixels -> scalefactor = %.4f\n", 
       height_char, scale);

  // assign outputs
  *height_dimP = height_dim;
  *width_dimP  = width_dim;
  *baselineP   = baseline;
  *scaleP      = scale;
  // return OK
  return NULL;
}


/* 
 * render: fill in bitmaps "bms", one for each character in "dict"
 * also fills in the character widths, cws, if non-null
 */
static
char *
render(stbtt_fontinfo *font,
       mxChar *dict,
       int Ndict,
       double *cpos,         // char positions
       unsigned char *bms,   // bitmaps
       int Hdim, 
       int Wdim,
       int baseline,
       int width_pad_left,
       int width_pad_right,
       float scale)
{
  unsigned char *bms1;
  int x0, y0, x1, y1;
  int xOrig, yOrig;
  int nchar;
  int c;
  float scalefac;

  // Load each bitmap
  for (nchar = 0, bms1 = bms; nchar < Ndict; nchar++, bms1 += Wdim*Hdim) {
    // the char we're rendering
    c = (int) dict[nchar];
    // bitmap of this char extends from x0..x1 (width) and y0..y1 (height)
    // Typically y0 is negative, with increasing negativity meaning 
    // "extending higher above baseline".
    // Typically x0 is positive, with increasing x0 meaning "beginning
    // farther over to the right".
    // See above note on coordinate systems for more.
    stbtt_GetCodepointBitmapBox(font, c, scale, scale,
                &x0, &y0, &x1, &y1);
    // desired x origin for *our* bitmap
    xOrig = x0 + width_pad_left;
    if (xOrig < 0) xOrig = 0;   // will thus be clipped on left
    if (xOrig > Wdim) continue; // is totally off-image (should not happen)
    // desired y origin
    yOrig = baseline + y0;
    if (yOrig < 0) yOrig = 0;
    if (yOrig > Hdim) continue; // totally off-image
    // put the bitmap in starting at (xOrig, yOrig)
    stbtt_MakeCodepointBitmap(font, 
                  bms1 + xOrig + yOrig*Wdim, 
                  Wdim-xOrig, // limit width so bitmap chip does not overflow
                  Hdim-yOrig, // limit height
                  Wdim,       // stride between rows of bitmap
                  scale, scale, c);
    // set up char width
    if (cpos) {
      // char position within bitmap (take padding into account)
      cpos[nchar*2+0] = x0 + width_pad_left + 1; // +1 for matlab coords
      cpos[nchar*2+1] = x1 + width_pad_left + 1; // +1 for matlab coords
      // make into a valid Matlab index into the bitmap
      if (cpos[nchar*2+0] < 1   ) cpos[nchar*2+0] = 1;
      if (cpos[nchar*2+0] > Wdim) cpos[nchar*2+0] = Wdim;
    }
    if (0)
      printf("*** Copied char #%d = <%04x> = <%c>\n"
         "\tX: % 3d .. % 3d\n\tY: % 3d .. % 3d\n", 
         nchar+1, c, c, x0, x1, y0, y1);
  }
  return NULL;
}

/*******************************************************************
 * Gateway Routine
 *******************************************************************/

// largest number of pixels in each dimension of bitmap, for error checks
#define MAX_PIX_SIZE 1024

#ifdef StaticP  /* undefined under mex */
StaticP
#endif
void
mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[])
{
  char errstr[256];
  char *msg;
  // font info
  stbtt_fontinfo *font;
  unsigned char *fontbuf;
  // font filename
  char *fontfile;
  // character dictionary
  mxChar *dict;
  int Ndict;
  // all height info
  double *heights;
  int Nheight;
  int height_char, add_descenders, height_pad_top, height_pad_bot;
  // all width info
  double *widths;
  int Nwidth;
  int width_reference, width_pad_left, width_pad_right;
  // derived dimension info
  int height_dim, width_dim;
  int baseline;
  float scale;
  // bitmaps
  mwSize dims[3];
  // char widths
  double *cpos_arg;

  /* Hook for introspection (function signature, docstring) */
  if (nrhs < 0) { 
    plhs[0] = mxt_PackSignature((mxt_Signature) (-nrhs), 
                               NARGIN_MIN, NARGIN_MAX, 
                       NARGOUT_MIN, NARGOUT_MAX, 
                               in_names, in_specs, out_names, docstring);
    return;
  }
  /* argument checking */
  if ((nrhs < NARGIN_MIN) || (nrhs > NARGIN_MAX))
    mexErrMsgTxt((snprintf(errstr, sizeof(errstr),
             "%s: Expect %d <= input args <= %d",
              progname, NARGIN_MIN, NARGIN_MAX), errstr));
  if ((nlhs < NARGOUT_MIN) || (nlhs > NARGOUT_MAX))
    mexErrMsgTxt((snprintf(errstr, sizeof(errstr),
             "%s: Expect %d <= output args <= %d",
              progname, NARGOUT_MIN, NARGOUT_MAX), errstr));
  mexargparse(nrhs, prhs, in_names, in_specs, NULL, progname);

  //
  // LOAD AND CHECK ARGUMENTS
  //

  // check heights + widths first, before any allocations

  // bitmap height
  if (nrhs > ARG_height) {
    heights = mxGetPr(prhs[ARG_height]);
    Nheight = mxGetNumberOfElements(prhs[ARG_height]);
  } else {
    heights = NULL;
    Nheight = 0;
  }
  if (Nheight > 0)
    height_char = heights[0];
  else
    height_char = 32;
  if (Nheight > 1) 
    add_descenders = (heights[1] > 0);
  else
    add_descenders = 1;
  if (Nheight > 2)
    height_pad_top = heights[2];
  else
    height_pad_top = 0;
  if (Nheight > 3)
    height_pad_bot = heights[3];
  else
    height_pad_bot = height_pad_top;
  if (height_char <= 0 || height_char > MAX_PIX_SIZE)
    mexErrMsgTxt((snprintf(errstr, sizeof(errstr),
               "%s: character height is a positive integer, not too big, got %d", 
               progname, height_char), errstr));
  if (height_pad_top < -MAX_PIX_SIZE || height_pad_top > MAX_PIX_SIZE)
    mexErrMsgTxt((snprintf(errstr, sizeof(errstr),
               "%s: height pad top is too big, got %d", 
               progname, height_pad_top), errstr));
  if (height_pad_bot < -MAX_PIX_SIZE || height_pad_bot > MAX_PIX_SIZE)
    mexErrMsgTxt((snprintf(errstr, sizeof(errstr),
               "%s: height pad bot is too big, got %d", 
               progname, height_pad_bot), errstr));

  // desired bitmap width
  if (nrhs > ARG_width) {
    widths = mxGetPr(prhs[ARG_width]);
    Nwidth = mxGetNumberOfElements(prhs[ARG_width]);
  } else {
    widths = NULL;
    Nwidth = 0;
  }
  if (Nwidth > 0)
    width_reference = (int) widths[0]; // this is a character code
  else
    width_reference = (int) '0';  // default to the width of "0"
  if (Nwidth > 1)
    width_pad_left = widths[1];
  else
    width_pad_left = 0;
  if (Nwidth > 2)
    width_pad_right = widths[2];
  else
    width_pad_right = width_pad_left;
  if (width_pad_left < -MAX_PIX_SIZE || width_pad_left > MAX_PIX_SIZE)
    mexErrMsgTxt((snprintf(errstr, sizeof(errstr),
               "%s: width pad left is too big, got %d", 
               progname, width_pad_left), errstr));
  if (width_pad_right < -MAX_PIX_SIZE || width_pad_right > MAX_PIX_SIZE)
    mexErrMsgTxt((snprintf(errstr, sizeof(errstr),
               "%s: width pad right is too big, got %d", 
               progname, width_pad_right), errstr));

  // dictionary of chars
  Ndict = mxGetNumberOfElements(prhs[ARG_dict]);
  dict = mxGetChars(prhs[ARG_dict]);

  // font name
  if ((fontfile = mxArrayToString(prhs[ARG_font])) == NULL)
    mexErrMsgTxt((snprintf(errstr, sizeof(errstr),
               "%s: could not get the font name", 
               progname), errstr));
  if (access(fontfile, R_OK) < 0)
    mexErrMsgTxt((snprintf(errstr, sizeof(errstr),
               "%s: could not access the font file `%s'", 
               progname, fontfile), errstr));

  //
  // DO THE COMPUTATION
  //

  // open truetype file
  // (the calling routine needs to free font and fontbuf if it returns OK)
  msg = open_font(fontfile, &font, &fontbuf);
  if (msg) {
    mxFree(fontfile);
    mexErrMsgTxt((snprintf(errstr, sizeof(errstr),
               "%s: problem opening font file: %s", 
               progname, msg), errstr));
  }
  mxFree(fontfile); // don't need the filename any longer

  // determine bitmap dimensions and font scale based on height and width information
  msg = find_scale(font,
           // outputs
           &height_dim, &width_dim, &baseline, &scale,
           // height info
           height_char, add_descenders, height_pad_top, height_pad_bot,
           // width info
           width_reference, width_pad_left, width_pad_right);
  if (msg) {
    free(font);
    free(fontbuf);
    mexErrMsgTxt((snprintf(errstr, sizeof(errstr),
               "%s: problem finding font information: %s", 
               progname, msg), errstr));
  }
           
  // allocate memory: one bitmap for each entry in dict
  dims[0] = width_dim;
  dims[1] = height_dim;
  dims[2] = Ndict;
  if ((plhs[ARG_bm] = mxCreateNumericArray(3, dims, mxUINT8_CLASS, mxREAL)) == NULL) {
    free(font);
    free(fontbuf);
    mexErrMsgTxt((snprintf(errstr, sizeof(errstr),
               "%s: could not allocate memory for %d bitmaps of size %d x %d", 
               progname, Ndict, width_dim, height_dim), errstr));
  }
  if (nlhs > ARG_cpos) {
    plhs[ARG_cpos] = mxCreateDoubleMatrix(2, Ndict, mxREAL); // bm was ok, so don't check
    cpos_arg = mxGetPr(plhs[ARG_cpos]);
  } else {
    cpos_arg = NULL;
  }

  // render the chars in the dictionary
  msg = render(font,
           dict, Ndict, 
           cpos_arg,
           mxGetData(plhs[ARG_bm]),
           height_dim, width_dim, 
           baseline, width_pad_left, width_pad_right,
           scale);
  if (msg) {
    free(font);
    free(fontbuf);
    mxDestroyArray(plhs[ARG_bm]);
    if (cpos_arg) mxDestroyArray(plhs[ARG_cpos]); // it was allocated
    mexErrMsgTxt((snprintf(errstr, sizeof(errstr),
               "%s: problem rendering: %s", 
               progname, msg), errstr));
  }

  // free structures and return OK
  free(font);
  free(fontbuf);
}

/* Hook for generic tail matter */
#ifdef MEX2C_TAIL_HOOK
#include "mex2c_tail.h"
#endif

---