Whitebox QGIS Practice 29 — Aspect of Two Basins in Eight Directions, and a Z Factor That Flipped It by 180°

In sessions 27 and 28 I compared the elevation and slope of two basins with the same method: reclassify into bands, then count cells per basin with a zonal histogram. This time it is aspect, the direction a slope faces, measured clockwise from north toward the downhill side. 0° (360°) is north-facing, 90° east-facing, 180° south-facing. Sunlight, snowmelt timing, vegetation and soil moisture all follow aspect, so "which way do most slopes face" is often one of the first questions asked about a basin.

The steps are the same as in the last two sessions. Whitebox Aspect makes the aspect raster, Reclassify by table assigns eight compass codes, and Zonal histogram counts cells per basin. On the first run, however, the whole result came out rotated by 180°. Half of this post is about that.

Data

I copied the session 28 inputs into a new folder. The copied DTM has the same hash as the original.

InputOriginContents
wb29_input_dtm1m.tifSession 11 DTMUSGS 3DEP tile 13SDE474426, EPSG:26913, 1500×1500 cells, 1 m, 1,834 NoData cells
wb29_input_basins_merged.shpSession 26 merged polygonsVALUE 1 = interval basin (A−B) 1,218,780 m², VALUE 2 = basin B 211,372 m²

First run: Z conversion factor set to 1.0

Processing Toolbox → WhiteboxTools → Geomorphometric Analysis → Aspect has only three fields. As with Slope in session 28, I entered 1.0 in Z Conversion Factor. The DTM is projected, with metres both horizontally and vertically, so 1.0 looked like the right value.

Whitebox Aspect dialog in QGIS. Input DEM File is DTM 1 m elevation (practice 11), Z Conversion Factor is 1.000000, Output File is wb29_aspect_deg.tif. The map behind shows the purple interval basin and the orange basin B over a hillshade.
Figure 1. Aspect dialog on the first run, with Z Conversion Factor set to 1.0.

It finished in a few seconds with no error. After reclassifying into eight sectors, almost all of basin B came out in the south-facing colours (orange and red). The zonal histogram put 85.18% of basin B in SE, S and SW.

Eight-sector aspect map from the first run. The legend runs from 0 = flat in grey and 1 = N in dark blue to 8 = NW in light purple. Inside basin B, outlined in black, most cells are light orange and red (SE, S, SW); the slopes beyond the northern valley are blue.
Figure 2. Eight-sector map from the aspect made with Z factor 1.0. Basin B appears south-facing, which is the opposite of the real terrain.

That did not look right. The outlet of basin B (ID 2 = B in the figure) is at the northern end of the basin. If water gathers at a northern outlet, the ground should generally drop toward the north, and north-facing slopes should dominate. Checking the DTM directly, the correlation between elevation and row number (which increases southward) inside basin B was 0.966. The south is high and the north is low. 85% south-facing does not fit that terrain.

Narrowing down the cause

I checked three things separately.

  • Against the steepest-descent direction. I sampled 3,000 random DTM cells and found which of the eight neighbours drops most steeply. The Whitebox aspect was within 45° of that direction in 2 cells and off by 135° or more in 2,945.
  • Against a numpy Horn 3×3 aspect. Compared with an independently computed aspect, the median difference was 179.0°. Not one sector but the whole raster was reversed.
  • Running Whitebox directly. Outside QGIS, I ran Aspect with the same whitebox_tools.exe (v2.2.0) on the same DTM. Without a Z factor the sample cell came out at 91.36°; with --zfactor=1.0 it was 271.36°. The compression option and the number of threads did not change the result. On a synthetic plane rising to the north-east, which should face south-west (225°), I got 225° without the factor and 45° with 1.0.

So with this version, passing a Z conversion factor value to Aspect rotates the aspect by 180°. Comparing the first-run result with the final result below cell by cell, all 2,248,165 valid cells differ by exactly 180° (within 0.01°). I did not find out why the tool does this internally. I also set 1.0 for Slope in session 28, but slope is a magnitude with no direction, so it is not affected, and the mean difference from Horn 3×3 then was 0.56°.

Second run: leave the Z conversion factor empty

FieldValueReason
Input DEM FileDTM 1 m elevation (practice 11)Ground-point DTM. In a DSM, building walls and canopy edges scramble the aspect
Z Conversion FactorLeft empty (Not set)It is optional. Entering a value reversed the aspect, as above
Output Filewb29_aspect_deg.tifThe first-run output was moved to a separate folder and kept
Whitebox Aspect dialog opened again. The optional Z Conversion Factor field is empty (Not set), Input DEM File is DTM 1 m elevation (practice 11), Output File is wb29_aspect_deg.tif.
Figure 3. Second run, with the Z Conversion Factor field left empty.

Run this way, --zfactor is dropped from the command line the plugin builds. The result is float32 with 1,834 NoData cells (same as the DTM) and values from 0.0002° to 359.9999°. Exactly one cell has the value −1. It appears to be the value Whitebox writes when it cannot assign a direction. In the synthetic-plane test, a plane tilted exactly north–south (zero east–west gradient) also came out as −1. Such cells are rare in natural terrain, but with data full of stepped, man-made surfaces it is worth counting the −1 cells once.

Reclassifying into eight sectors

I split aspect into eight 45° sectors. North straddles 0°, split into 337.5–360° and 0–22.5°, so both rows get code 1. Negative values (−1) go to a separate flat code 0. Codes run clockwise from 1 = N to 8 = NW, so the histogram fields h_1 to h_8 come out in compass order.

FieldValueReason
Raster layerAspect, degrees from north (Whitebox Aspect)The aspect just made
Band numberBand 1
Reclassification table10 rows: −1000–0 → 0, 0–22.5 → 1, 22.5–67.5 → 2, 67.5–112.5 → 3, 112.5–157.5 → 4, 157.5–202.5 → 5, 202.5–247.5 → 6, 247.5–292.5 → 7, 292.5–337.5 → 8, 337.5–361 → 1Two rows handle north crossing 0°. The last maximum is 361 so cells very close to 360° are not lost
Output no data value−9999
Range boundariesmin <= value < maxA cell exactly on a boundary such as 22.5° goes to the next sector clockwise
Use no data when no range matches valueChecked
Output data typeInt16
Reclassified rasterwb29_aspect_8dir.tif
Eight-sector aspect map made with the Z factor left empty. Basin B, outlined in black, is mostly blue (N, NE) with light purple (NW) along its edges. The large interval basin on the left is mostly blue and light blue with pink and purple (W, NW) bands along the central valley; the slopes beyond the northern valley are orange and red.
Figure 4. Final eight-sector aspect map. Basin B now shows north and north-east slopes facing its northern outlet.

Placed next to Figure 2, the colours are exactly swapped: what was blue is now orange and red, and what was orange is now blue.

Area by direction for each basin

FieldValueReason
Raster layerAspect, 8 directions (1 = N … 8 = NW, 0 = flat)
Band numberBand 1
Vector layer containing zonesBasins merged: 1 = interval A-B, 2 = B (practice 26)
Output column prefixh_h_0 (flat) to h_8 (NW)
Output zoneswb29_basin_aspect_histogram.shp
Attribute table of Basins with aspect class cell counts over the map. The VALUE 1 row reads h_0 1, h_1 214252, h_2 267115, h_3 186782, h_4 152280, h_5 108260; the VALUE 2 row reads h_0 0, h_1 103300, h_2 41682, h_3 14445, h_4 8158, h_5 1616. Labels on the map read A-B N: 214,252 m2 S: 108,260 m2 inside the interval basin and B N: 103,300 m2 S: 1,616 m2 inside basin B.
Figure 5. Zonal histogram attribute table (visible up to h_5) and north/south area labels. The remaining fields are in the table below.
DirectionInterval basin A−B area (m²)ShareBasin B area (m²)Share
N214,25217.58%103,30048.87%
NE267,11521.92%41,68219.72%
E186,78215.33%14,4456.83%
SE152,28012.49%8,1583.86%
S108,2608.88%1,6160.76%
SW59,6774.90%8700.41%
W89,6817.36%6,2462.96%
NW140,73211.55%35,05516.59%
Flat (code 0)10.00%00%
Total1,218,780100%211,372100%
Bar chart of basin area share by eight directions. The x axis is N, NE, E, SE, S, SW, W, NW and the y axis is share of basin area (%). The hatched orange bars (basin B) peak at N with 48.9%, then NE 19.7% and NW 16.6%, with S and SW below 1%. The purple bars (interval basin A-B) are spread more evenly: NE 21.9%, N 17.6%, E 15.3%, SE 12.5%, NW 11.5%, with SW lowest at 4.9%.
Figure 6. Zonal histogram cell counts converted to basin area shares (drawn in matplotlib from the QGIS output table).

Basin B leans hard to one side. N, NE and NW together make up 85.18%, while SE, S and SW are only 5.04%. It is a narrow valley that rises to the south and drains to a northern outlet, so most of its slopes face north. Averaging aspect as unit vectors gives 8.2° (almost due north), and the mean resultant length (0 for directions spread evenly, 1 for a single direction) is 0.726.

The interval basin is much more even. Its largest sector is NE (21.92%), but E, SE and NW each hold between about 11% and 15%. The three northern sectors total 51.04% against 26.27% for the three southern ones, so north-facing ground still dominates, but the mean resultant length is 0.294, less than half of basin B's. The mean direction is 46.1° (north-east). With several branching valleys inside the larger basin, opposite valley sides appear to cancel each other out.

In session 28 the median slopes of the two basins were nearly the same, around 30°. With aspect, the two basins look quite different. Basin B is almost entirely north-facing, so it has a larger share of shaded slopes even at the same elevation, while the interval basin mixes slopes facing many directions. When comparing basins for insolation, snow or vegetation, this difference may matter more than slope. Here I only checked the distribution; I did not compute insolation.

Independent check

I recomputed the final result with a separate script. Putting the Whitebox aspect values through the same eight-sector rule in numpy left 0 cells different from the QGIS reclassification. Cell counts per sector, from basin polygons rasterised by cell centre, matched the attribute table for every sector in both basins, and the totals matched the session 26 areas.

Against an aspect computed separately with numpy Horn 3×3, over 2,242,171 cells excluding the edges, the median difference was 1.00°, the mean 1.80°, and 99% of cells were within 13.65°. 96.13% of cells fell in the same eight-way sector. The cells with large differences appear to be nearly flat ground, where direction is unstable. On the first run the median of this comparison was 179.0°, so this one check alone is enough to catch a reversed result.

Practical notes

  • With WhiteboxTools v2.2.0 Aspect, leave Z Conversion Factor empty. Entering 1.0 produces, without any error, an aspect raster rotated by 180°. I did not test other versions or values other than 1.0.
  • Check the aspect result once against terrain you already know, such as the outlet location or stream direction. Just checking that slopes descend toward the valley outlet is enough to catch a reversal.
  • North crosses 0°/360°. If the reclassification table does not split it into two rows, only half of the north-facing ground is captured. For averages, use the vector mean rather than the arithmetic mean (the arithmetic mean of 350° and 10° is 180°).
  • Flat cells come out as a separate value such as −1. Without a negative range in the reclassification table they can disappear as NoData or mix into north.
  • Whitebox aspect refers to the downhill direction. When mixing tools, first align the convention (north 0°, clockwise) and how flat cells are marked.

Next session

After elevation, slope and aspect, the next question is where water gathers. I plan to make a Whitebox topographic wetness index (Wetness Index, TWI) and compare the wetness distribution of the two basins in the same way. The index changes a lot depending on which tools produce the specific contributing area and slope, so I will start with preparing those inputs.

Work notes

This session was run by a QGIS startup script that filled in the same dialogs and ran them, and the screens are captures from that run. The original project was left untouched and the work was done in a copy (QGIS_Play_NaGeoAI_20261118_29_aspect8dir.qgz). The first result, made with Z factor 1.0, was kept separately with try1_zfactor1 in its name, and Figures 1 and 2 are from that run. The direct Whitebox runs and synthetic-plane tests used to find the cause were done separately outside QGIS. The data source is USGS 3DEP (The National Map) tile 13SDE474426, and the original DTM is not redistributed. Figure 6, the shares, the vector means and the independent check come from a separate script that re-reads the output files. QGIS 3.44.15, WhiteboxTools v2.2.0 (wbt_for_qgis plugin). First 12 characters of SHA-256:

  • Input DTM 069a9c249240
  • Input merged polygons .shp / .dbf 235891ed214a / 67d3965a6d72
  • Aspect raster 90bbd5f3c503
  • Eight-sector raster 5bd9eb5e5aad
  • Zonal histogram .shp / .dbf 235891ed214a / 9173dd77e473

This is an English adaptation of a post in the Korean Whitebox QGIS practice series. The original is here.

This post was drafted with the help of AI tools and reviewed by the author. Tool features and data portals change over time, so check the official documentation when you practice.

Comments

Popular posts from this blog

What Is GeoAI, and How Does It Help Disaster Safety?

Getting Started with QGIS: What to Do First

Whitebox QGIS Practice 26 — Elevation Statistics of Two Basins: Means of 2,000.1 m and 1,924.3 m, a 76 m Gap