i.cutlines
Creates semantically meaningful tile borders
i.cutlines input=name output=name number_lines=integer edge_detection=string [existing_cutlines=name [,name,...]] no_edge_friction=integer lane_border_multiplier=integer [min_tile_size=integer] [zc_threshold=float] [zc_width=integer] [canny_low_threshold=float] [canny_high_threshold=float] [canny_sigma=float] [tile_width=integer] [tile_height=integer] [overlap=integer] processes=integer memory=integer [--overwrite] [--verbose] [--quiet] [--qq] [--ui]
Example:
i.cutlines input=name output=name number_lines=integer edge_detection=zc no_edge_friction=5 lane_border_multiplier=10 processes=1 memory=300
grass.script.run_command("i.cutlines", input, output, number_lines, edge_detection="zc", existing_cutlines=None, no_edge_friction=5, lane_border_multiplier=10, min_tile_size=None, zc_threshold=1, zc_width=9, canny_low_threshold=3, canny_high_threshold=10, canny_sigma=2, tile_width=None, tile_height=None, overlap=1, processes=1, memory=300, overwrite=False, verbose=False, quiet=False, superquiet=False)
Example:
gs.run_command("i.cutlines", input="name", output="name", number_lines=integer, edge_detection="zc", no_edge_friction=5, lane_border_multiplier=10, processes=1, memory=300)
Parameters
input=name [required]
Raster map to use as input for tiling
output=name [required]
Name of output vector map with cutline polygons
number_lines=integer [required]
Number of tile border lines in each direction
edge_detection=string [required]
Edge detection algorithm to use
Allowed values: zc, canny
Default: zc
existing_cutlines=name [,name,...]
Input vector maps with existing cutlines
Or data source(s) for direct OGR access
no_edge_friction=integer [required]
Additional friction for non-edge pixels
Default: 5
lane_border_multiplier=integer [required]
Multiplier for borders of lanes compared to non-edge pixels
Default: 10
min_tile_size=integer
Minimum size of tiles in map units
zc_threshold=float
Sensitivity of Gaussian filter (i.zc)
Default: 1
zc_width=integer
x-y extent of the Gaussian filter (i.zc)
Default: 9
canny_low_threshold=float
Low treshold for edges (i.edge)
Default: 3
canny_high_threshold=float
High treshold for edges (i.edge)
Default: 10
canny_sigma=float
Kernel radius (i.edge)
Default: 2
tile_width=integer
Width of tiles for tiled edge detection (pixels)
tile_height=integer
Height of tiles for tiled edge detection (pixels)
overlap=integer
Overlap between tiles for tiled edge detection (pixels)
Default: 1
processes=integer [required]
Number of parallel processes
Default: 1
memory=integer [required]
RAM memory available (in MB)
Default: 300
--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
input : str, required
Raster map to use as input for tiling
Used as: input, raster, name
output : str, required
Name of output vector map with cutline polygons
Used as: output, vector, name
number_lines : int, required
Number of tile border lines in each direction
edge_detection : str, required
Edge detection algorithm to use
Allowed values: zc, canny
Default: zc
existing_cutlines : str | list[str], optional
Input vector maps with existing cutlines
Or data source(s) for direct OGR access
Used as: input, vector, name
no_edge_friction : int, required
Additional friction for non-edge pixels
Default: 5
lane_border_multiplier : int, required
Multiplier for borders of lanes compared to non-edge pixels
Default: 10
min_tile_size : int, optional
Minimum size of tiles in map units
zc_threshold : float, optional
Sensitivity of Gaussian filter (i.zc)
Default: 1
zc_width : int, optional
x-y extent of the Gaussian filter (i.zc)
Default: 9
canny_low_threshold : float, optional
Low treshold for edges (i.edge)
Default: 3
canny_high_threshold : float, optional
High treshold for edges (i.edge)
Default: 10
canny_sigma : float, optional
Kernel radius (i.edge)
Default: 2
tile_width : int, optional
Width of tiles for tiled edge detection (pixels)
tile_height : int, optional
Height of tiles for tiled edge detection (pixels)
overlap : int, optional
Overlap between tiles for tiled edge detection (pixels)
Default: 1
processes : int, required
Number of parallel processes
Default: 1
memory : int, required
RAM memory available (in MB)
Default: 300
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.cutlines tiles the images into tiles with irregular borders that avoid cutting through meaningful objects. This allows tiling an image for parallel processing while avoiding border effects.
The approach used in i.cutlines is inspired by Soares et al (2016). The module first uses an edge detection algorithm (which the user can chose with the edge_detection parameter) to identify edges in the image. It then uses r.cost and r.drain to draw lines through the image, following edges when possible and going straight when there are none.
The user can determine the number of lines desired (number_lines) in each direction and the friction associated with pixels which are not on an edge detected in the image (no_edge_friction). The higher this value, the more the module will follow the detected edges.
In order to avoid that all lines gather into one single lowest cost path, the module defines a lane for each desired line. The parameter lane_border_multiplier defines the a multiplier of the no_edge_friction value, in order to define the cost to cross that line, i.e. the lower the value, the more likely cutlines will join each other across lanes. Output is in the form of vector polygon tiles. The user can decide a minimum size defined in map units (min_tile_size). Tiles smaller than that size will be merged with the neighboring tile they share the longest border with.
The user can provide a series of auxiliary vector maps which contain existing cutlines (roads, boundaries, etc) that the module should take into account (existing_cutlines). These can be either lines or polygons. The module will transform all to potential cutlines.
For edge detection the user can chose between the i.zc module or the i.edge addon. For the former, the user can determine the zc_threshold and the zc_width parameters. For the latter, the canny_low_threshold, canny_high_threshold and canny_sigma parameters. See the manual page of the respective modules for details about these parameters which might need tuning to fit to the specific image. As these modules read the entire image into RAM, i.cutlines allows the user to run split the image into rectangular tiles and to process each tile separately. Tiles can be defined with the tile_width, tile_height and overlap parameters. If processes is higher than one, these tiles will be processed in parallel as will the r.cost calls for the two directions.
The memory parameter determines the memory used both for the r.cost runs.
NOTES
Until GRASS GIS version 7.4 included, there was a parameter name conflict between i.zc and the GridModule class in pygrass. For older GRASS GIS versions tiled edge detection is thus only possible with i.edge.
EXAMPLES
Zero-crossing edge detection
Using the default i.zc edge detection without tiling, default parameters and 10 horizontal and 10 vertical cutlines, creating vector polygon output:
# ortho photo subarea
g.region raster=ortho_2001_t792_1m n=221070 s=219730 -p
i.cutlines input=ortho_2001_t792_1m number_lines=10 output=ortho_tiles_zc
Irregular vector tiles created for the NC demo data set orthophoto
(default setting)
Canny edge detection
Using the i.edge Canny edge detection with tiling and (needed) tile overlap, increased memory, two parallel processes and 10 horizontal and 10 vertical cutlines, creating vector polygon output:
# ortho photo subarea
g.region raster=ortho_2001_t792_1m n=221070 s=219730 -p
i.cutlines input=ortho_2001_t792_1m number_lines=10 edge_detection=canny \
tile_width=500 tile_height=500 overlap=10 memory=2000 processes=2 output=ortho_tiles_canny
Irregular vector tiles created for the NC demo data set orthophoto
(Canny edge detection)
REFERENCES
Soares, Anderson Reis, Thales Sehn Körting, and Leila Maria Garcia Fonseca. 2016. "Improvements of the Divide and Segment Method for Parallel Image Segmentation." Revista Brasileira de Cartografia 68 (6), http://www.lsie.unb.br/rbc/index.php/rbc/article/view/1602
SEE ALSO
i.zc, i.edge, r.tile, v.mkgrid, i.segment
AUTHOR
Moritz Lennert
SOURCE CODE
Available at: i.cutlines source code
(history)
Latest change: Thursday Feb 20 13:02:26 2025 in commit 53de819