Last modified: August 2023

AHELP for CIAO 4.16


Context: Tools::Image


Group pixels by steepest gradient ascent to local maximum


pathfinder  infile outfile [minval] [direction] [verbose] [clobber]


For each pixel, identify the maximum neighboring pixel. Those form a group. Continue from that maximum to identify it's maximum neighbor which is then added to the group and so on. When the algorithm finds a local maximum which already belongs to a group, the new group is abandoned and the pixels are added to the existing group. The process is repeated until the pixel being processed is the local maximum.

The input image should be modestly smoothed such that the local maxima are statistically significant.

This algorithm can be helpful to separate region based on the "saddle-point" (where the gradient goes to zero). For example it helps find the natural separation point between point-likes sources with different intensities (or different extent); rather than simply using the mid-point between them, it uses the gradient to assign pixel ownership to one-or-the-other.


Example 1

% pathfinder smoothed.img

The smoothed infile, smoothed.img, is processed through the path-finding algorithm. The outfile,, contains the group ID for each local maxima.

Example 2

% pathfinder smoothed.img direction=perpendicular

Same as above; however this time restrict the search for neighboring maxima to only 4 pixels: top, bottom, left, right.


name type ftype def min max reqd
infile file input       yes
outfile file output       yes
minval real   0      
direction string   diagonal      
verbose integer   1 0 5  
clobber boolean   no      

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input image.

The image to be grouped. Generally this algorithm works better if it is moderately smoothed.

Null and NaN pixels, as well as those pixels outside the image subspace will not be grouped.

Parameter=outfile (file required filetype=output)

Output map file

The outfile is a map file containing integer pixel values. The pixel values indicate which pixels are grouped together by the algorithm. A pixel value of 0 are pixels which are ungrouped (ie outside the image subspace or below minval).

Parameter=minval (real default=0)

Minimum pixel value to group

Pixels values less than minval will be left ungrouped.

Parameter=direction (string default=diagonal)

Direction to follow gradient: perpendicular or diagonal

When searching for the neighboring pixel with the maximum value, the tool will just consider just the 4 perpendicular pixels (top, bottom, left, right) of the current pixel, or can consider all 8 adjacent pixels including the diagonal pixels.

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

Amount of chatter from the tool.

Parameter=clobber (boolean default=no)

Delete outfile if it already exists?

About Contributed Software

This script is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see this page for installation instructions.


There are no known bugs for this tool.

See Also

centroid_map, dmfilth, dmimg2jpg, dmimgadapt, dmimgblob, dmimgcalc, dmimgdist, dmimgfilt, dmimghist, dmimgpick, dmimgpm, dmimgproject, dmimgreproject, dmimgthresh, dmmaskbin, dmmaskfill, dmnautilus, dmradar, dmregrid, dmregrid2, energy_hue_map, evalpos, hexgrid, map2reg, merge_too_small, mkregmap, vtbin
dmcontour, dmellipse, dmimghull, dmimglasso
mean_energy_map, pileup_map
dmstat, imgmoment, statmap