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