Trac #29227: Plotting single text3d results in empty scene with Three.js viewer

Attempting to plot a single piece of text using the three.js viewer
results in an empty scene (besides the coordinate frame):

{{{
text3d("Hello world!", (1, 2, 3))
}}}

Inspecting the javascript in the generated HTML file, the `texts` array
is empty: `var texts = []`

Adding any other Graphics3d object (even an empty one) to it fixes the
problem:

{{{
from sage.plot.plot3d.base import Graphics3d
text3d("Hello world!", (1, 2, 3)) + Graphics3d()
}}}

I encountered this in my Ubuntu install based on 9.1.beta3 while working
on #29194. I also tried it on my Windows install which is still 8.9, and
the bug is present there as well.

URL: https://trac.sagemath.org/29227
Reported by: gh-jcamp0x2a
Ticket author(s): Joshua Campbell
Reviewer(s): Paul Masson, Eric Gourgoulhon, Travis Scrimshaw

Author: Release Manager

src/sage/plot/plot3d/base.pyx

@@ -400,44 +400,11 @@ cdef class Graphics3d(SageObject):
         ambient = '{{"color":"{}"}}'.format(Color(.5,.5,.5).html_color())
 
         import json
-        from sage.plot.plot3d.shapes import arrow3d
-        points, lines, texts = [], [], []
-
-        if not hasattr(self, 'all'):
-            self += Graphics3d()
-        for p in self.flatten().all:
-            if hasattr(p, 'loc'):
-                color = p._extra_kwds.get('color', 'blue')
-                opacity = float(p._extra_kwds.get('opacity', 1))
-                points.append('{{"point":{}, "size":{}, "color":"{}", "opacity":{}}}'.format(
-                              json.dumps(p.loc), p.size, color, opacity))
-            if hasattr(p, 'points'):
-                color = p._extra_kwds.get('color', 'blue')
-                opacity = float(p._extra_kwds.get('opacity', 1))
-                thickness = p._extra_kwds.get('thickness', 1)
-                lines.append('{{"points":{}, "color":"{}", "opacity":{}, "linewidth":{}}}'.format(
-                             json.dumps(p.points), color, opacity, thickness))
-            if hasattr(p, '_trans'):
-                m = p.get_transformation().get_matrix()
-                t = (m[0,3], m[1,3], m[2,3])
-                if hasattr(p.all[0], 'points'):
-                    translated = [[sum(x) for x in zip(t,u)] for u in p.all[0].points]
-                    width = .5 * p.all[0].thickness
-                    color = p.all[0].texture.color
-                    opacity = p.all[0].texture.opacity
-                    self += arrow3d(translated[0], translated[1], width=width, color=color, opacity=opacity)
-                if hasattr(p.all[0], 'string'):
-                    color = '#' + p.all[0].texture.hex_rgb();
-                    texts.append('{{"text":"{}", "x":{}, "y":{}, "z":{}, "color":"{}"}}'.format(
-                                 p.all[0].string, t[0], t[1], t[2], color))
-
-        points = '[' + ','.join(points) + ']'
-        lines = '[' + ','.join(lines) + ']'
-        texts = '[' + ','.join(texts) + ']'
-
-        surfaces = self.json_repr(self.default_render_params())
-        surfaces = flatten_list(surfaces)
-        surfaces = '[' + ','.join(surfaces) + ']'
+
+        reprs = {'point': [], 'line': [], 'text': [], 'surface': []}
+        for kind, desc in self.threejs_repr(self.default_render_params()):
+            reprs[kind].append(desc)
+        reprs = {kind: json.dumps(descs) for kind, descs in reprs.items()}
 
         from sage.env import SAGE_EXTCODE
         with open(os.path.join(
@@ -449,10 +416,10 @@ cdef class Graphics3d(SageObject):
         html = html.replace('SAGE_BOUNDS', bounds)
         html = html.replace('SAGE_LIGHTS', lights)
         html = html.replace('SAGE_AMBIENT', ambient)
-        html = html.replace('SAGE_TEXTS', str(texts))
-        html = html.replace('SAGE_POINTS', str(points))
-        html = html.replace('SAGE_LINES', str(lines))
-        html = html.replace('SAGE_SURFACES', str(surfaces))
+        html = html.replace('SAGE_TEXTS', str(reprs['text']))
+        html = html.replace('SAGE_POINTS', str(reprs['point']))
+        html = html.replace('SAGE_LINES', str(reprs['line']))
+        html = html.replace('SAGE_SURFACES', str(reprs['surface']))
 
         from sage.repl.rich_output.output_catalog import OutputSceneThreejs
         return OutputSceneThreejs(html);
@@ -1164,6 +1131,21 @@ end_scene""" % (render_params.antialiasing,
         """
         return []
 
+    def threejs_repr(self, render_params):
+        """
+        A flat list of ``(kind, desc)`` tuples where ``kind`` is one of:
+        'point', 'line', 'text', or 'surface'; and where ``desc`` is a dictionary
+        describing a point, line, text, or surface.
+
+        EXAMPLES::
+
+            sage: G = sage.plot.plot3d.base.Graphics3d()
+            sage: G.threejs_repr(G.default_render_params())
+            []
+
+        """
+        return []
+
     def texture_set(self):
         """
         Often the textures of a 3d file format are kept separate from the
@@ -2149,6 +2131,31 @@ class Graphics3dGroup(Graphics3d):
         """
         return [g.jmol_repr(render_params) for g in self.all]
 
+    def threejs_repr(self, render_params):
+        r"""
+        The three.js representation of a group is the concatenation of the
+        representations of its objects.
+
+        EXAMPLES::
+
+            sage: G = point3d((1,2,3)) + point3d((4,5,6)) + line3d([(1,2,3), (4,5,6)])
+            sage: G.threejs_repr(G.default_render_params())
+            [('point',
+              {'color': '#6666ff', 'opacity': 1.0, 'point': (1.0, 2.0, 3.0), 'size': 5.0}),
+             ('point',
+              {'color': '#6666ff', 'opacity': 1.0, 'point': (4.0, 5.0, 6.0), 'size': 5.0}),
+             ('line',
+              {'color': '#6666ff',
+               'linewidth': 1.0,
+               'opacity': 1.0,
+               'points': [(1.0, 2.0, 3.0), (4.0, 5.0, 6.0)]})]
+
+        """
+        reprs = []
+        for g in self.all:
+            reprs += g.threejs_repr(render_params)
+        return reprs
+
     def stl_binary_repr(self, render_params):
         r"""
         The stl binary representation of a group is simply the
@@ -2405,6 +2412,29 @@ class TransformGroup(Graphics3dGroup):
         render_params.pop_transform()
         return rep
 
+    def threejs_repr(self, render_params):
+        r"""
+        Transformations for three.js are applied at the leaf nodes.
+
+        EXAMPLES::
+
+            sage: G = point3d((1,2,3)) + point3d((4,5,6))
+            sage: G = G.translate(-1, -2, -3).scale(10)
+            sage: G.threejs_repr(G.default_render_params())
+            [('point',
+              {'color': '#6666ff', 'opacity': 1.0, 'point': (0.0, 0.0, 0.0), 'size': 5.0}),
+             ('point',
+              {'color': '#6666ff',
+               'opacity': 1.0,
+               'point': (30.0, 30.0, 30.0),
+               'size': 5.0})]
+
+        """
+        render_params.push_transform(self.get_transformation())
+        rep = Graphics3dGroup.threejs_repr(self, render_params)
+        render_params.pop_transform()
+        return rep
+
     def get_transformation(self):
         """
         Return the actual transformation object associated with ``self``.
@@ -2600,6 +2630,28 @@ cdef class PrimitiveObject(Graphics3d):
         """
         return self.triangulation().jmol_repr(render_params)
 
+    def threejs_repr(self, render_params):
+        r"""
+        Default behavior is to render the triangulation.
+
+        EXAMPLES::
+
+            sage: from sage.plot.plot3d.base import PrimitiveObject
+            sage: class SimpleTriangle(PrimitiveObject):
+            ....:     def triangulation(self):
+            ....:         return polygon3d([(0,0,0), (1,0,0), (0,1,0)])
+            sage: G = SimpleTriangle()
+            sage: G.threejs_repr(G.default_render_params())
+            [('surface',
+              {'color': '#0000ff',
+               'faces': [[0, 1, 2]],
+               'opacity': 1.0,
+               'vertices': [{'x': 0.0, 'y': 0.0, 'z': 0.0},
+                {'x': 1.0, 'y': 0.0, 'z': 0.0},
+                {'x': 0.0, 'y': 1.0, 'z': 0.0}]})]
+
+        """
+        return self.triangulation().threejs_repr(render_params)
 
 
 class BoundingSphere(SageObject):

src/sage/plot/plot3d/implicit_surface.pyx

@@ -1144,6 +1144,30 @@ cdef class ImplicitSurface(IndexFaceSet):
         self.triangulate()
         return IndexFaceSet.json_repr(self, render_params)
 
+    def threejs_repr(self, render_params):
+        r"""
+        Return a represention of the surface suitable for plotting with three.js.
+
+        EXAMPLES::
+
+            sage: from sage.plot.plot3d.implicit_surface import ImplicitSurface
+            sage: _ = var('x,y,z')
+            sage: G = ImplicitSurface(x + y + z, (x,-1, 1), (y,-1, 1), (z,-1, 1))
+            sage: G.threejs_repr(G.default_render_params())
+            [('surface',
+              {'color': '#6666ff',
+               'faces': [[0, 1, 2],
+                ...
+               'opacity': 1.0,
+               'vertices': [{'x': ...,
+                 'y': -0.9743589743589...,
+                 'z': -0.02564102564102...},
+                ...
+                {'x': -1.0, 'y': 0.9487179487179..., 'z': 0.05128205128205...}]})]
+        """
+        self.triangulate()
+        return IndexFaceSet.threejs_repr(self, render_params)
+
     def triangulate(self, force=False):
         """
         The IndexFaceSet will be empty until you call this method,

src/sage/plot/plot3d/index_face_set.pyx

@@ -1284,6 +1284,124 @@ cdef class IndexFaceSet(PrimitiveObject):
 
         return json
 
+    def threejs_repr(self, render_params):
+        r"""
+        Return representation of the surface suitable for plotting with three.js.
+
+        EXAMPLES:
+
+        A simple triangle::
+
+            sage: G = polygon([(0,0,1), (1,1,1), (2,0,1)])
+            sage: G.threejs_repr(G.default_render_params())
+            [('surface',
+              {'color': '#0000ff',
+               'faces': [[0, 1, 2]],
+               'opacity': 1.0,
+               'vertices': [{'x': 0.0, 'y': 0.0, 'z': 1.0},
+                {'x': 1.0, 'y': 1.0, 'z': 1.0},
+                {'x': 2.0, 'y': 0.0, 'z': 1.0}]})]
+
+        The same but with more options applied::
+
+            sage: G = polygon([(0,0,1), (1,1,1), (2,0,1)], color='red', opacity=0.5,
+            ....:             render_order=2, threejs_flat_shading=True,
+            ....:             single_side=True, mesh=True)
+            sage: G.threejs_repr(G.default_render_params())
+            [('surface',
+              {'color': '#ff0000',
+               'faces': [[0, 1, 2]],
+               'opacity': 0.5,
+               'renderOrder': 2.0,
+               'showMeshGrid': True,
+               'singleSide': True,
+               'useFlatShading': True,
+               'vertices': [{'x': 0.0, 'y': 0.0, 'z': 1.0},
+                {'x': 1.0, 'y': 1.0, 'z': 1.0},
+                {'x': 2.0, 'y': 0.0, 'z': 1.0}]})]
+
+        TESTS:
+
+        Transformations apply to the surface's vertices::
+
+            sage: G = polygon([(0,0,1), (1,1,1), (2,0,1)]).scale(2,1,-1)
+            sage: G.threejs_repr(G.default_render_params())
+            [('surface',
+              {'color': '#0000ff',
+               'faces': [[0, 1, 2]],
+               'opacity': 1.0,
+               'vertices': [{'x': 0.0, 'y': 0.0, 'z': -1.0},
+                {'x': 2.0, 'y': 1.0, 'z': -1.0},
+                {'x': 4.0, 'y': 0.0, 'z': -1.0}]})]
+
+        Per-face colors::
+
+            sage: from sage.plot.plot3d.index_face_set import IndexFaceSet
+            sage: from sage.plot.plot3d.texture import Texture
+            sage: point_list = [(2,0,0),(0,2,0),(0,0,2),(0,1,1),(1,0,1),(1,1,0)]
+            sage: face_list = [[0,4,5],[3,4,5],[2,3,4],[1,3,5]]
+            sage: col = rainbow(10, 'rgbtuple')
+            sage: t_list=[Texture(col[i]) for i in range(10)]
+            sage: S = IndexFaceSet(face_list, point_list, texture_list=t_list)
+            sage: S.threejs_repr(S.default_render_params())
+            [('surface',
+              {'faceColors': ['#ff0000', '#ff9900', '#cbff00', '#33ff00'],
+               'faces': [[0, 4, 5], [3, 4, 5], [2, 3, 4], [1, 3, 5]],
+               'opacity': 1.0,
+               'vertices': [{'x': 2.0, 'y': 0.0, 'z': 0.0},
+                {'x': 0.0, 'y': 2.0, 'z': 0.0},
+                {'x': 0.0, 'y': 0.0, 'z': 2.0},
+                {'x': 0.0, 'y': 1.0, 'z': 1.0},
+                {'x': 1.0, 'y': 0.0, 'z': 1.0},
+                {'x': 1.0, 'y': 1.0, 'z': 0.0}]})]
+
+        """
+        surface = {}
+
+        vertices = []
+        cdef Transformation transform = render_params.transform
+        cdef point_c res
+        for i from 0 <= i < self.vcount:
+            if transform is None:
+                res = self.vs[i]
+            else:
+                transform.transform_point_c(&res, self.vs[i])
+            vertices.append(dict(x=float(res.x), y=float(res.y), z=float(res.z)))
+        surface['vertices'] = vertices
+
+        faces = []
+        cdef face_c face
+        for i from 0 <= i < self.fcount:
+            face = self._faces[i]
+            faces.append([int(face.vertices[j]) for j from 0 <= j < face.n])
+        surface['faces'] = faces
+
+        if self.global_texture:
+            surface['color'] = '#' + str(self.texture.hex_rgb())
+        else:
+            face_colors = []
+            for i from 0 <= i < self.fcount:
+                face = self._faces[i]
+                color = Color(face.color.r, face.color.g, face.color.b)
+                face_colors.append(str(color.html_color()))
+            surface['faceColors'] = face_colors
+
+        surface['opacity'] = float(self._extra_kwds.get('opacity', 1.0))
+
+        if 'render_order' in self._extra_kwds:
+            surface['renderOrder'] = float(self._extra_kwds['render_order'])
+
+        if self._extra_kwds.get('single_side'):
+            surface['singleSide'] = True
+
+        if self._extra_kwds.get('threejs_flat_shading'):
+            surface['useFlatShading'] = True
+
+        if self._extra_kwds.get('mesh'):
+            surface['showMeshGrid'] = True
+
+        return [('surface', surface)]
+
     def obj_repr(self, render_params):
         """
         Return an obj representation for ``self``.

src/sage/plot/plot3d/parametric_surface.pyx

@@ -309,6 +309,28 @@ cdef class ParametricSurface(IndexFaceSet):
         self.triangulate(render_params)
         return IndexFaceSet.json_repr(self, render_params)
 
+    def threejs_repr(self, render_params):
+        r"""
+        Return a represention of the surface suitable for plotting with three.js.
+
+        EXAMPLES::
+
+            sage: _ = var('x,y')
+            sage: P = plot3d(x^2-y^2, (x, -2, 2), (y, -2, 2))
+            sage: P.threejs_repr(P.default_render_params())
+            [('surface',
+              {'color': '#6666ff',
+               'faces': [[0, 1, 2, 3],
+                ...
+               'opacity': 1.0,
+               'vertices': [{'x': -2.0, 'y': -2.0, 'z': 0.0},
+                ...
+                {'x': 2.0, 'y': 2.0, 'z': 0.0}]})]
+
+        """
+        self.triangulate(render_params)
+        return IndexFaceSet.threejs_repr(self, render_params)
+
     def is_enclosed(self):
         """
         Return a boolean telling whether or not it is necessary to
@@ -723,7 +745,7 @@ cdef class ParametricSurface(IndexFaceSet):
         Draw a 3D plot of this graphics object, which just returns this
         object since this is already a 3D graphics object.
         Needed to support PLOT in doctrings, see :trac:`17498`
-        
+
         EXAMPLES::
 
             sage: S = parametric_plot3d( (sin, cos, lambda u: u/10), (0, 20))
@@ -754,7 +776,7 @@ class MoebiusStrip(ParametricSurface):
 
         sage: from sage.plot.plot3d.parametric_surface import MoebiusStrip
         sage: M = MoebiusStrip(3,3)
-        sage: M.show() 
+        sage: M.show()
     """
 
     def __init__(self, r, width, twists=1, **kwds):