===============
whitebox-python
===============
.. image:: https://colab.research.google.com/assets/colab-badge.svg
:target: https://gishub.org/whitebox-colab
.. image:: https://mybinder.org/badge_logo.svg
:target: https://gishub.org/whitebox-cloud
.. image:: https://img.shields.io/pypi/v/whitebox.svg
:target: https://pypi.python.org/pypi/whitebox
.. image:: https://pepy.tech/badge/whitebox
:target: https://pepy.tech/project/whitebox
.. image:: https://anaconda.org/conda-forge/whitebox/badges/version.svg
:target: https://anaconda.org/conda-forge/whitebox
.. image:: https://readthedocs.org/projects/whitebox/badge/?version=latest
:target: https://whitebox.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://img.shields.io/badge/License-MIT-yellow.svg
:target: https://opensource.org/licenses/MIT
.. image:: https://img.shields.io/badge/Donate-Buy%20me%20a%20coffee-yellowgreen.svg
:target: https://www.buymeacoffee.com/opengeos
Important Note
--------------
.. image:: https://i.imgur.com/Ic8BA7C.png
This repository is related to the WhiteboxTools Python Frontend only. You can report issues to this repo if you have problems installing this Python package. If you encounter any tool functioning specific errors, please `open an issue`_ on Dr. John Lindsay's WhiteboxTools_ repo.
**Links**
* Authors: Dr. John Lindsay (https://jblindsay.github.io/ghrg/index.html)
* Contributors: Dr. Qiusheng Wu (https://wetlands.io)
* GitHub repo: https://github.com/opengeos/whitebox-python
* WhiteboxTools: https://github.com/jblindsay/whitebox-tools
* User Manual: https://www.whiteboxgeo.com/manual/wbt_book/intro.html
* PyPI: https://pypi.org/project/whitebox/
* conda-forge: https://anaconda.org/conda-forge/whitebox
* Documentation: https://whitebox.readthedocs.io
* Binder: https://gishub.org/whitebox-cloud
* Free software: `MIT license`_
**Contents**
- `Description`_
- `Installation`_
- `whitebox Tutorials`_
- `whitebox GUI`_
- `Available Tools`_
- `Supported Data Formats`_
- `Contributing`_
- `License`_
- `Reporting Bugs`_
- `Credits`_
Description
-----------
The **whitebox** Python package is built on **WhiteboxTools**, an advanced geospatial data analysis platform developed by Prof. John Lindsay (webpage_; jblindsay_) at the University of Guelph's `Geomorphometry and Hydrogeomatics Research Group`_. *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, simple classification (k-means), 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.
Installation
------------
**whitebox** supports a variety of platforms, including Microsoft Windows, macOS, and Linux operating systems. Note that you will need to have Python 3.x installed. Python 2.x is not supported. The **whitebox** Python package can be installed using the following command:
.. code:: python
pip install whitebox
If you have installed **whitebox** Python package before and want to upgrade to the latest version, you can use the following command:
.. code:: python
pip install whitebox -U
It is recommended that you use a Python virtual environment (e.g., conda) to test the whitebox package. Please follow the `conda user guide`_ to install conda if necessary. Once you have conda installed, you can use Terminal or an Anaconda Prompt to create a Python virtual environment. Check `managing Python environment`_ for more information.
.. code:: python
conda create -n wbt python
source activate wbt
conda install whitebox -c conda-forge
If you encounter an GLIBC errors when installing the whitebox package, you can try the following command:
.. code:: python
import whitebox
whitebox.download_wbt(linux_musl=True, reset=True)
Alternatively, you can set the environment variable ``WBT_LINUX`` to ``MUSL`` before installing the whitebox package. It will automatically download the MUSL version of WhiteboxTools.
.. code:: python
import os
os.environ["WBT_LINUX"] = "MUSL"
whitebox Tutorials
------------------
Launch the whitebox tutorial notebook directly with **mybinder.org** now:
.. image:: https://mybinder.org/badge_logo.svg
:target: https://gishub.org/whitebox-cloud
Quick Example
=============
Tool names in the **whitebox** Python package can be called either using the snake_case or CamelCase convention (e.g. *lidar_info* or *LidarInfo*). See below for an example Python script (example.py_). If you are interested in using the *WhiteboxTools* command-line program, check `WhiteboxTools Usage`_.
.. code:: python
import os
import pkg_resources
import whitebox
wbt = whitebox.WhiteboxTools()
print(wbt.version())
print(wbt.help())
# identify the sample data directory of the package
data_dir = os.path.dirname(pkg_resources.resource_filename("whitebox", 'testdata/'))
wbt.set_working_dir(data_dir)
wbt.verbose = False
wbt.feature_preserving_smoothing("DEM.tif", "smoothed.tif", filter=9)
wbt.breach_depressions("smoothed.tif", "breached.tif")
wbt.d_inf_flow_accumulation("breached.tif", "flow_accum.tif")
A Jupyter Notebook Tutorial for whitebox
========================================
This tutorial can be accessed in three ways:
- HTML version: https://gishub.org/whitebox-html
- Viewable Notebook: https://gishub.org/whitebox-notebook
- Interactive Notebook: https://gishub.org/whitebox-cloud
Launch this tutorial as an interactive Jupyter Notebook on the cloud - https://gishub.org/whitebox-cloud.
.. image:: https://i.imgur.com/LF4UE1j.gif
whitebox GUI
------------
WhiteboxTools also provides a Graphical User Interface (GUI) - **WhiteboxTools Runner**, which can be invoked using the following Python script:
.. code:: python
import whitebox
whitebox.Runner()
.. image:: https://wetlands.io/file/images/whitebox.png
Troubleshooting
---------------
Linux
=====
When using ``import whitebox``, if you get an error that says ``No module named '_tkinter', please install the python3-tk package``, you can try the following solution:
- For Ubuntu, Linux Mint, etc: ``sudo apt-get install python3-tk``
- For Manjaro, Arch Linux: ``sudo pacman -S tk``
Available Tools
---------------
The library currently contains **518** tools, which are each grouped based on their main function into one of the following categories: Data Tools, GIS Analysis, Hydrological Analysis, Image Analysis, LiDAR Analysis, Mathematical and Statistical Analysis, Stream Network Analysis, and Terrain Analysis. For a listing of available tools, complete with documentation and usage details, please see the `WhiteboxTools User Manual`_.
Supported Data Formats
----------------------
The WhiteboxTools library currently supports read/writing raster data in Whitebox GAT, GeoTIFF, ESRI (ArcGIS) ASCII and binary (.flt & .hdr), GRASS GIS, Idrisi, SAGA GIS (binary and ASCII), and Surfer 7 data formats. At present, there is limited ability in WhiteboxTools to read vector geospatial data. Support for Shapefile (and other common vector formats) will be enhanced within the library soon.
Contributing
------------
If you would like to contribute to the project as a developer, follow these instructions to get started:
1. Fork the whitebox project (https://github.com/opengeos/whitebox-python)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request
License
-------
The **whitebox** package is distributed under the `MIT license`_, a permissive open-source (free software) license.
Reporting Bugs
--------------
Report bugs at https://github.com/opengeos/whitebox-python/issues.
If you are reporting a bug, please include:
* Your operating system name and version.
* Any details about your local setup that might be helpful in troubleshooting.
* Detailed steps to reproduce the bug.
Credits
-------
This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.
.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
.. _example.py: https://github.com/opengeos/whitebox-python/blob/master/whitebox/example.py
.. _WhiteboxTools: https://github.com/jblindsay/whitebox-tools
.. _webpage: https://jblindsay.github.io/ghrg/index.html
.. _jblindsay: https://github.com/jblindsay
.. _`Geomorphometry and Hydrogeomatics Research Group`: https://jblindsay.github.io/ghrg/index.html
.. _`conda user guide`: https://conda.io/docs/user-guide/install/index.html
.. _`managing Python environment`: https://conda.io/docs/user-guide/tasks/manage-environments.html
.. _`WhiteboxTools Usage`: https://github.com/jblindsay/whitebox-tools#3-usage
.. _`MIT license`: https://opensource.org/licenses/MIT
.. _`open an issue`: https://github.com/jblindsay/whitebox-tools/issues
.. _`WhiteboxTools User Manual`: https://www.whiteboxgeo.com/manual/wbt_book/intro.html
=======
History
=======
0.2.0 (2018-06-08)
------------------
0.1.0 (2018-06-06)
------------------
* First release on PyPI.
Raw data
{
"_id": null,
"home_page": "https://github.com/opengeos/whitebox-python",
"name": "whitebox",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "whitebox",
"author": "Qiusheng Wu",
"author_email": "giswqs@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/df/ed/84ff85589a53bb61fa6f0f96a659ef20fbada1fcd6d1bb3c48dcbc24bb40/whitebox-2.3.5.tar.gz",
"platform": null,
"description": "===============\nwhitebox-python\n===============\n\n.. image:: https://colab.research.google.com/assets/colab-badge.svg\n :target: https://gishub.org/whitebox-colab\n\n.. image:: https://mybinder.org/badge_logo.svg \n :target: https://gishub.org/whitebox-cloud\n\n.. image:: https://img.shields.io/pypi/v/whitebox.svg\n :target: https://pypi.python.org/pypi/whitebox\n\n.. image:: https://pepy.tech/badge/whitebox\n :target: https://pepy.tech/project/whitebox\n\n.. image:: https://anaconda.org/conda-forge/whitebox/badges/version.svg\n :target: https://anaconda.org/conda-forge/whitebox\n\n.. image:: https://readthedocs.org/projects/whitebox/badge/?version=latest\n :target: https://whitebox.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\n.. image:: https://img.shields.io/badge/License-MIT-yellow.svg\n :target: https://opensource.org/licenses/MIT\n\n.. image:: https://img.shields.io/badge/Donate-Buy%20me%20a%20coffee-yellowgreen.svg\n :target: https://www.buymeacoffee.com/opengeos\n\n\nImportant Note\n--------------\n.. image:: https://i.imgur.com/Ic8BA7C.png\n\nThis repository is related to the WhiteboxTools Python Frontend only. You can report issues to this repo if you have problems installing this Python package. If you encounter any tool functioning specific errors, please `open an issue`_ on Dr. John Lindsay's WhiteboxTools_ repo. \n\n**Links**\n\n* Authors: Dr. John Lindsay (https://jblindsay.github.io/ghrg/index.html)\n* Contributors: Dr. Qiusheng Wu (https://wetlands.io)\n* GitHub repo: https://github.com/opengeos/whitebox-python\n* WhiteboxTools: https://github.com/jblindsay/whitebox-tools\n* User Manual: https://www.whiteboxgeo.com/manual/wbt_book/intro.html\n* PyPI: https://pypi.org/project/whitebox/\n* conda-forge: https://anaconda.org/conda-forge/whitebox\n* Documentation: https://whitebox.readthedocs.io\n* Binder: https://gishub.org/whitebox-cloud\n* Free software: `MIT license`_\n\n\n**Contents**\n\n- `Description`_\n- `Installation`_\n- `whitebox Tutorials`_\n- `whitebox GUI`_\n- `Available Tools`_\n- `Supported Data Formats`_\n- `Contributing`_\n- `License`_\n- `Reporting Bugs`_\n- `Credits`_\n\n\n\nDescription\n-----------\nThe **whitebox** Python package is built on **WhiteboxTools**, an advanced geospatial data analysis platform developed by Prof. John Lindsay (webpage_; jblindsay_) at the University of Guelph's `Geomorphometry and Hydrogeomatics Research Group`_. *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, simple classification (k-means), 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.\n\n\nInstallation\n------------\n**whitebox** supports a variety of platforms, including Microsoft Windows, macOS, and Linux operating systems. Note that you will need to have Python 3.x installed. Python 2.x is not supported. The **whitebox** Python package can be installed using the following command: \n\n.. code:: python\n\n pip install whitebox\n\n\nIf you have installed **whitebox** Python package before and want to upgrade to the latest version, you can use the following command:\n\n.. code:: python\n\n pip install whitebox -U\n\n\nIt is recommended that you use a Python virtual environment (e.g., conda) to test the whitebox package. Please follow the `conda user guide`_ to install conda if necessary. Once you have conda installed, you can use Terminal or an Anaconda Prompt to create a Python virtual environment. Check `managing Python environment`_ for more information.\n\n.. code:: python\n\n conda create -n wbt python\n source activate wbt\n conda install whitebox -c conda-forge\n\nIf you encounter an GLIBC errors when installing the whitebox package, you can try the following command:\n\n.. code:: python\n\n import whitebox\n whitebox.download_wbt(linux_musl=True, reset=True)\n\n\nAlternatively, you can set the environment variable ``WBT_LINUX`` to ``MUSL`` before installing the whitebox package. It will automatically download the MUSL version of WhiteboxTools.\n\n.. code:: python\n\n import os\n os.environ[\"WBT_LINUX\"] = \"MUSL\"\n\nwhitebox Tutorials\n------------------\n\nLaunch the whitebox tutorial notebook directly with **mybinder.org** now:\n\n.. image:: https://mybinder.org/badge_logo.svg \n :target: https://gishub.org/whitebox-cloud\n\nQuick Example\n=============\n\nTool names in the **whitebox** Python package can be called either using the snake_case or CamelCase convention (e.g. *lidar_info* or *LidarInfo*). See below for an example Python script (example.py_). If you are interested in using the *WhiteboxTools* command-line program, check `WhiteboxTools Usage`_.\n\n.. code:: python\n\n import os\n import pkg_resources\n import whitebox\n\n wbt = whitebox.WhiteboxTools()\n print(wbt.version())\n print(wbt.help())\n\n # identify the sample data directory of the package\n data_dir = os.path.dirname(pkg_resources.resource_filename(\"whitebox\", 'testdata/'))\n\n wbt.set_working_dir(data_dir)\n wbt.verbose = False\n wbt.feature_preserving_smoothing(\"DEM.tif\", \"smoothed.tif\", filter=9)\n wbt.breach_depressions(\"smoothed.tif\", \"breached.tif\")\n wbt.d_inf_flow_accumulation(\"breached.tif\", \"flow_accum.tif\")\n\n\nA Jupyter Notebook Tutorial for whitebox\n========================================\n\nThis tutorial can be accessed in three ways:\n\n- HTML version: https://gishub.org/whitebox-html\n- Viewable Notebook: https://gishub.org/whitebox-notebook\n- Interactive Notebook: https://gishub.org/whitebox-cloud\n\nLaunch this tutorial as an interactive Jupyter Notebook on the cloud - https://gishub.org/whitebox-cloud.\n\n.. image:: https://i.imgur.com/LF4UE1j.gif\n\n\nwhitebox GUI\n------------\n\nWhiteboxTools also provides a Graphical User Interface (GUI) - **WhiteboxTools Runner**, which can be invoked using the following Python script:\n\n.. code:: python\n\n import whitebox\n whitebox.Runner()\n\n.. image:: https://wetlands.io/file/images/whitebox.png\n\n\n\n\n\nTroubleshooting\n---------------\n\nLinux\n=====\nWhen using ``import whitebox``, if you get an error that says ``No module named '_tkinter', please install the python3-tk package``, you can try the following solution:\n\n- For Ubuntu, Linux Mint, etc: ``sudo apt-get install python3-tk``\n- For Manjaro, Arch Linux: ``sudo pacman -S tk``\n\n\n\n\nAvailable Tools\n---------------\nThe library currently contains **518** tools, which are each grouped based on their main function into one of the following categories: Data Tools, GIS Analysis, Hydrological Analysis, Image Analysis, LiDAR Analysis, Mathematical and Statistical Analysis, Stream Network Analysis, and Terrain Analysis. For a listing of available tools, complete with documentation and usage details, please see the `WhiteboxTools User Manual`_.\n\n\nSupported Data Formats\n----------------------\n\nThe WhiteboxTools library currently supports read/writing raster data in Whitebox GAT, GeoTIFF, ESRI (ArcGIS) ASCII and binary (.flt & .hdr), GRASS GIS, Idrisi, SAGA GIS (binary and ASCII), and Surfer 7 data formats. At present, there is limited ability in WhiteboxTools to read vector geospatial data. Support for Shapefile (and other common vector formats) will be enhanced within the library soon. \n\nContributing\n------------\n\nIf you would like to contribute to the project as a developer, follow these instructions to get started:\n\n1. Fork the whitebox project (https://github.com/opengeos/whitebox-python)\n2. Create your feature branch (git checkout -b my-new-feature)\n3. Commit your changes (git commit -am 'Add some feature')\n4. Push to the branch (git push origin my-new-feature)\n5. Create a new Pull Request\n\nLicense\n-------\n\nThe **whitebox** package is distributed under the `MIT license`_, a permissive open-source (free software) license.\n\n\nReporting Bugs\n--------------\nReport bugs at https://github.com/opengeos/whitebox-python/issues.\n\nIf you are reporting a bug, please include:\n\n* Your operating system name and version.\n* Any details about your local setup that might be helpful in troubleshooting.\n* Detailed steps to reproduce the bug.\n\nCredits\n-------\n\nThis package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.\n\n.. _Cookiecutter: https://github.com/audreyr/cookiecutter\n.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage\n.. _example.py: https://github.com/opengeos/whitebox-python/blob/master/whitebox/example.py\n.. _WhiteboxTools: https://github.com/jblindsay/whitebox-tools\n.. _webpage: https://jblindsay.github.io/ghrg/index.html\n.. _jblindsay: https://github.com/jblindsay\n.. _`Geomorphometry and Hydrogeomatics Research Group`: https://jblindsay.github.io/ghrg/index.html\n.. _`conda user guide`: https://conda.io/docs/user-guide/install/index.html\n.. _`managing Python environment`: https://conda.io/docs/user-guide/tasks/manage-environments.html\n.. _`WhiteboxTools Usage`: https://github.com/jblindsay/whitebox-tools#3-usage\n.. _`MIT license`: https://opensource.org/licenses/MIT\n.. _`open an issue`: https://github.com/jblindsay/whitebox-tools/issues\n.. _`WhiteboxTools User Manual`: https://www.whiteboxgeo.com/manual/wbt_book/intro.html\n\n\n=======\nHistory\n=======\n0.2.0 (2018-06-08)\n------------------\n0.1.0 (2018-06-06)\n------------------\n\n* First release on PyPI.\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "An advanced geospatial data analysis platform",
"version": "2.3.5",
"project_urls": {
"Homepage": "https://github.com/opengeos/whitebox-python"
},
"split_keywords": [
"whitebox"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a85fb3734743c856c5f616e92e74e612b727eb0465d7f8726b7d44e8734179aa",
"md5": "51bf3493405b35b0f66005d978f441be",
"sha256": "dd9db85bbb687356741afe935dd25286a2b31e7bf87b74c60b655cdf84a9d922"
},
"downloads": -1,
"filename": "whitebox-2.3.5-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "51bf3493405b35b0f66005d978f441be",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 72384,
"upload_time": "2024-07-16T01:25:24",
"upload_time_iso_8601": "2024-07-16T01:25:24.475313Z",
"url": "https://files.pythonhosted.org/packages/a8/5f/b3734743c856c5f616e92e74e612b727eb0465d7f8726b7d44e8734179aa/whitebox-2.3.5-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dfed84ff85589a53bb61fa6f0f96a659ef20fbada1fcd6d1bb3c48dcbc24bb40",
"md5": "b3ee1583d7cbc757e0b117f439e140b8",
"sha256": "4a9fb6da799dc0f99daf139d6dbe573ca12af3785c48708e56728b8372c6a2a7"
},
"downloads": -1,
"filename": "whitebox-2.3.5.tar.gz",
"has_sig": false,
"md5_digest": "b3ee1583d7cbc757e0b117f439e140b8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 76615,
"upload_time": "2024-07-16T01:25:26",
"upload_time_iso_8601": "2024-07-16T01:25:26.728249Z",
"url": "https://files.pythonhosted.org/packages/df/ed/84ff85589a53bb61fa6f0f96a659ef20fbada1fcd6d1bb3c48dcbc24bb40/whitebox-2.3.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-16 01:25:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "opengeos",
"github_project": "whitebox-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "whitebox"
}
JSON
