Module Vectorize
See also

Aim of module

Performs raster-to-vector conversion and exports polyline geometries.

General description

The process of converting raster data to vector topology is referred to as {Vectorization}. The Module Vectorize accepts raster data in all GDAL supported data formats (inFile) and writes the results to an output vector file (outFile) in either OPALS Datamanager , ESRI shape file or SCOP Winput format (oFormat). Depending on the raster content the vectorization can either generate polygons or polylines. Within the module Vectorize this can be controlled by the user via the procMode parameter. The following modes are supported:

  • toPolyline: If the input raster data source contains linear, skeleton-like shapes, this processing mode produces polyline vector shapes. All valid nonzero raster pixels are considered as feature pixels (foreground) and all other pixels as background. Neighbouring feature pixels are concatenated to a polyline until either the no bordering pixels are present (free line end) or a junction (i.e. a pixel with more than two outgoing segments) is detected. Please note, that line segments always connect neighbouring pixel centres.
  • toPolygon: In this processing mode, the outer boundary of concatenated feature pixels are returned as polygon shapes. Please note, that polygon vectorization is currently implemented in Module Contouring and is not yet part of Module Vectorize

Vector-to-Polyline mode

For deriving polyline shapes the following algorithm is applied:

  • Derivation of feature pixel list: In a first step all feature pixels together with their list of outgoing segments are extracted by traversing the entire raster data set with a 3x3 kernel. Starting from the central pixel within the kernel, first all axis parallel pixel neighbours (i.e. left, right, up, down) are considered. Diagonal pixel connections (top left, top right, bottom right, bottom left) are added if no axis parallel neighbours are present (i.e. both axis parallel neighbour pixels are background). Figure 1a illustrates this general rule.
  • Merging of line consecutive segments: In a second step the list (map) of feature pixels and outgoing segments is analysed and consecutive segments are merged. The algorithm first locates free ending line pixels or junction pixels (also denoting a line end) and neighbouring segments are merged into a single polyline until a corresponding free line end or junction is found. Figure 1b (simple y-junction), 1c (complex star-junction) and 1d (ladder-type junctions) illustrate the behaviour. The individual colours indicate individual polylines.
  • Rung removal: As can be seen in Figure 1d, the two parallel straight lines crossing the raster from top left to bottom right are "disturbed" by perpendicular segments like rungs of a ladder. These one-pixel-diagonal segments are automatically removed if the optional parameter suppressRungs is activated. The following preconditions must be fulfilled for such a line segment to be removed: (i) the segement is diagonal, (ii) the segment runs between two junctions, (iii) the segment length is 1 (pixel), and (iv) both birectional diagonal neighbour pixels are background.
Fig 1: (a) simple line; (b) y-junction; (c) star-junction; (d) ladder-junctions

The following Figure 2 shows a more complex example and illustrates the effect of the suppressRungs parameter.

Fig 2: vectorized line network (a) without and (b) with removal of rungs

Parameter description

-inFileinput grid/raster file
Type: opals::Path
Remarks: mandatory
Import grid/raster image in GDAL supported format,
-outFileoutput vector file
Type: opals::Path
Remarks: estimable
Path of the vector file containing vectorized line/polygon data in either ODM or ESRI shape file format.
Estimation rule: The current directory and the name (body) of the input file are used as file name basis. In addition, the postfix and the extension are constructed accodingto the specified vectorization type (i.e., '_polyline' or '_polygon') and oFormat (e.g. '.shp').
-oFormatvector file format [odm, shp, wnp]
Type: opals::String
Remarks: estimable
Estimation rule: The output format is estimated based on the extension of the output file (*.odm->OPALS Datamanager, *.shp->ESRI shape, *.wnp->SCOP Winput).
-procModeprocessing mode [toPolyline/toPolygon]
Type: opals::VectorizationMode
Remarks: default=toPolyline
Possible values:  
  toPolyline ... converts a grid/raster to polyline topology connecting the cell centers
Speizifies the vectorization mode. '_toPolyline' converts the raster to line topology by connecting the cell centers. 'to_polygon' returns the boundary of connected cells as (closed) polygons.
-suppressRungsremoval of 1-pixel-diagonal line segments
Type: bool
Remarks: optional
To (de)activate the suppression of short, diagonal line segements in polyline vectorization. Rungs occur when parallel diagonal pixel lines are present in the input raster. The opposing lines are touching each other in a single point of the respective pixel boundaries. This willgenerally create a line segment. These one-pixel-diagonal line segments are removed if no further pixel is found in the bidirectional extension of the line segment.


The data for the examples presented in this section are located in the directory $OPALS_ROOT/demo/ of the OPALS distribution.

Examples Vector-to-Polyline conversion

The first example uses standard parameters to perform the Vector-to-Polyline conversion.

opalsVectorize -inFile lineNetwork.asc

The resulting OPALS Datamanager file (lineNetwort.odm) can be exported to any vector file format via opalsExport. To directly generate an ESRI shape file either specify the output format or the entire output file name with .shp extension. The following commands both produce the same result file, correspond to Figure 2a.

opalsVectorize -procMode toPolyline -inFile lineNetwork.asc -oFormat shp
opalsVectorize -procMode toPolyline -inFile lineNetwork.asc -outFile lineNetwork.shp

To remove short rungs, as illustrated in Figure 2b, activate suppressRungs.

opalsVectorize -procMode toPolyline -inFile lineNetwork.asc -outFile lineNetwork_noRungs.shp -suppressRungs true


opalsVectorize is the executable file of Module Vectorize
Definition: ModuleExecutables.hpp:243
@ suppressRungs
remove all one-pixel-diagonal line elements (opalsVectorize, toPolyline)
@ procMode
processing mode
@ toPolyline
converts a grid/raster to polyline topology connecting the cell centers