array-kit 0.2.10 → 0.2.11

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,13 @@ 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
+	// 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 +130,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 ;
@@ -193,9 +207,44 @@ NDArray.prototype._initStridesUsingSizes = function( stride = 1 ) {
 	}
 } ;
 
+// 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 ;
 
-// Make the array zero-based, or based to the provided mins vector
+	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 on the provided mins vector
 NDArray.prototype.rebase = function( mins ) {
 	if ( mins ) {
 		for ( let d = 0 ; d < this.dimensions ; d ++ ) {
@@ -215,8 +264,41 @@ 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._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._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 ) ;
 
@@ -228,6 +310,10 @@ NDArray.prototype._cloneGeometry = function() {
 	Object.assign( newNDArray.maxs , this.maxs ) ;
 	Object.assign( newNDArray.strides , this.strides ) ;
 
+	// Start at index=0 in the physical storage
+	newNDArray.offset = this.offset - this.dataStart ;
+	newNDArray.dataEnd = this.dataEnd - this.dataStart ;
+
 	return newNDArray ;
 } ;
 
@@ -240,6 +326,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 +334,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 ) ;
@@ -308,8 +395,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 ) ;
@@ -453,14 +540,13 @@ 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 ;
+	let index = this.dataStart ;
 
 	for ( ;; ) {
 		callback( this.data[ index ] , coords , index , this ) ;
 
 		index += stride0 ;
-		if ( index >= dataEnd ) { return ; }
+		if ( index >= this.dataEnd ) { return ; }
 
 		for ( let i = 0 ; i < this.dimensions ; i ++ ) {
 			const d = this.order[ i ] ;
@@ -845,10 +931,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 +976,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 +997,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 +1028,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 +1113,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.11",
   "description": "An array manipulation toolbox.",
   "main": "lib/array-kit.js",
   "directories": {