array-kit 0.2.10 → 0.2.12

package/lib/NDArray.js

@@ -43,9 +43,13 @@
 			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 ]
-			offset: the offset if the ND-array does not start at the begining of the data storage (e.g. create a view of a Buffer)
+			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
+
+		Not added yet:
+			offset: the offset of the first logical element of the ND-array
+			dataEnd: the index in the data storage where the ND-array ends, excluded (e.g. the end of the view in the Buffer)
 */
 function NDArray( dataOrConstructor , sizes , params ) {
 	let dimensions , noInit = false ;
@@ -64,7 +68,9 @@ function NDArray( dataOrConstructor , sizes , params ) {
 	// Define the size in each axis
 	this.sizes = new Array( dimensions ) ;
 
-	// The full size of the ND-array, each axis-size multiplied
+	// The full logical size of the ND-array, each axis-size multiplied
+	// /!\ IT'S NOT THE PHYSICAL SIZE /!\
+	// See .dataStart and .dataEnd for that.
 	this.size = 1 ;
 
 	// Define the min for each axis, when the ND-array is not zero-based
@@ -80,9 +86,16 @@ 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 ) ;
 
-	// When the store is only partially used, this is the offset in the store natural index
+	// 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 ;
 
+	// 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
 	this.data = null ;
 
@@ -120,24 +133,28 @@ NDArray.prototype._init = function( dataOrConstructor , sizes , params = {} ) {
 	// Compute the stride
 	this._initStridesUsingSizes( params.stride ) ;
 
-	// Data store start and end
-	this.offset = params.offset || 0 ;
+	// The index where the ND-array region starts
+	this.dataStart = params.dataStart || 0 ;
+
+	// Compute data store start and end
+	//this._initStartEndFromOffsetSizesStrides() ;
+	this._initOffsetEndFromStartSizesStrides() ;
 
 	// 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)
-			this.data = dataOrConstructor.allocUnsafe( this.offset + this.size ) ;
+			this.data = dataOrConstructor.allocUnsafe( this.dataEnd ) ;
 		}
 		else {
-			this.data = new dataOrConstructor( this.offset + this.size ) ;
+			this.data = new dataOrConstructor( this.dataEnd ) ;
 		}
 	}
 	else {
 		/*
 		// Not sure it's good to check the length, since Array is extensible and only rarer TypedArray is fixed
-		if ( dataOrConstructor.length < this.offset + this.size ) {
-			throw new RangeError( "Provided data store is too small (expecting at least " + ( this.offset + this.size ) + " but got " + dataOrConstructor.length ) ;
+		if ( dataOrConstructor.length < this.dataEnd ) {
+			throw new RangeError( "Provided data store is too small (expecting at least " + this.dataEnd + " but got " + dataOrConstructor.length ) ;
 		}
 		*/
 		this.data = dataOrConstructor ;
@@ -189,13 +206,49 @@ NDArray.prototype._initMinsMaxsFromSizes = function( sizes ) {
 NDArray.prototype._initStridesUsingSizes = function( stride = 1 ) {
 	for ( const d of this.order ) {
 		this.strides[ d ] = stride ;
+		this.backStrides[ d ] = ( 1 - this.sizes[ d ] ) * stride ;
 		stride *= this.sizes[ d ] ;
 	}
 } ;
 
+// 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 ;
+	this.offset = this.dataStart ;
+
+	for ( let d = 0 ; d < this.dimensions ; d ++ ) {
+		const shift = this.strides[ d ] * ( this.sizes[ d ] - 1 ) ;
+
+		if ( shift >= 0 ) {
+			this.dataEnd += shift ;
+		}
+		else {
+			this.dataEnd -= shift ;
+			this.offset -= shift ;
+		}
+	}
+} ;
+
+/*	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 ;
+	this.dataEnd = this.offset + 1 ;
+
+	for ( const d of this.order ) {
+		if ( this.strides[ d ] >= 0 ) {
+			this.dataEnd += this.strides[ d ] * ( this.sizes[ d ] - 1 ) ;
+		}
+		else {
+			this.dataStart += this.strides[ d ] * ( this.sizes[ d ] - 1 ) ;
+		}
+	}
+} ;
+*/
+
 
 
-// Make the array zero-based, or based to the provided mins vector
+// Make the array zero-based, or based on the provided mins vector
 NDArray.prototype.rebase = function( mins ) {
 	if ( mins ) {
 		for ( let d = 0 ; d < this.dimensions ; d ++ ) {
@@ -215,8 +268,46 @@ NDArray.prototype.rebase = function( mins ) {
 
 
 
+// Translate, moving the coordinates of each value
+NDArray.prototype.translate = function( translation ) {
+	for ( let d = 0 ; d < this.dimensions ; d ++ ) {
+		this.mins[ d ] += translation[ d ] ;
+		this.maxs[ d ] += translation[ d ] ;
+	}
+
+	return this ;
+} ;
+
+
+
+// Flip coordinates along a dimension, but preserving min and max
+NDArray.prototype.flip = function( dimension ) {
+	if ( dimension < 0 || dimension >= this.dimensions ) {
+		throw new RangeError( "Bad dimension, should be between [0," + this.dimensions + ") but got: " + dimension ) ;
+	}
+
+	this.strides[ dimension ] *= - 1 ;
+	this.backStrides[ dimension ] *= - 1 ;
+	this._initOffsetEndFromStartSizesStrides() ;
+
+	return this ;
+} ;
+
+// 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 ;
+		this.backStrides[ d ] *= - 1 ;
+	}
+
+	this._initOffsetEndFromStartSizesStrides() ;
+	return this ;
+} ;
+
+
+
 // 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 (offset = 0).
+// The new data is limited to the used size (dataStart = 0).
 NDArray.prototype._cloneGeometry = function() {
 	const newNDArray = new NDArray( this.dimensions ) ;
 
@@ -227,6 +318,11 @@ 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 ;
 
 	return newNDArray ;
 } ;
@@ -240,6 +336,7 @@ NDArray.prototype._resizeGeometry = function( mins , maxs ) {
 	Object.assign( newNDArray.order , this.order ) ;
 	newNDArray._initSizesFromMinsMaxs( mins , maxs ) ;
 	newNDArray._initStridesUsingSizes() ;
+	newNDArray._initOffsetEndFromStartSizesStrides() ;
 
 	return newNDArray ;
 } ;
@@ -247,7 +344,7 @@ NDArray.prototype._resizeGeometry = function( mins , maxs ) {
 
 
 // Create a new data store of the same type
-NDArray.prototype._newStorageOfTheSameKind = function( size = this.size ) {
+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 ) ;
@@ -263,7 +360,6 @@ NDArray.prototype._newStorageOfTheSameKind = function( size = this.size ) {
 // 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 ;
 } ;
@@ -308,8 +404,8 @@ NDArray.prototype._getCoords = function( index , coords = new Array( this.dimens
 
 NDArray.prototype._getCoordsCheck =
 NDArray.prototype.getCoords = function( index , coords ) {
-	if ( index < this.offset || index >= this.offset + this.size ) {
-		throw new RangeError( "Index " + index + " out of bounds, which is [" + this.offset + "," + ( this.offset + this.size ) + ")" ) ;
+	if ( index < this.dataStart || index >= this.dataEnd ) {
+		throw new RangeError( "Index " + index + " out of bounds, which is [" + this.dataStart + "," + this.dataEnd + ")" ) ;
 	}
 
 	coords = coords ?? new Array( this.dimensions ) ;
@@ -450,32 +546,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 ) ;
-	const dataEnd = this.offset + this.size ;
-	let index = this.offset ;
-
-	for ( ;; ) {
-		callback( this.data[ index ] , coords , index , this ) ;
-
-		index += stride0 ;
-		if ( index >= 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 ) ;
 } ;
 
 
@@ -511,10 +582,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 ) ;
@@ -591,6 +671,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 )
@@ -610,10 +697,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 ( ;; ) {
@@ -845,10 +942,8 @@ NDArray.prototype._eachVectorIndexInRegionBackward = function*( strideStartCoord
 
 
 NDArray.prototype.fill = function( value ) {
-	for ( let i = this.offset , end = this.offset + this.size ; i < end ; i ++ ) {
-		this.data[ i ] = value ;
-	}
-
+	const stride0 = this.strides[ this.order[ 0 ] ] ;
+	for ( let i = this.dataStart ; i < this.dataEnd ; i += stride0 ) { this.data[ i ] = value ; }
 	return this ;
 } ;
 
@@ -892,7 +987,7 @@ NDArray.prototype.map = function( callback ) {
 	newNDArray.data = this._newStorageOfTheSameKind() ;
 
 	this._forEach( ( value , coords , index ) => {
-		newNDArray.data[ index - this.offset ] = callback( value , coords , index , this ) ;
+		newNDArray.data[ index - this.dataStart ] = callback( value , coords , index , this ) ;
 	} ) ;
 
 	return newNDArray ;
@@ -913,7 +1008,7 @@ NDArray.prototype.mapInRegion = function( mins , maxs , callback ) {
 
 	this._checkRegion( mins , maxs ) ;
 	const newNDArray = this._resizeGeometry( mins , maxs ) ;
-	newNDArray.data = this._newStorageOfTheSameKind( newNDArray.size ) ;
+	newNDArray.data = this._newStorageOfTheSameKind( newNDArray.dataEnd ) ;
 
 	this._dualStepCallback( newNDArray , mins , maxs , mins , maxs , callback ) ;
 
@@ -944,7 +1039,7 @@ NDArray.prototype.mapVectorInRegion = function( mins , maxs , callback ) {
 
 	this._checkRegion( strideStartCoords , strideEndCoords , vectorDimension ) ;
 	const newNDArray = this._resizeGeometry( strideStartCoords , strideEndCoords ) ;
-	newNDArray.data = this._newStorageOfTheSameKind( newNDArray.size ) ;
+	newNDArray.data = this._newStorageOfTheSameKind( newNDArray.dataEnd ) ;
 
 	this._dualStepVectorCallback( newNDArray , strideStartCoords , strideEndCoords , strideStartCoords , strideEndCoords , vectorDimension , callback ) ;
 
@@ -1029,7 +1124,7 @@ NDArray.prototype.extractRegion = function( mins , maxs ) {
 
 	this._checkRegion( mins , maxs ) ;
 	const newNDArray = this._resizeGeometry( mins , maxs ) ;
-	newNDArray.data = this._newStorageOfTheSameKind( newNDArray.size ) ;
+	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.10",
+  "version": "0.2.12",
   "description": "An array manipulation toolbox.",
   "main": "lib/array-kit.js",
   "directories": {