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.