From 7770164d85682d5fefde84ecc2bd5263ab708b74 Mon Sep 17 00:00:00 2001 From: Mojtaba Samimi Date: Tue, 9 Jan 2024 10:20:28 -0500 Subject: [PATCH 01/23] add examples using base64 --- doc/python/b64.md | 198 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 198 insertions(+) create mode 100644 doc/python/b64.md diff --git a/doc/python/b64.md b/doc/python/b64.md new file mode 100644 index 00000000000..5ac82779854 --- /dev/null +++ b/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 + +``` From c2d755e14b25c28030ede373e8b28ae99bf906c0 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Tue, 17 Sep 2024 10:03:38 -0400 Subject: [PATCH 02/23] remove example + make small changes to metadata --- doc/python/b64.md | 109 ++++------------------------------------------ 1 file changed, 8 insertions(+), 101 deletions(-) diff --git a/doc/python/b64.md b/doc/python/b64.md index 5ac82779854..ffd1585c8a8 100644 --- a/doc/python/b64.md +++ b/doc/python/b64.md @@ -6,7 +6,7 @@ jupyter: extension: .md format_name: markdown format_version: '1.3' - jupytext_version: 1.15.2 + jupytext_version: 1.16.3 kernelspec: display_name: Python 3 (ipykernel) language: python @@ -20,20 +20,21 @@ jupyter: name: python nbconvert_exporter: python pygments_lexer: ipython3 - version: 3.9.0 + version: 3.10.0 plotly: - description: How to format axes of 3d plots in Python with Plotly. - display_as: b64 + description: How to use typed arrays in Plotly.py + display_as: file_settings language: python layout: base - name: b64 - order: 1 - page_type: example_index + name: Improving Performance with Typed Arrays + order: 39 permalink: python/b64/ thumbnail: thumbnail/b64.png --- +```python ### 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 @@ -102,97 +103,3 @@ fig = go.Figure(data=[go.Scatter3d( 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 - -``` From d0bc21b8351b517eea7b5f8f2091faf5b79f848d Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Tue, 17 Sep 2024 10:25:31 -0400 Subject: [PATCH 03/23] add back correct examples --- doc/python/b64.md | 66 +++++++++++++++++------------------------------ 1 file changed, 23 insertions(+), 43 deletions(-) diff --git a/doc/python/b64.md b/doc/python/b64.md index ffd1585c8a8..89e161f9303 100644 --- a/doc/python/b64.md +++ b/doc/python/b64.md @@ -32,73 +32,53 @@ jupyter: thumbnail: thumbnail/b64.png --- -```python -### Simple example showing how arrays of numbers could be passed as base64 typed array objects to plotly.js -``` +### Example where base64 is automatically applied to pass numpy arrays to plotly.js ```python import plotly.graph_objects as go +import numpy as np -# x = [-200000 -100000 0 100000 200000] -x = {'dtype': 'int32', 'bdata': 'wPL8/2B5/v8AAAAAoIYBAEANAwA='} +np.random.seed(1) -# y = [0 1 2 3 4 5 6 7 8 9] -y = {'dtype': 'uint8', 'bdata': 'AAECAwQFBgcICQ=='} +N = 10000 -# 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' -} +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.Surface( +fig = go.Figure(data=[go.Scatter3d( x=x, y=y, - z=z + z=z, + marker=dict(color=c), + mode='markers', + opacity=0.2 )]) fig.show() ``` -### Example where base64 is applied to pass values as typed array objects to plotly.js +### 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 -def b64(arr) : - return { - 'dtype': str(arr.dtype), - 'bdata': b64encode(arr).decode('ascii') - } - np.random.seed(1) -N = 10000 +M = 100 +N = 200 -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') +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.Scatter3d( - x=b64(x), - y=b64(y), - z=b64(z), - marker=dict(color= b64(c)), - mode='markers', - opacity=0.2 +fig = go.Figure(data=[go.Surface( + x=x, + y=y, + z=z )]) fig.show() From fb0a5d848ab728fab1b67735dfe0c48e7db2c366 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Wed, 18 Sep 2024 15:14:40 -0400 Subject: [PATCH 04/23] add content for numpy arrays --- doc/python/b64.md | 57 ++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 52 insertions(+), 5 deletions(-) diff --git a/doc/python/b64.md b/doc/python/b64.md index 89e161f9303..fb50b4fff0e 100644 --- a/doc/python/b64.md +++ b/doc/python/b64.md @@ -32,7 +32,48 @@ jupyter: thumbnail: thumbnail/b64.png --- -### Example where base64 is automatically applied to pass numpy arrays to plotly.js +*New in Plotly.py 6.0** + +Improve the performance of generating Plotly figures that use a large number of data points by using NumPy arrays and other objects that can be converted to NumPy arrays, such as Pandas Series and Index objects. + +Plotly.py uses Plotly.js for rendering, which supports base64-encoded typed arrays. In Plotly.py, NumPy array and NumPy-convertible arrays are base64 encoded before being passed to Plotly.js for rendering. + + +## Arrays and Data Types Supported + +The following types of array objects in Python are supported: + +- Numpy `numpy.ndarray` objects. +- Pandas Index, `pandas.Index`, or Series, `pandas.Series`, objects. +- Array objects that can be converted to `numpy.ndarray` objects. i.e., they implement `"__array__"` or `"__array_interface__"` and return a `numpy.ndarray. + +The following array data types are supported: + +- int8 +- uint8 +- int16 +- uint16 +- int32 +- uint32 +- float32 +- float64 +- int64* +- uint64* + +*If the array dtype is **int64** and **uint64**, often the default dtype for arrays in NumPy when no dtype is specified, those dtypes will be changed to other types internally by Plotly.py where possible. + + + +## Unsupported Attributes + +Arrays passsed to attributes with the following names do not use the Plotly.js base64 typed arrays functionality: + +`geojson`, `layers`, and `range`. + + +## Example with NumPy Arrays + +Here, we use NumPy arrays with a `go.Scatter3d` figure. ```python import plotly.graph_objects as go @@ -40,8 +81,10 @@ import numpy as np np.random.seed(1) +# Number of data points N = 10000 +# Generate random data x = np.random.randn(N) y = np.random.randn(N).astype('float32') z = np.random.randint(size=N, low=0, high=256, dtype='uint8') @@ -59,20 +102,24 @@ fig = go.Figure(data=[go.Scatter3d( fig.show() ``` -### Example where base64 is automatically applied to pass multi-dimensional numpy arrays to plotly.js +### Example with Multi-Dimensional Array + +Here, we use a multi dimensional array with a `go.Surface` figure. + ```python import plotly.graph_objects as go import numpy as np -from base64 import b64encode np.random.seed(1) +# Define the dimensions M = 100 N = 200 -x = np.arange(0, M, 1, 'int32') -y = np.arange(0, N, 1, 'uint8') +x = np.arange(0, M, 1, dtype='int32') +y = np.arange(0, N, 1, dtype='uint8') + z = np.random.random([N, M]) fig = go.Figure(data=[go.Surface( From 49ae4989a994694812f31f6ff6c600357164dc06 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Thu, 19 Sep 2024 10:00:46 -0400 Subject: [PATCH 05/23] fix typo --- doc/python/b64.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/python/b64.md b/doc/python/b64.md index fb50b4fff0e..e20f44c233e 100644 --- a/doc/python/b64.md +++ b/doc/python/b64.md @@ -45,7 +45,7 @@ The following types of array objects in Python are supported: - Numpy `numpy.ndarray` objects. - Pandas Index, `pandas.Index`, or Series, `pandas.Series`, objects. -- Array objects that can be converted to `numpy.ndarray` objects. i.e., they implement `"__array__"` or `"__array_interface__"` and return a `numpy.ndarray. +- Array objects that can be converted to `numpy.ndarray` objects. i.e., they implement `"__array__"` or `"__array_interface__"` and return a `numpy.ndarray`. The following array data types are supported: From 589d105c24c6640f5a31d379d81585a8e460c558 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Thu, 19 Sep 2024 10:26:14 -0400 Subject: [PATCH 06/23] rename file --- doc/python/{b64.md => numpy-arrays.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename doc/python/{b64.md => numpy-arrays.md} (100%) diff --git a/doc/python/b64.md b/doc/python/numpy-arrays.md similarity index 100% rename from doc/python/b64.md rename to doc/python/numpy-arrays.md From 79afc5c0dfb1a8c656b4b22815538ad96ff284c2 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Thu, 19 Sep 2024 10:30:28 -0400 Subject: [PATCH 07/23] update titles and link --- doc/python/numpy-arrays.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/python/numpy-arrays.md b/doc/python/numpy-arrays.md index e20f44c233e..0b1ebd7a166 100644 --- a/doc/python/numpy-arrays.md +++ b/doc/python/numpy-arrays.md @@ -22,19 +22,19 @@ jupyter: pygments_lexer: ipython3 version: 3.10.0 plotly: - description: How to use typed arrays in Plotly.py + description: How to use NumPy arrays in Plotly.py for improved performance display_as: file_settings language: python layout: base - name: Improving Performance with Typed Arrays + name: Improving Performance with NumPy Arrays order: 39 - permalink: python/b64/ + permalink: python/performance/ thumbnail: thumbnail/b64.png --- *New in Plotly.py 6.0** -Improve the performance of generating Plotly figures that use a large number of data points by using NumPy arrays and other objects that can be converted to NumPy arrays, such as Pandas Series and Index objects. +Improve the performance of generating Plotly figures that use a large number of data points by using NumPy arrays and other objects that can be converted to NumPy arrays, such as Pandas Series and Index objects. Plotly.py uses Plotly.js for rendering, which supports base64-encoded typed arrays. In Plotly.py, NumPy array and NumPy-convertible arrays are base64 encoded before being passed to Plotly.js for rendering. @@ -59,8 +59,8 @@ The following array data types are supported: - float64 - int64* - uint64* - -*If the array dtype is **int64** and **uint64**, often the default dtype for arrays in NumPy when no dtype is specified, those dtypes will be changed to other types internally by Plotly.py where possible. + +*If the array dtype is **int64** and **uint64**, often the default dtype for arrays in NumPy when no dtype is specified, those dtypes will be changed to other types internally by Plotly.py where possible. From af1c4a441ba4b1713b311adbf967e02b75225afc Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Thu, 19 Sep 2024 13:42:05 -0400 Subject: [PATCH 08/23] fix typo and shorten content --- doc/python/numpy-arrays.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/python/numpy-arrays.md b/doc/python/numpy-arrays.md index 0b1ebd7a166..670719674c7 100644 --- a/doc/python/numpy-arrays.md +++ b/doc/python/numpy-arrays.md @@ -66,7 +66,7 @@ The following array data types are supported: ## Unsupported Attributes -Arrays passsed to attributes with the following names do not use the Plotly.js base64 typed arrays functionality: +Arrays passed to attributes with the following names are not supported: `geojson`, `layers`, and `range`. From 170d7f9346250691b1945fde9318c3f89ad8ff0d Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Thu, 19 Sep 2024 13:54:10 -0400 Subject: [PATCH 09/23] Update numpy-arrays.md --- doc/python/numpy-arrays.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/doc/python/numpy-arrays.md b/doc/python/numpy-arrays.md index 670719674c7..a4b1db40c1f 100644 --- a/doc/python/numpy-arrays.md +++ b/doc/python/numpy-arrays.md @@ -38,7 +38,6 @@ Improve the performance of generating Plotly figures that use a large number of Plotly.py uses Plotly.js for rendering, which supports base64-encoded typed arrays. In Plotly.py, NumPy array and NumPy-convertible arrays are base64 encoded before being passed to Plotly.js for rendering. - ## Arrays and Data Types Supported The following types of array objects in Python are supported: @@ -62,8 +61,6 @@ The following array data types are supported: *If the array dtype is **int64** and **uint64**, often the default dtype for arrays in NumPy when no dtype is specified, those dtypes will be changed to other types internally by Plotly.py where possible. - - ## Unsupported Attributes Arrays passed to attributes with the following names are not supported: From 7a67f81b1889cd177e64b9742adfc2cedef9e3f6 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Mon, 23 Sep 2024 10:44:11 -0400 Subject: [PATCH 10/23] merge performance content --- doc/python/numpy-arrays.md | 129 ------------------------------------- doc/python/webgl-vs-svg.md | 116 ++++++++++++++++++++++++++++++--- 2 files changed, 107 insertions(+), 138 deletions(-) delete mode 100644 doc/python/numpy-arrays.md diff --git a/doc/python/numpy-arrays.md b/doc/python/numpy-arrays.md deleted file mode 100644 index a4b1db40c1f..00000000000 --- a/doc/python/numpy-arrays.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -jupyter: - jupytext: - notebook_metadata_filter: all - text_representation: - extension: .md - format_name: markdown - format_version: '1.3' - jupytext_version: 1.16.3 - 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.10.0 - plotly: - description: How to use NumPy arrays in Plotly.py for improved performance - display_as: file_settings - language: python - layout: base - name: Improving Performance with NumPy Arrays - order: 39 - permalink: python/performance/ - thumbnail: thumbnail/b64.png ---- - -*New in Plotly.py 6.0** - -Improve the performance of generating Plotly figures that use a large number of data points by using NumPy arrays and other objects that can be converted to NumPy arrays, such as Pandas Series and Index objects. - -Plotly.py uses Plotly.js for rendering, which supports base64-encoded typed arrays. In Plotly.py, NumPy array and NumPy-convertible arrays are base64 encoded before being passed to Plotly.js for rendering. - -## Arrays and Data Types Supported - -The following types of array objects in Python are supported: - -- Numpy `numpy.ndarray` objects. -- Pandas Index, `pandas.Index`, or Series, `pandas.Series`, objects. -- Array objects that can be converted to `numpy.ndarray` objects. i.e., they implement `"__array__"` or `"__array_interface__"` and return a `numpy.ndarray`. - -The following array data types are supported: - -- int8 -- uint8 -- int16 -- uint16 -- int32 -- uint32 -- float32 -- float64 -- int64* -- uint64* - -*If the array dtype is **int64** and **uint64**, often the default dtype for arrays in NumPy when no dtype is specified, those dtypes will be changed to other types internally by Plotly.py where possible. - -## Unsupported Attributes - -Arrays passed to attributes with the following names are not supported: - -`geojson`, `layers`, and `range`. - - -## Example with NumPy Arrays - -Here, we use NumPy arrays with a `go.Scatter3d` figure. - -```python -import plotly.graph_objects as go -import numpy as np - -np.random.seed(1) - -# Number of data points -N = 10000 - -# Generate random data -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 with Multi-Dimensional Array - -Here, we use a multi dimensional array with a `go.Surface` figure. - - -```python -import plotly.graph_objects as go -import numpy as np - -np.random.seed(1) - -# Define the dimensions -M = 100 -N = 200 - -x = np.arange(0, M, 1, dtype='int32') -y = np.arange(0, N, 1, dtype='uint8') - -z = np.random.random([N, M]) - -fig = go.Figure(data=[go.Surface( - x=x, - y=y, - z=z -)]) - -fig.show() -``` diff --git a/doc/python/webgl-vs-svg.md b/doc/python/webgl-vs-svg.md index 386ea40e1cd..f0545699c6a 100644 --- a/doc/python/webgl-vs-svg.md +++ b/doc/python/webgl-vs-svg.md @@ -6,7 +6,7 @@ jupyter: extension: .md format_name: markdown format_version: '1.3' - jupytext_version: 1.16.1 + jupytext_version: 1.16.3 kernelspec: display_name: Python 3 (ipykernel) language: python @@ -20,17 +20,17 @@ jupyter: name: python nbconvert_exporter: python pygments_lexer: ipython3 - version: 3.10.11 + version: 3.10.0 plotly: - description: Using WebGL for increased speed, improved interactivity, and the - ability to plot even more data! + description: Using WebGL and NumPy arrays for increased speed, improved interactivity, + and the ability to plot even more data! display_as: basic language: python layout: base - name: WebGL vs SVG + name: High Performance Visualization order: 14 - permalink: python/webgl-vs-svg/ - redirect_from: python/compare-webgl-svg/ + permalink: python/performance/ + redirect_from: python/webgl-vs-svg/ thumbnail: thumbnail/webgl.jpg --- @@ -72,12 +72,12 @@ To use it, in the environment where your Plotly figures are being rendered, load In a Jupyter notebook environment that supports magic commands, you can load it with the [HTML magic command](https://ipython.readthedocs.io/en/stable/interactive/magics.html#cellmagic-html): - + ``` %%html ``` - + ### WebGL for Scatter Performance @@ -198,3 +198,101 @@ fig.show() ### Reference See https://plotly.com/python/reference/scattergl/ for more information and chart attribute options! + +## NumPy Arrays + +*New in Plotly.py 6.0** + +Improve the performance of generating Plotly figures that use a large number of data points by using NumPy arrays and other objects that can be converted to NumPy arrays, such as Pandas Series and Index objects. + +Plotly.py uses Plotly.js for rendering, which supports base64-encoded typed arrays. In Plotly.py, NumPy array and NumPy-convertible arrays are base64 encoded before being passed to Plotly.js for rendering. + +### Arrays and Data Types Supported + +The following types of array objects in Python are supported: + +- Numpy `numpy.ndarray` objects. +- Pandas Index, `pandas.Index`, or Series, `pandas.Series`, objects. +- Array objects that can be converted to `numpy.ndarray` objects. i.e., they implement `"__array__"` or `"__array_interface__"` and return a `numpy.ndarray`. + +The following array data types are supported: + +- int8 +- uint8 +- int16 +- uint16 +- int32 +- uint32 +- float32 +- float64 +- int64* +- uint64* + +*If the array dtype is **int64** and **uint64**, often the default dtype for arrays in NumPy when no dtype is specified, those dtypes will be changed to other types internally by Plotly.py where possible. + +### Unsupported Attributes + +Arrays passed to attributes with the following names are not supported: + +`geojson`, `layers`, and `range`. + + +### Example with NumPy Arrays + +Here, we use NumPy arrays with a `go.Scatter3d` figure. + +```python +import plotly.graph_objects as go +import numpy as np + +np.random.seed(1) + +# Number of data points +N = 10000 + +# Generate random data +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 with Multi-Dimensional Array + +Here, we use a multi dimensional array with a `go.Surface` figure. + + +```python +import plotly.graph_objects as go +import numpy as np + +np.random.seed(1) + +# Define the dimensions +M = 100 +N = 200 + +x = np.arange(0, M, 1, dtype='int32') +y = np.arange(0, N, 1, dtype='uint8') + +z = np.random.random([N, M]) + +fig = go.Figure(data=[go.Surface( + x=x, + y=y, + z=z +)]) + +fig.show() +``` From f75521c88fceb3cb7723dfa172e7b2069ff6811a Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Mon, 23 Sep 2024 12:06:42 -0400 Subject: [PATCH 11/23] add intro and restructure svg intro --- doc/python/webgl-vs-svg.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/doc/python/webgl-vs-svg.md b/doc/python/webgl-vs-svg.md index f0545699c6a..7f2a80f209e 100644 --- a/doc/python/webgl-vs-svg.md +++ b/doc/python/webgl-vs-svg.md @@ -34,9 +34,22 @@ jupyter: thumbnail: thumbnail/webgl.jpg --- -### SVG and canvas/WebGL: two browser capabilities for rendering +In some examples in the documentation, you'll see figures created using data structures that are native to Python, such as lists and tuples, and which use trace types that render as SVGs. -`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: +This will work fine for many use cases, but may not provide optimal performance with larger datasets. + +For improved performance, consider using WebGL-based traces and NumPy arrays. + + +## WebGL + +`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 +- 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` @@ -71,7 +84,7 @@ If you encounter WebGL context limits when using WebGL-based figures, you can us To use it, in the environment where your Plotly figures are being rendered, load the Virtual WebGL script, "https://unpkg.com/virtual-webgl@1.0.6/src/virtual-webgl.js", for example, using a `