User Guide
Make sure to first install the Geometric Attributes plugin for QGIS which is explained in detail here. To use the Geometric Attributes toolbox, it is important that the dataset are in a projected coordinate system (e.g. UTM) in order to properly analyze the geometry.
If you require any additional help, please check the FAQ and closed issues section before posting a new issue or email.
Note - This user guide is a work in progress. For additional background, please refer to the old user guide available here.
For this example, we will use the Congo River dataset available for download here that was shown in the original article. This dataset contains two files, 1) the 'Congo Bars' that maps the extent of 2164 mid channel bars as individual polygons, and 2) the 'Congo River' that shows the delineation of the multi-threaded Congo River.
Once downloaded, drag and drop the contents within the QGIS map. This tutorial will show a few steps needed to derive geometrical information from polygons, linestrings or raster datasets. Use the navigation menu to the right to find the relevant section.
To analyze the centerlines and all possible paths from start to endpoint along the Congo River polygon, we will use the 'All' function within the 'Centerlines' tool found under the Polygons tab. For the different centerline options, please check out this link. For now, we will use the following options:
1. Polygons -> CongoRiver
2. Centerlines -> All
3. Trim Iterations -> 0.0
4. Simplify Vertex Spacing -> 0.0
5. Densify Vertex Spacing - 250.0
Note - This step may take some time to complete. If it takes too long, consider using the simplify vertex spacing and/or reduce the densify vertex spacing!
Video1.mp4
The last parameter in this tool will create an additional vertex every 250 meters (map units) to increase the resolution/accuracy of the centerline calculations. A simplify vertex spacing can also be used to simplify the geometry in certain locations, if it is super complex and the additional vertices create computational processes.
Based on the output from the tool, visualize the change in distance along the Congo River by following these steps:
1. Right click -> properties
2. Symbology -> Graduated
3. Value -> Distance
4. Classify
Symbology.mp4
For the mid-channel bars of along the Congo River, we are not interested in defining multiple centerlines for each polygon. For this reason we will use the following paramters.
1. Polygons -> CongoBars
2. Centerlines -> Centerlines
3. Trim Iterations -> 0.0
4. Simplify Vertex Spacing -> 0.0
5. Densify Vertex Spacing - 250.0
Optional - Change the Simplify and Densify parameters to check how this impacts the resulting centerline definition!
Video2.mp4
If you examine the 'Distance' field assigned to the centerlines of each Mid-Channel bar, you will notice that there is no order related to the river channel (e.g. increasing or decreasing upstream along the Congo River). To fix this issue, we will use the centerline distance along the Congo River in step #1 to correct the Mid-channel bar distances. To do this, open the 'Directional Centerline' tool found under the Lines Tool and use the following parameters:
1. Centerlines -> Mid-channel bar Centerlines
2. Direction -> Congo River Centerlines
Hopefully, you will now see that the centerlines distances of each mid-channel bar are increasing in the same direction!
Video3.mp4
Once we have the centerlines, we can start to define geometrical attributes along those centerlines (e.g., width, centerline deviation, etc...). To accomplish this we will use the 'Geometric Attributes' tool found under the Polygon tools option. Use the following options:
1. Polygons -> CongoBars
2. Centerlines -> Congo Bars Centerlines
3. Samples -> 100
We will keep the rest of the parameters to their default values. In this case, we will sample 100 perpendicular lines at an even spacing for each mid-channel bar. If you want to have an equal spaced samples by distance, then click the 'Sample By Distance' option. You should notice that several perpendicular lines have been created in the output.
Examine the attribute table, you will notice that there are several new fields including the 'Diff' field which will show how much the right width value is similar to the left, which can be used to quality control the measurements. There are also two other fields, 'WidthL' and 'WidthR' that will show the absolute value of each measurement.
Note - The fast compute option is quicker and will measure width as simply the closest distance from each centerline point to the polygon edge times 2.
Video4.mp4
Creating perpendicular lines to the centerline to measure width and other parameters may create errenous values depending on the accuracy of the original centerline. While increasing the accuracy of the centerline would be ideal by creating a more dense vertex spacing, this may not be computationally reasonable. Another way is to simply delete those values that are likely wrong by using a threshold on the 'Diff' field. Here we will use the following steps:
1. Right click -> Attributes Table
2. Left Click -> Select features using an expression
3. In the blank box type -> "Diff" < 95
4. Left Click -> Select Features
5. Left Click -> Toggle editing mode
6. Left Click -> Delete selected features
7. Left Click -> 'Toggle editing mode' and save your edits
We have improved our geometrical analyses by removing any perpendicular width measurement that differs by more than 5% between the left and right side of the centerline.
Video7.mp4
Once we have defined the centerline and geometrical attributes of the mid-channel bars, we can define the shape of each features as either 1) ellipical/rectangular, 2) sinuous and 3) cresentric with either a linear, asymmetrical or symmetrical pattern to yield 9 possible classes.
Use the 'Shape Analysis' tool found under the Polygons toolbox and use the following parameters.
1. Polygons -> CongoBars
2. Geometric Attributes -> Congo Bars Geometric Attributes
The results show the mid-channel bars as a new polygon shapefile. Examine the new attribute table and you will notice a new field called 'Shape' that will show the geometry of shape the of the feature.
Video5.mp4
The adjacency tool will show which polygon features are connected to which feature and the length of the perimeter shared between those two polygons. Use the 'Adjacency' tool found under the Polygons toolbox and use the following parameters.
1. Polygons -> Shape (dervied from step #4)
2. Field -> Shape
3. Tolerance -> 1.0
4. Calculate Shared Perimeter
The resulting attribute table of the output will contain an ORIG_ID field that indicated the ID used for the polygon. The 'Adjacent' will populate all the ORIG_IDs that are the current polygon has intersected sperated by a comma field. Lastly, the attributes table will contain one field for each unique field in the 'Shape' parameter showing the length shared between the current polygon and that field. This may be useful to identify for example, how long does the current polygon share a border with an ellipictal assymetrical mid-channel bar?
Note - A tolerance is needed to create an intersected region between the two adjacent polygons. The shared perimeter between two polygon is thus an estimate calculated based on the intersected length of the polygons divided by two.
Video6.mp4
We may want to perform geometrical analyses on a manually defined centerline or a previously defined centerline. To demonstrate this scenario, we will create our own centerline for the Congo River dataset using the following steps:
1. Select Layer -> Create Layer -> New Shapefile Layer...
2. Choose a File name
3. Geometry type -> LineString
4. Coordinate System - ESRI:54034 - World_Cylindrical_Equal_Area
5. Press OK
We have now created a blank new shapefile that we can use to digitze geometries. Use the following options:
1. Select 'Toggle Editing' button
2. Select 'Add Line Feature' button
3. Select 'Add Snapping'
4. Draw the line geometry by left clicking
5. Right click to end the line shape and press OK.
6. Select 'Toggle Editing' button and save your edits.
We have now created a centerline representing the Congo River!
Important - If you want to use a manually defined centerline for the geometric attributes tool, the dataset requires an ID field that is case sensitive! The ID field of the centerline must also match the ID of the polygon.
Video13.mp4
For each linestring, this tool will calculate the sinuosity as distance/shortest pathway. In the video below, sinuosity is measured for the manually drawn centerlines along the same Congo River defined in the previous example.
The distance along centerline tool can be used to define a distance field for a manually interpreted centerline. In this case try the following parameters:
1. Centerlines -> Centerlines
2. Vertex Density -> 1000
3. Explode lines -> Checked
This will calculate distance along the centerline every 1 km and the resulting output will be split at each vertex (explode lines).
Video8.mp4
Merge Linestrings will do the opposite of the explode function and merge linestring together that share a common end and start point. Summary statistics of the merged lines can be performed (min, max, mean, range, sum, all) that may be useful to analyze the grouped results. Test it out on the newly created 'Distance Along Centerline' output created in step #3.
Note - This tool will not merge lines that have multiple intersections.
Tortuosity will calculate the distance along a line from a start and end point. The difference to the shortest path defines the tortuosity of the line. If the start and end point do not occur directly on the line, the algorithm will choose the closest vertex. The start and end point for the example shown below were manually digitized using the same step in #1 but for a point geometry.
Video9.mp4
To create regularlly spaced transects along any centerline, the 'Transects by Distance' tool will achieve this goal. Here we will use the following parameters:
1. Centerlines -> Distance Along Centerline (Step 3)
2. Transect Width -> 1000
2. Sampling Distance -> 1000
3. Vertex Density -> 100
This will create a transect roughly every 1 km that is 1 km wide to either side of the centerline (e.g. 2 km width in total). It is always advisable to have the vertex density lower than the sampling distance to ensure that the angle and desired sampling is achieved.
Video10.mp4
Here we will first create a binary raster image that is suitable for creating centerlines. To accomplish this we will use the 'rasterize' tool that can be found by searching in the Processing Toolbox. Use the following parameters:
1. Input layer - CongoRiver (polygons)
2. A fixed value to burn -> 1
3. Output raster size units -> Georeferenced units
4. Width/Horizontal resolution -> 100
5. Height/Vertical resolution -> 100
6. Output extent -> Calculate from Layer -> CongoRiver (polygons)
7. Press Run
Note - The 'Thresholding' tool may be used to automatically create a binary raster from an RGB image. This option is not part of the user guide and is based on the scikit-image package - please refer to the user manual available here for more information about the parameters.
Video14.mp4
Create a centerline based on the binary raster image. Different centerline tools and parameters are available, please check the scikit-image manual for more detail. For the purpose of this example, simply use the default values for the Centerlines (skeletonize) tool available in the Raster toolbox.
Video11.mp4
This tool can be used to sample raster datasets at the end vertex of every linestring segment. As such it may be important to use the QGIS 'explode tool' or 'Distance Along Centerline' tool in step 3 of the Linestring toolbox to create multiple linestring segments. In the video below, the 'Distance Along Centerline' tool is used on the transects created earlier in step 6 of the Linestring toolbox tutorial. This created multiple line segments every 100 meters along each transect which is subsequently sampled against the Congo River raster dataset by the 'Sample Transects' tool using the following parameters.
1. Transects -> Transects (or Distance Along Centerline output)
2. Raster -> Congo River
The results in the example below will show a -1 value for a mid-channel bar and a 1 for the active river channel for the rvalue_1 attribute. If there are multiple bands in the raster being sampled the naming convention will follow rvalue_x.
Video12.mp4
Once the transects have been sampled, we can plot the data against the distance calculated previously by the 'Distance Along Centerline' tool. To accomplish this we will use the Data Plotly plugin available through the Plugin Manager. Use the following steps:
1. Select one transect line using the selection tool
2. Open Data Plotly
3. Select 'Scatter Plot' for the Plot type
4. Select the 'Sampled Transects' layer
5. Select 'Use only selected features' checkbox
6. Select 'Distance' for the x axis and 'rvalue_1' for the y axis.
7. Click 'Create Plot'
This plot shows where we identify a river verus a mid-channel bar for the selected transect of the Congo River.
Video13.mp4
To use the SAM model requires first an installation of the segment-geospatial python module and the checkpoints that represent Meta's trained model. Given the numerous dependencies of the segment-geospatial package (GDAL, rasterio, pytorch to name a few), this may be difficult and may require manual installation. However, the configure tool available in the Geometric Attributes toolbox has been designed to aid this process. If the configure tool fails for windows users then check that Microsoft visual studio C++ is greater than 14.0 -> see here for more information.
If manually installing, the checkpoints need to be downloaded and saved within the Geometric Attributes plugin found at ~QGIS3\profiles\default\python\plugins\geometric_attributes. The files can be downloaded from:
https://dl.fbaipublicfiles.com/segment_anything/sam_vit_h_4b8939.pth
https://dl.fbaipublicfiles.com/segment_anything/sam_vit_l_0b3195.pth
https://dl.fbaipublicfiles.com/segment_anything/sam_vit_b_01ec64.pth
Note - The checkpoint files are large (~4gb) and may take several minutes (10+) to download! The configure tool will cause the QGIS interface to become unresponsive during that time.
Media2.mp4
Once the tool is configured, the SAM tool can be used on geospatial images within QGIS! The Landsat 9 example below is courtesy of the USGS and can be downloaded from the Earth Explorer. A few caveats of the tools that are important to note.
-
First the input image needs to be a 3 Band RGB image and 8bit. One method to convert an image to the required input is to utilize the gdal_translate tool available in the processing toolbox in QGIS. The ‘-scale min max’ option under ‘Additional command-line parameters’ is useful to scale the input to the require 8 bit range. Remember to select ‘Byte’ as the ‘Output data type’.
-
The advanced parameters dropdown menu provides additional parameters to fine tune the model. The impact of each parameter on the resulting classification are not quite clear yet but these notebooks may provide a few hints.
TIP – If you open the python console in QGIS before running the SAM script, you will see a progress bar reported in the python console.
Media2.mp4
The Segment Anything Model with training points will try to identify the objects defined by the training point dataset.