Wondering what’s next for npm?Check out our public roadmap! »

    multi-array-view
    TypeScript icon, indicating that this package has built-in type declarations

    0.1.5 • Public • Published

    MultiArrayView NPM Build Status

    A small JavaScript library for efficient work with multidimensional arrays.

    When working with a large data, (for example, in 3d-graphics), working with nested arrays in JavaScript can affect the performance of the code. The more productive analogy of nested arrays is strided arrays—multidimensional data placed in the plane of a one-dimensional array. Unfortunately, working with strided arrays can lead to code repetition, complex operations, and syntactic noise in the code. The MultiArrayView library serves to simplify the work with strided arrays as if it were an ordinary multidimensional array.

    A simple 3x3 matrix:

    const array = [
      [0, 0, 0],
      [0, 0, 0],
      [0, 0, 1]
    ]
     
    const item = arr[2][2] // 1

    And a similar 3x3 matrix in the form of a one-dimensional strided array wrapped in MultiArrayView:

    const array = [
      0, 0, 0,
      0, 0, 0,
      0, 0, 1
    ]
     
    // Wrapping the strided array
    const multiArray = MultiArrayView.wrap(arr, [3, 3])
     
    const unit = multiArray.get(2, 2) // 1

    Getting Started

    Installation using npm:

    $ npm install multi-array-view
    

    Or using yarn:

    $ yarn add multi-array-view
    

    Usage

    You can import the package in your node.js-project the following way:

    const MultiArrayView = require('multi-array-view')

    If your project has ES6 or TypeScript support, use the following import method. The MultiArrayView has full typing support.

    import MultiArrayView from 'multi-array-view'

    API reference

    Static methods

    MultiArrayView.create(shape[, constructor, offset, order])

    Creates a new array using the specified constructor. If the constructor is not specified, the Array is used as the constructor. Returns instance of MultiArrayView class.

    • shape
      List of array dimensions.

    • constructor Optional
      Constructor for creating the source one-dimensional array.
      Defaults to Array.

    • offset Optional
      The starting offset of the array view.
      Defaults to 0.

    • order Optional
      Ordering method for storing data. See ordering methods section for more information.
      Available values:

      • MultiArray.C_ORDER — Row-major order (C-style)
      • MultiArray.F_ORDER — Column-major (Fortran-style)

    A minimal example

    // Creates empty 4x4 matrix
    const multiArray = MultiArrayView.create([4, 4])
     
    console.log(multiArray.array) // (16) [empty × 16] 
     

    With specified constructor and offset

    const multiArray = MultiArrayView.create([4, 4], Uint8Array, 2)
     
    console.log(multiArray.array)
    // Uint8Array(18) [
    //   0, 0,          <— 2 offsetted items
    //   0, 0, 0, 0,    <— matrix start
    //   0, 0, 0, 0,
    //   0, 0, 0, 0,
    //   0, 0, 0, 0
    // ]

    MultiArrayView.wrap(array, shape[, offset, order])

    Wraps the readymade strided array in the MultiArrayView class for multi-dimensional viewing. Returns instance of MultiArrayView class.

    • array
      The 1d array to wrap.

    • shape
      List of array dimensions.

    • offset Optional
      The starting offset of the array view.
      Defaults to 0.

    • order Optional
      Ordering method for storing data. See ordering methods section for more information.
      Available values:

      • MultiArray.C_ORDER — Row-major order (C-style)
      • MultiArray.F_ORDER — Column-major (Fortran-style)

    Simple example

    const shape = [128, 256, 512]
    const length = shape.reduce((a, b) => a * b) // Calculation the length of the array
    const typedArray = new Int32Array(length) 
     
    // Wrapping the array
    const multiArray = MultiArrayView.wrap(typedArray, shape) 
     
    console.log(multiArray.array) // Int32Array(16777216) [0, 0, 0, 0, 0, ...

    Instance methods

    .get(x1 [, x2, ..., xN])

    Returns the value of the item by the specified path.

    • x1 ... xN
      List of indices for each dimension to obtain an item. The same as indices in a simple multidimensional array.

    .set(value, x1 [, x2, ..., xN])

    Sets the item value by the specified path.

    • value
      The value to set

    • x1 ... xN
      List of indices for each dimension to set a value to the item. The same as indices in a simple multidimensional array.

    Example

    const multiArray = MultiArrayView.create([100, 100])
     
    const value = 1337
    multiArray.set(value, 90, 10)
     
    console.log(multiArray.get(90, 10)) // 1337

    .getIndex(x1 [, x2, ..., xN])

    Returns the real index of source array by the specified path.

    • x1 ... xN
      List of indices for each dimension to get the real index. The same as indices in a simple multidimensional array.

    .array

    The source array.

    .shape

    Shape of the array that was putted when the MultiArrayView instance was created.

    .length

    Length of the source array computed by the shape.

    Ordering methods

    Image from wikipedia

    There are two values for the sorting method:

    • MultiArray.C_ORDER — Row-major order (C-style)
    • MultiArray.F_ORDER — Column-major (Fortran-style)

    They differ in the way of storing data in the source array.

    Simple 3x3 matrix:

    const matrix3x3 = [
      [1, 2, 3],
      [4, 5, 6],
      [7, 8, 9],
    ]

    And flat representation of the matrix above after applying different-ordered arrays:

    // Default row-major ordered array
    const cOrdered = MultiArrayView.create([3, 3], Uint8Array, 0, MultiArrayView.C_ORDER)
     
    // Column-major ordered array
    const fOrdered = MultiArrayView.create([3, 3], Uint8Array, 0, MultiArrayView.F_ORDER)
     
    // Applying matrix to arrays
    for (let x = 0; x < matrix3x3.length; x++) {
      for (let y = 0; y < matrix3x3[x].length; y++) {
        const value = matrix3x3[x][y]
        
        cOrdered.set(value, x, y)
        fOrdered.set(value, x, y)
      }
    }
     
    // Row-major source array representation
    console.log(cOrdered.array)
    // [1, 2, 3, 4, 5, 6, 7, 8, 9]
     
     
    // Column-major source array representation
    console.log(fOrdered.array)
    // [1, 4, 7, 2, 5, 8, 3, 6, 9]

    Install

    npm i multi-array-view

    DownloadsWeekly Downloads

    0

    Version

    0.1.5

    License

    MIT

    Unpacked Size

    31.9 kB

    Total Files

    13

    Last publish

    Collaborators

    • avatar