DatBounds

By Geep, 2024

Introduction

DatBounds is a Windows command-line utility to help visualize TDM/Doom3 bitmap font bounding boxes and related metrics. It generates a special set of .tga image files, which are then brought into a tool like GIMP to view. But only view; any needed metric changes must be applied separately (e.g., by editing a .ref file). Nevertheless, this viewing helps (when used in conjunction with other tools like refont's "stats") to understand, improve, and extend complex and often overlapping metadata relationships.

The command-line format is:

datBounds -in <path to input metrics file> [options]

with options:

-tag = each drawn bounds box has a 2-hex-digit codepoint label.
-hug = show, in tan, horizontal baseline & pitch (as vertical line) that 'hug' each glyph.
-xskip = show xSkip as red dot on rightside of baseline.
-long_baseline_left = draw horizontal baseline from left boundary, instead of from pitch line to right. [new v1.3]
-long_baseline_right = draw horizontal baseline to xSkip red dot, instead of to right boundary. [new v1.3]
-long_pitchline_down = extend vertical pitchline downward to baseline (e.g., below lower boundary). [new 1.3]
-boundless = suppress multicolor outer bounds; e.g., to help make tag-only .tga" [new v1.3]
-from <codepoint num> (default   0)
-to   <codepoint num> (default 255)
    shows codepoints between 'from' and 'to', inclusive,
    where <codepoint num> is 0xHH or decimal from 0 to 255.
-alpha = render background transparent instead of white.

Running "datbounds" with no arguments, or with "-h" or "?", will show this summary.

Otherwise, the program will generate one special .tga file for every regular glyph-containing .tga/.dds file. To keep datbounds relatively simple:

the .tga format is used for output, instead of, say, .jpg or .png, that need more code or libraries;
the names of the output files are not specified, but just derived from shader names contained in the -in file. For example, "stone_0_24" --> "stone_0_24_bounds.tga";
These special files do not contain images of the font glyphs themselves.

So either view each one side by side with the corresponding glyph-containing file [Figure 1 below], or import copies of those paired files into GIMP as separate layers for combined viewing, as discussed further below.

File I/O

The input file, with metadata for a particular font and fontsize, should be one of these formats:

TDM/Doom3's '.dat'
refont's '.ref'
q3font's '.fnt'

Note that DatBounds does not read bitmap files, nor does it make use of refont’s annotation file.

DatBounds outputs multiple .tga files, into the same directory as the input file. The generated filenames are that of the set of shaderNames given in the input file, but with suffix "_bounds.tga".

Example Output

Figure 1. [Click either to enlarge further.] These show information about the english/stone font of 24 pt size, as distributed with TDM 2.12 in Feb, 2024. That size requires two bitmaps; we see just one of them here. Both images are screenshots of GIMP. The left image shows the datBounds output, framed in the gray scales of the GIMP view/edit panel. The right image shows the corresponding glyph bitmap, with the usual checkerboard indicating a transparent background.

This datBounds Version 1.0 command was used to generate the left image, which has the default opaque white background:

datBounds -in fontImage_24.ref -tag -hug -xskip -to 127

With Version 1.3, this would get the same results:

datBounds -in fontImage_24.ref -tag -hug -xskip -long_baseline_left -to 127

For simplicity, this figure has only bounds for the ASCII codepoints (because of "-to 127"). For each of those, it shows:

the overall bounds as a green/blue box
the pitch (aka xOffset) as a vertical tan line, and the baseline as a horizontal tan line (because of "-hug")
the 2-digit-hex codepoint label, red on black (because of "-tag")
the horizontal xSkip distance from the pitch line, shown as a red dot near the right end of the baseline (due to "-xskip")

Regarding the baselines in Figures 1 & 3: These were generated with datBounds Version 1.0, and are slightly shorter in subsequent versions. Version 1.3 introduces the long_baseline_left option, to once-again generate the Version 1.0 form. "See "Downloads" at end for more about this.

Generated Visualizations and Options

Within each ...bounds.tga file will be a 256 x 256 image. It contains, for each codepoint's glyph outer bounds, a two-color box. The walls of the box are defined by integer values in the range 0-255, namely:

s_coord, t_coord, (s2_coord - 1), (t2_coord - 1) in .ref terms
round(s*256), round(t*256), round((s2-1)*256), round ((t2-1)*256) in .dat or .fnt terms

Since s2 & t2 are considered to just beyond the glyph’s actual pixels, 1 is subtracted here. So the glyph pixels (if they were seen) would partially lap the box edges (except for the left edge due to pitch offset.) A box is rendered in two colors to help disambiguate abutting glyphs. Green for top & left edges (sharing s & t), blue for right & bottom (s2 & t2).

Visualization Order

The visualization algorithm uses a loop in codepoint order. Consequently, visual elements of higher codepoint numbers may obscure or hide those of lower numbers. This often occurs with shared or overlapping bounding boxes. While it can’t be avoided, if you wish you can manage it with the "from" and "to" options.

Tag Option

This shows a "tag", i.e., a label, having the codepoint value as a 2-digit hexadecimal number. It appears in the upper-left corner of the bounding box, with red digits on a black background. The tiny "dot matrix" font here is generated within the program. It is legible with practice when zoomed in within GIMP.

Figure 2. Closeup of the digits of datBounds.

Hug Option

This shows two lines in a tan color, that informally can be said to "hug" the glyph:

The baseline, shown as a horizontal line, offset downward from the bounding box top edge by the "top" metric value. For a glyph without descender, this is often just below the bounding box bottom edge (because of latter’s t2-1 subtraction); the glyph is visualized as resting on the baseline.
The "pitch", shown as a vertical line, offset rightward from the bounding box left edge by the "pitch" metric value. Most glyphs will not extend leftward beyond the pitch line.

XSkip Option

Invoked with either "-xskip" or "-xSkip", this shows a red dot on the rightside of the baseline, corresponding to a horizontal location of:

s_coord + pitch + xSkip

Long_baseline_left Option

Ordinarily, drawing of the horizontal baseline starts at the vertical pitch line. The "-long_baseline_left" option moves the start leftward, to begin at the left boundary given by coord_s. (Actually, from the leftmost of the pitchline and the left boundary.)

Long_baseline_right Option

Ordinarily, the horizontal baseline ends at the right boundary given by coord_s2 - 1. The "-long_baseline_right" option extends it to abut the xSkip red dot instead. (Actually, to the rightmost of the right boundary and the red dot.)

These "long baseline" options are most useful with odd fonts that use unusual pitch values, e.g., Medusa, that has the pitch line to the right of the character glyph instead of the left.

Long_pitchline_down Option

Ordinarily, the vertical pitch line travels downward to the lower boundary given by coord_t2 - 1. The "-long_pitchline_down" option extends it downward to the baseline given by coord_t + top. (Actually, to the lower of the baseline and lower boundary.) This can be helpful particularly for certain punctuation characters, that with many fonts have tight bounding boxes with baselines far below.

Boundless Option

The "-boundless" option suppresses drawing of the multicolor outer bounds. Its main use is paired with the "-tag" option, to generate tag-only .tga files for GIMP layers.

From & To: Codepoint Range Options

These accept decimal or two-digit hex numbers (the latter preceded by "0x"). If both "-from" and "-to" are given, the value of "-to" should be greater than or equal to "-from". These options can be helpful to reduce the complexity of visualization with densely overlapping bounding boxes.

Alpha Option – Make Background Transparent.

By default, the background is opaque white. This provides good contrast if, in GIMP, you prefer to turn on grid lines, which are black. However, a transparent background option is provided in case you want to also see the glyphs and metrics superimposed, as discussed next.

A Combined View of Both Metrics and Glyphs in GIMP

For some fonts and font sizes, there is an existing TDM-created GIMP .xcf project file, that contains each bitmap of a glyph set as a separate layer, and that serves as the source file for TDM’s version of the font. Make a working copy of that for what is described here (as shown in Figure 3).

Or you can create your own version of this, e.g., importing both the _bounds file(s) and the corresponding glyph-containing bitmap file(s) into GIMP, as separate layers.

In either case, GIMP’s "Open as Layers..." is what you use. Be sure the _bounds files were created with the –alpha option. Once files are imported, hide all the layers except those of a particular pair (i.e., matching bounds & glyphs) of interest. Which one you place in front of the other depends on whether it’s more important to see the glyphs unclipped or the tags (if present) un-obscured.

More elaborately, you can import and stack multiple versions of a _bounds file, e.g., with different ranges, to toggle for differences.

TIP: Viewing glyphs against the checkerboard "transparency" pattern can be tedious. Consider adding an all-black background layer. To do so in GIMP, set the foreground color to black, then, when creating a new layer, you can ask it to fill with the foreground color.

You are creating a "snapshot in time", great for planning and quality control. But of course any subsequent edits to the DAT metrics renders the _bounds file(s) within the .xcf somewhat obsolete.

Example Combined View

Figure 3. In GIMP, this shows the native project file (.xcf) that serves as master source for english stone 24pt bitmaps. This size has two bitmaps (_0_ and _1_). Only layers associated with _0_ are momentarily visible in the left panel. They are the glyph bitmap, and two datBounds bitmaps (lower 128 and upper 128 characters). While these are all transparent, the lowest "black background" layer renders the stack as shown.

This snapshot shows a few early changes towards font completion for TDM 2.13. So, for instance, the N in row 4 now has a tilde above it. Note how N and Ñ have overlapping bounds, allowing them to share the base letter but not the accent. This is common with hand-done font bitmaps to conserve bitmap real estate. (Subsequent to this image, the two bitmaps, further revised, were renamed to be more apt, as "_0_ Mostly ASCII" and "_1_ Mostly ANSI".)

Downloads

Version 1.3 of 2024, August 16

Prevents a crash if drawn lines are out of bounds. Fixes a bug where xSkip dot was always showing, even if -xskip not specified. Adds "0x" before hex form output of warnings and errors. Adds command-line options -boundless, -long_baseline_left, -long_baseline_right, and -long_pitchline_down.

Earlier Version 1.2 of 2024, June 9

Fixes a bug with codepoint 255 being skipped. Adds metadata consistency checking.

Earlier Version 1.1 of 2024, May 20

This shortens baselines. The left end of a baseline now begins at the pitch vertical. So that the red xSkip dot will be less likely to be obscured by the baseline of an adjoining character.

Original Version 1.0 of 2024, May 10