# Begin iterate๐

A starting point for a part of a processing graph that needs to be repeated multiple times with different parameters. This tool takes in a matrix, a table or an array that it splits into smaller blocks, producing a variable number of outputs depending on the size of the input.

A typical use case for iteration is to repeat the same analysis
steps for a variable number of detected objects, such as blobs. For example, its *iterable* input can be
connected to the *frame* output of blob geometry analysis. In this case, *blockSize* would be need
to be set to four. The *element* output can then be connected for
example to script to analyze each frame
separately.

Another use case that involves variable block sizes is boundary detection. Connecting its
*blockSize* output to the *blockSize* input of this tool produces
output matrices with a variable number of rows.

If multiple iterable inputs are provided, the tool first inspects
which has the minimum number rows. *blockSize* refers to this
matrix/table, and the row count in the other inputs must be the
same as the minimum or a multiple of it. The tool then adapts the
block size to each of the other matrices accordingly. For example,
if *blockSize* is 1, *iterable0* is a matrix with 10 rows and
*iterable1* is a matrix with 40 rows, the resulting block size will
be one for *element0* and four for *element1*.

Note that โiterationโ on the VisionAppster platform does not mean sequential processing. Unless the tools that follow are forced to sequential mode (by enabling state in a script, for example), iterations may be executed simultaneously or even out of order. The platform however ensures that the final output parameters will be sent in the correct order.

At the end of an iteration, collecting the results back to a matrix/table may be required for subsequent analysis.

## Inputs๐

`iterableX`

: A matrix, a table or an array to be split into smaller pieces. X ranges from 0 to*dynamicInputCount*- 1.`blockSize`

: The number of rows in each output block. If this parameter is not connected, its value will be used as a fixed block size. If it is connected, the input may be either an integer constant specifying the number of rows in each output matrix/table, or a matrix specifying a variable number of rows for the output matrices/tables. In the latter case, the number of rows in the*blockSize*matrix determines the number of output elements. If*blockSize*is set to zero, the tool tries to automatically deduce a suitable block size based on connected inputs.`column`

: Setting*column*to a non-negative value makes the tool to send the matrix/table element on the specified column (zero-based index) instead of the whole row. An array is a one dimensional object so*column*cannot be greater than zero.

## Outputs๐

`sync`

: Emits`true`

before the start of each loop. This output is usually connected to the*sync*input of an end iterate tool.`elementX`

: A variable number of sub-matrices, sub-tables or individual matrix/table elements.