# 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 or a table 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 or table 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.

## 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.