line chart: introduce renderer (#4249)

Renderer is an abstraction over how we are going to draw line, text, and                                                   
rect. For now, we only support two renderer, SVG and THREE.js based                                                        
WebGL.                                                                                                                     
                                                                                                                           
It is worth to note that both renderers we are supporting uses Object to                                                   
represent a pixel--SVG uses elements to describe path, circle, and text and                                                
THREE.js uses Object3d to represent shader. Contrary to canvas renderer that                                               
renders pixels, for an update, the object based renderer allow us make                                                     
modification without erasing entire scene/canvas/DOM to guarantee correctness.                                             
This allows us to make optimization where we minimally make changes to an                                                  
object and let the library/browser make an efficient update to pixels.                                                     
                                                                                                                           
Based on this idea, our renderer in its shape rendering API takes an object as                                             
a parameter to update an object instead of creating one.

Author: stephanwlee

Diff for: tensorboard/webapp/BUILD

@@ -283,6 +283,7 @@ tf_ng_web_test_suite(
         "//tensorboard/webapp/widgets/histogram:histogram_test",
         "//tensorboard/webapp/widgets/line_chart:line_chart_test",
         "//tensorboard/webapp/widgets/line_chart_v2/lib:lib_tests",
+        "//tensorboard/webapp/widgets/line_chart_v2/lib/renderer:renderer_test",
         "//tensorboard/webapp/widgets/range_input:range_input_tests",
         "//tensorboard/webapp/widgets/text:text_tests",
     ],

Diff for: tensorboard/webapp/widgets/line_chart_v2/lib/README.md

@@ -6,10 +6,19 @@ This is a generic charting library with a focus on performance.
 
 - Agnostic to HTMLCanvas vs. OffscreenCanvas
 - Generic to different implementation of renderer; SVG vs. WebGL.
-- Minimize cache eviction and try to do a minimal work for render
+- Do a minimal work; for example, it should only do a coordinate system conversion upon
+  requested and it should do the minimal operation on rendered object.
 
-### Jargons we define
+### Key concepts
 
 - coordinatior: A utility module for converting coordinate systems. Abstracts
   away certain renderer quirks and holds onto state, helping with performance
   optimizations.
+- renderer: A pure module responsible for shape rendering (e.g., line, rect, triangle,
+  etc...) of a given technology such as SVG or Three.js.
+- data drawable: a view that draws renders data in a reigon given. Examples of data
+  drawable are series line and bar drawers. As implementer of a new visualizer should
+  subclass DataDrawable and implement a `redraw` method. The base class maintains both
+  data and render caches and let visualizer focus on the `redraw` method.
+- paint brush: primitives, such as `setLine`, for a data drawable that should be used
+  inside a `redraw` method.

Diff for: tensorboard/webapp/widgets/line_chart_v2/lib/renderer/BUILD

@@ -0,0 +1,46 @@
+load("//tensorboard/defs:defs.bzl", "tf_ts_library")
+
+package(default_visibility = ["//tensorboard:internal"])
+
+tf_ts_library(
+    name = "renderer",
+    srcs = [
+        "index.ts",
+        "svg_renderer.ts",
+        "threejs_renderer.ts",
+    ],
+    deps = [
+        ":types",
+        "//tensorboard/webapp/third_party:d3",
+        "//tensorboard/webapp/widgets/line_chart_v2/lib:coordinator",
+        "//tensorboard/webapp/widgets/line_chart_v2/lib:types",
+        "//tensorboard/webapp/widgets/line_chart_v2/lib:utils",
+        "@npm//three",
+    ],
+)
+
+tf_ts_library(
+    name = "types",
+    srcs = [
+        "renderer_types.ts",
+    ],
+    deps = [
+        "//tensorboard/webapp/widgets/line_chart_v2/lib:types",
+    ],
+)
+
+tf_ts_library(
+    name = "renderer_test",
+    testonly = True,
+    srcs = [
+        "renderer_test.ts",
+    ],
+    deps = [
+        ":renderer",
+        ":types",
+        "//tensorboard/webapp/widgets/line_chart_v2/lib:coordinator",
+        "//tensorboard/webapp/widgets/line_chart_v2/lib:types",
+        "@npm//@types/jasmine",
+        "@npm//three",
+    ],
+)

Diff for: tensorboard/webapp/widgets/line_chart_v2/lib/renderer/index.ts

@@ -0,0 +1,18 @@
+/* Copyright 2020 The TensorFlow Authors. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+==============================================================================*/
+
+export * from './renderer_types';
+export {SvgRenderer} from './svg_renderer';
+export {ThreeRenderer} from './threejs_renderer';

Diff for: tensorboard/webapp/widgets/line_chart_v2/lib/renderer/renderer_test.ts

@@ -0,0 +1,254 @@
+/* Copyright 2020 The TensorFlow Authors. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+==============================================================================*/
+import * as THREE from 'three';
+
+import {ThreeCoordinator} from '../threejs_coordinator';
+import {Polyline} from '../types';
+import {SvgRenderer} from './svg_renderer';
+import {ThreeRenderer} from './threejs_renderer';
+
+describe('line_chart_v2/lib/renderer test', () => {
+  const SVG_NS = 'http://www.w3.org/2000/svg';
+  const DEFAULT_LINE_OPTIONS = {visible: true, color: '#f00', width: 6};
+
+  describe('svg renderer', () => {
+    let renderer: SvgRenderer;
+    let el: SVGElement;
+
+    beforeEach(() => {
+      el = document.createElementNS(SVG_NS, 'svg');
+      renderer = new SvgRenderer(el);
+    });
+
+    it('creates a line', () => {
+      expect(el.children.length).toBe(0);
+
+      renderer.createOrUpdateLineObject(
+        null,
+        new Float32Array([0, 10, 10, 100]),
+        {visible: true, color: '#f00', width: 6}
+      );
+
+      expect(el.children.length).toBe(1);
+      const path = el.children[0] as SVGPathElement;
+      expect(path.tagName).toBe('path');
+      expect(path.getAttribute('d')).toBe('M0,10L10,100');
+      expect(path.style.stroke).toBe('rgb(255, 0, 0)');
+      expect(path.style.strokeWidth).toBe('6');
+      expect(path.style.display).toBe('');
+    });
+
+    it('updates a cached path and styles', () => {
+      const cacheObject = renderer.createOrUpdateLineObject(
+        null,
+        new Float32Array([0, 10, 10, 100]),
+        {visible: true, color: '#f00', width: 6}
+      );
+
+      renderer.createOrUpdateLineObject(
+        cacheObject,
+        new Float32Array([0, 5, 5, 50]),
+        {visible: true, color: '#0f0', width: 3}
+      );
+
+      expect(el.children.length).toBe(1);
+      const path = el.children[0] as SVGPathElement;
+      expect(path.tagName).toBe('path');
+      expect(path.getAttribute('d')).toBe('M0,5L5,50');
+      expect(path.style.stroke).toBe('rgb(0, 255, 0)');
+      expect(path.style.strokeWidth).toBe('3');
+      expect(path.style.display).toBe('');
+    });
+
+    it('updates a cached path to an empty polyline', () => {
+      const cacheObject = renderer.createOrUpdateLineObject(
+        null,
+        new Float32Array([0, 10, 10, 100]),
+        {visible: true, color: '#f00', width: 6}
+      );
+
+      renderer.createOrUpdateLineObject(cacheObject, new Float32Array(0), {
+        visible: true,
+        color: '#0f0',
+        width: 3,
+      });
+
+      expect(el.children.length).toBe(1);
+      const path = el.children[0] as SVGPathElement;
+      expect(path.tagName).toBe('path');
+      expect(path.getAttribute('d')).toBe('');
+      // While it is possible to update minimally and only change the path or visibility,
+      // such optimization is a bit too premature without a clear benefit.
+      expect(path.style.stroke).toBe('rgb(0, 255, 0)');
+      expect(path.style.strokeWidth).toBe('3');
+      expect(path.style.display).toBe('');
+    });
+
+    it('skips updating path and color if visibility goes from true to false', () => {
+      const cacheObject = renderer.createOrUpdateLineObject(
+        null,
+        new Float32Array([0, 10, 10, 100]),
+        {visible: true, color: '#f00', width: 6}
+      );
+
+      renderer.createOrUpdateLineObject(
+        cacheObject,
+        new Float32Array([0, 5, 5, 50]),
+        {visible: false, color: '#0f0', width: 3}
+      );
+
+      expect(el.children.length).toBe(1);
+      const path = el.children[0] as SVGPathElement;
+      expect(path.tagName).toBe('path');
+      expect(path.style.display).toBe('none');
+      expect(path.getAttribute('d')).toBe('M0,10L10,100');
+      expect(path.style.stroke).toBe('rgb(255, 0, 0)');
+      expect(path.style.strokeWidth).toBe('6');
+    });
+
+    it('skips rendering DOM when a new cacheId starts with visible=false', () => {
+      renderer.createOrUpdateLineObject(
+        null,
+        new Float32Array([0, 10, 10, 100]),
+        {visible: false, color: '#f00', width: 6}
+      );
+
+      expect(el.children.length).toBe(0);
+    });
+  });
+
+  describe('threejs renderer', () => {
+    let renderer: ThreeRenderer;
+    let scene: THREE.Scene;
+
+    function assertLine(line: THREE.Line, polyline: Polyline) {
+      const geometry = line.geometry as THREE.BufferGeometry;
+      const positions = geometry.getAttribute(
+        'position'
+      ) as THREE.BufferAttribute;
+      let positionIndex = 0;
+      for (
+        let polylineIndex = 0;
+        polylineIndex < polyline.length;
+        polylineIndex += 2
+      ) {
+        const expectedX = polyline[polylineIndex];
+        const expectedY = polyline[polylineIndex + 1];
+        const actualX = positions.array[positionIndex++];
+        const actualY = positions.array[positionIndex++];
+        const actualZ = positions.array[positionIndex++];
+        expect(actualX).toBe(expectedX);
+        expect(actualY).toBe(expectedY);
+        expect(actualZ).toBe(0);
+      }
+    }
+
+    function assertMaterial(
+      line: THREE.Line,
+      longHexString: string,
+      visibility: boolean
+    ) {
+      const material = line.material as THREE.LineBasicMaterial;
+      expect(material.visible).toBe(visibility);
+      expect(material.color.getHexString()).toBe(longHexString.slice(1));
+    }
+
+    beforeEach(() => {
+      scene = new THREE.Scene();
+      spyOn(THREE, 'Scene').and.returnValue(scene);
+
+      const canvas = document.createElement('canvas');
+      const coordinator = new ThreeCoordinator();
+      renderer = new ThreeRenderer(canvas, coordinator, 2);
+    });
+
+    it('creates a line', () => {
+      renderer.createOrUpdateLineObject(
+        null,
+        new Float32Array([0, 10, 10, 100]),
+        {visible: true, color: '#f00', width: 6}
+      );
+
+      expect(scene.children.length).toBe(1);
+      const lineObject = scene.children[0] as THREE.Line;
+      expect(lineObject).toBeInstanceOf(THREE.Line);
+      assertLine(lineObject, new Float32Array([0, 10, 10, 100]));
+      assertMaterial(lineObject, '#ff0000', true);
+    });
+
+    it('updates cached path and styles', () => {
+      const cacheObject = renderer.createOrUpdateLineObject(
+        null,
+        new Float32Array([0, 10, 10, 100]),
+        {visible: true, color: '#f00', width: 6}
+      );
+
+      renderer.createOrUpdateLineObject(
+        cacheObject,
+        new Float32Array([0, 5, 5, 50, 10, 100]),
+        {visible: true, color: '#0f0', width: 3}
+      );
+
+      const lineObject = scene.children[0] as THREE.Line;
+      assertLine(lineObject, new Float32Array([0, 5, 5, 50, 10, 100]));
+      assertMaterial(lineObject, '#00ff00', true);
+    });
+
+    it('updates object when going from non-emtpy polyline to an empty one', () => {
+      const cacheObject = renderer.createOrUpdateLineObject(
+        null,
+        new Float32Array([0, 10, 10, 100]),
+        {visible: true, color: '#f00', width: 6}
+      );
+
+      renderer.createOrUpdateLineObject(cacheObject, new Float32Array(0), {
+        visible: true,
+        color: '#0f0',
+        width: 3,
+      });
+
+      const lineObject = scene.children[0] as THREE.Line;
+      assertLine(lineObject, new Float32Array(0));
+      assertMaterial(lineObject, '#00ff00', true);
+    });
+
+    it('does not update color and paths when visibility go from true to false', () => {
+      const cachedObject = renderer.createOrUpdateLineObject(
+        null,
+        new Float32Array([0, 10, 10, 100]),
+        {visible: true, color: '#f00', width: 6}
+      );
+
+      renderer.createOrUpdateLineObject(
+        cachedObject,
+        new Float32Array([0, 5, 5, 50, 10, 100]),
+        {visible: false, color: '#0f0', width: 3}
+      );
+
+      const lineObject = scene.children[0] as THREE.Line;
+      assertLine(lineObject, new Float32Array([0, 10, 10, 100]));
+      assertMaterial(lineObject, '#ff0000', false);
+    });
+
+    it('skips rendering if render starts with visibility=false ', () => {
+      renderer.createOrUpdateLineObject(null, new Float32Array([0, 1, 0, 1]), {
+        ...DEFAULT_LINE_OPTIONS,
+        visible: false,
+      });
+
+      expect(scene.children.length).toBe(0);
+    });
+  });
+});