# whitebox-tools

**Repository Path**: abstract2015/whitebox-tools

## Basic Information

- **Project Name**: whitebox-tools
- **Description**: 维护和升级`whitebox-tools`。官方最新的版本是v2.4.0(20240523)，后续未更新。
- **Primary Language**: Rust
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-15
- **Last Updated**: 2026-06-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

![](./img/WhiteboxToolsLogoBlue.png)


> Note: Compiled WhiteboxTools binaries for Windows, macOS, and Linux can be found at: https://www.whiteboxgeo.com/download-whiteboxtools/

*This page is related to the stand-alone command-line program and Python scripting API for geospatial analysis, **WhiteboxTools**.

The official WhiteboxTools User Manual can be found [at this link](https://whiteboxgeo.com/manual/wbt_book/preface.html).

**Contents**

1. [Description](#1-description)
2. [Getting Help](#2-getting-help)
3. [Downloads and Installation](#3-pre-compiled-binaries)
4. [Building From Source Code](#4-building-from-source-code)
5. [编译问题解决方案](#5-编译问题解决方案-2026-04)

## 1 Description

**WhiteboxTools** is an advanced geospatial data analysis platform developed by Prof. John Lindsay ([webpage](http://www.uoguelph.ca/~hydrogeo/index.html); [jblindsay](https://github.com/jblindsay)) at the [University of Guelph's](http://www.uoguelph.ca) [*Geomorphometry and Hydrogeomatics Research Group*](http://www.uoguelph.ca/~hydrogeo/index.html). *WhiteboxTools* can be used to perform common geographical information systems (GIS) analysis operations, such as cost-distance analysis, distance buffering, and raster reclassification. Remote sensing and image processing tasks include image enhancement (e.g. panchromatic sharpening, contrast adjustments), image mosaicing, numerous filtering operations, classification, and common image transformations. *WhiteboxTools* also contains advanced tooling for spatial hydrological analysis (e.g. flow-accumulation, watershed delineation, stream network analysis, sink removal), terrain analysis (e.g. common terrain indices such as slope, curvatures, wetness index, hillshading; hypsometric analysis; multi-scale topographic position analysis), and LiDAR data processing. LiDAR point clouds can be interrogated (LidarInfo, LidarHistogram), segmented, tiled and joined, analyized for outliers, interpolated to rasters (DEMs, intensity images), and ground-points can be classified or filtered. *WhiteboxTools* is not a cartographic or spatial data visualization package; instead it is meant to serve as an analytical backend for other data visualization software, mainly GIS.

## 2 Getting help

WhiteboxToos possesses extensive help documentation. Users are referred to the [User Manual](https://www.whiteboxgeo.com/manual/wbt_book/) located on www.whiteboxgeo.com.

## 3 Pre-compiled binaries

*WhiteboxTools* is a stand-alone executable command-line program with no actual installation. If you intend to use the Python programming interface for *WhiteboxTools* you will need to have Python 3 (or higher) installed. Pre-compiled binaries can be downloaded from the [*Whitebox Geospatial Inc. website*](https://www.whiteboxgeo.com/download-whiteboxtools/) with support for various operating systems.

## 4 Building from source code

It is likely that *WhiteboxTools* will work on a wider variety of operating systems and architectures than the distributed binary files. If you do not find your operating system/architecture in the list of available *WhiteboxTool* binaries, then compilation from source code will be necessary. WhiteboxTools can be compiled from the source code with the following steps:

1. Install the Rust compiler; Rustup is recommended for this purpose. Further instruction can be found at this [link](https://www.rust-lang.org/en-US/install.html).

2. Download the *WhiteboxTools* from this GitHub repo.
```

3. Decompress the zipped download file.

4. Open a terminal (command prompt) window and change the working directory to the `whitebox-tools` folder:

```
>> cd /path/to/folder/whitebox-tools/
```

5. Finally, use the Python build.py script to compile the code:

```
>> python build.py
```

Read the notes in the `build.py` file for detailed information about customizing the build. In particular, the `do_clean`,
`exclude_runner` and `zip` arguments can be used to add or remove functionality during the build process. Running the build
script requires a Python environment. (Note, WhiteboxTools itself is pure Rust code.)

Depending on your system, the compilation may take several minutes. Also depending on your system, it may be necessary to use the `python3` command instead. When completed, the script will have created a new `WBT` folder within `whitebox-tools`. This folder will contain all of the files needed to run the program, including the main Whitebox executable file (whitebox_tools.exe), the Whitebox Runner GUI application, and the various plugins.

Be sure to follow the instructions for installing Rust carefully. In particular, if you are installing on MS Windows, you must have a linker installed prior to installing the Rust compiler (rustc). The Rust webpage recommends either the **MS Visual C++ 2015 Build Tools** or the GNU equivalent and offers details for each installation approach. You should also consider using **RustUp** to install the Rust compiler.

## 5 编译问题解决方案 (2026-04)

### 5.1 Rust 工具链版本要求

项目依赖的最新 crate（如 `icu_collections`、`time` 等）需要较新的 Rust 版本。如果编译报错提示 `requires rustc X.XX`：

```bash
# 升级 Rust 到最新稳定版
rustup upgrade stable

# 验证版本
rustc --version
# 应显示 1.86.0 或更高版本
```

### 5.2 tsp-rs 依赖问题

`whitebox-plugins/Cargo.toml` 中依赖的 `tsp-rs = "0.1.0"` crate 存在设计问题：其 `Cargo.toml` 设置了 `autolib = false`，导致没有 library target，无法被其他 crate 引用。

**解决方案**：在 `travelling_salesman_problem/main.rs` 中使用本地实现的 TSP 算法（Metrizable trait、Point 结构体、Tour 结构体含 2-opt 优化），并从 `Cargo.toml` 中移除 `tsp-rs` 依赖。

### 5.3 编译命令

```bash
# 清理并以 release 模式编译
cargo clean
cargo build --release

# 仅编译核心组件（排除有问题的插件）
cargo build -p whitebox_tools -p whitebox_runner -p whitebox_common -p whitebox_raster -p whitebox_lidar -p whitebox_vector
```

### 5.4 打包步骤

1. 创建 `WBT` 目录结构：
```
WBT/
├── whitebox_tools.exe
├── whitebox_runner.exe
├── whitebox_tools.py
├── settings.json
├── LICENSE.txt
├── readme.txt
├── UserManual.txt
├── img/
└── plugins/
```

2. 复制文件：
```powershell
# 复制主程序
Copy-Item whitebox_tools.exe WBT\
Copy-Item whitebox_runner.exe WBT\

# 复制配置文件
Copy-Item whitebox_tools.py WBT\
Copy-Item settings.json WBT\
Copy-Item LICENSE.txt WBT\
Copy-Item readme.txt WBT\
Copy-Item UserManual.txt WBT\

# 复制图标
Copy-Item img WBT\ -Recurse

# 复制插件（exe + json）
Get-ChildItem whitebox-plugins/src/*/*.json | Copy-Item -Destination WBT\plugins\
Get-ChildItem *.exe | Where-Object { $_.Name -ne "whitebox_tools.exe" -and $_.Name -ne "whitebox_runner.exe" } | Copy-Item -Destination WBT\plugins\
```

3. **直接拷贝整个 `WBT` 文件夹到目标位置即可使用**

### 5.5 Cargo 镜像配置

如遇网络问题，可配置国内镜像（编辑 `~/.cargo/config.toml`）：

```toml
[source.aliyun]
registry = "sparse+https://mirrors.aliyun.com/crates.io-index/"

[source]
replace-with = "aliyun"
```