Use plotly.js base64 API to store and pass typed arrays declared by numpy, pandas, etc.

doc/python/b64.md

@@ -0,0 +1,198 @@
+---
+jupyter:
+  jupytext:
+    notebook_metadata_filter: all
+    text_representation:
+      extension: .md
+      format_name: markdown
+      format_version: '1.3'
+      jupytext_version: 1.15.2
+  kernelspec:
+    display_name: Python 3 (ipykernel)
+    language: python
+    name: python3
+  language_info:
+    codemirror_mode:
+      name: ipython
+      version: 3
+    file_extension: .py
+    mimetype: text/x-python
+    name: python
+    nbconvert_exporter: python
+    pygments_lexer: ipython3
+    version: 3.9.0
+  plotly:
+    description: How to format axes of 3d plots in Python with Plotly.
+    display_as: b64
+    language: python
+    layout: base
+    name: b64
+    order: 1
+    page_type: example_index
+    permalink: python/b64/
+    thumbnail: thumbnail/b64.png
+---
+
+### Simple example showing how arrays of numbers could be passed as base64 typed array objects to plotly.js
+
+```python
+import plotly.graph_objects as go
+
+# x = [-200000 -100000       0  100000  200000]
+x = {'dtype': 'int32', 'bdata': 'wPL8/2B5/v8AAAAAoIYBAEANAwA='}
+
+# y = [0 1 2 3 4 5 6 7 8 9]
+y = {'dtype': 'uint8', 'bdata': 'AAECAwQFBgcICQ=='}
+
+# z = [
+# [  61 -295 -765  863  932]
+# [-897   96  724  791 -993]
+# [ -95 -796 -285  381  669]
+# [ 985 -153  425  -40  136]
+# [-856  955 -871  414  996]
+# [ 966  607 -154 -251 -882]
+# [-492 -116  414  426  305]
+# [ 919  202 -505  300 -833]
+# [ 278 -152 -643 -950  -86]
+# [ 898 -532  608  -93  110]]
+z = {
+  'dtype': 'int16',
+  'bdata': 'PQDZ/gP9XwOkA3/8YADUAhcDH/yh/+T84/59AZ0C2QNn/6kB2P+IAKj8uwOZ/J4B5APGA18CZv8F/478FP6M/54BqgExAZcDygAH/iwBv/wWAWj/ff1K/Kr/ggPs/WACo/9uAA==', 'shape': '10, 5'
+}
+
+fig = go.Figure(data=[go.Surface(
+    x=x,
+    y=y,
+    z=z
+)])
+
+fig.show()
+```
+
+### Example where base64 is applied to pass values as typed array objects to plotly.js
+
+```python
+import plotly.graph_objects as go
+import numpy as np
+from base64 import b64encode
+
+def b64(arr) :
+  return {
+      'dtype': str(arr.dtype),
+      'bdata': b64encode(arr).decode('ascii')
+  }
+
+np.random.seed(1)
+
+N = 10000
+
+x = np.random.randn(N)
+y = np.random.randn(N).astype('float32')
+z = np.random.randint(size=N, low=0, high=256, dtype='uint8')
+c = np.random.randint(size=N, low=-10, high=10, dtype='int8')
+
+fig = go.Figure(data=[go.Scatter3d(
+    x=b64(x),
+    y=b64(y),
+    z=b64(z),
+    marker=dict(color= b64(c)),
+    mode='markers',
+    opacity=0.2
+)])
+
+fig.show()
+```
+
+### Similar example where base64 is automatically applied to pass numpy arrays to plotly.js
+
+```python
+import plotly.graph_objects as go
+import numpy as np
+
+np.random.seed(1)
+
+N = 10000
+
+x = np.random.randn(N)
+y = np.random.randn(N).astype('float32')
+z = np.random.randint(size=N, low=0, high=256, dtype='uint8')
+c = np.random.randint(size=N, low=-10, high=10, dtype='int8')
+
+fig = go.Figure(data=[go.Scatter3d(
+    x=x,
+    y=y,
+    z=z,
+    marker=dict(color=c),
+    mode='markers',
+    opacity=0.2
+)])
+
+fig.show()
+```
+
+
+### Example where base64 is applied to pass 2 dimensional values as typed array objects to plotly.js using shape in the spec
+
+```python
+import plotly.graph_objects as go
+import numpy as np
+from base64 import b64encode
+
+def b64(arr) :
+  return {
+      'dtype': str(arr.dtype),
+      'bdata': b64encode(arr).decode('ascii'),
+      'shape': None if arr.ndim == 1 else str(arr.shape)[1:-1]
+  }
+
+np.random.seed(1)
+
+M = 100
+N = 200
+
+x = np.arange(0, M, 1, 'int32')
+y = np.arange(0, N, 1, 'uint8')
+z = np.random.random([N, M])
+
+fig = go.Figure(data=[go.Surface(
+    x=b64(x),
+    y=b64(y),
+    z=b64(z)
+)])
+
+fig.show()
+```
+
+### Similar example where base64 is automatically applied to pass multi-dimensional numpy arrays to plotly.js
+
+```python
+import plotly.graph_objects as go
+import numpy as np
+from base64 import b64encode
+
+np.random.seed(1)
+
+M = 100
+N = 200
+
+x = np.arange(0, M, 1, 'int32')
+y = np.arange(0, N, 1, 'uint8')
+z = np.random.random([N, M])
+
+fig = go.Figure(data=[go.Surface(
+    x=x,
+    y=y,
+    z=z
+)])
+
+fig.show()
+```
+
+
+```python
+
+```
+
+```python
+
+```