Data Tools

AddPointCoordinatesToTable

This tool modifies the attribute table of a vector of POINT ShapeType by adding two fields, XCOORD and YCOORD, containing each point's X and Y coordinates respectively.

Parameters:

Flag Description
-i, --input Input vector Points file

Python function:

wbt.add_point_coordinates_to_table(
    i, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=AddPointCoordinatesToTable -v ^
--wd="/path/to/data/" --input=points.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/09/2018

Last Modified: 12/10/2018

CleanVector

This tool can be used to remove all features in Shapefiles that are of the null ShapeType. It also removes line features with fewer than two vertices and polygon features with fewer than three vertices.

Parameters:

Flag Description
-i, --input Input vector file
-o, --output Output vector file

Python function:

wbt.clean_vector(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=CleanVector -v --wd="/path/to/data/" ^
-i=input.shp -o=output.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 30/06/2019

Last Modified: 27/05/2020

ConvertNodataToZero

This tool can be used to change the value within the grid cells of a raster file (--input) that contain NoData to zero. The most common reason for using this tool is to change the background region of a raster image such that it can be included in analysis since NoData values are usually ignored by by most tools. This change, however, will result in the background no longer displaying transparently in most GIS. This change can be reversed using the SetNoDataValue tool.

See Also: SetNoDataValue, IsNoData

Parameters:

Flag Description
-i, --input Input raster file
-o, --output Output raster file

Python function:

wbt.convert_nodata_to_zero(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ConvertNodataToZero -v ^
--wd="/path/to/data/" --input=in.tif -o=NewRaster.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 11/07/2017

Last Modified: 12/10/2018

ConvertRasterFormat

This tool converts raster data from one format to another. It determines input/output raster formats based on extensions, but due to file extension naming collisions, it would be good to add user hints. For example, the extension 'grd' could belong to a SurferAscii or a Surfer7Binary. This is more important for distinguishing output files since input files can be read and distiguishing features idenfitied from the file structure. At the moment, this tool does not support user hints however.

Parameters:

Flag Description
-i, --input Input raster file
-o, --output Output raster file

Python function:

wbt.convert_raster_format(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ConvertRasterFormat -v ^
--wd="/path/to/data/" --input=DEM.tif -o=output.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: July 6, 2017

Last Modified: 12/10/2018

CsvPointsToVector

This tool can be used to import a series of points contained within a comma-separated values (*.csv) file (--input) into a vector shapefile of a POINT ShapeType. The input file must be an ASCII text file with a .csv extensions. The tool will automatically detect the field data type; for numeric fields, it will also determine the appropriate length and precision. The user must specify the x-coordinate (--xfield) and y-coordiante (--yfield) fields. All fields are imported as attributes in the output (--output) vector file. The tool assumes that the first line of the file is a header line from which field names are retreived.

See Also: MergeTableWithCsv, ExportTableToCsv

Parameters:

Flag Description
-i, --input Input CSV file (i.e. source of data to be imported)
-o, --output Output vector file
--xfield X field number (e.g. 0 for first field)
--yfield Y field number (e.g. 1 for second field)
--epsg EPSG projection (e.g. 2958)

Python function:

wbt.csv_points_to_vector(
    i, 
    output, 
    xfield=0, 
    yfield=1, 
    epsg=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=CsvPointsToVector -v ^
--wd="/path/to/data/" -i=points.csv -o=points.shp --xfield=0 ^
--yfield=1 --epsg=4326 

Source code on GitHub

Author: Prof. John Lindsay

Created: 07/08/2019

Last Modified: 28/01/2020

ExportTableToCsv

This tool can be used to export a vector's attribute table to a comma separated values (CSV) file. CSV files stores tabular data (numbers and text) in plain-text form such that each row corresponds to a record and each column to a field. Fields are typically separated by commas within records. The user must specify the name of the vector (and associated attribute file), the name of the output CSV file, and whether or not to include the field names as a header column in the output CSV file.

See Also: MergeTableWithCsv

Parameters:

Flag Description
-i, --input Input vector file
-o, --output Output raster file
--headers Export field names as file header?

Python function:

wbt.export_table_to_csv(
    i, 
    output, 
    headers=True, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ExportTableToCsv -v ^
--wd="/path/to/data/" -i=lines.shp -o=output.csv --headers 

Source code on GitHub

Author: Dr. John Lindsay

Created: 24/04/2018

Last Modified: 18/10/2019

JoinTables

This tool can be used to join (i.e. merge) a vector's attribute table with a second table. The user must specify the name of the vector file (and associated attribute file) as well as the primary key within the table. The primary key (--pkey flag) is the field within the table that is being appended to that serves as the identifier. Additionally, the user must specify the name of a second vector from which the data appended into the first table will be derived. The foreign key (--fkey flag), the identifying field within the second table that corresponds with the data contained within the primary key in the table, must be specified. Both the primary and foreign keys should either be strings (text) or integer values. Fields containing decimal values are not good candidates for keys. Lastly, the names of the field within the second file to include in the merge operation can also be input (--import_field). If the --import_field field is not input, all fields in the attribute table of the second file, that are not the foreign key nor FID, will be imported to the first table.

Merging works for one-to-one and many-to-one database relations. A one-to-one relations exists when each record in the attribute table corresponds to one record in the second table and each primary key is unique. Since each record in the attribute table is associated with a geospatial feature in the vector, an example of a one-to-one relation may be where the second file contains AREA and PERIMETER fields for each polygon feature in the vector. This is the most basic type of relation. A many-to-one relation would exist when each record in the first attribute table corresponds to one record in the second file and the primary key is NOT unique. Consider as an example a vector and attribute table associated with a world map of countries. Each country has one or more more polygon features in the shapefile, e.g. Canada has its mainland and many hundred large islands. You may want to append a table containing data about the population and area of each country. In this case, the COUNTRY columns in the attribute table and the second file serve as the primary and foreign keys respectively. While there may be many duplicate primary keys (all of those Canadian polygons) each will correspond to only one foreign key containing the population and area data. This is a many-to-one relation. The JoinTables tool does not support one-to-many nor many-to-many relations.

See Also: MergeTableWithCsv, ReinitializeAttributeTable, ExportTableToCsv

Parameters:

Flag Description
--i1, --input1 Input primary vector file (i.e. the table to be modified)
--pkey Primary key field
--i2, --input2 Input foreign vector file (i.e. source of data to be imported)
--fkey Foreign key field
--import_field Imported field (all fields will be imported if not specified)

Python function:

wbt.join_tables(
    input1, 
    pkey, 
    input2, 
    fkey, 
    import_field, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=JoinTables -v --wd="/path/to/data/" ^
--i1=properties.shp --pkey=TYPE --i2=land_class.shp ^
--fkey=VALUE --import_field=NEW_VALUE 

Source code on GitHub

Author: Prof. John Lindsay

Created: 07/10/2018

Last Modified: 22/11/2018

LinesToPolygons

This tool converts vector polylines into polygons. Note that this tool will close polygons that are open and will ensure that the first part of an input line is interpreted as the polygon hull and subsequent parts are considered holes. The tool does not examine input lines for line crossings (self intersections), which are topological errors.

See Also: PolygonsToLines

Parameters:

Flag Description
-i, --input Input vector line file
-o, --output Output vector polygon file

Python function:

wbt.lines_to_polygons(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=LinesToPolygons -v ^
--wd="/path/to/data/" -i=input.shp -o=output.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/09/2018

Last Modified: 12/10/2018

MergeTableWithCsv

This tool can be used to merge a vector's attribute table with data contained within a comma separated values (CSV) text file. CSV files stores tabular data (numbers and text) in plain-text form such that each row is a record and each column a field. Fields are typically separated by commas although the tool will also support seimi-colon, tab, and space delimited files. The user must specify the name of the vector (and associated attribute file) as well as the primary key within the table. The primary key (--pkey flag) is the field within the table that is being appended to that serves as the unique identifier. Additionally, the user must specify the name of a CSV text file with either a *.csv or *.txt extension. The file must possess a header row, i.e. the first row must contain information about the names of the various fields. The foreign key (--fkey flag), that is the identifying field within the CSV file that corresponds with the data contained within the primary key in the table, must also be specified. Both the primary and foreign keys should either be strings (text) or integer values. Fields containing decimal values are not good candidates for keys. Lastly, the user may optionally specify the name of a field within the CSV file to import in the merge operation (--import_field flag). If this flag is not specified, all of the fields within the CSV, with the exception of the foreign key, will be appended to the attribute table.

Merging works for one-to-one and many-to-one database relations. A one-to-one relations exists when each record in the attribute table corresponds to one record in the second table and each primary key is unique. Since each record in the attribute table is associated with a geospatial feature in the vector, an example of a one-to-one relation may be where the second file contains AREA and PERIMETER fields for each polygon feature in the vector. This is the most basic type of relation. A many-to-one relation would exist when each record in the first attribute table corresponds to one record in the second file and the primary key is NOT unique. Consider as an example a vector and attribute table associated with a world map of countries. Each country has one or more more polygon features in the shapefile, e.g. Canada has its mainland and many hundred large islands. You may want to append a table containing data about the population and area of each country. In this case, the COUNTRY columns in the attribute table and the second file serve as the primary and foreign keys respectively. While there may be many duplicate primary keys (all of those Canadian polygons) each will correspond to only one foreign key containing the population and area data. This is a many-to-one relation. The JoinTables tool does not support one-to-many nor many-to-many relations.

See Also: JoinTables, ReinitializeAttributeTable, ExportTableToCsv

Parameters:

Flag Description
-i, --input Input primary vector file (i.e. the table to be modified)
--pkey Primary key field
--csv Input CSV file (i.e. source of data to be imported)
--fkey Foreign key field
--import_field Imported field (all fields will be imported if not specified)

Python function:

wbt.merge_table_with_csv(
    i, 
    pkey, 
    csv, 
    fkey, 
    import_field=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MergeTableWithCsv -v ^
--wd="/path/to/data/" -i=properties.shp --pkey=TYPE ^
--csv=land_class.csv --fkey=VALUE ^
--import_field=NEW_VALUE
>>./whitebox_tools -r=MergeTableWithCsv ^
-v --wd="/path/to/data/" -i=properties.shp --pkey=TYPE ^
--csv=land_class.csv --fkey=VALUE 

Source code on GitHub

Author: Prof. John Lindsay

Created: 11/10/2018

Last Modified: 09/03/2020

MergeVectors

Combines two or more input vectors of the same ShapeType creating a single, new output vector. Importantly, the attribute table of the output vector will contain the ubiquitous file-specific FID, the parent file name, the parent FID, and the list of attribute fields that are shared among each of the input files. For a field to be considered common between tables, it must have the same name and field_type (i.e. data type and precision).

Overlapping features will not be identified nor handled in the merging. If you have significant areas of overlap, it is advisable to use one of the vector overlay tools instead.

The difference between MergeVectors and the Append tool is that merging takes two or more files and creates one new file containing the features of all inputs, and Append places the features of a single vector into another existing (appended) vector.

This tool only operates on vector files. Use the Mosaic tool to combine raster data.

See Also: Append, Mosaic

Parameters:

Flag Description
-i, --inputs Input vector files
-o, --output Output vector file

Python function:

wbt.merge_vectors(
    inputs, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MergeVectors -v --wd="/path/to/data/" ^
-i='polys1.shp;polys2.shp;polys3.shp' -o=out_file.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 01/10/2018

Last Modified: 12/10/2018

ModifyNoDataValue

This tool can be used to modify the value of pixels containing the NoData value for an input raster image. This operation differs from the SetNodataValue tool, which sets the NoData value for an image in the image header without actually modifying pixel values. Also, SetNodataValue does not overwrite the input file, while the ModifyNoDataValue tool does.

See Also: SetNodataValue, ConvertNodataToZero

Parameters:

Flag Description
-i, --input Input raster file
--new_value New NoData value

Python function:

wbt.modify_no_data_value(
    i, 
    new_value="-32768.0", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ModifyNoDataValue -v ^
--wd="/path/to/data/" --input=in.tif --new_value= -999.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 08/09/2019

Last Modified: 08/09/2019

MultiPartToSinglePart

This tool can be used to convert a vector file containing multi-part features into a vector containing only single-part features. Any multi-part polygons or lines within the input vector file will be split into seperate features in the output file, each possessing their own entry in the associated attribute file. For polygon-type vectors, the user may optionally choose to exclude hole-parts from being separated from their containing polygons. That is, with the --exclude_holes flag, hole parts in the input vector will continue to belong to their enclosing polygon in the output vector. The tool will also convert MultiPoint Shapefiles into single Point vectors.

See Also: SinglePartToMultiPart

Parameters:

Flag Description
-i, --input Input vector line or polygon file
-o, --output Output vector line or polygon file
--exclude_holes Exclude hole parts from the feature splitting? (holes will continue to belong to their features in output.)

Python function:

wbt.multi_part_to_single_part(
    i, 
    output, 
    exclude_holes=True, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=MultiPartToSinglePart -v ^
--wd="/path/to/data/" -i=input.shp -o=output.shp ^
--exclude_holes 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/09/2018

Last Modified: 16/06/2020

NewRasterFromBase

This tool can be used to create a new raster with the same coordinates and dimensions (i.e. rows and columns) as an existing base image. The user must specify the name of the base image (--base), the value that the new grid will be filled with (--value flag; default of NoData), and the data type (--data_type flag; options include 'double', 'float', and 'integer'). Notice that the functionality of this tool is the same as multiplying the base image by zero and adding the constant value.

See Also: RasterCellAssignment

Parameters:

Flag Description
-i, --base Input base raster file
-o, --output Output raster file
--value Constant value to fill raster with; either 'nodata' or numeric value
--data_type Output raster data type; options include 'double' (64-bit), 'float' (32-bit), and 'integer' (signed 16-bit) (default is 'float')

Python function:

wbt.new_raster_from_base(
    base, 
    output, 
    value="nodata", 
    data_type="float", 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=NewRasterFromBase -v ^
--wd="/path/to/data/" --base=base.tif -o=NewRaster.tif ^
--value=0.0 --data_type=integer
>>./whitebox_tools ^
-r=NewRasterFromBase -v --wd="/path/to/data/" --base=base.tif ^
-o=NewRaster.tif --value=nodata 

Source code on GitHub

Author: Dr. John Lindsay

Created: July 11, 2017

Last Modified: 12/10/2018

PolygonsToLines

This tool converts vector polygons into polylines, simply by modifying the Shapefile geometry type.

See Also: LinesToPolygons

Parameters:

Flag Description
-i, --input Input vector polygon file
-o, --output Output vector lines file

Python function:

wbt.polygons_to_lines(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=PolygonsToLines -v ^
--wd="/path/to/data/" -i=input.shp -o=output.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 04/09/2018

Last Modified: 12/10/2018

PrintGeoTiffTags

This tool can be used to view the tags contained within a GeoTiff file. Viewing the tags of a GeoTiff file can be useful when trying to import the GeoTiff to different software environments. The user must specify the name of a GeoTiff file and the tag information will be output to the StdOut output stream (e.g. console). Note that tags that contain greater than 100 values will be truncated in the output. GeoKeys will also be interpreted as per the GeoTIFF specification.

Parameters:

Flag Description
-i, --input Input GeoTIFF file

Python function:

wbt.print_geo_tiff_tags(
    i, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=PrintGeoTiffTags -v ^
--wd="/path/to/data/" --input=DEM.tiff 

Source code on GitHub

Author: Dr. John Lindsay

Created: March 2, 2018

Last Modified: March 2, 2018

RasterToVectorLines

This tool converts raster lines features into a vector of the POLYLINE ShapeType. Grid cells associated with line features will contain non-zero, non-NoData cell values. The algorithm requires three passes of the raster. The first pass counts the number of line neighbours of each line cell; the second pass traces line segments starting from line ends (i.e. line cells with only one neighbouring line cell); lastly, the final pass traces any remaining line segments, which are likely forming closed loops (and therefore do not have line ends).

If the line raster contains streams, it is preferable to use the RasterStreamsToVector instead. This tool will use knowledge of flow directions to ensure connections between stream segments at confluence sites, whereas RasterToVectorLines will not.

See Also: RasterToVectorPolygons, RasterToVectorPoints, RasterStreamsToVector

Parameters:

Flag Description
-i, --input Input raster lines file
-o, --output Output raster file

Python function:

wbt.raster_to_vector_lines(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RasterToVectorLines -v ^
--wd="/path/to/data/" -i=lines.tif -o=lines.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 09/10/2018

Last Modified: 12/10/2018

RasterToVectorPoints

Converts a raster data set to a vector of the POINT shapetype. The user must specify the name of a raster file (--input) and the name of the output vector (--output). Points will correspond with grid cell centre points. All grid cells containing non-zero, non-NoData values will be considered a point. The vector's attribute table will contain a field called 'VALUE' that will contain the cell value for each point feature.

See Also: RasterToVectorPolygons, RasterToVectorLines

Parameters:

Flag Description
-i, --input Input raster file
-o, --output Output vector points file

Python function:

wbt.raster_to_vector_points(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RasterToVectorPoints -v ^
--wd="/path/to/data/" --input=points.tif -o=out.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 25/09/2018

Last Modified: 12/10/2018

RasterToVectorPolygons

Converts a raster data set to a vector of the POLYGON geometry type. The user must specify the name of a raster file (--input) and the name of the output (--output) vector. All grid cells containing non-zero, non-NoData values will be considered part of a polygon feature. The vector's attribute table will contain a field called 'VALUE' that will contain the cell value for each polygon feature, in addition to the standard feature ID (FID) attribute.

See Also: RasterToVectorPoints, RasterToVectorLines

Parameters:

Flag Description
-i, --input Input raster file
-o, --output Output vector polygons file

Python function:

wbt.raster_to_vector_polygons(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RasterToVectorPolygons -v ^
--wd="/path/to/data/" --input=points.tif -o=out.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 18/02/2020

Last Modified: 05/03/2020

ReinitializeAttributeTable

Reinitializes a vector's attribute table deleting all fields but the feature ID (FID). Caution: this tool overwrites the input file's attribute table.

Parameters:

Flag Description
-i, --input Input vector file

Python function:

wbt.reinitialize_attribute_table(
    i, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=ReinitializeAttributeTable -v ^
--wd="/path/to/data/" -i=input.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 04/09/2018

Last Modified: 12/10/2018

RemovePolygonHoles

This tool can be used to remove holes from the features within a vector polygon file. The user must specify the name of the input vector file, which must be of a polygon shapetype, and the name of the output file.

Parameters:

Flag Description
-i, --input Input vector polygon file
-o, --output Output vector polygon file

Python function:

wbt.remove_polygon_holes(
    i, 
    output, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=RemovePolygonHoles -v ^
--wd="/path/to/data/" --input=polygons.shp ^
--output=no_holes.shp 

Source code on GitHub

Author: Dr. John Lindsay

Created: 26/09/2018

Last Modified: 12/10/2018

SetNodataValue

This tool will re-assign a user-defined background value in an input raster image the NoData value. More precisely, the NoData value will be changed to the specified background value and any existing grid cells containing the previous NoData value, if it had been defined, will be changed to this new value. Most WhiteboxTools tools recognize NoData grid cells and treat them specially. NoData grid cells are also often displayed transparently by GIS software. The user must specify the names of the input and output rasters and the background value. The default background value is zero, although any numeric value is possible.

This tool differs from the ModifyNoDataValue tool in that it simply updates the NoData value in the raster header, without modifying pixel values. The ModifyNoDataValue tool will update the value in the header, and then modify each existing NoData pixel to contain this new value. Also, SetNodataValue does not overwrite the input file, while the ModifyNoDataValue tool does.

See Also: ModifyNoDataValue, ConvertNodataToZero, IsNoData

Parameters:

Flag Description
-i, --input Input raster file
-o, --output Output raster file
--back_value Background value to set to nodata

Python function:

wbt.set_nodata_value(
    i, 
    output, 
    back_value=0.0, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=SetNodataValue -v --wd="/path/to/data/" ^
-i=in.tif -o=newRaster.tif --back_value=1.0 

Source code on GitHub

Author: Dr. John Lindsay

Created: 10/09/2017

Last Modified: 24/01/2019

SinglePartToMultiPart

This tool can be used to convert a vector file containing single-part features into a vector containing multi-part features. The user has the option to either group features based on an ID Field (--field flag), which is a categorical field within the vector's attribute table. The ID Field should either be of String (text) or Integer type. Fields containing decimal values are not good candidates for the ID Field. If no --field flag is specified, all features will be grouped together into one large multi-part vector.

This tool works for vectors containing either point, line, or polygon features. Since vectors of a POINT ShapeType cannot represent multi-part features, the ShapeType of the output file will be modified to a MULTIPOINT ShapeType if the input file is of a POINT ShapeType. If the input vector is of a POLYGON ShapeType, the user can optionally set the algorithm to search for polygons that should be represented as hole parts. In the case of grouping based on an ID Field, hole parts are polygon features contained within larger polygons of the same ID Field value. Please note that searching for polygon holes may significantly increase processing time for larger polygon coverages.

See Also: MultiPartToSinglePart

Parameters:

Flag Description
-i, --input Input vector line or polygon file
--field Grouping ID field name in attribute table
-o, --output Output vector line or polygon file

Python function:

wbt.single_part_to_multi_part(
    i, 
    output, 
    field=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=SinglePartToMultiPart -v ^
--wd="/path/to/data/" -i=input.shp -o=output.shp ^
--field='COUNTRY' 

Source code on GitHub

Author: Dr. John Lindsay

Created: 27/09/2018

Last Modified: 12/10/2018

VectorLinesToRaster

This tool can be used to convert a vector lines or polygon file into a raster grid of lines. If a vector of one of the polygon ShapeTypes is selected, the resulting raster will outline the polygons without filling these features. Use the VectorPolygonToRaster tool if you need to fill the polygon features.

The user must specify the name of the input vector (--input) and the output raster file (--output). The Field Name (--field) is the field from the attributes table, from which the tool will retrieve the information to assign to grid cells in the output raster. Note that if this field contains numerical data with no decimals, the output raster data type will be INTEGER; if it contains decimals it will be of a FLOAT data type. The field must contain numerical data. If the user does not supply a Field Name parameter, each feature in the raster will be assigned the record number of the feature. The assignment operation determines how the situation of multiple points contained within the same grid cell is handled. The background value is the value that is assigned to grid cells in the output raster that do not correspond to the location of any points in the input vector. This value can be any numerical value (e.g. 0) or the string 'NoData', which is the default.

If the user optionally specifies the --cell_size parameter then the coordinates will be determined by the input vector (i.e. the bounding box) and the specified Cell Size. This will also determine the number of rows and columns in the output raster. If the user instead specifies the optional base raster file parameter (--base), the output raster's coordinates (i.e. north, south, east, west) and row and column count will be the same as the base file. If the user does not specify either of these two optional parameters, the tool will determine the cell size automatically as the maximum of the north-south extent (determined from the shapefile's bounding box) or the east-west extent divided by 500.

See Also: VectorPointsToRaster, VectorPolygonsToRaster

Parameters:

Flag Description
-i, --input Input vector lines file
--field Input field name in attribute table
-o, --output Output raster file
--nodata Background value to set to NoData. Without this flag, it will be set to 0.0
--cell_size Optionally specified cell size of output raster. Not used when base raster is specified
--base Optionally specified input base raster file. Not used when a cell size is specified

Python function:

wbt.vector_lines_to_raster(
    i, 
    output, 
    field="FID", 
    nodata=True, 
    cell_size=None, 
    base=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=VectorLinesToRaster -v ^
--wd="/path/to/data/" -i=lines.shp --field=ELEV -o=output.tif ^
--nodata --cell_size=10.0
        >>./whitebox_tools ^
-r=VectorLinesToRaster -v --wd="/path/to/data/" -i=lines.shp ^
--field=FID -o=output.tif --base=existing_raster.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 18/04/2018

Last Modified: 22/10/2019

VectorPointsToRaster

This tool can be used to convert a vector points file into a raster grid. The user must specify the name of the input vector and the output raster file. The field name (--field) is the field from the attributes table from which the tool will retrieve the information to assign to grid cells in the output raster. The field must contain numerical data. If the user does not supply a field name parameter, each feature in the raster will be assigned the record number of the feature. The assignment operation determines how the situation of multiple points contained within the same grid cell is handled. The background value is zero by default but can be set to NoData optionally using the --nodata value.

If the user optionally specifies the grid cell size parameter (--cell_size) then the coordinates will be determined by the input vector (i.e. the bounding box) and the specified cell size. This will also determine the number of rows and columns in the output raster. If the user instead specifies the optional base raster file parameter (--base), the output raster's coordinates (i.e. north, south, east, west) and row and column count will be the same as the base file.

In the case that multiple points are contained within a single grid cell, the output can be assigned (--assign) the first, last (default), min, max, or sum of the contained points.

See Also: VectorPolygonsToRaster, VectorLinesToRaster

Parameters:

Flag Description
-i, --input Input vector Points file
--field Input field name in attribute table
-o, --output Output raster file
--assign Assignment operation, where multiple points are in the same grid cell; options include 'first', 'last' (default), 'min', 'max', 'sum'
--nodata Background value to set to NoData. Without this flag, it will be set to 0.0
--cell_size Optionally specified cell size of output raster. Not used when base raster is specified
--base Optionally specified input base raster file. Not used when a cell size is specified

Python function:

wbt.vector_points_to_raster(
    i, 
    output, 
    field="FID", 
    assign="last", 
    nodata=True, 
    cell_size=None, 
    base=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=VectorPointsToRaster -v ^
--wd="/path/to/data/" -i=points.shp --field=ELEV -o=output.tif ^
--assign=min --nodata ^
--cell_size=10.0
        >>./whitebox_tools ^
-r=VectorPointsToRaster -v --wd="/path/to/data/" -i=points.shp ^
--field=FID -o=output.tif --assign=last ^
--base=existing_raster.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 19/04/2018

Last Modified: 18/10/2019

VectorPolygonsToRaster

Converts a vector containing polygons into a raster.

Parameters:

Flag Description
-i, --input Input vector polygons file
--field Input field name in attribute table
-o, --output Output raster file
--nodata Background value to set to NoData. Without this flag, it will be set to 0.0
--cell_size Optionally specified cell size of output raster. Not used when base raster is specified
--base Optionally specified input base raster file. Not used when a cell size is specified

Python function:

wbt.vector_polygons_to_raster(
    i, 
    output, 
    field="FID", 
    nodata=True, 
    cell_size=None, 
    base=None, 
    callback=default_callback
)

Command-line Interface:

>>./whitebox_tools -r=VectorPolygonsToRaster -v ^
--wd="/path/to/data/" -i=lakes.shp --field=ELEV -o=output.tif ^
--nodata --cell_size=10.0
        >>./whitebox_tools ^
-r=VectorPolygonsToRaster -v --wd="/path/to/data/" ^
-i=lakes.shp --field=ELEV -o=output.tif ^
--base=existing_raster.tif 

Source code on GitHub

Author: Dr. John Lindsay

Created: 17/04/2018

Last Modified: 18/10/2019