dmellipse

Synopsis

Finds ellipse for specified fraction

dmellipse  infile outfile fraction [shape] [x_centroid] [y_centroid]
[angle] [ellipticity] [fix_centroid] [fix_angle] [fix_ellipticity]
[tolerance] [minstep] [maxwalk] [step] [normalize] [clobber] [verbose]

Description

`dmellipse' finds the an ellipse that encloses the user supplied fraction to within some specified tolerance. The tool picks the first ellipse it finds that falls within the tolerance range on the enclosed fraction.

The tool works by first finding the centroid, angle, radii, and ellipticity of the entire image. It uses these as a starting point. The fraction inside the ellipse defined by those parameters is computed. If the fraction computed is bigger than the fraction desired, the radius is decreased and the process is repeated (opposite if fraction is too small). During this process if the direction changes (so for example the previous iteration was too small and the current too big) we change the divide the step size by 2. This lets us converge onto a value. During the iterations the centroid, ellipticity, and/or angle may be taken from the previous iteration, from some user supplied values, or fixed to be the global values computed in the 1st step; the user controls these with the fix_* parameters.

Once we find a radius that mets the requirement that the fraction is within the 'tolerance' of the requested fraction we then do one more iteration. This is to check that with the final centroid, angle, and ellipticity that we still have the requested fraction. If not, then we use the new values to seed the next iteration. We refer to this as 'walking' since its kind of like a random-walk process.

The iterations can stop for several reason. First, if we find a radius with moments such that the fraction is met we stop successfully. Second, if we keep stepping and keep changing direction then the step size can get increasingly small; there is a limit on this. Third, if we keep 'walking' at the same step-size but unable to find an ellipse whose moments are consistent with fraction we stop after 'maxwalk' steps.

Example 1

dmellipse img.fits 50perc.reg 0.5

Finds the ellipse that encloses 50% of the energy/flux in the image.

Example 2

dmellipse img.fits 50perc.reg 0.5,0.9

Finds the ellipses that encloses 50% and 90% of the energy/flux in the image.

Example 3

dmellipse img.fits 50perc.reg lgrid(0.5:0.91:0.1)

Finds the ellipse that encloses 50%, 60%, 70%, 80% and 90% of the energy/flux in the image.

Note that to get the 90% radii we used an upper limit of 0.91 in the grid specification. This is because the stack grid computes values x<value for floating-point-value not x<=value.

Example 4

dmellipse img.fits 50perc.reg 0.5 fix_centroid=yes

Finds the ellipses that encloses 50% and 90% of the energy/flux in the image. The centroid is fixed to be the centroid of the entire image; rather than being left to vary.

Example 5

dmellipse img.fits 50perc.reg 0.5 fix_centroid=yes x_centroid=4096
y_centroid=4096

Similar to above. Finds the ellipses that encloses 50% and 90% of the energy/flux in the image. The centroid is fixed to be the user supplied value (4096,4096).

Example 6

dmellipse img.fits 50perc.reg 0.5 shape=rotbox

Finds the rotated-box (rectangle) that encloses 50% of the energy/flux in the image.

Example 7

dmellipse img.fits[sky=circle(4096,4096,100)] 50perc.reg 0.5
normalize=no

Find ellipse that encloses 50% of the flux; setting normalize=no lets the tool know that the data have already been normalized (so 'no' the tool should not normalize the data).

Example 8

dmellipse img.fits eef.fits fraction=0.9 shape=ellipse
fix_ellipticity=yes ellipticity=1

By freezing the ellipticity to a value=1, we have forced the ellipses to become circular. Since the angle of a circle is undefined, we could also go ahead and freeze the angle to be 0 by setting fix_angle=yes angle=0. The output file will still contain "shape=ellipse" however both radii will be the same.

Parameters

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input image

Input image. It must have all positive values (so if background subtracted, make sure to threshold).

Parameter=outfile (file required filetype=output)

Output region file

ASC-FITS region file with additional columns indicating which fraction and status information.

Parameter=fraction (string required stacks=yes)

Enclosed counts/flux fraction.

The value(s) to find the ellipse. This can be specified using any of the stack syntax including lgrid() or just a comma separated list (or just a single value).

Parameter=shape (string not required default=ellipse)

shape of region

can be either 'ellipse' or 'rotbox'

Parameter=x_centroid (real not required default=INDEF)

default x-centroid

The default x-centroid can be input via this parameter or if the value is set to INDEF the value will be computed over the entire image.

Parameter=y_centroid (real not required default=INDEF)

default y-centroid

The default y-centroid can be input via this parameter or if the value is set to INDEF the value will be computed over the entire image.

Parameter=angle (real not required default=INDEF)

default angle

The default angle can be input via this parameter or if the value is set to INDEF the value will be computed over the entire image.

Parameter=ellipticity (real not required default=INDEF)

default ellipticity

The default ellipticity can be input via this parameter or if the value is set to INDEF the value will be computed over the entire image.

Parameter=fix_centroid (boolean not required default=no)

allow centroid to vary

during the iterations the centroid can be allowed to vary or it can be held fixed at the default value (see x_ and y_centroid for default value)

Parameter=fix_angle (boolean not required default=no)

allow angle to vary

during the iterations the angle can be allowed to vary or it can be held fixed at the default value (see angle parameter for the default value)

Parameter=fix_ellipticity (boolean not required default=no)

allow ellipticity to vary

during the iterations the ellipticity can be allowed to vary or it can be held fixed at the default value (see ellipticity parameter for the default value).

Parameter=tolerance (real not required default=0.001 min=0 max=1)

How close to desired fraction is close enough?

The iterations will continue until the fraction is within fraction-tolerance to fraction+tolerance (so total-width is 2*tolerance).

Parameter=minstep (real not required default=0.001 min=0 max=1)

minimum step size

As the iterations proceed and we change from increasing to decreasing the radii we make the step size increasing smaller; this is the minimum step size to use. After reaching this the iterations will stop.

Parameter=maxwalk (integer not required default=10 min=1)

maximum number of equally applicable iterations.

We we have a candidate radii we use the ellipticity, angle, and centroid to do one last check. If the ellipse defined by those is still good (fraction is within tolerance) the we stop. If not, we 'walk' to the next iteration. This could lead to a situation where we oscillate between good and bad without changing step-size. This parameter limits this condition.

Parameter=step (real not required default=1 min=0)

Initial step size

The intial step size. If the program seems to be taking a long time it may be because the algorithm is creaping slowly towards the solution. Setting verbose greater than 2 will show the progress of the tool. Increasing the step size will allow the program to get close to the optimal solution quicky and then more quickly refine the solution until the tolerance (or other exit conditions) is (are) met.

Parameter=normalize (boolean not required default=yes)

Normalize input image or not?

Is the fraction really a fraction (% of total flux) or is it the integral?

Parameter=clobber (boolean default=no)

Remove output if it exists?

Used to specify whether or not to clobber existing file that has the same name as the specified output file

Parameter=verbose (integer default=0 min=0 max=5)

The tool chatter level

Verbose can be from 0 to 5, generating different amounts of debugging output.

Changes in CIAO 4.5

• New Tool!

  The dmellipse tool finds the best-fit ellipse (or rotated box) that encloses the specified fraction of flux to within a given tolerance.

  This tool was initially developed for use with the Chandra Source Catalog.

Bugs

There are no known bugs for this tool.

See Also

dm

dmfiltering

tools

dmappend, dmcontour, dmfilth, dmimg2jpg, dmimgadapt, dmimgblob, dmimgcalc, dmimgdist, dmimgfilt, dmimghist, dmimghull, dmimglasso, dmimgpick, dmimgpm, dmimgproject, dmimgreproject, dmimgthresh, dmmaskbin, dmmaskfill, dmnautilus, dmregrid, dmregrid2, dmstat, evalpos, get_fov_limits, get_sky_limits, imgmoment, mean_energy_map, pileup_map