OOF2: The Manual

OOF.PixelGroup.AutoGroup
	6.2.187. OOF.PixelGroup Commands

Name

OOF.PixelGroup.AutoGroup — Put all pixels into pixel groups, sorted by color or orientation.

Synopsis

OOF.PixelGroup.AutoGroup(grouper,delta,gamma,minsize,contiguous,name_template,clear)

Details

Parent Menu: OOF.PixelGroup
Callback: function autoPixelGroup in module ooflib.common.IO.pixelgroupmenu
Parameters:

grouper

Which pixel values to use, and how to compute the difference between them. Type: An object of the PixelGrouper class.

delta

Pixels within this many standard deviations of a group's mean will be added to the group. Type: A real number.

gamma

Groups within this many standard deviations of each other's means will be merged. Type: A real number.

minsize

Don't create groups or isolated parts of groups with fewer than this many pixels. Instead, assign pixels to the nearest large group. Set minsize=0 to skip this step. Type: Integer.

contiguous

Create only contiguous groups. Similar pixels that aren't connected to one another will be put into separate groups. Type: Boolean, 0 (false) or 1 (true).

name_template

Name for the new pixel groups. '%n' will be replaced by an integer. Type: A character string.

clear

Clear pre-existing groups before adding pixels to them. This will NOT clear groups to which no pixels are being added. Type: Boolean, 0 (false) or 1 (true).

Description

Automatically assign every active pixel in the Microstructure to a PixelGroup according to the criterion given by grouper. Unlike OOF.Image.AutoGroup, this command is designed to handle noisy images (but not too noisy), and it can group pixels according to EBSD data as well as color. It can create either contiguous groups (each group containing a connected set of pixels) or discontiguous groups (a single group possibly comprising disjoint regions).

AutoGroup works well on images with regions of constant color (or orientation) with a small amount of added noise, when you want the final PixelGroups to be insensitive to the noise. It also works well on antialiased images, where the transition from one region of constant color to another has been smoothed out over the span of a few pixels, but the interpolated colors in the boundary should not be put into their own PixelGroups.

Pixels are compared to one another using the operation given by the grouper parameter, and put into groups if they are within a set number of standard deviations of the group's mean, which is also determined by the grouper. The grouper has a parameter sigma0 which is the minimum standard deviation of a group. (Any deviation smaller than sigma0 will be set equal to sigma0.) Using a small sigma0 will tend to create many groups, each containing a small range of pixel values. Using a large sigma0 will tend to create fewer, larger groups, with a wide range of pixel values in each.

There are three steps in the process:

Preliminary groups are created from statistically similar pixels. AutoGroup keeps track of the mean and standard deviation of the groups that it's creating. It selects a pixel at random and sees if that pixel's value is within delta standard deviations of the mean of any existing pixel group (where "existing" means any of the groups already created during this call to AutoGroup). If it is, then the pixel is added to the group and the group's mean and deviation are recomputed. If the pixel is close to the mean of more than one group, the closest one is used (ie, the one whose mean is the fewest standard deviations from the pixel value). After recomputing the mean, the group is compared to all other groups, and if it's within gamma deviations of one, the two groups are merged. Again, if more than one is found, the closest one is used. The mean and deviation of the merged group is recomputed and checked against the remaining groups recursively until no more merges are found.

If the pixel being examined is not within delta standard deviations of any group, a new group is created for it, and a standard deviation of sigma0 is imposed. If at any time adding a pixel brings the standard deviation (or one if its components, if it's a vector) below sigma0, the deviation is reset to sigma0.
After putting pixels into preliminary groups, each group is split into contiguous pieces, where each piece is a single connected set of pixels. Any sets containing fewer than minsize pixels are absorbed into the neighboring groups. If there are multiple groups neighboring a pixel, the pixel is added to the group with the nearest mean, measured in terms of the group's standard deviation.
If the parameter contiguous is false, the groups that were split in the previous step are reassembled, so the final PixelGroups may be discontiguous.
Finally, the groups are sorted by size, largest to smallest, and each group is given a name, determined by the name_template parameter. A %n in the name will be replaced by an integer, starting from 0. If name_template does not contain %n, one will be appended to it.


OOF.PixelGroup.AddSelection		OOF.PixelGroup.Clear