array-kit 0.2.11 → 0.2.13

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
@@ -86,14 +86,21 @@ function NDArray( dataOrConstructor , sizes , params ) {
 	// Define the layout of the array in memory, strides are products of all faster dimensions
 	this.strides = new Array( dimensions ) ;
 
+	// Use to speed up the whole array iteration
+	this.backStrides = new Array( dimensions ) ;
+
 	// 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 ) {
@@ -128,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 ;
@@ -140,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 {
@@ -161,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 ] ;
@@ -200,13 +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 ;
-		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 ;
@@ -225,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 ;
@@ -240,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 ) ;
+} ;
 
 
 
@@ -283,6 +356,7 @@ NDArray.prototype.flip = function( dimension ) {
 	}
 
 	this.strides[ dimension ] *= - 1 ;
+	this.backStrides[ dimension ] *= - 1 ;
 	this._initOffsetEndFromStartSizesStrides() ;
 
 	return this ;
@@ -290,16 +364,78 @@ NDArray.prototype.flip = function( dimension ) {
 
 // Flip coordinates along all dimensions at once, but preserving min and max
 NDArray.prototype.flipAll = function() {
-	for ( let d = 0 ; d < this.dimensions ; d ++ ) { this.strides[ d ] *= - 1 ; }
+	for ( let d = 0 ; d < this.dimensions ; d ++ ) {
+		this.strides[ d ] *= - 1 ;
+		this.backStrides[ d ] *= - 1 ;
+	}
+
 	this._initOffsetEndFromStartSizesStrides() ;
 	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._cloneGeometry( true ) ;
+	newNDArray.data = this.data ;
+	return newNDArray ;
+} ;
+
+
+
+// Full clone
+NDArray.prototype.clone = function() {
+	const newNDArray = this._cloneGeometry() ;
+	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._cloneGeometry = function( keepDataStart = false ) {
 	const newNDArray = new NDArray( this.dimensions ) ;
 
 	// Copy geometry
@@ -309,10 +445,18 @@ NDArray.prototype._cloneGeometry = function() {
 	Object.assign( newNDArray.mins , this.mins ) ;
 	Object.assign( newNDArray.maxs , this.maxs ) ;
 	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 ;
 } ;
@@ -325,7 +469,7 @@ NDArray.prototype._resizeGeometry = function( mins , maxs ) {
 
 	Object.assign( newNDArray.order , this.order ) ;
 	newNDArray._initSizesFromMinsMaxs( mins , maxs ) ;
-	newNDArray._initStridesUsingSizes() ;
+	newNDArray._initStridesFromSizes() ;
 	newNDArray._initOffsetEndFromStartSizesStrides() ;
 
 	return newNDArray ;
@@ -333,24 +477,11 @@ 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 ]
 NDArray.prototype._getIndex = function( coords ) {
 	let index = this.offset ;
-	//for ( const d of this.order ) { index += ( coords[ d ] - this.mins[ d ] ) * this.strides[ d ] ; }
 	for ( let d = 0 ; d < this.dimensions ; d ++ ) { index += ( coords[ d ] - this.mins[ d ] ) * this.strides[ d ] ; }
 	return index ;
 } ;
@@ -358,7 +489,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 ] ;
 
@@ -537,31 +667,7 @@ NDArray.prototype._getStrideStartAndVectorDimension = function( coords ) {
 */
 NDArray.prototype.forEach =
 NDArray.prototype._forEach = function( callback ) {
-	// Usually =1, but later we could group neighbours (e.g. for RGBA images => stride0 = 4)
-	const stride0 = this.strides[ this.order[ 0 ] ] ;
-	const coords = Array.from( this.mins ) ;
-	let index = this.dataStart ;
-
-	for ( ;; ) {
-		callback( this.data[ index ] , coords , index , this ) ;
-
-		index += stride0 ;
-		if ( index >= this.dataEnd ) { return ; }
-
-		for ( let i = 0 ; i < this.dimensions ; i ++ ) {
-			const d = this.order[ i ] ;
-			coords[ d ] ++ ;
-			if (
-				i < this.dimensions - 1
-				&& coords[ d ] - this.mins[ d ] >= this.strides[ this.order[ i + 1 ] ]
-			) {
-				coords[ d ] = this.mins[ d ] ;
-			}
-			else {
-				break ;
-			}
-		}
-	}
+	return this._forEachInRegion( this.mins , this.maxs , callback , true ) ;
 } ;
 
 
@@ -597,10 +703,19 @@ NDArray.prototype._forEachInRegionCheck = function( mins , maxs , callback ) {
 	this._forEachInRegion( mins , maxs , callback ) ;
 } ;
 
-NDArray.prototype._forEachInRegion = function( mins , maxs , callback ) {
-	const backStrides = mins.map( ( min , d ) => ( min - maxs[ d ] ) * this.strides[ d ] ) ;
+// wholeArray=true when coming from ._forEach()
+NDArray.prototype._forEachInRegion = function( mins , maxs , callback , wholeArray = false ) {
+	let backStrides , index ;
 	const coords = Array.from( mins ) ;
-	let index = this._getIndex( coords ) ;
+
+	if ( wholeArray ) {
+		backStrides = this.backStrides ;
+		index = this.offset ;
+	}
+	else {
+		backStrides = mins.map( ( min , d ) => ( min - maxs[ d ] ) * this.strides[ d ] ) ;
+		index = this._getIndex( coords ) ;
+	}
 
 	for ( ;; ) {
 		callback( this.data[ index ] , coords , index , this ) ;
@@ -677,6 +792,13 @@ NDArray.prototype._forEachVectorInRegion = function( strideStartCoords , maxs ,
 
 
 
+// Return a Generator
+// .each()
+NDArray.prototype.each =
+NDArray.prototype._each = function() {
+	return this._eachInRegion( this.mins , this.maxs , true ) ;
+} ;
+
 // Return a Generator
 // .eachInRegion( region )
 // .eachInRegion( mins , maxs )
@@ -696,10 +818,20 @@ NDArray.prototype._eachInRegionCheck = function( mins , maxs ) {
 
 // Generator
 // The yielded entry { coords , index , value } should be cloned, as well as entry.coords, if userland want to modify it
-NDArray.prototype._eachInRegion = function*( mins , maxs ) {
-	const backStrides = mins.map( ( min , d ) => ( min - maxs[ d ] ) * this.strides[ d ] ) ;
+// wholeArray=true when coming from ._each()
+NDArray.prototype._eachInRegion = function*( mins , maxs , wholeArray = false ) {
+	let backStrides , index ;
 	const coords = Array.from( mins ) ;
-	let index = this._getIndex( coords ) ;
+
+	if ( wholeArray ) {
+		backStrides = this.backStrides ;
+		index = this.offset ;
+	}
+	else {
+		backStrides = mins.map( ( min , d ) => ( min - maxs[ d ] ) * this.strides[ d ] ) ;
+		index = this._getIndex( coords ) ;
+	}
+
 	const entry = { coords , index , value: undefined } ;
 
 	for ( ;; ) {
@@ -931,8 +1063,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 ;
 } ;
 

package/package.json

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