**CIGAL Reference Manual, Chapter 3 (Functions): analyze** ===== Analyze -- Calculate the frequency distribution of values within a variable ===== **usage: resultarray = analyze(ivarb)** ANALYZE reads the input variable, IVARB, and creates an output array where the values of the array elements represent a frequency histogram of the values of elements in IVARB. The output array is of LONG type (see [[jvs:cigal:manual:chapter1:variables|VARIABLES(1)]]). The elements in the array represent the frequency distribution of the possible values in the input. Thus, element 45 in the output array corresponds to the number of elements in the input array with value equal to 45. By default, RESULTARRAY will be allocated 256 elements if IVARB is a byte array, or 4096 elements otherwise. If RESULTARRAY already has more than that many elements allocated to it the entire array will be used as the output histogram. In general, the length of RESULTARRAY should be 1 more than the largest integer value in IVARB. Any IVARB values less than 0 will be counted in the 0 element of RESULTARRAY, and IVARB values greater than the length of RESULTARRY will be counted in the last element of RESULTARRAY. The array produced by ANALYZE is useful for measuring various descriptive properties of the input variable. For example, it can be used to determine the optimal contrast enhancement to perform for a given image matrix, or as a way of computing the average value of the input. Some image processing hardware is capable of performing an ANALYZE operation on an entire image at the hardware's video refresh rate. If the hardware is capable of this, and you run ANALYZE on an appropriate hardware image variable, then CIGAL automatically lets the hardware perform the computation. Otherwise, the software will do the work, but it may be a bit slow for very large variables. As an example, if you have a byte matrix called VGA0, which contains a 320x184 image with pixel values covering the middle of the 0-255 intensity range, then the command: buf = analyze(vga0) might produce the following array BUF: 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 33 65 74 78 61 74 62 97 97 92 98 132 120 164 121 192 220 204 288 294 389 421 461 545 673 628 815 691 971 1022 988 1086 1257 1107 1006 1171 1321 901 1084 1042 891 1133 962 949 1025 1042 1165 1038 1145 1084 1245 928 960 1066 1052 786 953 855 731 762 831 842 887 734 828 777 879 761 891 687 690 631 664 560 502 534 464 487 457 692 683 681 729 738 490 447 341 220 147 145 130 80 85 74 40 52 18 29 11 10 9 2 2 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 The command STATS could then be used to describe BUF as: stats buf which tells you that the intensities in VGA0 range from 26 to 130 with the greatest number of pixels (1321) at intensity 63. The mean pixel value can be quickly calculated from the ANALYZE array as: a = sum(buf) ; total number of pixels in VGA0 buf = buf * ramp(256) ; weight each intensity by its num. of pixels sum(buf)/a ; the mean pixel intensity The command MEAN(VGA0) would give the same result, but is sometimes slower. **See Also:**\\ [[jvs:cigal:manual:chapter3:bin|BIN(3)]], [[jvs:cigal:manual:chapter1:iproc|IPROC(1)]], [[jvs:cigal:manual:chapter3:stats|STATS(3)]], [[jvs:cigal:manual:chapter1:variables|VARIABLES(1)]] [[jvs:cigal|CIGAL Home]], [[jvs:cigal:manual|CIGAL Manual]], [[jvs:cigal:manual:chapter3|Functions List]], [[jvs:cigal:manual:help|Manual Help]]