array-kit 0.2.12 → 0.2.14

package/lib/NDArray.js

@@ -42,10 +42,10 @@
 		params: an object of optional parameters, where:
 			order: array of coord order stored in the storage, by default [ 0 , 1 , 2 , ..., N ], for 2D it's row-first,
 			  if you want column-first, use [ 1 , 0 ], or params.reverse = true
-			reverse: syntactic sugar, like params.order = [ N , ... , 2 , 1 , 0 ]
+			reverse: syntactic sugar, like params.order = [ N , ... , 2 , 1 , 0 ], means that the slowest moving dimension comes first
 			dataStart: the index in the data storage where the ND-array starts (e.g. the start of the view in the Buffer)
-			stride: (default: 1) the stride of the fastest moving dimension, usually 1 except if there is more dimensions fastest
-			  dimensions that are removed from the view
+			stride: (default: 1) the stride of the fastest moving dimension, usually 1 except if there is faster dimensions
+			  that are removed from the view
 
 		Not added yet:
 			offset: the offset of the first logical element of the ND-array
@@ -92,11 +92,15 @@ function NDArray( dataOrConstructor , sizes , params ) {
 	// This is the index of the first logical element in the physical data storage
 	this.offset = 0 ;
 
+	// True if the physical backend is contiguous, that can speed up some operation like .fill()
+	this.isContiguous = true ;
+
 	// This is physical start and end of the ND-array in the data storage
 	this.dataStart = 0 ;
 	this.dataEnd = 0 ;
 
-	// The underlying data store: Array, TypedArray, Buffer... anything that is indexed
+	// The underlying physical data store backend.
+	// Can be: Array, TypedArray, Buffer... anything that is indexed.
 	this.data = null ;
 
 	if ( ! noInit ) {
@@ -131,7 +135,7 @@ NDArray.prototype._init = function( dataOrConstructor , sizes , params = {} ) {
 	}
 
 	// Compute the stride
-	this._initStridesUsingSizes( params.stride ) ;
+	this._initStridesFromSizes( params.stride ) ;
 
 	// The index where the ND-array region starts
 	this.dataStart = params.dataStart || 0 ;
@@ -143,7 +147,7 @@ NDArray.prototype._init = function( dataOrConstructor , sizes , params = {} ) {
 	// Set or create a new data store
 	if ( typeof dataOrConstructor === 'function' ) {
 		if ( typeof dataOrConstructor.allocUnsafe === 'function' ) {
-			// Detect Node.js's Buffer referencing it (avoid browser compatibility layer)
+			// Detect Node.js's Buffer without referencing it (avoid browser compatibility layer)
 			this.data = dataOrConstructor.allocUnsafe( this.dataEnd ) ;
 		}
 		else {
@@ -164,6 +168,8 @@ NDArray.prototype._init = function( dataOrConstructor , sizes , params = {} ) {
 // Fragmented init, because it can be re-use by various cloning things
 
 NDArray.prototype._initMinsMaxsSizesFromRegion = function( region ) {
+	this.size = 1 ;
+
 	for ( let d = 0 ; d < this.dimensions ; d ++ ) {
 		this.mins[ d ] = region[ d ][ 0 ] ;
 		this.maxs[ d ] = region[ d ][ 1 ] ;
@@ -203,14 +209,23 @@ NDArray.prototype._initMinsMaxsFromSizes = function( sizes ) {
 } ;
 
 // Sizes is not passed as argument, it should already be computed on the instance
-NDArray.prototype._initStridesUsingSizes = function( stride = 1 ) {
+NDArray.prototype._initStridesFromSizes = function( nextStride = 1 ) {
+	// It's always contiguous when strides start at 1
+	this.isContiguous = nextStride === 1 ;
+
 	for ( const d of this.order ) {
-		this.strides[ d ] = stride ;
-		this.backStrides[ d ] = ( 1 - this.sizes[ d ] ) * stride ;
-		stride *= this.sizes[ d ] ;
+		this.strides[ d ] = nextStride ;
+		this.backStrides[ d ] = ( 1 - this.sizes[ d ] ) * nextStride ;
+		nextStride *= this.sizes[ d ] ;
 	}
 } ;
 
+// Strides is not passed as argument, it should already be computed on the instance
+NDArray.prototype._initOrderFromStrides = function() {
+	this.order = Array.from( { length: this.strides.length } , ( v , i ) => i ) ;
+	this.order.sort( ( a , b ) => this.strides[ a ] - this.strides[ b ] ) ;
+} ;
+
 // Offset, sizes and strides are not passed as argument, they should already be computed on the instance
 NDArray.prototype._initOffsetEndFromStartSizesStrides = function() {
 	this.dataEnd = this.dataStart + 1 ;
@@ -229,7 +244,6 @@ NDArray.prototype._initOffsetEndFromStartSizesStrides = function() {
 	}
 } ;
 
-/*	Not sure if it's useful to compute based on offset
 // Offset, sizes and strides are not passed as argument, they should already be computed on the instance
 NDArray.prototype._initStartEndFromOffsetSizesStrides = function() {
 	this.dataStart = this.offset ;
@@ -244,7 +258,62 @@ NDArray.prototype._initStartEndFromOffsetSizesStrides = function() {
 		}
 	}
 } ;
-*/
+
+// Init .isContiguous based on strides and sizes.
+// Usually only called for views, because if ._initStridesFromSizes() is called it already set it to the right value.
+NDArray.prototype._initIsContiguousFromStridesSizes = function() {
+	let nextStride = 1 ;
+
+	for ( const d of this.order ) {
+		const absStride = Math.abs( this.strides[ d ] ) ;
+
+		if ( absStride !== nextStride ) {
+			this.isContiguous = false ;
+			return ;
+		}
+
+		nextStride *= absStride ;
+	}
+
+	this.isContiguous = true ;
+} ;
+
+
+
+// Create a new data back-end from another one
+// sliceStart and sliceEnd are optional
+NDArray.prototype._createDataFrom = function( data , sliceStart = 0 , sliceEnd = data.length ) {
+	if ( Array.isArray( data ) ) {
+		this.data = data.slice( sliceStart , sliceEnd ) ;
+	}
+	else if ( typeof data.constructor.allocUnsafe === 'function' ) {
+		// Detect Node.js's Buffer without referencing it (avoid browser compatibility layer)
+		this.data = data.constructor.allocUnsafe( sliceEnd - sliceStart ) ;
+		data.copy( this.data , 0 , sliceStart , sliceEnd ) ;
+	}
+	else if ( typeof data.slice === 'function' ) {
+		this.data = data.slice( sliceStart , sliceEnd ) ;
+	}
+	else {
+		this.data = new data.constructor( data.length ) ;
+
+		for ( let src = sliceStart , dst = 0 ; src < sliceEnd ; src ++ , dst ++ ) {
+			this.data[ dst ] = data[ src ] ;
+		}
+	}
+} ;
+
+
+
+// Create a new data store of the same type
+NDArray.prototype._newStorageOfTheSameKind = function( size = this.dataEnd - this.dataStart ) {
+	if ( typeof this.data?.constructor?.allocUnsafe === 'function' ) {
+		// Detect Node.js's Buffer referencing it (avoid browser compatibility layer)
+		return this.data.constructor.allocUnsafe( size ) ;
+	}
+
+	return new this.data.constructor( size ) ;
+} ;
 
 
 
@@ -306,9 +375,100 @@ NDArray.prototype.flipAll = function() {
 
 
 
+// Transpose: swap coordinates orders
+NDArray.prototype.transpose = function( ... dimensionList ) {
+	// It's not possible to swap because each dimension look up for the source at its original place
+	const dMax = Math.min( dimensionList.length , this.dimensions ) ,
+		sizes = new Array( this.dimensions ) ,
+		mins = new Array( this.dimensions ) ,
+		maxs = new Array( this.dimensions ) ,
+		order = new Array( this.dimensions ) ,
+		strides = new Array( this.dimensions ) ,
+		backStrides = new Array( this.dimensions ) ;
+
+	for ( let d = 0 ; d < dMax ; d ++ ) {
+		const fromD = dimensionList[ d ] ;
+		sizes[ d ] = this.sizes[ fromD ] ;
+		mins[ d ] = this.mins[ fromD ] ;
+		maxs[ d ] = this.maxs[ fromD ] ;
+		order[ d ] = this.order[ fromD ] ;
+		strides[ d ] = this.strides[ fromD ] ;
+		backStrides[ d ] = this.backStrides[ fromD ] ;
+	}
+
+	this.sizes = sizes ;
+	this.mins = mins ;
+	this.maxs = maxs ;
+	this.order = order ;
+	this.strides = strides ;
+	this.backStrides = backStrides ;
+
+	return this ;
+} ;
+
+
+
+/*
+	Fix some axis and reduce the number of dimensions.
+	Like .pick() in the "ndarray" package.
+
+	Examples:
+		.select( null , 3 , null )		fix the second coordinate to 3, the ND-array will now have 2 dimensions instead of 3
+		.select( 1 , 3 , null )			fix the first and second coordinates respectively to 1 and 3, the ND-array will now have 1 dimensions instead of 3
+*/
+NDArray.prototype.select = function( ... coords ) {
+	this.size = 1 ;
+
+	// dimensions should be cached because it's modified along the way
+	for ( let d = 0 , newD = 0 , dimensions = this.dimensions ; d < dimensions ; d ++ ) {
+		const coord = coords[ d ] ;
+
+		if ( coord === null || coord === undefined ) {
+			this.size *= this.sizes[ newD ] ;
+			newD ++ ;
+		}
+		else {
+			this.offset += ( coord - this.mins[ newD ] ) * this.strides[ newD ] ;
+			this.sizes.splice( newD , 1 ) ;
+			this.mins.splice( newD , 1 ) ;
+			this.maxs.splice( newD , 1 ) ;
+			this.strides.splice( newD , 1 ) ;
+			this.backStrides.splice( newD , 1 ) ;
+			this.dimensions -- ;
+		}
+	}
+
+	this._initOrderFromStrides() ;
+	this._initStartEndFromOffsetSizesStrides() ;
+	this._initIsContiguousFromStridesSizes() ;
+
+	return this ;
+} ;
+
+
+
+// Clone only the view, the data storage is the same
+NDArray.prototype.cloneView =
+NDArray.prototype.view = function() {
+	const newNDArray = this._cloneLogical( true ) ;
+	newNDArray.data = this.data ;
+	return newNDArray ;
+} ;
+
+
+
+// Full clone
+NDArray.prototype.clone = function() {
+	const newNDArray = this._cloneLogical() ;
+	newNDArray._createDataFrom( this.data , this.dataStart , this.dataEnd ) ;
+	return newNDArray ;
+} ;
+
+
+
 // Create a new clone of the current NDArray with the same geometry but an empty (but ready) data
-// The new data is limited to the used size (dataStart = 0).
-NDArray.prototype._cloneGeometry = function() {
+// The new data is limited to the used size (dataStart = 0) except if keepDataStart is set to true.
+NDArray.prototype._cloneLogical = function( keepDataStart = false ) {
 	const newNDArray = new NDArray( this.dimensions ) ;
 
 	// Copy geometry
@@ -320,9 +480,16 @@ NDArray.prototype._cloneGeometry = function() {
 	Object.assign( newNDArray.strides , this.strides ) ;
 	Object.assign( newNDArray.backStrides , this.backStrides ) ;
 
-	// Start at index=0 in the physical storage
-	newNDArray.offset = this.offset - this.dataStart ;
-	newNDArray.dataEnd = this.dataEnd - this.dataStart ;
+	if ( keepDataStart ) {
+		newNDArray.dataStart = this.dataStart ;
+		newNDArray.dataEnd = this.dataEnd ;
+		newNDArray.offset = this.offset ;
+	}
+	else {
+		// Start at index=0 in the physical storage
+		newNDArray.offset = this.offset - this.dataStart ;
+		newNDArray.dataEnd = this.dataEnd - this.dataStart ;
+	}
 
 	return newNDArray ;
 } ;
@@ -330,12 +497,12 @@ NDArray.prototype._cloneGeometry = function() {
 
 
 // Clone with a modified geometry
-NDArray.prototype._resizeGeometry = function( mins , maxs ) {
+NDArray.prototype._resizeLogical = function( mins , maxs ) {
 	const newNDArray = new NDArray( this.dimensions ) ;
 
 	Object.assign( newNDArray.order , this.order ) ;
 	newNDArray._initSizesFromMinsMaxs( mins , maxs ) ;
-	newNDArray._initStridesUsingSizes() ;
+	newNDArray._initStridesFromSizes() ;
 	newNDArray._initOffsetEndFromStartSizesStrides() ;
 
 	return newNDArray ;
@@ -343,18 +510,6 @@ NDArray.prototype._resizeGeometry = function( mins , maxs ) {
 
 
 
-// Create a new data store of the same type
-NDArray.prototype._newStorageOfTheSameKind = function( size = this.dataEnd - this.dataStart ) {
-	if ( typeof this.data?.constructor?.allocUnsafe === 'function' ) {
-		// Detect Node.js's Buffer referencing it (avoid browser compatibility layer)
-		return this.data.constructor.allocUnsafe( size ) ;
-	}
-
-	return new this.data.constructor( size ) ;
-} ;
-
-
-
 // Internal version without any unnessessary test
 // Classic strided array access is:
 // index = coords[ 0 ] * strides[ 0 ] + coords[ 1 ] * strides[ 1 ] + ... + coords[ n ] * strides[ n ]
@@ -367,7 +522,6 @@ NDArray.prototype._getIndex = function( coords ) {
 NDArray.prototype._getIndexCheck = function( coords ) {
 	let index = this.offset ;
 
-	//for ( const d of this.order ) {
 	for ( let d = 0 ; d < this.dimensions ; d ++ ) {
 		const c = coords[ d ] ;
 
@@ -942,8 +1096,18 @@ NDArray.prototype._eachVectorIndexInRegionBackward = function*( strideStartCoord
 
 
 NDArray.prototype.fill = function( value ) {
-	const stride0 = this.strides[ this.order[ 0 ] ] ;
-	for ( let i = this.dataStart ; i < this.dataEnd ; i += stride0 ) { this.data[ i ] = value ; }
+	if ( this.isContiguous ) {
+		// Fast path: iterate directly on the physical data
+		for ( let i = this.dataStart ; i < this.dataEnd ; i ++ ) {
+			this.data[ i ] = value ;
+		}
+	}
+	else {
+		for ( const { index } of this._each() ) {
+			this.data[ index ] = value ;
+		}
+	}
+
 	return this ;
 } ;
 
@@ -983,7 +1147,7 @@ NDArray.prototype.fillVectorInRegion = function( mins , maxs , vector ) {
 	The classic .map(), returning a new ND-Array with its own data storage.
 */
 NDArray.prototype.map = function( callback ) {
-	const newNDArray = this._cloneGeometry() ;
+	const newNDArray = this._cloneLogical() ;
 	newNDArray.data = this._newStorageOfTheSameKind() ;
 
 	this._forEach( ( value , coords , index ) => {
@@ -1007,7 +1171,7 @@ NDArray.prototype.mapInRegion = function( mins , maxs , callback ) {
 	}
 
 	this._checkRegion( mins , maxs ) ;
-	const newNDArray = this._resizeGeometry( mins , maxs ) ;
+	const newNDArray = this._resizeLogical( mins , maxs ) ;
 	newNDArray.data = this._newStorageOfTheSameKind( newNDArray.dataEnd ) ;
 
 	this._dualStepCallback( newNDArray , mins , maxs , mins , maxs , callback ) ;
@@ -1038,7 +1202,7 @@ NDArray.prototype.mapVectorInRegion = function( mins , maxs , callback ) {
 	strideEndCoords[ vectorDimension ] = this.maxs[ vectorDimension ] ;
 
 	this._checkRegion( strideStartCoords , strideEndCoords , vectorDimension ) ;
-	const newNDArray = this._resizeGeometry( strideStartCoords , strideEndCoords ) ;
+	const newNDArray = this._resizeLogical( strideStartCoords , strideEndCoords ) ;
 	newNDArray.data = this._newStorageOfTheSameKind( newNDArray.dataEnd ) ;
 
 	this._dualStepVectorCallback( newNDArray , strideStartCoords , strideEndCoords , strideStartCoords , strideEndCoords , vectorDimension , callback ) ;
@@ -1123,7 +1287,7 @@ NDArray.prototype.extractRegion = function( mins , maxs ) {
 	}
 
 	this._checkRegion( mins , maxs ) ;
-	const newNDArray = this._resizeGeometry( mins , maxs ) ;
+	const newNDArray = this._resizeLogical( mins , maxs ) ;
 	newNDArray.data = this._newStorageOfTheSameKind( newNDArray.dataEnd ) ;
 
 	this._dualStepCopy( newNDArray , mins , maxs , mins , maxs ) ;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "array-kit",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "description": "An array manipulation toolbox.",
   "main": "lib/array-kit.js",
   "directories": {