[general]
name=AR-Tarseem
qgisMinimumVersion=3.22
qgisMaximumVersion=4.99
description=DEM-to-hydrograph watershed modelling: delineation, special delineation points with reservoir storage routing (modified Puls), SCS-CN/UH design hydrographs (CN from a raster or a single constant value), custom return periods, spatially-variable rainfall via Thiessen stations, four SCS storm types + custom hyetographs, adjustable Ia/S, ARF, Muskingum & Muskingum-Cunge routing, HEC-HMS .basin/.met/.pdata export. Pure NumPy + GDAL.
version=1.1.0
author=Ahmed M. Raslan, PhD & Amr R. Refaiy, PhD
email=amrgaballa93@gmail.com

about=Copyright (C) 2026 Ahmed M. Raslan, PhD & Amr R. Refaiy, PhD -
 Water Engineering Experts. Free software, licensed under the GNU
 General Public License version 2 or (at your option) any later
 version. A copy of the licence ships with the plugin in the file
 LICENSE.
 .
 AR-Tarseem is a complete DEM-to-hydrograph watershed modelling tool.
 From a metric DEM and a pour-points layer it produces:
   • Streams, Catchments, Longest Flow Paths (three Tc estimates),
     optional sub-basins / sub-LFPs / reaches / junctions.
   • Special Delineation Points: enforce junctions at dam locations
     (snapped to the main flow path), split sub-catchments at the
     points only or combined with the area-based subdivision, and
     define any point as a Reservoir with modified-Puls storage
     routing (elevation-volume curve + spillway/orifice structures,
     or a storage-discharge table) — with inflow, outflow,
     attenuation, storage and stage outputs.
   • Design-storm hydrographs per catchment / sub-basin / junction /
     reach: CSVs + interactive HTML charts, with an editable output
     window so every hydrograph is complete (recession to zero).
   • Curve Number from a raster (auto-aligned to the DEM) or a single
     constant value; adjustable lambda = Ia/S (0.01-0.5).
   • Rainfall: all four SCS/NRCS 24-h distributions or a custom
     hyetograph CSV; custom return periods; Thiessen station
     weighting; TRRL-UK / Riyadh / fixed Areal Reduction Factors.
   • Reach routing: Lag, Muskingum, and variable-parameter
     Muskingum-Cunge on a trapezoidal channel.
   • HEC-HMS interchange: .basin (with true Reservoir elements),
     per-return-period .met files, and a .pdata carrying the
     reservoir Elevation-Storage tables (HEC-HMS 4.7-4.13 / WMS).
   • Automatic QML styling. Uses ONLY libraries that ship with QGIS:
     numpy, osgeo (GDAL), QGIS API.
 .
 RECOMMENDED COMPANION: download AR-Awdiya, the hydrologic network
 modelling companion of AR-Tarseem. Opening the exported .basin /
 .pdata files in AR-Awdiya gives an interactive network editor and
 lets you generate polished Word and PDF report documents of all the
 outputs (hydrographs, reservoir routing tables, summaries) for
 direct use in engineering deliverables.

tracker=https://plugins.qgis.org/plugins/ar_tarseem/
repository=https://plugins.qgis.org/plugins/ar_tarseem/
homepage=https://plugins.qgis.org/plugins/ar_tarseem/

category=Plugins
icon=icon.png
experimental=False
deprecated=False
hasProcessingProvider=no

tags=hydrology,watershed,delineation,reservoirs,dams,DEM,catchment,subbasin,SCS-CN,unit hydrograph,kirpich,nrcs,muskingum,muskingum-cunge,ARF,hec-hms,basin export,scs storm types,custom hyetograph,ar-tarseem

changelog=1.1.0 — QGIS 4 (Qt 6) support and GPL licensing (November 2026)
 - AR-Tarseem is now free software under the GNU General Public
   License version 2 or (at your option) any later version, replacing
   the previous proprietary notice. The full licence text ships with
   the plugin in the file LICENSE, and every source header carries the
   standard GPL notice.
 - metadata.txt now carries the tracker, repository and homepage links
   and the author e-mail required by the QGIS plugin repository.
 .
 One package now installs and runs on both QGIS generations:
 QGIS 3.22-3.4x (Qt 5) and QGIS 4.x (Qt 6, including the 4.2 LTR).
 - New qt_compat module resolves every Qt enumeration in both its
   scoped (Qt 6 / PyQt6: Qt.CheckState.Checked) and unscoped
   (Qt 5 / PyQt5: Qt.Checked) spelling, at import time.
 - Attribute-table field types are now built from QMetaType.Type on
   Qt 6 and QVariant.Type on Qt 5; PyQt6 removed QVariant.Type, which
   made every output layer fail to build under QGIS 4.
 - Layer-filter, file-widget, selection-mode, button-role and
   message-level enumerations ported to the same resolver.
 - Background execution is now gated: under Qt 6 the run executes on
   the main thread with the same live progress bar. Qt 6 enforces
   thread affinity strictly enough that handing it layers built on a
   worker thread could abort QGIS outright, which was the cause of
   the hard crashes reported on QGIS 4. The background task is
   unchanged on QGIS 3, and can be forced on either generation with
   the AR_TARSEEM_BACKGROUND environment variable or the
   AR-Tarseem/background_run QSettings key.
 - QgsTask flag construction hardened against all three PyQt
   spellings, with a description-only fallback.
 - metadata.txt now declares qgisMaximumVersion=4.99.
 - About tab reports the running QGIS and Qt versions and the run
   mode in force.

 1.0.0 — First official release (July 2026)
 AR-Tarseem graduates from its development series (v0.14-v0.24) into
 its first official, production-ready release. Highlights of the full
 feature set:
 - Watershed delineation: pit filling, D8 flow direction and
   accumulation, stream extraction, one catchment per pour point with
   snapping to the main flow path, longest flow paths with segment
   slopes and three time-of-concentration estimates (Kirpich
   holistic, Kirpich 10-85, NRCS lag).
 - Sub-catchment subdivision by target area, with reaches, junctions
   and per-sub-basin longest flow paths.
 - Special Delineation Points: enforce junctions at dam/structure
   locations (snapped within the delineation snap radius); divide at
   the points only or combined with the area-based subdivision;
   junctions renamed with the point name and carrying the point's
   attributes.
 - Reservoir storage routing: any special point can be defined as a
   reservoir (elevation-volume curve with spillway and orifice
   outflow structures, or a direct storage-discharge table); the
   combined inflow is routed by the modified-Puls method and the
   attenuated outflow continues downstream. Outputs include inflow
   and outflow peaks, attenuation, peak storage and peak stage, plus
   full routing tables and interactive charts.
 - Hydrology: SCS-CN losses (Curve Number from a raster or a constant
   value; adjustable lambda = Ia/S), SCS Unit Hydrograph with
   adjustable peak rate factor, four SCS 24-h storm types or custom
   hyetographs, fully editable return periods, Thiessen rainfall
   stations, and TRRL-UK / Riyadh / fixed areal reduction.
 - Routing: Lag, Muskingum, variable-parameter Muskingum-Cunge.
 - Progress reporting: a live progress bar reports every stage and
   catchment. On QGIS 3 the engine runs as a background task, so QGIS
   stays fully responsive during a run; on QGIS 4 it runs on the main
   thread (see 1.0.1 above).
 - Results: attribute tables with peaks and volumes per return
   period; hydrograph CSVs and interactive HTML charts for every
   catchment, sub-basin, reach and junction, with an editable output
   window (tail length and cap) to guarantee complete hydrographs
   that recede to zero flow.
 - AR-Awdiya export: a new "AR-Awdiya" tab writes the whole model as
   a ready-to-run AR-Awdiya project (.json) - catchments, junctions,
   reach routing, reservoirs and design storms included - so the
   network opens with "Load project" and can be run and reported
   (Word / PDF) immediately.
 - Interoperability: HEC-HMS .basin export (versions 4.7-4.13,
   including true Reservoir elements), .met files per return period,
   and a .pdata file with the reservoir Elevation-Storage tables.
 .
 RECOMMENDED: download AR-Awdiya, the companion hydrologic network
 modeller, for tighter integration — open the exported files there
 to edit the network interactively and to generate Word and PDF
 documents of all outputs for engineering reports.
