Friday, September 9, 2011

Using arrays in script (part 2.0): Results window

If the Array and List data structures are too limited in one of your IJ script, there is an interesting alternative for storing a data collection: The Results which is a specific window (tool?) working like a very basic spreadsheet...

The Results window is a specialized Table (a non-image window) working only with numbers and extensively used in many plugins like the Analyze > Analyze Particles... . Moreover, this window has specific menus to explore the data (distribution, statistics computation: min, max, average, standard deviation,etc.).
There are two utility functions to manipulate the data in a Results Window:
  • setResult(...): Creation and set Data
  • getResult(...): Get data

1-Create and fill the Results window

There is no specific function for the creation of the Results window, each time a new value is added in this table via the function setResult(..), the window, a new row or a new column are automatically created if required.
The function  setResult(...) has three arguments:
  1. the column name (a String)
  2. the row index (Notice that the first index is 0 (zero) !! )
  3. the value
Here is an example...
+++ IJ snippet: array_results_creation.ijm +++
+++ End of IJ snippet +++

There are some constraints when defining rows:
  • Keep in mind that the first row has the index 0. 
  • You have to define the rows indexes by ascending order (an increment of 1) - we can't create rows #3, then #2 and #4, you must follow the ascending order (#2, #3, and #4).

2-Read the data

The function getResult(...) allows to read a value, you need two arguments:
  1. The column name ( a String)
  2. The row index .

+++ IJ snippet +++
+++ End of IJ snippet +++

Don't be confused between the indexes displayed in the Results window and the index of the getResult(...) function.
As shown in Fig. 1, the Results begins with the row # 1 ...

Fig. 1: Results window. The first row has the index 1.

...but in a macro/script to get the values of the first row, you need to type:
getResult("faces",0); // 4
getResult("edges",0); // 6

3- Utilily functions

nResults(): To get the rows number. That's very useful to scan all the values in a loop.

run("Clear Results"): To reset (and clear) the Results window.

4- Conclusion

Pros: easy access, good for large arrays (columns)
Cons: Only one unique Results table, strings not supported, no row access.

The Results window is a specialized version of the Table window ... and this is the subject of my next post.

No comments:

Post a Comment