DOC: Make ftface_props example generate a font metrics figure

AMAN194701 · AMAN194701 · commit f9343ba9280c · 2026-03-21T11:02:05.000+05:30
The example only printed to stdout with no visual output, so Sphinx Gallery could not auto-generate a thumbnail. Added a matplotlib figure that visualises the font metrics (ascender, descender, bbox, underline position/thickness) normalised to units_per_EM using the same font loaded in the example. Closes #17479
diff --git a/galleries/examples/misc/ftface_props.py b/galleries/examples/misc/ftface_props.py
@@ -11,40 +11,31 @@
 import os
 
 import matplotlib
+import matplotlib.pyplot as plt
 import matplotlib.ft2font as ft
 
 font = ft.FT2Font(
     # Use a font shipped with Matplotlib.
     os.path.join(matplotlib.get_data_path(),
                  'fonts/ttf/DejaVuSans-Oblique.ttf'))
 
-print('Num instances:  ', font.num_named_instances)  # number of named instances in file
-print('Num faces:      ', font.num_faces)            # number of faces in file
-print('Num glyphs:     ', font.num_glyphs)           # number of glyphs in the face
-print('Family name:    ', font.family_name)          # face family name
-print('Style name:     ', font.style_name)           # face style name
-print('PS name:        ', font.postscript_name)      # the postscript name
-print('Num fixed:      ', font.num_fixed_sizes)      # number of embedded bitmaps
+print('Num instances:  ', font.num_named_instances)
+print('Num faces:      ', font.num_faces)
+print('Num glyphs:     ', font.num_glyphs)
+print('Family name:    ', font.family_name)
+print('Style name:     ', font.style_name)
+print('PS name:        ', font.postscript_name)
+print('Num fixed:      ', font.num_fixed_sizes)
 
-# the following are only available if face.scalable
 if font.scalable:
-    # the face global bounding box (xmin, ymin, xmax, ymax)
     print('Bbox:               ', font.bbox)
-    # number of font units covered by the EM
     print('EM:                 ', font.units_per_EM)
-    # the ascender in 26.6 units
     print('Ascender:           ', font.ascender)
-    # the descender in 26.6 units
     print('Descender:          ', font.descender)
-    # the height in 26.6 units
     print('Height:             ', font.height)
-    # maximum horizontal cursor advance
     print('Max adv width:      ', font.max_advance_width)
-    # same for vertical layout
     print('Max adv height:     ', font.max_advance_height)
-    # vertical position of the underline bar
     print('Underline pos:      ', font.underline_position)
-    # vertical thickness of the underline
     print('Underline thickness:', font.underline_thickness)
 
 for flag in ft.StyleFlags:
@@ -54,3 +45,48 @@
 for flag in ft.FaceFlags:
     name = flag.name.replace('_', ' ').title() + ':'
     print(f"{name:17}", flag in font.face_flags)
+
+# ── Visualise font metrics ──────────────────────────────────────────────────
+if font.scalable:
+    u = font.units_per_EM  # normalise every value: divide by EM = 1.0
+
+    ascender = font.ascender / u
+    descender = font.descender / u
+    bbox_ymax = font.bbox[3] / u
+    bbox_ymin = font.bbox[1] / u
+    ul_pos = font.underline_position / u
+    ul_thick = font.underline_thickness / u
+
+    fig, ax = plt.subplots(figsize=(5, 4))
+
+    ax.text(0.15, 0, "Ag", fontsize=74, va='baseline',
+            fontfamily='DejaVu Sans', color='black', zorder=3)
+
+    metrics = [
+        ("ascender",           ascender,  "tab:blue"),
+        ("baseline (y=0)",     0,         "black"),
+        ("descender",          descender, "tab:red"),
+        ("bbox top (ymax)",    bbox_ymax, "tab:green"),
+        ("bbox bottom (ymin)", bbox_ymin, "tab:purple"),
+        ("underline_position", ul_pos,    "tab:orange"),
+    ]
+
+    for label, y, color in metrics:
+        ax.axhline(y, color=color, linewidth=1, linestyle='--', alpha=0.8)
+        ax.text(0.82, y, label, color=color, va='center',
+                fontsize=7.5, clip_on=True)
+
+    ax.axhspan(ul_pos - ul_thick, ul_pos,
+               color='tab:orange', alpha=0.25,
+               label=f'underline_thickness = {font.underline_thickness}')
+
+    ax.set_xlim(0, 1.55)
+    ax.set_ylim(bbox_ymin - 0.05, bbox_ymax + 0.05)
+    ax.set_title(
+        f"Font metrics — {font.family_name} {font.style_name}\n"
+        f"(values normalised to units_per_EM = {font.units_per_EM})"
+    )
+    ax.legend(fontsize=7, loc='lower right')
+    ax.axis('off')
+    plt.tight_layout()
+    plt.show()
