Trac #30628: Change font of axis labels in Three.js

#30614 allows the font for text3d to be changed in the Three.js viewer.
This ticket proposes allowing the font for the viewer's axis labels to
be changed as well.

URL: https://trac.sagemath.org/30628
Reported by: gh-jcamp0x2a
Ticket author(s): Joshua Campbell
Reviewer(s): Eric Gourgoulhon

Author: Release Manager

src/doc/en/reference/plot3d/threejs.rst

@@ -34,6 +34,11 @@ Options currently supported by the viewer:
 - ``axes_labels`` -- (default: ['x','y','z']) list or tuple of three strings;
   set to False to remove all labels
 
+- ``axes_labels_style`` -- (default: None) list of three dicts, one per axis, or
+  a single dict controlling all three axes; supports the same styling options as
+  :func:`~sage.plot.plot3d.shapes2.text3d` such as ``color``, ``opacity``, ``fontsize``,
+  ``fontweight``, ``fontstyle``, and ``fontfamily``
+
 - ``color`` -- (default: 'blue') color of the 3D object
 
 - ``decimals`` -- (default: 2) integer determining decimals displayed in labels

src/sage/ext_data/threejs/threejs_template.html

@@ -98,41 +98,56 @@
         var d = options.decimals; // decimals
         var offsetRatio = 0.1;
         var al = options.axesLabels;
+        var als = options.axesLabelsStyle || [{}, {}, {}];
 
         var offset = offsetRatio * a[1]*( b[1].y - b[0].y );
         var xm = xMid.toFixed(d);
         if ( /^-0.?0*$/.test(xm) ) xm = xm.substr(1);
-        addLabel( al[0] + '=' + xm, a[0]*xMid, a[1]*b[1].y+offset, a[2]*b[0].z );
-        addLabel( ( b[0].x ).toFixed(d), a[0]*b[0].x, a[1]*b[1].y+offset, a[2]*b[0].z );
-        addLabel( ( b[1].x ).toFixed(d), a[0]*b[1].x, a[1]*b[1].y+offset, a[2]*b[0].z );
+        addLabel( al[0] + '=' + xm, a[0]*xMid, a[1]*b[1].y+offset, a[2]*b[0].z, als[0] );
+        addLabel( ( b[0].x ).toFixed(d), a[0]*b[0].x, a[1]*b[1].y+offset, a[2]*b[0].z, als[0] );
+        addLabel( ( b[1].x ).toFixed(d), a[0]*b[1].x, a[1]*b[1].y+offset, a[2]*b[0].z, als[0] );
 
         var offset = offsetRatio * a[0]*( b[1].x - b[0].x );
         var ym = yMid.toFixed(d);
         if ( /^-0.?0*$/.test(ym) ) ym = ym.substr(1);
-        addLabel( al[1] + '=' + ym, a[0]*b[1].x+offset, a[1]*yMid, a[2]*b[0].z );
-        addLabel( ( b[0].y ).toFixed(d), a[0]*b[1].x+offset, a[1]*b[0].y, a[2]*b[0].z );
-        addLabel( ( b[1].y ).toFixed(d), a[0]*b[1].x+offset, a[1]*b[1].y, a[2]*b[0].z );
+        addLabel( al[1] + '=' + ym, a[0]*b[1].x+offset, a[1]*yMid, a[2]*b[0].z, als[1] );
+        addLabel( ( b[0].y ).toFixed(d), a[0]*b[1].x+offset, a[1]*b[0].y, a[2]*b[0].z, als[1] );
+        addLabel( ( b[1].y ).toFixed(d), a[0]*b[1].x+offset, a[1]*b[1].y, a[2]*b[0].z, als[1] );
 
         var offset = offsetRatio * a[1]*( b[1].y - b[0].y );
         var zm = zMid.toFixed(d);
         if ( /^-0.?0*$/.test(zm) ) zm = zm.substr(1);
-        addLabel( al[2] + '=' + zm, a[0]*b[1].x, a[1]*b[0].y-offset, a[2]*zMid );
-        addLabel( ( b[0].z ).toFixed(d), a[0]*b[1].x, a[1]*b[0].y-offset, a[2]*b[0].z );
-        addLabel( ( b[1].z ).toFixed(d), a[0]*b[1].x, a[1]*b[0].y-offset, a[2]*b[1].z );
+        addLabel( al[2] + '=' + zm, a[0]*b[1].x, a[1]*b[0].y-offset, a[2]*zMid, als[2] );
+        addLabel( ( b[0].z ).toFixed(d), a[0]*b[1].x, a[1]*b[0].y-offset, a[2]*b[0].z, als[2] );
+        addLabel( ( b[1].z ).toFixed(d), a[0]*b[1].x, a[1]*b[0].y-offset, a[2]*b[1].z, als[2] );
 
     }
 
-    function addLabel( text, x, y, z, color='black', fontSize=14, fontFamily='monospace',
-                       fontStyle='normal', fontWeight='normal', opacity=1 ) {
+    function addLabel( text, x, y, z, style ) {
+
+        var color = style.color || 'black';
+        var fontSize = style.fontSize || 14;
+        var fontFamily = style.fontFamily || 'monospace';
+        var fontStyle = style.fontStyle || 'normal';
+        var fontWeight = style.fontWeight || 'normal';
+        var opacity = style.opacity || 1;
 
         if ( options.theme === 'dark' )
             if ( color === 'black' || color === '#000000' )
                 color = 'white';
 
+        if ( Array.isArray( fontStyle ) ) {
+            fontFamily = fontFamily.map( function( f ) {
+                // Need to put quotes around fonts that have whitespace in their names.
+                return /\s/.test( f ) ? '"' + f + '"' : f;
+            }).join(', ');
+        }
+
         var canvas = document.createElement( 'canvas' );
         var context = canvas.getContext( '2d' );
         var pixelRatio = Math.round( window.devicePixelRatio );
 
+        // For example: italic bold 20px "Times New Roman", Georgia, serif
         var font = [fontStyle, fontWeight, fontSize + 'px', fontFamily].join(' ');
 
         context.font = font;
@@ -278,13 +293,7 @@
     for ( var i=0 ; i < texts.length ; i++ ) addText( texts[i] );
 
     function addText( json ) {
-        json.fontFamily = json.fontFamily.map( function( f ) {
-            // Need to put quotes around fonts that have whitespace in their names.
-            return /\s/.test( f ) ? '"' + f + '"' : f;
-        }).join(', ');
-        var sprite = addLabel( json.text, a[0]*json.x, a[1]*json.y, a[2]*json.z, json.color,
-                               json.fontSize, json.fontFamily, json.fontStyle, json.fontWeight,
-                               json.opacity );
+        var sprite = addLabel( json.text, a[0]*json.x, a[1]*json.y, a[2]*json.z, json );
         sprite.userData = json;
     }
 

src/sage/plot/plot3d/base.pyx

@@ -417,6 +417,7 @@ cdef class Graphics3d(SageObject):
         js_options['autoPlay'] = options.get('auto_play', True)
         js_options['axes'] = options.get('axes', False)
         js_options['axesLabels'] = options.get('axes_labels', ['x','y','z'])
+        js_options['axesLabelsStyle'] = options.get('axes_labels_style')
         js_options['decimals'] = options.get('decimals', 2)
         js_options['delay'] = options.get('delay', 20)
         js_options['frame'] = options.get('frame', True)
@@ -455,6 +456,21 @@ cdef class Graphics3d(SageObject):
 
         if not js_options['frame']:
             js_options['axesLabels'] = False
+            js_options['axesLabelsStyle'] = None
+
+        if js_options['axesLabelsStyle'] is not None:
+            from .shapes import _validate_threejs_text_style
+            style = js_options['axesLabelsStyle']
+            if isinstance(style, dict):
+                style = _validate_threejs_text_style(style)
+                style = [style, style, style]
+            elif isinstance(style, list) and len(style) == 3 and all([isinstance(s, dict) for s in style]):
+                style = [_validate_threejs_text_style(s) for s in style]
+            else:
+                import warnings
+                warnings.warn("axes_labels_style must be a dict or a list of 3 dicts")
+                style = [dict(), dict(), dict()]
+            js_options['axesLabelsStyle'] = style
 
         from sage.repl.rich_output import get_display_manager
         scripts = get_display_manager().threejs_scripts(options['online'])

src/sage/plot/plot3d/shapes.pyx

@@ -1209,65 +1209,10 @@ class Text(PrimitiveObject):
         center = (float(0), float(0), float(0))
         if render_params.transform is not None:
             center = render_params.transform.transform_point(center)
-
         color = '#' + str(self.texture.hex_rgb())
         string = str(self.string)
-
-        default_size = 14.0
-        size = self._extra_kwds.get('fontsize', default_size)
-        try:
-            size = float(size)
-        except (TypeError, ValueError):
-            scale = str(size).lower()
-            if scale.endswith('%'):
-                try:
-                    scale = float(scale[:-1]) / 100.0
-                    size = default_size * scale
-                except ValueError:
-                    import warnings
-                    warnings.warn(f"invalid fontsize: {size}, using: {default_size}")
-                    size = default_size
-            else:
-                from matplotlib.font_manager import font_scalings
-                try:
-                    size = default_size * font_scalings[scale]
-                except KeyError:
-                    import warnings
-                    warnings.warn(f"unknown fontsize: {size}, using: {default_size}")
-                    size = default_size
-
-        font = self._extra_kwds.get('fontfamily', ['monospace'])
-        if isinstance(font, str):
-            font = font.split(',')
-        font = [str(f).strip() for f in font]
-
-        default_style = 'normal'
-        style = str(self._extra_kwds.get('fontstyle', default_style))
-        if style not in ['normal', 'italic'] and not style.startswith('oblique'): # ex: oblique 30deg
-            import warnings
-            warnings.warn(f"unknown style: {style}, using: {default_style}")
-            style = default_style
-
-        default_weight = 'normal'
-        weight = self._extra_kwds.get('fontweight', default_weight)
-        if weight not in ['normal', 'bold']:
-            try:
-                weight = int(weight)
-            except:
-                from matplotlib.font_manager import weight_dict
-                try:
-                    weight = weight_dict[weight]
-                except KeyError:
-                    import warnings
-                    warnings.warn(f"unknown fontweight: {weight}, using: {default_weight}")
-                    weight = default_weight
-
-        opacity = float(self._extra_kwds.get('opacity', 1.0))
-
-        text = dict(text=string, x=center[0], y=center[1], z=center[2], color=color,
-                    fontSize=size, fontFamily=font, fontStyle=style, fontWeight=weight,
-                    opacity=opacity)
-
+        text = _validate_threejs_text_style(self._extra_kwds)
+        text.update(dict(text=string, x=center[0], y=center[1], z=center[2], color=color))
         return [('text', text)]
 
     def bounding_box(self):
@@ -1279,3 +1224,152 @@ class Text(PrimitiveObject):
             ((0, 0, 0), (0, 0, 0))
         """
         return (0,0,0), (0,0,0)
+
+
+def _validate_threejs_text_style(style):
+    """
+    Validate a combination of text styles for use in the Three.js viewer.
+
+    INPUT:
+
+    - ``style`` -- a dict optionally containing keys: 'color', 'fontSize',
+      'fontFamily', 'fontStyle', 'fontWeight', and 'opacity'
+
+    OUTPUT:
+
+    A corrected version of the dict, having printed out warning messages for
+    any problems found
+
+    TESTS:
+
+    Default values::
+
+        sage: from sage.plot.plot3d.shapes import _validate_threejs_text_style as validate
+        sage: validate(dict())
+        {'color': '#000000',
+         'fontFamily': ['monospace'],
+         'fontSize': 14.0,
+         'fontStyle': 'normal',
+         'fontWeight': 'normal',
+         'opacity': 1.0}
+
+    Color by name or by HTML hex code::
+
+        sage: validate(dict(color='red'))
+        {'color': '#ff0000',...}
+        sage: validate(dict(color='#ff0000'))
+        {'color': '#ff0000',...}
+        sage: validate(dict(color='octarine'))
+        ...UserWarning: invalid color: octarine...
+
+    Font size in absolute units or in percentage/keyword relative to default::
+
+        sage: validate(dict(fontsize=20.5))
+        {...'fontSize': 20.5...}
+        sage: validate(dict(fontsize="200%"))
+        {...'fontSize': 28...}
+        sage: validate(dict(fontsize="x%"))
+        ...UserWarning: invalid fontsize: x%...
+        sage: validate(dict(fontsize="large"))
+        {...'fontSize': 16.8...}
+        sage: validate(dict(fontsize="ginormous"))
+        ...UserWarning: unknown fontsize: ginormous...
+
+    Font family as list or comma-delimited string::
+
+        sage: validate(dict(fontfamily=[" Times New Roman ", " Georgia", "serif "]))
+        {...'fontFamily': ['Times New Roman', 'Georgia', 'serif']...}
+        sage: validate(dict(fontfamily=" Times New Roman , Georgia,serif "))
+        {...'fontFamily': ['Times New Roman', 'Georgia', 'serif']...}
+
+    Font style keywords including the special syntax for 'oblique' angle::
+
+        sage: validate(dict(fontstyle='italic'))
+        {...'fontStyle': 'italic'...}
+        sage: validate(dict(fontstyle='oblique 30deg'))
+        {...'fontStyle': 'oblique 30deg'...}
+        sage: validate(dict(fontstyle='garrish'))
+        ...UserWarning: unknown style: garrish...
+
+    Font weight as keyword or integer::
+
+        sage: validate(dict(fontweight='bold'))
+        {...'fontWeight': 'bold'...}
+        sage: validate(dict(fontweight=500))
+        {...'fontWeight': 500...}
+        sage: validate(dict(fontweight='roman'))
+        {...'fontWeight': 500...}
+        sage: validate(dict(fontweight='bold & beautiful'))
+        ...UserWarning: unknown fontweight: bold & beautiful...
+
+    Opacity::
+
+        sage: validate(dict(opacity=0.5))
+        {...'opacity': 0.5}
+
+    """
+    default_color = '#000000' # black
+    color = style.get('color', default_color)
+    from .texture import Texture
+    try:
+        texture = Texture(color=color)
+    except ValueError:
+        import warnings
+        warnings.warn(f"invalid color: {color}, using: {default_color}")
+        color = default_color
+    else:
+        color = '#' + str(texture.hex_rgb())
+
+    default_size = 14.0
+    size = style.get('fontsize', default_size)
+    try:
+        size = float(size)
+    except (TypeError, ValueError):
+        scale = str(size).lower()
+        if scale.endswith('%'):
+            try:
+                scale = float(scale[:-1]) / 100.0
+                size = default_size * scale
+            except ValueError:
+                import warnings
+                warnings.warn(f"invalid fontsize: {size}, using: {default_size}")
+                size = default_size
+        else:
+            from matplotlib.font_manager import font_scalings
+            try:
+                size = default_size * font_scalings[scale]
+            except KeyError:
+                import warnings
+                warnings.warn(f"unknown fontsize: {size}, using: {default_size}")
+                size = default_size
+
+    font = style.get('fontfamily', ['monospace'])
+    if isinstance(font, str):
+        font = font.split(',')
+    font = [str(f).strip() for f in font]
+
+    default_style = 'normal'
+    fontstyle = str(style.get('fontstyle', default_style))
+    if fontstyle not in ['normal', 'italic'] and not fontstyle.startswith('oblique'): # ex: oblique 30deg
+        import warnings
+        warnings.warn(f"unknown style: {fontstyle}, using: {default_style}")
+        fontstyle = default_style
+
+    default_weight = 'normal'
+    weight = style.get('fontweight', default_weight)
+    if weight not in ['normal', 'bold']:
+        try:
+            weight = int(weight)
+        except:
+            from matplotlib.font_manager import weight_dict
+            try:
+                weight = weight_dict[weight]
+            except KeyError:
+                import warnings
+                warnings.warn(f"unknown fontweight: {weight}, using: {default_weight}")
+                weight = default_weight
+
+    opacity = float(style.get('opacity', 1.0))
+
+    return dict(color=color, fontSize=size, fontFamily=font, fontStyle=fontstyle,
+                fontWeight=weight, opacity=opacity)