arrayindex, arrayindex_b

These functions return the linear index of multi-dimensional coordinates in a multi-dimensional array. All coordinates must be integral values. This is the inverse of arraycoord, which converts an index to a coordinate array.

The arrayindex function does not check that the coordinates are inside the bounds of the array.

The arrayindex_b function checks that the coordinate bounds are greater than 0 and that the returned index is within the array.

Syntax

nIndex = arrayindex( Axis_Array, Coord_Array )

bullet.gif    where Axis_Array is a lua table containing the array dimensions, starting from the most rapidly varying index in element [1].

bullet.gif    Coord_Array is an n-dimensional array containing coordinates.

bullet.gif    nIndex is the linear index into the array.

bullet.gif    On failure, 0 is returned.

Remarks

Multi-dimensional arrays are stored from the lowest dimension to the highest. For example, a 3 dimensional array is stored according to column number, followed by row number, followed by plane number. Stated another way, it is a series of p planes each plane containing n rows, each row containing m columns. An array (or lua table) element is accessed in the same order: if x is a table, then an array element is accessed as x[p][n][m] The first element at coordinate [1][1][1] has linear offset 1. The axis dimensions must be known to calculate the linear offset of any element beyond the first. This is the function of the Axis_Array parameter.

Checking the coordinates and array bounds causes arrayindex_b to execute around 70 -- 80% as fast as arrayindex. On one test machine, finding the coordinate index into a 3 dimensional array, arrayindex processed 8.1 million calls per second while arrayindex_b processed 6.8 million calls per second. It is often best to check coordinates in the calling script and call the faster function.

Examples

The following script shows several cases of returning the linear index into a coordinate array.

axis = { 512, 1024, 2}

-- array containing the axis lengths

x = { 125, 40, 2 }

-- array containing the coordinate vector x

n = arrayindex( axis, x )

-- return the linear index for coordinates x

Printf("n = %d\n", n)

-- result: n = 544391

 

 

axis = { 512, 1024, 2}

-- array containing the axis lengths

x = { 125, 40, 1 }

-- array containing the coordinate vector x

n = arrayindex( axis, x )

-- return the linear index for coordinates x

Printf("n = %d\n", n)

-- result: n = 20093

 

 

x = { 125, 40 }

-- skipping highest dimension for plane 1

n = arrayindex( axis, x )

-- return the linear index for coordinates x

Printf("n = %d\n", n)

-- result: n = 20093

 

 

axis = { 512, 1024, 8, 4, 2 }

-- array containing the axis lengths

x = { 125, 40, 4, 1 }

-- array containing the coordinate vector x

n = arrayindex( axis, x )

-- return the linear index for coordinates x

Printf("n = %d\n", n)

-- result: n = 1592957

Related Topics

Array Functions

arraycoord


Mira Pro x64 Script User's Guide, v.8.77 Copyright Ⓒ 2024 Mirametrics, Inc. All Rights Reserved.