Accept objects for encoded typedarrays in data_array valType

.circleci/config.yml

@@ -253,6 +253,25 @@ jobs:
           paths:
             - plotly.js
 
+  make-baselines-b64:
+    parallelism: 4
+    docker:
+      - image: circleci/python:3.8.9
+    working_directory: ~/plotly.js
+    steps:
+      - attach_workspace:
+          at: ~/
+      - run:
+          name: Install kaleido, plotly.io and required fonts
+          command: .circleci/env_image.sh
+      - run:
+          name: Create all png files
+          command: .circleci/test.sh make-baselines-b64
+      - persist_to_workspace:
+          root: ~/
+          paths:
+            - plotly.js
+
   test-baselines:
     docker:
       - image: circleci/node:16.9.0
@@ -267,6 +286,20 @@ jobs:
           path: build
           destination: /
 
+  test-baselines-b64:
+    docker:
+      - image: circleci/node:16.9.0
+    working_directory: ~/plotly.js
+    steps:
+      - attach_workspace:
+          at: ~/
+      - run:
+          name: Compare pixels
+          command: .circleci/test.sh test-image ; find build -maxdepth 1 -type f -delete
+      - store_artifacts:
+          path: build
+          destination: /
+
   test-baselines-mathjax3:
     docker:
       - image: circleci/node:16.9.0
@@ -450,6 +483,12 @@ workflows:
       - test-baselines-mathjax3:
           requires:
             - make-baselines-mathjax3
+      - make-baselines-b64:
+          requires:
+            - install-and-cibuild
+      - test-baselines-b64:
+          requires:
+            - make-baselines-b64
       - make-baselines:
           requires:
             - install-and-cibuild

.circleci/env_image.sh

@@ -6,3 +6,5 @@ sudo cp -r .circleci/fonts/ /usr/share/ && \
 sudo fc-cache -f && \
 # install kaleido & plotly
 sudo python3 -m pip install kaleido==0.2.1 plotly==5.5.0 --progress-bar off
+# install numpy i.e. to convert arrays to typed arrays
+sudo python3 -m pip install numpy==1.24.2

.circleci/test.sh

@@ -87,6 +87,12 @@ case $1 in
         exit $EXIT_STATE
         ;;
 
+    make-baselines-b64)
+        SUITE=$(find $ROOT/test/image/mocks/ -type f -printf "%f\n" | sed 's/\.json$//1' | circleci tests split)
+        python3 test/image/make_baseline.py b64 $SUITE || EXIT_STATE=$?
+        exit $EXIT_STATE
+        ;;
+
     make-baselines)
         SUITE=$(find $ROOT/test/image/mocks/ -type f -printf "%f\n" | sed 's/\.json$//1' | circleci tests split)
         python3 test/image/make_baseline.py $SUITE || EXIT_STATE=$?

.eslintrc

@@ -14,8 +14,12 @@
     "Float32Array": true,
     "Float64Array": true,
     "Uint8Array": true,
+    "Int8Array": true,
+    "Uint8ClampedArray": true,
     "Int16Array": true,
+    "Uint16Array": true,
     "Int32Array": true,
+    "Uint32Array": true,
     "ArrayBuffer": true,
     "DataView": true,
     "SVGElement": false

draftlogs/5230_add.md

@@ -0,0 +1 @@
+ - Accept objects for encoded typedarrays in data_array valType [[#5230](https://github.com/plotly/plotly.js/pull/5230)]

package.json

@@ -76,6 +76,7 @@
     "@turf/area": "^6.4.0",
     "@turf/bbox": "^6.4.0",
     "@turf/centroid": "^6.0.2",
+    "base64-arraybuffer": "^1.0.2",
     "canvas-fit": "^1.5.0",
     "color-alpha": "1.0.4",
     "color-normalize": "1.5.0",

src/components/colorscale/helpers.js

@@ -13,7 +13,9 @@ function hasColorscale(trace, containerStr, colorKey) {
     var container = containerStr ?
         Lib.nestedProperty(trace, containerStr).get() || {} :
         trace;
+
     var color = container[colorKey || 'color'];
+    if(color && color._inputArray) color = color._inputArray;
 
     var isArrayWithOneNumber = false;
     if(Lib.isArrayOrTypedArray(color)) {

src/lib/array.js

@@ -1,4 +1,7 @@
 'use strict';
+var b64decode = require('base64-arraybuffer').decode;
+
+var isPlainObject = require('./is_plain_object');
 
 var isArray = Array.isArray;
 
@@ -48,6 +51,130 @@ exports.ensureArray = function(out, n) {
     return out;
 };
 
+var typedArrays = {
+    c1: typeof Uint8ClampedArray === 'undefined' ? undefined :
+               Uint8ClampedArray, // not supported in numpy?
+
+    i1: typeof Int8Array === 'undefined' ? undefined :
+               Int8Array,
+
+    u1: typeof Uint8Array === 'undefined' ? undefined :
+               Uint8Array,
+
+    i2: typeof Int16Array === 'undefined' ? undefined :
+               Int16Array,
+
+    u2: typeof Uint16Array === 'undefined' ? undefined :
+               Uint16Array,
+
+    i4: typeof Int32Array === 'undefined' ? undefined :
+               Int32Array,
+
+    u4: typeof Uint32Array === 'undefined' ? undefined :
+               Uint32Array,
+
+    f4: typeof Float32Array === 'undefined' ? undefined :
+               Float32Array,
+
+    f8: typeof Float64Array === 'undefined' ? undefined :
+               Float64Array,
+
+    /* TODO: potentially add Big Int
+
+    i8: typeof BigInt64Array === 'undefined' ? undefined :
+               BigInt64Array,
+
+    u8: typeof BigUint64Array === 'undefined' ? undefined :
+               BigUint64Array,
+    */
+};
+
+function isArrayBuffer(a) {
+    return a.constructor === ArrayBuffer;
+}
+exports.isArrayBuffer = isArrayBuffer;
+
+exports.decodeTypedArraySpec = function(vIn) {
+    var out = [];
+    var v = coerceTypedArraySpec(vIn);
+    var dtype = v.dtype;
+
+    var T = typedArrays[dtype];
+    if(!T) throw new Error('Error in dtype: "' + dtype + '"');
+    var BYTES_PER_ELEMENT = T.BYTES_PER_ELEMENT;
+
+    var buffer = v.bdata;
+    if(!isArrayBuffer(buffer)) {
+        buffer = b64decode(buffer);
+    }
+    var shape = v.shape === undefined ?
+        // detect 1-d length
+        [buffer.byteLength / BYTES_PER_ELEMENT] :
+        // convert number to string and split to array
+        ('' + v.shape).split(',');
+
+    shape.reverse(); // i.e. to match numpy order
+    var ndim = shape.length;
+
+    var nj, j;
+    var ni = +shape[0];
+
+    var rowBytes = BYTES_PER_ELEMENT * ni;
+    var pos = 0;
+
+    if(ndim === 1) {
+        out = new T(buffer);
+    } else if(ndim === 2) {
+        nj = +shape[1];
+        for(j = 0; j < nj; j++) {
+            out[j] = new T(buffer, pos, ni);
+            pos += rowBytes;
+        }
+    } else if(ndim === 3) {
+        nj = +shape[1];
+        var nk = +shape[2];
+        for(var k = 0; k < nk; k++) {
+            out[k] = [];
+            for(j = 0; j < nj; j++) {
+                out[k][j] = new T(buffer, pos, ni);
+                pos += rowBytes;
+            }
+        }
+    } else {
+        throw new Error('ndim: ' + ndim + 'is not supported with the shape:"' + v.shape + '"');
+    }
+
+    // attach bdata, dtype & shape to array for json export
+    out.bdata = v.bdata;
+    out.dtype = v.dtype;
+    out.shape = shape.reverse().join(',');
+
+    vIn._inputArray = out;
+
+    return out;
+};
+
+exports.isTypedArraySpec = function(v) {
+    return (
+        isPlainObject(v) &&
+        v.hasOwnProperty('dtype') && (typeof v.dtype === 'string') &&
+
+        v.hasOwnProperty('bdata') && (typeof v.bdata === 'string' || isArrayBuffer(v.bdata)) &&
+
+        (v.shape === undefined || (
+            v.hasOwnProperty('shape') && (typeof v.shape === 'string' || typeof v.shape === 'number')
+        ))
+    );
+};
+
+function coerceTypedArraySpec(v) {
+    return {
+        bdata: v.bdata,
+        dtype: v.dtype,
+        shape: v.shape
+    };
+}
+
 /*
  * TypedArray-compatible concatenation of n arrays
  * if all arrays are the same type it will preserve that type,

src/lib/coerce.js

@@ -12,21 +12,38 @@ var nestedProperty = require('./nested_property');
 var counterRegex = require('./regex').counter;
 var modHalf = require('./mod').modHalf;
 var isArrayOrTypedArray = require('./array').isArrayOrTypedArray;
+var isTypedArraySpec = require('./array').isTypedArraySpec;
+var decodeTypedArraySpec = require('./array').decodeTypedArraySpec;
 
 exports.valObjectMeta = {
     data_array: {
         // You can use *dflt=[] to force said array to exist though.
         description: [
             'An {array} of data.',
-            'The value MUST be an {array}, or we ignore it.',
-            'Note that typed arrays (e.g. Float32Array) are supported.'
+            'The value must represent an {array} or it will be ignored,',
+            'but this array can be provided in several forms:',
+            '(1) a regular {array} object',
+            '(2) a typed array (e.g. Float32Array)',
+            '(3) an object with keys dtype, bdata, and optionally shape.',
+            'In this 3rd form, dtype is one of *i1*, *u1*, *c1*,',
+            '*i2*, *u2*, *i4*, *u4*, *f4*, or *f8*.',
+            '`bdata` is either a base64-encoded string or the ArrayBuffer of',
+            'an integer or float typed array.',
+            'For either multi-dimensional arrays you must also',
+            'provide its dimensions separated by comma via `shape`.',
+            'For exmaple using `dtype`: *f4* and `shape`: *5,100* you can',
+            'declare a 2-D array that has 5 rows and 100 columns',
+            'containing float32 values i.e. 4 bits per value.',
+            '`shape` is optional for one dimensional arrays.'
         ].join(' '),
         requiredOpts: [],
         otherOpts: ['dflt'],
         coerceFunction: function(v, propOut, dflt) {
-            // TODO maybe `v: {type: 'float32', vals: [/* ... */]}` also
-            if(isArrayOrTypedArray(v)) propOut.set(v);
-            else if(dflt !== undefined) propOut.set(dflt);
+            propOut.set(
+                isArrayOrTypedArray(v) ? v :
+                isTypedArraySpec(v) ? decodeTypedArraySpec(v) :
+                dflt
+            );
         }
     },
     enumerated: {
@@ -368,15 +385,24 @@ exports.coerce = function(containerIn, containerOut, attributes, attribute, dflt
 
     if(dflt === undefined) dflt = opts.dflt;
 
-    /**
-     * arrayOk: value MAY be an array, then we do no value checking
-     * at this point, because it can be more complicated than the
-     * individual form (eg. some array vals can be numbers, even if the
-     * single values must be color strings)
-     */
-    if(opts.arrayOk && isArrayOrTypedArray(v)) {
-        propOut.set(v);
-        return v;
+    if(opts.arrayOk) {
+        if(isArrayOrTypedArray(v)) {
+            /**
+             * arrayOk: value MAY be an array, then we do no value checking
+             * at this point, because it can be more complicated than the
+             * individual form (eg. some array vals can be numbers, even if the
+             * single values must be color strings)
+             */
+
+            propOut.set(v);
+            return v;
+        } else {
+            if(isTypedArraySpec(v)) {
+                v = decodeTypedArraySpec(v);
+                propOut.set(v);
+                return v;
+            }
+        }
     }
 
     var coerceFunction = exports.valObjectMeta[opts.valType].coerceFunction;

src/lib/gl_format_color.js

@@ -31,6 +31,8 @@ function validateOpacity(opacityIn) {
 
 function formatColor(containerIn, opacityIn, len) {
     var colorIn = containerIn.color;
+    if(colorIn && colorIn._inputArray) colorIn = colorIn._inputArray;
+
     var isArrayColorIn = isArrayOrTypedArray(colorIn);
     var isArrayOpacityIn = isArrayOrTypedArray(opacityIn);
     var cOpts = Colorscale.extractOpts(containerIn);

src/lib/index.js

@@ -62,6 +62,7 @@ lib.toLogRange = require('./to_log_range');
 lib.relinkPrivateKeys = require('./relink_private');
 
 var arrayModule = require('./array');
+lib.isArrayBuffer = arrayModule.isArrayBuffer;
 lib.isTypedArray = arrayModule.isTypedArray;
 lib.isArrayOrTypedArray = arrayModule.isArrayOrTypedArray;
 lib.isArray1D = arrayModule.isArray1D;