Collapse
CollapsingX
  • - or -

Array functions


Array functions are a powerful set of tools you can use to generate and modify arrays within an expression. An array function iterates through each element of the array (unless constrained to a subset of the array, as explained below). You can use array functions in an array's Set, Add, or Insert operation in the Store step.

As implied, array functions (for example, SELECT) are distinct from, and used with, array operations available in the Store step (for example, Set) to build an expression that generates or modifies an array's content.

You would typically use array functions to:

Optional parameters

Many array functions have optional parameters you can add to provide more flexibility. Some common parameter sets are:

  • FUNCTION(Array, StartIndex, Count). When you provide a start index and count, the function only executes over a subset of the given array, starting at the start index and including a number of elements equal to Count. An example of this can be found in the AVERAGE function.

  • FUNCTION(Array, Expression). When you include an expression, the function applies the expression to each of the elements in the array before executing its core function. An example of this can be found in the CUMULATIVESUM function.

  • FUNCTION(Array, Condition, MaxCount). You can use the condition parameter to consider only certain elements of the input array. The function iterates through each element to check whether it satisfies the specified condition. An example of this can be found in the SKIPWHILE function.

    The MaxCount parameter specifies the maximum number of elements to include in the function's output array. The function stops iterating through the input array once it reaches the specified number of output elements.

Nesting functions

To accomplish complex operations in a single expression, you can have functions within functions. This is sometimes referred to as nesting functions. For example, to retrieve the area of the largest blob in an image, you could use (nest) the functions ELEMENTAT and ORDERBYDESC:

ELEMENTAT(ORDERBYDESC(BlobAnalysis.BlobFound, Item.Area), 1)

Array function keywords

Keywords provide an easy way to reference array elements and other characteristics of the array on which the function is operating. There are 3 main keywords:

  • Index. Denotes the index of the array element on which the function is currently operating. This keyword is useful when the function has to evaluate an array element based on the value of its index. For example, for an array variable named myArray set to [2,5,99,17,30], the function TAKEWHILE(Variables.myArray, Index < 4) evaluates whether the index of each element is less than 4, and returns all the elements that meet the specified condition. Since the fourth element has index 4, the function stops checking and returns the first 3 elements of the array. The result is the array [2,5,99].

  • Item. References the value of the array element on which the function is currently operating. This keyword is useful when each value of the array has to be modified in the same manner, or when evaluating a condition against the value of each element. For example, in the function SELECT(BlobAnalysis.BlobFound, Item.Area), Item.Area accesses the Area property of each blob found with the BlobAnalysis step. The SELECT function then returns an array with the blobs' areas.

  • ItemCount. Denotes the number of elements in the source array. This is also useful when you need to retrieve the index of the last element of the array. For example, the function SUM(Variables.myArray, 1, ItemCount - 5) returns the sum of all elements in myArray except for the last 5.

The following keywords are for specific use with the FLATTEN function, which allows you to extract a sub-array of items from an object in an indexed collection of objects. For more information on sub-arrays, see the Sub-arrays subsection of the Using object arrays section earlier in this chapter. Sub-array keywords essentially have the same functionality as the above-mentioned keywords, except that they refer specifically to the sub-array:

  • SubIndex. Denotes the index of the sub-array element on which the function is currently operating.

  • SubItem. References the value of the sub-array element on which the function is currently operating.

  • SubItemCount. Denotes the number of elements within the sub-array currently being operated on.

Displaying and logging arrays

You can view the current value(s) of an array variable, as well as evaluate array expressions, by accessing the Quick Evaluate pane. For more information, see the Quick Evaluate pane section in the Panes and editors reference chapter.

The content of an array can also be converted into a string, using the ARRAYTOSTRING function, and then logged or displayed. The function optionally lets you specify a separator character to insert between elements, as well as a format to apply to numeric arrays (for example, percentage or number of decimal places to include).

You can also specify the display format interactively. To do so, right-click on the text box in the Advanced editor window. Click on Format... in the presented context menu. This opens the Customize Expression Format dialog, in which you can select a predefined format or specify a custom format.

Advanced examples

This section shows some examples on how to use arrays. For more information about array functions, refer to the Matrox Design Assistant Reference.

Using the array operator when quantizing results

Initializing an array using the array operator can be useful, for example, when quantizing (constraining) a set of results based on a specific property. Consider the following expression, which ranks a set of blobs by the size of their areas:

LOOKUP(SELECT(BlobAnalysis.BlobFound, Item.Area), [0,25,50,75,100], LessOrEqual, [extra-small, small, medium, large, extra-large])

In this example, the LOOKUP function's parameters are the following:

  • SourceArray = SELECT(BlobAnalysis.BlobFound, Item.Area)
  • PositionLookupArray = [0,25,50,75,100]
  • MatchType = LessOrEqual
  • ResultLookupArray = [extra-small, small, medium, large, extra-large]

The SELECT function returns an array with the areas of all the blobs found (for example, [32.5, 50.2, 14.3, 100.3, 75, 30.4]). For each blob area, the LOOKUP function establishes the index of the last value in the position-lookup array which is less than or equal to the blob area. Considering the first area (32.5): the last value that is less than or equal to 32.5 in the position-lookup array is 25. Since 25 is at index 2, 2 is used for the first element of the source array. Going through each area yields temporary array [2, 3, 1, 5, 4, 2].

Then, for each element of the temporary array, the LOOKUP function maps the element's value to an index of the result-lookup array, and returns the value at this index. The final result is [small, medium, extra-small, extra-large, large, small].

A comprehensive example

As a comprehensive example, consider the following expression:

ARRAYTOSTRING(FLATTEN(PatternMatching.Models, Item.Occurrences,
CONCAT(Item.Name, " (", SubIndex, "/", SubItemCount, ")", " Score = ", TOSTRING(SubItem.Score, ":F1"))), "\r\n")

This expression has the following functions: ARRAYTOSTRING, FLATTEN, CONCAT, and TOSTRING.

The FLATTEN function's parameters are the following:

sourceArray = PatternMatching.Models
subArray = Item.Occurrences
expression = CONCAT(Item.Name, " (", SubIndex, "/", SubItemCount, ")", " Score = ", SubItem.Score)

The FLATTEN function references the results of a PatternMatching step. The source array parameter points to the collection of models, whereas the sub-array parameter uses the expression Item.Occurrences to point to the found occurrences for each model.

As such, the keywords SubIndex, SubItem, and SubItemCount let you extract and print information about the occurrences in the sub-array. For example, each model occurrence has a Score property, so the expression SubItem.Score accesses the score of each occurrence of the model whose results are currently being accessed.

The CONCAT function acts as the expression parameter to the FLATTEN function. Its parameters are the following:

value 1 = Item.Name
value 2 = " ("
value 3 = SubIndex
value 4 = "/"
value 5 = SubItemCount
value 6 = ")"
value 7 = " Score = "
value 8 = SubItem.Score

The CONCAT function converts the following information for each model occurrence into a single string: the model occurrence's name, its index with respect to the total number of occurrences for that model, and its score. The TOSTRING function allows you to represent the score with one decimal place.

The FLATTEN function then finishes executing by returning an array of strings, each string element of the array corresponding to an occurrence of a model.

Finally, the ARRAYTOSTRING function converts the entire array into one string, separating each string element into rows by using "\r\n" (return and newline) as separator characters.

Assuming the PatternMatching step model searches for 2 models named "Model_A" and "Model_B", if it found 6 occurrences and collected them in decreasing score order per model, a possible output for this expression would be:

Model_A (1/4) Score = 99.8

Model_A (2/4) Score = 80.2

Model_A (3/4) Score = 79.1

Model_A (4/4) Score = 75.2

Model_B (1/2) Score = 98.5

Model_B (2/2) Score = 78.3