i.segment.uspo
Unsupervised segmentation parameter optimization
i.segment.uspo [-kha] group=name [maps=name [,name,...]] [seeds=name] [output=name] [segment_map=name] regions=name [,name,...] segmentation_method=string [thresholds=float [,float,...]] [threshold_start=float] [threshold_stop=float] [threshold_step=float] [minsizes=integer [,integer,...]] [minsize_start=integer] [minsize_stop=integer] [minsize_step=integer] [radiuses=float [,float,...]] [radius_start=float] [radius_stop=float] [radius_step=float] [hrs=float [,float,...]] [hr_start=float] [hr_stop=float] [hr_step=float] [autocorrelation_indicator=string] [optimization_function=string] [f_function_alpha=float] [number_best=integer] [memory=integer] [processes=integer] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]
Example:
i.segment.uspo group=name regions=name segmentation_method=region_growing thresholds=float
grass.script.run_command("i.segment.uspo", group, maps=None, seeds=None, output=None, segment_map=None, regions, segmentation_method="region_growing", thresholds=None, threshold_start=None, threshold_stop=None, threshold_step=None, minsizes=None, minsize_start=None, minsize_stop=None, minsize_step=None, radiuses=None, radius_start=None, radius_stop=None, radius_step=None, hrs=None, hr_start=None, hr_stop=None, hr_step=None, autocorrelation_indicator="morans", optimization_function="sum", f_function_alpha=1, number_best=1, memory=300, processes=1, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)
Example:
gs.run_command("i.segment.uspo", group="name", regions="name", segmentation_method="region_growing", thresholds=float)
Parameters
group=name [required]
Group to use for segmentation
maps=name [,name,...]
Raster band(s) for which to calculate variance (default: all group members)
seeds=name
Seeds for segmentation
output=name
Name for output file (- for standard output)
segment_map=name
Prefix for "best" output segmentation map per region
regions=name [,name,...] [required]
Regions in which to analyze the variance
segmentation_method=string [required]
Segmentation method to use
Allowed values: region_growing, mean_shift
Default: region_growing
thresholds=float [,float,...]
Thresholds to test
threshold_start=float
Lowest threshold to test
threshold_stop=float
Threshold at which to stop (not included)
threshold_step=float
Step to use between thresholds
minsizes=integer [,integer,...]
Minimum number of cells in a segment to test
minsize_start=integer
Lowest minimum segment size to test
minsize_stop=integer
Value for minimum segment size at which to stop (not included)
minsize_step=integer
Step to use between minimum segment sizes
radiuses=float [,float,...]
Radiuses to test
radius_start=float
Lowest radius to test
radius_stop=float
Radius at which to stop (not included)
radius_step=float
Step to use between radiuses
hrs=float [,float,...]
Spectral bandwidths to test
hr_start=float
Lowest spectral bandwith to test
hr_stop=float
Spectral bandwith at which to stop (not included)
hr_step=float
Step to use between spectral bandwidths
autocorrelation_indicator=string
Indicator for measuring inter-segment heterogeneity
Allowed values: morans, geary
Default: morans
optimization_function=string
Optimization function used to determine "best" parameters
Allowed values: sum, f
Default: sum
f_function_alpha=float
Alpha value used for F-measure optimization function
Default: 1
number_best=integer
Number of desired best parameter values and maps
Default: 1
memory=integer
Total memory (in MB) to allocate (will be divided by processes)
Default: 300
processes=integer
Number of processes to run in parallel
Default: 1
-k
Keep all segmented maps
-h
Use hierarchical segmentation
-a
Use adaptive spectral bandwidth (with mean shift)
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--qq
Very quiet module output
--ui
Force launching GUI dialog
group : str, required
Group to use for segmentation
Used as: input, group, name
maps : str | list[str], optional
Raster band(s) for which to calculate variance (default: all group members)
Used as: input, raster, name
seeds : str, optional
Seeds for segmentation
Used as: input, raster, name
output : str, optional
Name for output file (- for standard output)
Used as: output, file, name
segment_map : str, optional
Prefix for "best" output segmentation map per region
Used as: output, raster, name
regions : str | list[str], required
Regions in which to analyze the variance
Used as: input, region, name
segmentation_method : str, required
Segmentation method to use
Allowed values: region_growing, mean_shift
Default: region_growing
thresholds : float | list[float] | str, optional
Thresholds to test
threshold_start : float, optional
Lowest threshold to test
threshold_stop : float, optional
Threshold at which to stop (not included)
threshold_step : float, optional
Step to use between thresholds
minsizes : int | list[int] | str, optional
Minimum number of cells in a segment to test
minsize_start : int, optional
Lowest minimum segment size to test
minsize_stop : int, optional
Value for minimum segment size at which to stop (not included)
minsize_step : int, optional
Step to use between minimum segment sizes
radiuses : float | list[float] | str, optional
Radiuses to test
radius_start : float, optional
Lowest radius to test
radius_stop : float, optional
Radius at which to stop (not included)
radius_step : float, optional
Step to use between radiuses
hrs : float | list[float] | str, optional
Spectral bandwidths to test
hr_start : float, optional
Lowest spectral bandwith to test
hr_stop : float, optional
Spectral bandwith at which to stop (not included)
hr_step : float, optional
Step to use between spectral bandwidths
autocorrelation_indicator : str, optional
Indicator for measuring inter-segment heterogeneity
Allowed values: morans, geary
Default: morans
optimization_function : str, optional
Optimization function used to determine "best" parameters
Allowed values: sum, f
Default: sum
f_function_alpha : float, optional
Alpha value used for F-measure optimization function
Default: 1
number_best : int, optional
Number of desired best parameter values and maps
Default: 1
memory : int, optional
Total memory (in MB) to allocate (will be divided by processes)
Default: 300
processes : int, optional
Number of processes to run in parallel
Default: 1
flags : str, optional
Allowed values: k, h, a
k
Keep all segmented maps
h
Use hierarchical segmentation
a
Use adaptive spectral bandwidth (with mean shift)
overwrite: bool, optional
Allow output files to overwrite existing files
Default: False
verbose: bool, optional
Verbose module output
Default: False
quiet: bool, optional
Quiet module output
Default: False
superquiet: bool, optional
Very quiet module output
Default: False
DESCRIPTION
i.segment.uspo provides unsupervised segmentation parameter optimization for i.segment determined by the compromise between intra-segment variance and inter-segment spatial autocorrelation.
The module runs segmentation across a user defined set of thresholds and minimum segment sizes, as well, for the mean shift algorithm, a set of spectral and spatial bandwiths. For the mean shift algorithm, you can also activate adaptive bandwidth using the -a flag.
The user provides an imagery group and the name of an output text file where parameter and optimization values for all tested segmentations are stored. The user can either give a list of thresholds and minimum sizes, or provides start, stop and step values for each. In addition, the user can provide a list of named regions for which to test the segmentation. This allows to not test the entire image, but rather to test specific areas in the image that might be characterstic for specific types of land cover.
The module then selects the parameters providing the highest values of a given optimization function. The number of "best" parameter combinations to provide to the user per region is defined by number_best.
Two optimization functions are available via the optimization_function parameter: A simple sum of the normalized criteria values as defined by Espindola et al (2006), or the F-function as defined by Johnson et al (2015). When using the F-function, the user can determine the f_function_alpha value which determines the relative weight of the intra-segment variance as compared to the inter-segment spatial autocorrelation. A value of 0.5 gives the former half weight of the latter, A value of 2 gives the former double weight than the latter.
The optimization functions use intra-segment variance and inter-segment spatial autocorrelation. For the latter, the user can chose to use either Moran's I or Geary's C.
The user can chose between non-hierarchical (default) and hierarchical segmentation using the h flag. The latter uses each segmentation at a given threshold level as seed for the segmentation at the next threshold level within a given minimum segment size. Note that this leads to less optimal parallelization as for a given minsize, all segmentations have to be done sequentially (see below).
The segment_map parameter allows to provide a basename for keeping the number_best best segmentations for each given region according to the optimization function. The resulting map names will be a combination of this basename, the region, the threshold, the minsize and the rank of the map within the region according to its optimization criteria value.
The module uses high-level parallelization (running different segmentations in parallel and then running the collection of parameter values in parallel). The parameter processes allows to define how many processes should be run in parallel. Note that when using hierarchical segmentation the number of parallel processes is limited to the number of different mininum segment sizes to test.
The k flag allows to keep all segmentation maps created during the process.
NOTES
The module depends on the addon r.neighborhoodmatrix which needs to be installed.
Any unsupervised optimization can at best be a support to the user. Visual and other types of validation of the results, possibly comparing several of the "best" solutions, remain necessary.
Even though the module allows the user to test different minsizes, it is probably better to run the module with minsizes=1 and then adapt the minsize in the final run of i.segment depending on the desired minimum mapping unit.
In hierarchical segmentation mode, each segmentation is used as seed for the next hierarchical level. This means that these segmentations have to be run sequentially. Currently, parallelization is thus only used if more than one value was given for minsize. In a future version, parallelization should optionally be run by region if the number of regions is larger than the number of different minsize values.
EXAMPLE
g.region -au n=220767 s=220392 w=638129 e=638501 res=1 save=region1
g.region -au n=222063 s=221667 w=637659 e=638058 res=1 save=region2
i.group ortho input=ortho_2001_t792_1m
i.segment.uspo group=ortho regions=region1,region2 \
output=ortho_parameters.csv segment_map=ortho_uspo \
threshold_start=0.02 threshold_stop=0.21 threshold_step=0.02 \
minsizes=5,10,15 number_best=5 processes=4 memory=4000
REFERENCES
G. M. Espindola , G. Camara , I. A. Reis , L. S. Bins , A. M. Monteiroi (2006), Parameter selection for region-growing image segmentation algorithms using spatial autocorrelation, International Journal of Remote Sensing, Vol. 27, Iss. 14, pp. 3035-3040, https://doi.org/10.1080/01431160600617194
B. A. Johnson, M. Bragais, I. Endo, D. B. Magcale-Macandog, P. B. M. Macandog (2015), Image Segmentation Parameter Optimization Considering Within- and Between-Segment Heterogeneity at Multiple Scale Levels: Test Case for Mapping Residential Areas Using Landsat Imagery, ISPRS International Journal of Geo-Information, 4(4), pp. 2292-2305, https://doi.org/10.3390/ijgi4042292
SEE ALSO
i.segment, i.group, i.segment.hierarchical, r.neighborhoodmatrix
AUTHOR
Moritz Lennert
SOURCE CODE
Available at: i.segment.uspo source code
(history)
Latest change: Thursday Feb 20 13:02:26 2025 in commit 53de819