Interfacing With Nim

Nim is a statically compiled programming language that has Python-like syntax (e.g. significant whitespace) and c-level efficiency. It has been used by Python programmers who are looking for a faster, more efficient language but don't want to give up the elegant and terse syntax of Python.

wbt_nim is a Nim-based application programming interface (API) used to call WhiteboxTools functionality from Nim programs. The documentation for wbt_nim can be found on GitHub. To use this API, simply copy the source file into your Nim project and import wbt_nim. You will need to ensure that the WhiteboxTools binary, pre-compiled for your operating system, is also within the same directory. Otherwise, use the setExecutableDirectory function to tell wbt_nim where the WhiteboxTools binary is located on your system.

The Nim interface is very similar to the Python API:

import wbt_nim
import options, strformat, strutils

proc main() =
    # Create a new WhiteboxTools object
    var wbt = newWhiteboxTools()

    # Tell the wbt object where to find the WhiteboxTools executable.
    # If you don't do this, it assumes that it is in the same directory as 
    # your Nim code.
    wbt.setExecutableDirectory("/Users/johnlindsay/Documents/programming/whitebox-tools/")

    # Set the working directory
    let wd = "/Users/johnlindsay/Documents/data/LakeErieLidar/"
    wbt.setWorkingDirectory(wd)

    # Set the verbose mode. By default it is 'true', which prints all output
    # from WBT. If you need to make it less chatty, set it to false.
    wbt.setVerboseMode(false)

    # By default, all GeoTiff outputs of tools will be compressed. You can 
    # modify this with the following:
    wbt.setCompressRasters(false)

    # Print out the version of WBT:
    echo(wbt.getVersionInfo())

    # WhiteboxTools is open-access software. If you'd like to see the source 
    # code for any tool, simply use the following:
    discard wbt.viewCode("balanceContrastEnhancement")

    # To get a brief description of a tool and it's parameters:
    echo(wbt.getToolHelp("breachDepressionsLeastCost"))

    # If you'd like to see more detailed help documentation:
    discard wbt.viewHelpPage("breachDepressionsLeastCost")
    # This will open the default browser and navigate to the relevant tool help.

    # Here's an example of how to run a tool:
    if wbt.hillshade(
        dem="90m_DEM.tif",
        output="tmp1.tif",
        azimuth=180.0,
        altitude=45.0,
        zFactor=1.0
    ) != 0:
        echo("Error while running hillshade.")

    # If you haven't previously set the working directory, you need to include
    # full file path names.

    # You can capture tool output by creating a custom callback function
    proc myCallback(value: string) =
        if not value.contains("%"):
            echo(value)
        else:
            let s = value.replace("%", "").strip()
            echo(fmt"{s} percent")

    wbt.setCallback(myCallback)
    
    # And to reset the default callback, which just prints to stdout
    wbt.setDefaultCallback()

main()