orjson and webgl docs

Author: nicolaskruchten

doc/python/compare-webgl-svg.md

@@ -40,11 +40,11 @@ Plotly's Python graphing library, `plotly.py`, gives you a wide range of options
 
 In general, there are five different approaches you can take in order to display `plotly` figures:
 
- 1. Using the `renderers` framework in the context of a script or notebook
+ 1. Using the `renderers` framework in the context of a script or notebook (the main topic of this page)
  2. Using [Dash](https://dash.plot.ly) in a web app context
- 3. Using a `FigureWidget` in an `ipywidgets` context
- 4. By [exporting to an HTML file](https://plotly.com/python/interactive-html-export/) and loading that file in a browser
- 5. By [rendering the figure to a static representation](https://plotly.com/python/static-image-export/) such as PNG, JPEG, SVG, PDF or EPS
+ 3. Using a [`FigureWidget` rather than a `Figure`](https://plotly.com/python/figurewidget/) in an [`ipywidgets` context](https://ipywidgets.readthedocs.io/en/stable/)
+ 4. By [exporting to an HTML file](https://plotly.com/python/interactive-html-export/) and loading that file in a browser immediately or later
+ 5. By [rendering the figure to a static image file using Kaleido](https://plotly.com/python/static-image-export/) such as PNG, JPEG, SVG, PDF or EPS and loading the resulting file in any viewer
 
 Each of the first three approaches is discussed below.
 
@@ -251,6 +251,10 @@ See the [Plotly FigureWidget Overview](https://plot.ly/python/figurewidget/) for
 It is important to note that `FigureWidget` does not use the renderers framework discussed above, so you should not use the `show()` figure method or the `plotly.io.show` function on `FigureWidget` objects.
 
 
-## Rendering Performance
+## Performance
 
-No matter the approach chosen to display a figure (including HTML and static image export), 
+No matter the approach chosen to display a figure, [the figure data structure](https://plotly.com/python/figure-structure/) is first (automatically, internally) serialized into a JSON string before being transferred from the Python context to the browser (or [to an HTML file first](https://plotly.com/python/interactive-html-export/) or [to Kaleido for static image export](https://plotly.com/python/static-image-export/)). 
+
+The default JSON serialization mechanism can be slow for figures with many data points or with large `numpy` arrays or data frames. **If [the `orjson` package](https://github.com/ijl/orjson) is installed**, `plotly` will use that instead of the built-in `json` package, which can lead to **5-10x** speedups for large figures.
+
+Once a figure is serialized to JSON, it must be rendered by a browser, either immediately in the user's browser, at some later point if the figure is exported to HTML, or immediately in Kaleido's internal headless browser for static image export. Rendering time is generally proportional to the total number of data points in the figure, the number of traces and the number of subplots. In situations where rendering performance is slow, we recommend considering [the use of `plotly` WebGL traces](/python/webgl-vs-svg/) to exploit GPU-accelerated rendering in the browser, or [using the Datashader library to do Python-side rendering](/python/datashader/) before using `px.imshow()` to render the figure.

doc/python/renderers.md

@@ -22,7 +22,7 @@ jupyter:
     pygments_lexer: ipython3
     version: 3.6.5
   plotly:
-    description: Implement WebGL for increased speed, improved interactivity, and
+    description: Using WebGL for increased speed, improved interactivity, and
       the ability to plot even more data!
     display_as: basic
     language: python
@@ -31,20 +31,40 @@ jupyter:
     order: 14
     permalink: python/webgl-vs-svg/
     thumbnail: thumbnail/webgl.jpg
+    redirect_from: python/compare-webgl-svg/
 ---
 
-Here we show that it is possible to represent millions of points with WebGL.
+### SVG and canvas/WebGL: two browser capabilities for rendering
+
+`plotly` figures are rendered by web browsers, which broadly speaking have two families of capabilities for rendering graphics: the SVG API which supports vector rendering, and the Canvas API which supports raster rendering, and can exploit GPU hardware acceleration via a browser technology known as WebGL. Each `plotly` trace type is primarily rendered with either SVG or WebGL, although WebGL-powered traces also use some SVG. The following trace types use WebGL for part or all of the rendering:
+
+* Accelerated versions of SVG trace types: `scattergl`, `scatterpolargl`, `heatmapgl`,
+* High-performance multidimensional trace types: `splom`, or `parcoords`
+* 3-d trace types `scatter3d`, `surface`, `mesh3d`, `cone`, `streamtube`
+* Mapbox Gl JS-powered trace types: `scattermapbox`, `choroplethmapbox`, `densitymapbox`
+
+### WebGL Limitations and Tradeoffs
+
+WebGL is a powerful technology for accelerating computation but comes with some strict limitations:
+
+1. GPU requirement: WebGL is a GPU (graphics card) technology and therefore requires specific hardware which is available in most but not all cases and is supported by most but not all browsers
+2. Rasterization: WebGL-rendered data is drawn as a grid of pixels rather than as individual shapes, so can appear pixelated or fuzz in certain cases, and when exported to static file formats will appear pixelated on zoom
+3. Context limits: browsers impose a strict limit on the number of WebGL "contexts" that any given web document can access. WebGL-powered traces in `plotly` can use multiple contexts in some cases but as a general rule, **it may not be possible to render more than 8 WebGL-involving figures on the same page at the same time.**
+4. Size limits: browsers impose hardware-dependent limits on the height and width of figures using WebGL
+
+### WebGL for Scatter Performance
+
+In the examples below we show that it is possible to represent up to around a million points with WebGL-enabled traces.
 For larger datasets, or for a clearer visualization of the density of points,
 it is also possible to use [datashader](/python/datashader/).
 
-#### Compare WebGL and SVG
-Checkout [this notebook](https://plotly.com/python/compare-webgl-svg) to compare WebGL and SVG scatter plots with 75,000 random data points
+### WebGL with Plotly Express
 
-#### WebGL with Plotly Express
+The `rendermode` argument to supported Plotly Express functions (e.g. `scatter` and `scatter_polar`) can be used to enable WebGL rendering.
 
-The `rendermode` argument to supported Plotly Express functions can be used to enable WebGL rendering.
+> **Note** The default `rendermode` is `"auto"`, in which case Plotly Express will automatically set `rendermode="webgl` if the input data is more than 1,000 rows long. If WebGL acceleration is *not* desired in this case, `rendermode` can be forced to `"svg"` for vectorized, if slower, rendering.
 
-Here is an example that creates a 100,000 point scatter plot using Plotly Express with WebGL rendering enabled.
+Here is an example that creates a 100,000 point scatter plot using Plotly Express with WebGL rendering explicitly enabled.
 
 ```python
 import plotly.express as px
@@ -65,9 +85,10 @@ fig.update_traces(marker_line=dict(width=1, color='DarkSlateGray'))
 fig.show()
 ```
 
-#### WebGL with 100,000 points
 
-The `Scattergl` trace type can be used to create a WebGL enabled scatter plot.
+#### WebGL with 100,000 points with Graph Objects
+
+If Plotly Express does not provide a good starting point, it is also possible to use [the more generic `go.Scattergl` class from `plotly.graph_objects`](/python/graph-objects/).
 
 ```python
 import plotly.graph_objects as go
@@ -95,7 +116,7 @@ fig.add_trace(
 fig.show()
 ```
 
-#### WebGL with 1 Million Points
+#### WebGL Rendering with 1 Million Points
 
 ```python
 import plotly.graph_objects as go
@@ -149,4 +170,4 @@ fig.show()
 
 ### Reference
 
-See https://plotly.com/python/reference/scattergl/ for more information and chart attribute options!
+See https://plotly.com/python/reference/scattergl/ for more information and chart attribute options!