Program: OBJECTS Purpose: Find and analyze isolated (extended) structures in an image. Category: ANALYSIS File: objects.c Author: M.G.R. Vogelaar R. Slagter Keywords: INSET= Give set, subsets: Maximum number of subsets is 2048. BOX= Give box in ..... [entire subset] When you use a box be sure that the output set is empty around it. The program doesn't empty the output set around the defined box. ** OBJNAME= Enter a name to identify field: [header] Tables on screen and on disk are identified by a name. The default is a name stored in the header of INSET= You can change this id by entering text here. OUTSET= Give output set (, subsets): Output set and subset(s) for the result. The number of output subsets is the same as the number of input sub- sets. RANGE= Give range of levels: [ ,->] At least one value is needed. Range selects all pixels in the analysis. To EXCLUDE a range of values, take the first value greater than the second. Examples: RANGE=3 Include all values >= 3 RANGE=3 5 Include values >= 3 and <= 5 RANGE=5 3 Include values <= 3 and >= 5 MAXCUT= Enter a cutoff for the max. in an object: [none] Do not include objects that have a maximum intensity less than this value. The intensities are in units of the map. SIZE= Give range of object sizes (number of pixels): [10,->] The size of an object in your image must be in the range as defined with SIZE= before it is counted as an object. To EXCLUDE a range of object sizes, take the first value greater than the second. Examples: SIZE=3 Include all sizes >= 3 SIZE=3 5 Include sizes >= 3 and <= 5 SIZE=5 3 Include sizes <= 3 and >= 5 BRIDGE= Give min. thickness allowed for bridges [1 1] If objects are connected by 'bridges', it is possible to disconnect them by defining the width or height of the bridge. BRIDGE= takes two values. The first value is the width in Y for a bridge in the X direction and the second is the width in X for a bridge in the Y direction. If [0 0] is given the program switches from checking 4-connectivity to 8-connectivity when selecting pixels of an object. TOSCREEN= Display table on screen? [Y]/N If the program examined all objects, it prints a table on screen. If you do not want this table, use TOSCREEN=N TOPLOT= Make Area-Perimeter plot of objects? [Y]/N MAXBORDER= Give max. pixels allowed on border of box: [2] This keyword is only prompted when TOPLOT=Y. Objects with pixels on a border are still isolated. This keyword allows you to eliminate objects, with pixels on the border, from the area-perimeter calculation. With this keyword you can give the minimum number of pixels that are allowed on the borders. The borders are given with BOX= . A pixel in the corner of the box is counted twice. GRDEVICE= Plot device: [List of devices] If TOPLOT=Y, specify the destination of the plot. VOLUMES= Connected clouds in subset direction? [Y]/N (Default depends on number of input subsets) Using more than one subset in your input, it could be interesting to examine connections of objects in three dimensions. OBJVOLUME= Give range of volumes: [as given with size] This keyword is only prompted when VOLUMES=Y. An object in your image must have a number of pixels in the range specified, before it is counted as a volume. DEPTH= Give range in depths of objects: [2,->] This keyword is only prompted when VOLUMES=Y. An object in your image must have a certain number of overlapping two dimensional objects in the third dimension before it is counted as a volume. You can include volumes if the first depth is smaller than the second. You can exclude volumes if the first depth is greater than the second. OVERLAP= Give the range in overlap: [1,->] This keyword is only prompted when VOLUMES=Y. An two-dimensional object is considered connected to another two-dimensional object, if they have a number of pixels in the range given by overlap, in common. It is also possible to select on the percentage overlap between two 2-dimensional objects (See the program description for the definition of the overlap percentage). In that case; end your range definition with the "%" sign. Note: it is only possible to include a range! TOSCREEN= Display table on screen? [Y]/N This keyword is only prompted when VOLUMES=Y. If the program examined all volumes, it prints a table on screen. If you do not want this table, use TOSCREEN=N EXCLUDE= Give index of volumes to exclude: [NONE] This keyword is only prompted when VOLUMES=Y. Before you make an output set is it possible to exclude objects. You can do this by giving their index numbers. The program will re-arrange the indices of the allowed objects. Because of gipsy limitations, it is only possible to use exclude 1024 volumes at once. Therefore the keyword EXCLUDE will reappear when your selection contains more than 1024 volumes. This loop will terminate if you respond with EXCLUDE=NONE. It's also possible to exclude volumes later, by using the program "CONDIT" (see program description). FILENAME= Name of ASCII file: [No output to file] If a name is specified, an ASCII file is created to store data. If you press carriage return, there will be no output to an ASCII file. If a given name already exists, APPEND= must be specified. APPEND= File exists, ok to append? [Y]/N The file specified in FILENAME= already exists. You can append to this file with APPEND=Y. If APPEND=N you will be prompted for another filename. GRDEVICE= Plot device: [List of devices] Destination of plot, Screen or Hardcopy. AGREED= Agreed with current selection? Y/[N] Selection of volumes can be repeated. The keywords DEPTH=, OBJVOLUME= and OVERLAP= are asked again. AGREED= Agreed with current output? [Y]/N Each selection can be stored in a set. This action can be repeated for different selections. ==== PLOTTING ==== ** PGMOSAIC= View surface sub divisions in x,y: [1,1] View surface can contain a number of plots in in X and Y direction (mosaic). Default is 1 plot in both X- and Y direction. ** PGPAPER= Give width(cm), aspect ratio: [calc, calc] Aspect ratio is height/width. ** PGBOX= Corners of box Xl,Yl,Xh,Yh: [default by application] It is possible to overrule the calculated PGPLOT box size with PGBOX=. The coordinates (x,y) of the lower point are given first. ** PGCOLOR= Give color 1..15: [1] See description for the available colors. ** PGWIDTH= Give line width 1..21: [2] ** PGHEIGHT= Give character height: [1.0] ** PGFONT= Give font 1..4: [2] ** MINBOXSIZ= Give min. box size for volume: [1,1] It is possible to set a minimum on the size of the minimum box around the volume. The first number indicates the minimum length of the box in the x- direction. The second number the minimum length in the y-direction. This keyword should be set when the other volume criteria are asked. ** MAXBOXSIZ= Give max. box size for volume: [ALL] It is possible to set a maximum on the size of the maximum box around the volume. The first number indicates the maximum length of the box in the x- direction. The second number the maximum length in the y-direction. This keyword should be set when the other volume criteria are asked. Description: Program description: The program "OBJECTS" finds and analyses isolated structures (called objects in the program), in two and three dimensions, automatically. In two dimensions a definition of an object is given with keywords as described above. The objects are isolated and stored in an output set and the analysis is written to screen or ASCII file. Also a plot of area against perimeter can be created. The analysis can be extended to the third dimension. The objects are then isolated volumes. "OBJECTS" starts always with finding objects in two dimensions. After the two-dimensional analysis, the user can directly continue with a three-dimensional analysis by responding with VOLUMES=Y. // In the near future it will also be possible to leave the program after the two- dimensional analysis and do the three-dimensional analysis later. Then it will be possible to rerun the three dimensional analysis without rerunning the two-dimensional analysis again. The user has to respond then to INSET= with the set created by the two-dimensional analysis and he will be prompted immediately with the keyword VOLUMES= for the three-dimensional analysis. // The two-dimensional analysis starts with the specification of the input with INSET= The input must be 2-dimensional. For a two-dimensional analysis you can manage with only one subset. For the three-dimensional case however, you need at least two subsets. In each subset the program searches for pixels which are in the range of image values (as given with the keyword RANGE=). You can also exclude data by specifying two values, the first value greater than the second one. If you give only one value, all pixels with an image value greater than this value will be part of an object. Pixels belong to the same object if they share at least one side (4-connec- tivity). (By setting the keyword BRIDGE=0 0, it is possible to change the 4-connectivity mode to 8-connectivity) The second criterion for an object is its size in pixels. A valid object must contain a number of pixels in the range of SIZE= before it is used for further inspection. An object can contain so called 'bridges'. These are very small connections. Sometimes it is useful to separate such objects. This can be achieved with BRIDGE= The default values are BRIDGE=1 1 This allows bridges of one pixel in size in each direction (See description at BRIDGE= for the directions). According to Mandelbrot, fractals are objects that exhibit a self similar geometry. That is, the appearance of a fractal object is the same even when subject to arbitrary magnification. The contortion and complexity of the perimeter of such object is given by the fractal dimension of the perimeter (D). If A is the area of the object and P is the perimeter, the fractal dimension is given by the relation: P ~ A ^ (D/2) (smooth appearance, e.g. squares and circles: D = 1 , distorted perimeter: 1 < D <= 2 ) The keyword TOPLOT=Y allows you to view this relation on a graphics device for all the objects selected. The perimeters in are summed in X- and Y- direction and multiplied with the grid spacing for that direction. The grid spacing is read from the header. Also the area is converted to header units. The plot that is showed is a LOG10-LOG10 plot. The fractal dimension is equal to twice the average slope. With the keyword MAXBORDER=, all the objects which have more than a certain number of pixels on the border of the box are excluded from the Area-Perimeter calculation. These objects however are still stored in the output set. Each valid object found in the search for isolated objects is stored in an output set (OUTSET=). Each object gets a unique number. The numbers start at 0 and for each new object the number is increased by 1 (independent of subset number). You can use the results in the output sets to blot out objects in your input set. The easiest way to do this is by using the program "CONDIT". Give your input set also as input set (INSET= ) for "CONDIT". Use one of the results output sets for the set which should operate on the input (XSET= ). Use the keyword RANGE= for selecting the objects which should be blotted out and the way in which they should be blotted out ( transfer blanks or transfer the original value or a replace value (REPLACE= ) ). The program updates a list of all the important information about the objects found in the analysis. Implemented are the starting position x, y of the objects, the subset, the area, the perimeters in x- and y direction, the flux, the flux per pixel, the maximum value and the number of pixels on the border of the box (see keyword BOX=). With the keywords TOSCREEN= and FILENAME= you can get this list on screen and file respectively. The Area-Perimeter results can be viewed in a plot with TOPLOT=Y. A graphics device can be selected with GRDEVICE=. The three-dimensional analysis is based on the results of the (previous) two-dimensional analysis (so don't change the output set). Each object left from the two-dimensional analysis is examined to have overlapping pixels with objects in the previous or next subset (connections in the third dimension). If two objects have overlapping pixels in the range as given with OVERLAP=, then they are connected and a new 3d-object (volume) is found. It is also possible to select on the overlap percentage. In that case, end your input with "%". The user can put further restraints on the volume in pixels (keyword OBJVOLUME=) and the range in depths (keyword DEPTH= , the minimum number of planes in which the object was found). With the hidden keywords MINBOXSIZ= and MAXBOXSIZ= you can also select on the size of the minimum box around a volume. The selected volumes and all important information about them, are updated in a list. Implemented are the index number, the starting position x,y of the volumes, the lowest and highest pixel position and subset they are found in, the depth of the volume, the volume in pixels, the flux per pixel, the maximum value and the overlap-percentage. The overlap-percentage of a volume is the average overlap- percentage of all overlapping 2-dimensional objects forming the volume. The overlap-percentage of two connected 2-dimensional objects is 100% if the smallest object is completely overlapped by the biggest. After inspection of the list of selected volumes the user can exclude volumes with EXCLUDE= The keyword accepts the index numbers of volumes in the generated list. Because of gipsy limitations, you can only use exclude 1024 volumes at once. This has to be no problem because the program will repeat prompting you the EXCLUDE= keyword. You can also do the excluding later by using "CONDIT". If you want to blot out with "CONDIT", the excluding with "CONDIT" can be done at the same moment, which will save you (for large data cubes) a lot of time. If the user is not satisfied with the volume-selection or the user wants to create several output sets with different selections, he can specify new output sets with keyword OUTSETn= where n is an integer number. If the user wants to make more output sets he may not use the previous OUTSET= of the two-dimensional analysis for OUTSETn= The loop over selections and output sets is controlled by AGREED= Be aware of the correct clip levels when viewing the resulting output sets. If the clip levels are wrong, iso- lated clouds could seem to have similar colors. When the maps contain a lot of objects, the value given in "GIDS" may be wrong. Use for the correct values the program "PRINT". If you want to view just one volume, use the box parameters in the table to select a nice box for "VIEW". OUTPUT TABLE: Example: INDX|===X|===Y|SUB|===AREA|===XPER|===YPER|===FLUX|FLUX/PIX|====MAX|BORD| ------------------------------------------------------------------------- 1| -5| -15| 0| 613| 108| 90|10768.5| 17.5669|78.2993| 0| 2| 10| -12| 0| 32| 20| 16|120.502| 3.76568|7.07311| 0| 3| 12| 4| 0| 10| 12| 4|40.1944| 4.01944|5.81718| 0| 4| -22| 8| 0| 12| 8| 12|48.9353| 4.07795|6.70393| 0| 5| -14| -20| 1| 936| 100| 120| 397945| 425.155|543.007| 0| INDX Each object gets a unique number, starting with 1 X X-position of first pixel encountered that is part of current object. Y Y-position of first pixel encountered that is part of current object. SUB The subset number to which the object belongs. AREA The number of pixel in this object. XPER The perimeter in pixels in X-direction. YPER The perimeter in pixels in Y-direction. FLUX Sum of the pixel values in this object. FLUX/PIX Average flux per pixel in this object. MAX The maximum pixel value in this object BORD The number of pixels of this object that belongs to the border of the current box. Each table with more than one entry is followed by a table with averages and standard deviations. Example: Average perimeter in DEGREE = 0.210573 +- 0.251443 Average perimeter in X in pixels = 38.363636 +- 46.396709 Average perimeter in Y in pixels = 37.454544 +- 44.750214 Average area in DEGREE x DEGREE = 0.001595 +- 0.002571 Average area in pixels = 206.818176 +- 333.314819 Average flux in map units = 40646.238281 +- 118619.796875 Average flux per pixel in map units = 161.308823 +- 212.934387 Average maximum value in map units = 185.303741 +- 230.783920 Table if VOLUMES=Y ==NR|===X|===Y|LOWX|LOWY|LOSUB|HIGX|HIGY|HISUB|DEPTH|VOLUME|=FLUX/PIX|======MAX| -------------------------------------------------------------------------------- 1| -5| -15| -22| -20| 0| 19| 23| 2| 3| 2167| 191.057| 543.007| 2| 12| 4| 12| 4| 0| 17| 7| 1| 2| 30| 291.273| 445.613| 3| -22| 8| -22| 8| 0| -17| 17| 2| 3| 54| 268.066| 478.646| NR Each object gets a unique number, starting with 1. X X-position of first pixel encountered that is part of current object. Y Y-position of first pixel encountered that is part of current object. LOWX Lowest X coordinate of this volume. LOWY Lowest Y coordinate of this volume. LOSUB First subset with a pixel that belongs to this volume. HIGX Highest X coordinate of this volume. HIGY Highest Y coordinate of this volume. HISUB Last subset with a pixel that belongs to this volume. DEPTH number of subsets that contributed to this volume FLUX Sum of the pixel values in this volume. FLUX/PIX Average flux per pixel in this volume. MAX The maximum pixel value in this volume. Each table with more than one entry is followed by a table with averages and standard deviations. Example: AVERAGES AND STANDARD DEVIATIONS USING 3 VOLUMES =================================================== Average volume in pixels = 750.333313 +- 1226.927979 Average depth in pixels = 2.666667 +- 0.577350 Average flux in map units = 145744.765625 +- 232351.328125 Average flux per pixel in map units = 250.132126 +- 52.459873 Average maximum value in map units = 489.088715 +- 49.529644 COLOR INDICES: 0 Background 1 Default (Black if background is white) 2 Red 3 Green 4 Blue 5 Cyan 6 Magenta 7 Yellow 8 Orange 7 Yellow 8 Orange 9 Green + Yellow 10 Green + Cyan 11 Blue + Cyan 12 Blue + Magenta 13 Red + Magenta 14 Dark Gray 15 Light Gray 16-255 Undefined Available fonts: 1 single stroke "normal" font 2 roman font 3 italic font 4 script font Notes: Future developments: If the input set is the previous output set of the two dimensional analysis then the two dimensional analysis will be skipped. Example: objects OBJECTS Version 1.1 (Aug 12 1993) OBJECTS INSET=set_van_tape 1:10 Set set_van_tape has 3 axes RA from -127 to 128 DEC from -127 to 128 FREQ from 1 to 59 OBJECTS BOX=-100 -100 100 100 BOX range for set set_van_tape : RA from -100 to 100 DEC from -100 to 100 Be sure your output set is empty around the defined box !!! OBJECTS OUTSET=output Set output has 3 axes RA from -127 to 128 DEC from -127 to 128 FREQ from 1 to 10 OBJECTS FILENAME=ASCII_data OBJECTS APPEND=y OBJECTS RANGE=5.0 10.0 OBJECTS SIZE=20 4 OBJECTS BRIDGE=0 0 Mode changed to 8-connectivity 111 objects found OBJECTS TOSCREEN=y OBJECTS TOPLOT= OBJECTS MAXBORDER=0 User: R.Slagter, date: Thu Aug 12 13:39:16 1993 range of data values: [5, 10] Range of sizes: [20,4] All bridges allowed INDX|===X|===Y|SUB|===AREA|===XPER|===YPER|===FLUX|FLUX/PIX|====MAX|BORD| ------------------------------------------------------------------------- 1| 47|-100| 1| 1| 2| 2|5.36739| 5.36739|5.36739| 1| 2| -52| -98| 1| 1| 2| 2|5.21503| 5.21503|5.21503| 0| 3| 86| -92| 1| 1| 2| 2|5.24646| 5.24646|5.24646| 0| 4| 57| -75| 1| 2| 4| 2|11.3251| 5.66257|6.24437| 0| CORRELATION AND REGRESSION ========================== Data points diagram : n = 108 (1) Regression Y on X: Y = +0.610541 (+/-0.003152) X +1.095081 (+/-0.013920) (2) Regression X on Y: X = +1.633277 (+/-0.008433) Y -1.801008 (+/-0.013506) Linear corr. coeff. : r = 0.998590 Average slope : M = 0.611403 (+/-0.002232) Probability that Parent Distribution is uncorrelated : Pc(r,n) < 1.0e-18 ( Very highly significant ) OBJECTS VOLUMES= Found 11 connections between objects in successive subsets OBJECTS OBJVOLUME=5 OBJECTS DEPTH=3 7 OBJECTS OVERLAP=90% Selected 0 volumes : found in 0.00 sec (0.00 cpu sec) OBJECTS TOSCREEN=n OBJECTS AGREED= OBJECTS OBJVOLUME= OBJECTS DEPTH=1 OBJECTS OVERLAP=1 Selected 1 volumes : found in 0.00 sec (0.00 cpu sec) OBJECTS TOSCREEN=y Analysis of volumes: minimum volume: 5 range of data values: [5, 10] overlap: [1, ->] depth of volumes: [1, ->] ==NR|===X|===Y|LOWX|LOWY|LOSUB|HIGX|HIGY|HISUB|DEPTH|VOLUME|=FLUX/PIX|======MAX|OVERLAP| ---------------------------------------------------------------------------------------- 0| 10| -28| 10| -28| 3| 11| -26| 10| 8| 18| 6.76017| 9.47997| 100%| OBJECTS AGREED=y OBJECTS EXCLUDE= OBJECTS OUTSET1=output OBJECTS OKAY= Set output has 3 axes RA from -127 to 128 DEC from -127 to 128 FREQ from 1 to 10 OBJECTS AGREED=y OBJECTS +++ FINISHED +++ Updates: Jun 25, 1993: VOG, Document created. Jul 29, 1997: VOG, Added averages for objects in table Oct 29, 1997: VOG, Added OBJNAME= keyword Feb 1, 2000: JPT, Increased number of subsets.