[general]
name=basinkit
qgisMinimumVersion=3.28
qgisMaximumVersion=4.99
description=Click a river anywhere on Earth and get an analysis-ready basin package: elevation, land cover, soil, rainfall, surface water, rivers, and full Horton-Strahler morphometry, clipped to the basin.
version=0.5.0
author=Pradeepika Kaushik
email=pradeepikakaushik4@gmail.com

about=Click a point on any river in the world and get the basin draining into it, then pull DEM, land cover, soil, rainfall, surface water, rivers and lakes for that basin -- clipped and masked to the polygon, not to its bounding box. No account is needed for any of it. Delineation is validated blind against 2,550 gauges in 99 countries on six continents, whose catchment areas are published by the agencies that operate them, and the plugin reports which accuracy regime an answer falls in rather than quoting a single figure: 0.3 percent median area error above 100,000 square kilometres, 1.7 percent from 2,000 to 10,000. Below about 2,000 square kilometres the DEM backend is the right instrument, and the plugin says so at the moment it matters and switches to it where the evidence supports the switch.
    Other plugins delineate from a clicked point, and Sen Hydro does it well through the same public mghydro service this plugin can use. Three things here are different. The data: elevation, land cover, soil, rainfall, surface water, rivers and lakes come back as layers clipped to the polygon, not as a report. The morphometry: the full Horton-Strahler-Schumm set from one algorithm, with Strahler streams counted as streams rather than as the reaches a river dataset splits them into. And the offline path: the default backend walks the HydroBASINS level-12 graph from a cached local copy, so after the first download it needs no network at all. Every algorithm is a Processing algorithm, so batch mode, the Model Builder and qgis_process all work.
    SETUP: this plugin runs on the Python package "basinkit", which is installed once with pip into the Python that QGIS itself uses. The plugin detects whether it is present and prints the exact command for your installation, so setup is a single copy and paste. See the plugin homepage for details.

tracker=https://github.com/Praddy-GByte/basinkit/issues
repository=https://github.com/Praddy-GByte/basinkit
homepage=https://praddy-gbyte.github.io/basinkit/

category=Vector
icon=icon.png
experimental=False
deprecated=False
hasProcessingProvider=yes

# The pip distribution this plugin runs on. QGIS installs plugins but not
# their Python dependencies, so the plugin detects it at load
# and hands the user a command that works. Declaring it here is what puts it in
# the "External dependencies" field on plugins.qgis.org.
external_deps=basinkit>=0.5
server=False

tags=hydrology,watershed,catchment,basin,delineation,dem,remote sensing,satellite,srtm,copernicus,sentinel,landsat,rainfall,soil,stac,processing

changelog=0.5.0
    - Compatibility across the full supported QGIS range. The provider now
      resolves the Processing source-type enum by asking the API for it, so it
      loads identically on QGIS 3.28 through 4.x. QGIS 3.34, the current
      long-term release, is covered by a continuous integration job that
      installs QGIS and loads every algorithm.
    - Accuracy is now reported by catchment size, from blind validation against
      2,550 gauges in 99 countries whose catchment areas are published by the
      agencies that operate them: 0.3 percent median error above
      100,000 square kilometres, 1.3 percent from 10,000 to 100,000, 1.7
      percent from 2,000 to 10,000. Below about 2,000 square kilometres the
      'dem' backend is the better instrument, and the plugin now says so at the
      moment it matters.
    - Every answer is checked against the river network. When the basin exceeds
      twice the area draining to the largest river within two kilometres of the
      outlet, the plugin reports it: 85 percent of the outlets it flags need
      attention, and it stays quiet on 97 percent of the ones that do not.
      Precision runs from 75 percent in Europe to 93 percent in Africa.
    - The 'auto' backend refines on the elevation model when the river network
      and a 30 metre routing of the same point agree on a smaller catchment.
      Across 300 gauges drawn after the method was fixed and used nowhere else
      in its design, it improved 19 results, left 279 unchanged and reduced
      none. Where it acts, the median error falls from 1,731 percent to 4.3
      percent, at a median cost of 1.6 seconds.
    - Refinement acts only when the river it is judging by lies within a
      kilometre of the outlet. Beyond that distance the point is not on that
      river, so the two sources stop being independent. Every refinement that
      improved a result had its river within 0.91 kilometres.
    - The plugin now names what kind of place the outlet is in. An endorheic
      system, a coastal strip draining straight to the ocean, and an outlet
      with nothing draining into it are each reported, the last being what a
      lake surface and a sub-grid headwater have in common.
    - Messages are matched to the cause and say what to do next: a coordinate
      outside the network's coverage, one beyond the snap distance, and one on
      a hillslope rather than in a channel each get their own guidance.
    - The consistency line now compares the result against the river network
      rather than against the source dataset's own upstream-area field, which
      confirms the traversal rather than the choice of outlet.
    - The river-network check is a checkbox, on by default, and is the only
      thing that downloads the regional rivers file.
    - Against pysheds and WhiteboxTools on identical 30 metre rasters across 59
      catchments under 2,000 square kilometres, the 'dem' backend returned a
      basin for every one, matched the agency figure within 20 percent on 68
      percent of them against 56 and 51, and had the lowest median error.
    - Requires basinkit 0.5 or newer.

    0.4.0
    - New algorithm: Basin morphometry. The full Horton-Strahler-Schumm set
      from one run, with the per-order table showing Strahler streams and
      dataset reaches side by side, and the counts tested against what Strahler
      ordering allows. A bifurcation ratio below 2 and more than one stream of
      the basin's highest order are both impossible, and are now reported
      instead of being handed back as numbers to interpret. Until now
      morphometry was in the Python package but not reachable from QGIS.
    - The plugin description leads with the data package rather than with
      "delineate". QGIS already has
      several delineation plugins, and the old wording put this one in that
      queue while morphometry, which is the part with no equivalent elsewhere,
      went unmentioned.
    - Requires basinkit 0.4 or newer.

    0.3.3
    - Pairs with basinkit 0.3.3, which corrects channel_gradient_m_per_km. Up to
      0.3.0 it divided total basin relief by main channel length, which reports
      a fall the river never makes, because the highest point in a basin is a
      ridge top and not the head of the main stem. It is now read from the bed:
      the DEM is sampled along the main channel and the drop between its ends is
      divided by the channel length. On the Koshi that is 9.6 m/km, not 15.1.
      The Basin statistics algorithm never reported this figure, so nothing in
      the plugin's own output changes; it matters if you called morphometry()
      from the Python Console or a script, where the old value should be
      recomputed.
    - Basin.morphometry() now checks its own stream counts. Two of the checks
      are impossibilities rather than oddities: an order-u+1 stream is formed
      where two order-u streams meet, so N(u) >= 2*N(u+1) and the bifurcation
      ratio can never fall below 2, and a basin with one outlet has exactly one
      stream of its highest order. Counts that break either are reported rather
      than returned as numbers.
    - The plugin description now says plainly what this does that a
      delineate-from-a-click plugin offers, rather than leaving a reader to
      work it out.

    0.3.2
    - Declares its pip dependency in the external_deps metadata field, so it
      shows in the External dependencies box on the plugin page.

    0.3.1
    - Fixed 16 Qt6 compatibility issues found by the plugin repository's own
      checker: every Qt and QGIS enum is now spelled with its full scope
      (QgsWkbTypes.Type.Polygon rather than QgsWkbTypes.Polygon, and so on).
      The scoped spelling works on both PyQt5 and PyQt6, so QGIS 3.28 onwards
      and QGIS 4 are both covered by one code path, with no version guard.
    - A test now scans the plugin for unscoped enums, so they cannot come back.

    0.3.0
    The plugin version now tracks the basinkit package version, so it is clear
    which plugin goes with which package. No algorithm has changed since 0.1.0.
    - Fixed: on macOS the "package missing" notice printed the QGIS application
      binary instead of an interpreter, so the suggested pip command opened a
      second QGIS window and installed nothing. A path is now offered only once
      it is verified to be a python executable, and there is a Python Console
      snippet that needs no path at all
    - New icon: the b is drawn as a river basin with a dendritic stream network
      draining to a single outlet
    - Pairs with basinkit 0.3.0, which adds Basin.morphometry() -- the classical
      Horton-Strahler-Schumm parameters -- to the Python API
    0.1.0
    First release.
    - Delineate a basin from a canvas click, globally, via HydroBASINS graph traversal or DEM flow routing
    - Fetch DEM, land cover, soil, surface water, rivers and lakes clipped to the basin
    - Basin statistics: area, relief, mean slope, land cover fractions, bounding-box efficiency
    - Every algorithm runs in the Processing framework, so batch mode and the Model Builder work
