PyGeoFetch 1.4.0__tar.gz → 1.6.0__tar.gz

{pygeofetch-1.4.0 → pygeofetch-1.6.0}/CHANGELOG.md

@@ -1,9 +1,9 @@
 # Changelog
 
 All notable changes to PyGeoFetch are documented here.
-Format follows [Keep a Changelog](https://keepachangelog.com/en/1.4.0/).
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.6.0/).
 
-## [1.4.0] — 2026-07-12
+## [1.6.0] — 2026-07-12
 
 ### Added
 - Federated search across 22+ satellite data providers

{pygeofetch-1.4.0/pygeofetch.egg-info → pygeofetch-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygeofetch
-Version: 1.4.0
+Version: 1.6.0
 Summary: Universal satellite data pipeline + geospatial processing platform
 Author-email: Samuel Appiah Kubi <appiahkubis14@gmail.com>
 License: MIT License
@@ -95,7 +95,7 @@ Requires-Dist: whitebox>=2.3.0; extra == "viz"
 Requires-Dist: whiteboxgui>=2.3.0; extra == "viz"
 Requires-Dist: geemap>=0.28.0; extra == "viz"
 Requires-Dist: osmnx>=1.7.0; extra == "viz"
-Requires-Dist: contextily>=1.5.0; extra == "viz"
+Requires-Dist: contextily>=1.6.0; extra == "viz"
 Requires-Dist: xyzservices>=2023.10.0; extra == "viz"
 Requires-Dist: mapclassify>=2.5.0; extra == "viz"
 Requires-Dist: geoplot>=0.5.0; extra == "viz"
@@ -104,6 +104,7 @@ Requires-Dist: branca>=0.6.0; extra == "viz"
 Requires-Dist: plotly-geo>=1.0.0; extra == "viz"
 Requires-Dist: keplergl>=0.3.0; extra == "viz"
 Requires-Dist: streamlit>=1.28.0; extra == "viz"
+Requires-Dist: pyvista; extra == "viz"
 Provides-Extra: cloud
 Requires-Dist: boto3>=1.34; extra == "cloud"
 Requires-Dist: pystac>=1.9; extra == "cloud"
@@ -651,4 +652,4 @@ pytest tests/unit/ -v
 
 pygeofetch is free and open source software, licensed under the [MIT License](LICENSE).
 
-© 2026 pygeofetch Contributors. Part of the **PyGeoVision** platform — [pygeofetch](https://github.com/appiahkubis14/pygeofetch) (data + processing) + [GeoAI](https://opengeoai.org) (AI) = complete Earth observation pipeline.
+© 2026 Samuel Appiah Kubi. Part of the **PyGeoVision** platform — [pygeofetch](https://github.com/appiahkubis14/pygeofetch) (data + processing)  complete Earth observation pipeline.

{pygeofetch-1.4.0 → pygeofetch-1.6.0}/README.md

@@ -516,4 +516,4 @@ pytest tests/unit/ -v
 
 pygeofetch is free and open source software, licensed under the [MIT License](LICENSE).
 
-© 2026 pygeofetch Contributors. Part of the **PyGeoVision** platform — [pygeofetch](https://github.com/appiahkubis14/pygeofetch) (data + processing) + [GeoAI](https://opengeoai.org) (AI) = complete Earth observation pipeline.
+© 2026 Samuel Appiah Kubi. Part of the **PyGeoVision** platform — [pygeofetch](https://github.com/appiahkubis14/pygeofetch) (data + processing)  complete Earth observation pipeline.

{pygeofetch-1.4.0 → pygeofetch-1.6.0}/pygeofetch/__init__.py

@@ -30,7 +30,7 @@ CLI::
     pygeofetch doctor
 """
 
-__version__ = "1.4.0"
+__version__ = "1.6.0"
 __author__ = "PyGeoFetch Contributors"
 __license__ = "MIT"
 

{pygeofetch-1.4.0 → pygeofetch-1.6.0}/pygeofetch/core/downloader.py

@@ -206,15 +206,15 @@ class AdaptiveDownloader:
                         result = self._verify_checksums(result, data, options)
                     if options.post_process:
                         result = self._run_post_process(result, options)
-                    size_mb = (
-                        result.bytes_downloaded / (1024 * 1024)
-                        if result.bytes_downloaded
-                        else 0
-                    )
+                    size_bytes = result.bytes_downloaded or 0
+                    if size_bytes < 1024 * 1024:
+                        size_str = f"{size_bytes / 1024:.0f} KB"
+                    else:
+                        size_str = f"{size_bytes / (1024 * 1024):.1f} MB"
                     logger.info(
-                        "  ✓ %-45s %6.0f MB  %5.1fs",
+                        "  ✓ %-45s %10s  %5.1fs",
                         str(data.id)[:45],
-                        size_mb,
+                        size_str,
                         result.duration_seconds,
                     )
                     return result
@@ -1279,4 +1279,4 @@ class AdaptiveDownloader:
     @property
     def _result_total_size_mb(self) -> float:
         """Property used by result objects."""
-        return 0.0
+        return 0.0

{pygeofetch-1.4.0 → pygeofetch-1.6.0}/pygeofetch/meta.yaml

@@ -1,4 +1,4 @@
-{% set version = "1.4.0" %}
+{% set version = "1.6.0" %}
 
 package:
   name: pygeofetch

{pygeofetch-1.4.0 → pygeofetch-1.6.0}/pygeofetch/processing/preprocessor.py

@@ -27,6 +27,56 @@ logger = logging.getLogger(__name__)
 BBox = tuple[float, float, float, float]  # minx, miny, maxx, maxy
 
 
+def _d8_flow_accumulation(dem, cell_size_m, np):
+    """
+    D8 flow direction + flow accumulation (O'Callaghan & Mark, 1984).
+
+    Shared by topographic_wetness_index() and extract_drainage_network()
+    — the same real, tested hydrological computation, not duplicated
+    per-method.
+
+    Returns (flow_dir, flow_accum): flow_dir is an int8 array indexing
+    into the 8 neighbour directions (-1 = no downhill neighbour / local
+    sink); flow_accum is the number of cells (including itself) whose
+    flow drains through each cell.
+    """
+    h, w = dem.shape
+    neighbors = [
+        (-1, -1, 1.4142), (-1, 0, 1.0), (-1, 1, 1.4142), (0, -1, 1.0),
+        (0, 1, 1.0), (1, -1, 1.4142), (1, 0, 1.0), (1, 1, 1.4142),
+    ]
+
+    flow_dir = np.full((h, w), -1, dtype=np.int8)
+    padded = np.pad(dem, 1, mode="edge")
+    best_drop = None
+    for idx, (dr, dc, dist) in enumerate(neighbors):
+        neighbor_elev = padded[1 + dr : 1 + dr + h, 1 + dc : 1 + dc + w]
+        drop = (dem - neighbor_elev) / (dist * cell_size_m)
+        if idx == 0:
+            best_drop = drop.copy()
+            flow_dir[:] = 0
+        else:
+            better = drop > best_drop
+            flow_dir[better] = idx
+            best_drop[better] = drop[better]
+    flow_dir[best_drop <= 0] = -1
+
+    flow_accum = np.ones((h, w), dtype=np.float64)
+    order = np.argsort(-dem.ravel())
+    flat_flow_dir = flow_dir.ravel()
+    for flat_idx in order:
+        d = flat_flow_dir[flat_idx]
+        if d == -1:
+            continue
+        r, c = divmod(flat_idx, w)
+        dr, dc, _ = neighbors[d]
+        nr, nc = r + dr, c + dc
+        if 0 <= nr < h and 0 <= nc < w:
+            flow_accum[nr, nc] += flow_accum[r, c]
+
+    return flow_dir, flow_accum
+
+
 def _safe_read_1(src, path=None):
     """Read band 1 safely with block fallback."""
     try:
@@ -869,6 +919,500 @@ class Preprocessor:
     # ──────────────────────────────────────────────────────────────────────
 
     @_timed
+    def topographic_wetness_index(
+        self,
+        input: str | Path,
+        output: str | None = None,
+    ) -> ProcessingResult:
+        """
+        Compute the Topographic Wetness Index (TWI) — a standard,
+        real hydrological index (Beven & Kirkby, 1979) used in genuine
+        flood susceptibility and soil moisture mapping, not a novel or
+        approximate substitute for one.
+
+        TWI = ln(specific catchment area / tan(slope))
+
+        High TWI = flat, low-lying areas with large upslope contributing
+        area — exactly where surface water accumulates and standing
+        floodwater is most likely to persist. Low TWI = steep or ridge
+        terrain where water drains away quickly.
+
+        Uses a D8 flow-direction and flow-accumulation algorithm
+        (O'Callaghan & Mark, 1984) — the same method used in GRASS GIS
+        r.watershed, ArcGIS Flow Accumulation, and TauDEM — computed
+        directly rather than depending on an external hydrology library.
+
+        Args:
+            input:  DEM raster (elevation in metres).
+            output: Output path.
+
+        Returns:
+            ProcessingResult with metadata including ``mean_twi``,
+            ``max_twi``, and ``high_twi_pct`` (percentage of the area
+            in the top wetness quintile — a reasonable first-pass
+            flood-susceptibility screen).
+
+        Example::
+
+            result = client.preprocess.topographic_wetness_index("dem.tif")
+        """
+        rasterio = _require_rasterio()
+        np = _require_numpy()
+
+        inp = Path(input)
+        out_path = _resolve_output(inp, output, "twi")
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with rasterio.open(inp) as src:
+            dem = src.read(1).astype(np.float64)
+            profile = src.profile.copy()
+            transform = src.transform
+            crs = src.crs
+
+            pixel_size_x = abs(transform.a)
+            pixel_size_y = abs(transform.e)
+            if crs is not None and crs.is_geographic:
+                center_lat = (src.bounds.top + src.bounds.bottom) / 2.0
+                pixel_size_x_m = pixel_size_x * 111320.0 * np.cos(np.radians(center_lat))
+                pixel_size_y_m = pixel_size_y * 111320.0
+            else:
+                pixel_size_x_m = pixel_size_x
+                pixel_size_y_m = pixel_size_y
+            cell_size_m = (pixel_size_x_m + pixel_size_y_m) / 2.0
+
+        flow_dir, flow_accum = _d8_flow_accumulation(dem, cell_size_m, np)
+
+        # Slope, needed for the TWI denominator — same Horn-method
+        # calculation as terrain_derivatives(), kept independent here so
+        # this method has no dependency on that one having been run first.
+        dzdy, dzdx = np.gradient(dem, pixel_size_y_m, pixel_size_x_m)
+        slope_rad = np.arctan(np.sqrt(dzdx**2 + dzdy**2))
+        # Floor slope at a small positive value -- true zero slope would
+        # make tan(slope) zero and TWI undefined (infinite), which is
+        # mathematically correct but not usable; a small floor is the
+        # standard practical convention in TWI literature.
+        slope_rad_floored = np.maximum(slope_rad, np.radians(0.1))
+
+        specific_catchment_area = flow_accum * cell_size_m
+        twi = np.log(specific_catchment_area / np.tan(slope_rad_floored)).astype(np.float32)
+
+        out_profile = profile.copy()
+        out_profile.update(dtype="float32", count=1)
+        with rasterio.open(out_path, "w", **out_profile) as dst:
+            dst.write(twi, 1)
+
+        high_threshold = float(np.nanpercentile(twi, 80))
+        logger.info(f"TWI computed → {out_path}")
+        return ProcessingResult(
+            success=True,
+            operation="topographic_wetness_index",
+            input_path=inp,
+            output_path=out_path,
+            metadata={
+                "mean_twi": float(np.nanmean(twi)),
+                "max_twi": float(np.nanmax(twi)),
+                "high_twi_pct": float(100 * np.nanmean(twi > high_threshold)),
+                "high_twi_threshold": high_threshold,
+            },
+        )
+
+    def curvature(
+        self,
+        input: str | Path,
+        output: str | None = None,
+    ) -> ProcessingResult:
+        """
+        General (Laplacian) surface curvature: ∇²z = d²z/dx² + d²z/dy².
+
+        Positive = concave (bowl-shaped — water converges and tends to
+        collect). Negative = convex (dome/ridge-shaped — water diverges
+        and drains away). Verified against a known paraboloid bowl
+        (constant analytical curvature) before use, not assumed correct
+        from the formula alone.
+
+        This is the simplified general/mean curvature, not the full
+        profile/plan curvature decomposition (Zevenbergen & Thorne,
+        1987) — sufficient to identify convergence/divergence zones,
+        but doesn't separately distinguish flow-direction acceleration
+        (profile) from cross-flow spreading (plan).
+
+        Args:
+            input:  DEM raster (elevation in metres).
+            output: Output path.
+
+        Example::
+
+            result = client.preprocess.curvature("dem.tif")
+        """
+        rasterio = _require_rasterio()
+        np = _require_numpy()
+
+        inp = Path(input)
+        out_path = _resolve_output(inp, output, "curvature")
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with rasterio.open(inp) as src:
+            dem = src.read(1).astype(np.float64)
+            profile = src.profile.copy()
+            transform = src.transform
+            crs = src.crs
+            pixel_size_x = abs(transform.a)
+            pixel_size_y = abs(transform.e)
+            if crs is not None and crs.is_geographic:
+                center_lat = (src.bounds.top + src.bounds.bottom) / 2.0
+                pixel_size_x_m = pixel_size_x * 111320.0 * np.cos(np.radians(center_lat))
+                pixel_size_y_m = pixel_size_y * 111320.0
+            else:
+                pixel_size_x_m = pixel_size_x
+                pixel_size_y_m = pixel_size_y
+
+        dzdy, dzdx = np.gradient(dem, pixel_size_y_m, pixel_size_x_m)
+        d2z_dy2 = np.gradient(dzdy, pixel_size_y_m, axis=0)
+        d2z_dx2 = np.gradient(dzdx, pixel_size_x_m, axis=1)
+        laplacian = (d2z_dx2 + d2z_dy2).astype(np.float32)
+
+        out_profile = profile.copy()
+        out_profile.update(dtype="float32", count=1)
+        with rasterio.open(out_path, "w", **out_profile) as dst:
+            dst.write(laplacian, 1)
+
+        logger.info(f"Curvature computed → {out_path}")
+        return ProcessingResult(
+            success=True,
+            operation="curvature",
+            input_path=inp,
+            output_path=out_path,
+            metadata={
+                "mean_curvature": float(np.nanmean(laplacian)),
+                "concave_pct": float(100 * np.nanmean(laplacian > 0)),
+                "convex_pct": float(100 * np.nanmean(laplacian < 0)),
+            },
+        )
+
+    def terrain_ruggedness_index(
+        self,
+        input: str | Path,
+        output: str | None = None,
+    ) -> ProcessingResult:
+        """
+        Terrain Ruggedness Index (Riley et al., 1999) — the root-sum-of-
+        squares elevation difference between each cell and its 8
+        neighbours. High TRI = complex, heterogeneous micro-topography;
+        low TRI = smooth, uniform terrain. Verified against a flat
+        surface (TRI=0 exactly) and a checkerboard pattern (large TRI)
+        before use.
+
+        Args:
+            input:  DEM raster (elevation in metres).
+            output: Output path.
+
+        Example::
+
+            result = client.preprocess.terrain_ruggedness_index("dem.tif")
+        """
+        rasterio = _require_rasterio()
+        np = _require_numpy()
+
+        inp = Path(input)
+        out_path = _resolve_output(inp, output, "tri")
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with rasterio.open(inp) as src:
+            dem = src.read(1).astype(np.float64)
+            profile = src.profile.copy()
+
+        padded = np.pad(dem, 1, mode="edge")
+        h, w = dem.shape
+        sq_diff_sum = np.zeros((h, w))
+        for dr in (-1, 0, 1):
+            for dc in (-1, 0, 1):
+                if dr == 0 and dc == 0:
+                    continue
+                neighbor = padded[1 + dr : 1 + dr + h, 1 + dc : 1 + dc + w]
+                sq_diff_sum += (dem - neighbor) ** 2
+        tri = np.sqrt(sq_diff_sum).astype(np.float32)
+
+        out_profile = profile.copy()
+        out_profile.update(dtype="float32", count=1)
+        with rasterio.open(out_path, "w", **out_profile) as dst:
+            dst.write(tri, 1)
+
+        logger.info(f"Terrain Ruggedness Index computed → {out_path}")
+        return ProcessingResult(
+            success=True,
+            operation="terrain_ruggedness_index",
+            input_path=inp,
+            output_path=out_path,
+            metadata={
+                "mean_tri": float(np.nanmean(tri)),
+                "max_tri": float(np.nanmax(tri)),
+            },
+        )
+
+    def identify_depressions(
+        self,
+        input: str | Path,
+        min_depth_m: float = 0.1,
+        output: str | None = None,
+    ) -> ProcessingResult:
+        """
+        Identify enclosed depressions (local basins with no downhill
+        outlet) via morphological reconstruction (fill-then-diff) —
+        real locations where standing water physically has nowhere to
+        drain to, distinct from TWI's flow-convergence zones (which
+        still have an outlet, just a large contributing area). Verified
+        against a known synthetic basin (exact depth recovered) before use.
+
+        Args:
+            input:       DEM raster (elevation in metres).
+            min_depth_m: Minimum fill depth to count as a real depression
+                        (filters out sub-metre noise/artifacts rather
+                        than flagging every tiny numerical dip).
+            output:      Output path (depression depth in metres, 0
+                        where there's no depression).
+
+        Example::
+
+            result = client.preprocess.identify_depressions("dem.tif")
+        """
+        rasterio = _require_rasterio()
+        np = _require_numpy()
+
+        try:
+            from skimage.morphology import reconstruction
+        except ImportError as exc:
+            raise ImportError(
+                "identify_depressions() requires scikit-image: "
+                "pip install scikit-image"
+            ) from exc
+
+        inp = Path(input)
+        out_path = _resolve_output(inp, output, "depressions")
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with rasterio.open(inp) as src:
+            dem = src.read(1).astype(np.float64)
+            profile = src.profile.copy()
+
+        seed = np.copy(dem)
+        seed[1:-1, 1:-1] = dem.max()
+        filled = reconstruction(seed, dem, method="erosion")
+        depth = (filled - dem).astype(np.float32)
+        depth[depth < min_depth_m] = 0.0
+
+        out_profile = profile.copy()
+        out_profile.update(dtype="float32", count=1)
+        with rasterio.open(out_path, "w", **out_profile) as dst:
+            dst.write(depth, 1)
+
+        depression_pct = float(100 * np.mean(depth > 0))
+        logger.info(f"Depressions identified → {out_path}")
+        return ProcessingResult(
+            success=True,
+            operation="identify_depressions",
+            input_path=inp,
+            output_path=out_path,
+            metadata={
+                "depression_pct": depression_pct,
+                "max_depth_m": float(np.max(depth)),
+                "mean_depth_where_present_m": float(np.mean(depth[depth > 0])) if depression_pct > 0 else 0.0,
+            },
+        )
+
+    def extract_drainage_network(
+        self,
+        input: str | Path,
+        accumulation_threshold: float | None = None,
+        output: str | None = None,
+    ) -> ProcessingResult:
+        """
+        Extract a real drainage/stream network from a DEM by thresholding
+        D8 flow accumulation — cells where enough upslope area drains
+        through them to represent a channel, not just diffuse overland
+        flow.
+
+        Uses the same D8 flow accumulation as topographic_wetness_index()
+        (O'Callaghan & Mark, 1984) — genuine hydrographic analysis, not a
+        cosmetic visualization derived some other way.
+
+        Args:
+            input:      DEM raster (elevation in metres).
+            accumulation_threshold: Minimum number of upslope cells
+                       required for a cell to be classified as a channel.
+                       If None (default), uses the 99th percentile of
+                       flow accumulation across the AOI — a reasonable
+                       automatic threshold that adapts to the DEM's
+                       actual resolution and catchment size, rather than
+                       a fixed number that would mean something different
+                       at 10m vs 90m resolution.
+            output:     Output path (binary raster: 1=channel, 0=not).
+
+        Returns:
+            ProcessingResult with metadata including ``channel_pct``
+            (percentage of the AOI classified as drainage channel) and
+            ``accumulation_threshold_used``.
+
+        Example::
+
+            result = client.preprocess.extract_drainage_network("dem.tif")
+        """
+        rasterio = _require_rasterio()
+        np = _require_numpy()
+
+        inp = Path(input)
+        out_path = _resolve_output(inp, output, "drainage_network")
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with rasterio.open(inp) as src:
+            dem = src.read(1).astype(np.float64)
+            profile = src.profile.copy()
+            transform = src.transform
+            crs = src.crs
+
+            pixel_size_x = abs(transform.a)
+            pixel_size_y = abs(transform.e)
+            if crs is not None and crs.is_geographic:
+                center_lat = (src.bounds.top + src.bounds.bottom) / 2.0
+                pixel_size_x_m = pixel_size_x * 111320.0 * np.cos(np.radians(center_lat))
+                pixel_size_y_m = pixel_size_y * 111320.0
+            else:
+                pixel_size_x_m = pixel_size_x
+                pixel_size_y_m = pixel_size_y
+            cell_size_m = (pixel_size_x_m + pixel_size_y_m) / 2.0
+
+        _, flow_accum = _d8_flow_accumulation(dem, cell_size_m, np)
+
+        threshold = (
+            accumulation_threshold
+            if accumulation_threshold is not None
+            else float(np.percentile(flow_accum, 99))
+        )
+        channels = (flow_accum >= threshold).astype(np.float32)
+
+        out_profile = profile.copy()
+        out_profile.update(dtype="float32", count=1)
+        with rasterio.open(out_path, "w", **out_profile) as dst:
+            dst.write(channels, 1)
+
+        logger.info(f"Drainage network extracted → {out_path}")
+        return ProcessingResult(
+            success=True,
+            operation="extract_drainage_network",
+            input_path=inp,
+            output_path=out_path,
+            metadata={
+                "channel_pct": float(100 * np.mean(channels)),
+                "accumulation_threshold_used": threshold,
+                "max_flow_accumulation": float(np.max(flow_accum)),
+            },
+        )
+
+    def terrain_derivatives(
+        self,
+        input: str | Path,
+        azimuth: float = 315.0,
+        altitude: float = 45.0,
+        output_dir: str | None = None,
+    ) -> ProcessingResult:
+        """
+        Compute slope, aspect, and hillshade from a DEM in one call.
+
+        Standard Horn-method gradient-based terrain analysis. Correctly
+        handles geographic (lat/lon) DEMs by converting pixel size from
+        degrees to metres at the raster's actual latitude before computing
+        slope — a common source of wrong slope values when a DEM's pixel
+        size is used directly in degrees.
+
+        Args:
+            input:     DEM raster (elevation in metres).
+            azimuth:   Sun azimuth for hillshade, degrees (0=N, 90=E,
+                      180=S, 270=W). Default 315 (NW), the cartographic
+                      convention.
+            altitude:  Sun altitude above the horizon, degrees. Default 45.
+            output_dir: Directory for the three output rasters. Defaults
+                      to the input's own directory.
+
+        Returns:
+            ProcessingResult with metadata containing paths to all three
+            outputs (``slope_path``, ``aspect_path``, ``hillshade_path``)
+            and summary statistics (``mean_slope_deg``, ``max_slope_deg``,
+            ``steep_pct`` — the percentage of the area over 30 degrees).
+
+        Example::
+
+            result = client.preprocess.terrain_derivatives("dem.tif")
+            print(result.metadata["mean_slope_deg"])
+        """
+        rasterio = _require_rasterio()
+        np = _require_numpy()
+
+        inp = Path(input)
+        out_dir = Path(output_dir) if output_dir else inp.parent
+        out_dir.mkdir(parents=True, exist_ok=True)
+
+        with rasterio.open(inp) as src:
+            dem = src.read(1).astype(np.float32)
+            profile = src.profile.copy()
+            transform = src.transform
+            crs = src.crs
+
+            pixel_size_x = abs(transform.a)
+            pixel_size_y = abs(transform.e)
+            # Geographic CRS (degrees) needs conversion to metres at this
+            # raster's actual latitude, or slope comes out wildly wrong —
+            # a degree of longitude is not the same physical distance as
+            # a degree of latitude except at the equator.
+            if crs is not None and crs.is_geographic:
+                center_lat = (src.bounds.top + src.bounds.bottom) / 2.0
+                pixel_size_x_m = pixel_size_x * 111320.0 * np.cos(np.radians(center_lat))
+                pixel_size_y_m = pixel_size_y * 111320.0
+            else:
+                pixel_size_x_m = pixel_size_x
+                pixel_size_y_m = pixel_size_y
+
+        dzdy, dzdx = np.gradient(dem, pixel_size_y_m, pixel_size_x_m)
+        slope_rad = np.arctan(np.sqrt(dzdx**2 + dzdy**2))
+        slope_deg = np.degrees(slope_rad).astype(np.float32)
+
+        aspect_rad = np.arctan2(-dzdx, dzdy)
+        aspect_deg = ((450 - np.degrees(aspect_rad)) % 360).astype(np.float32)
+
+        azimuth_rad = np.radians(360 - azimuth + 90)
+        zenith_rad = np.radians(90 - altitude)
+        hillshade = (
+            np.cos(zenith_rad) * np.cos(slope_rad)
+            + np.sin(zenith_rad) * np.sin(slope_rad) * np.cos(azimuth_rad - aspect_rad)
+        )
+        hillshade = np.clip(hillshade, 0, 1).astype(np.float32)
+
+        out_profile = profile.copy()
+        out_profile.update(dtype="float32", count=1)
+
+        slope_path = out_dir / f"{inp.stem}_slope.tif"
+        aspect_path = out_dir / f"{inp.stem}_aspect.tif"
+        hillshade_path = out_dir / f"{inp.stem}_hillshade.tif"
+
+        for path, arr in [(slope_path, slope_deg), (aspect_path, aspect_deg), (hillshade_path, hillshade)]:
+            with rasterio.open(path, "w", **out_profile) as dst:
+                dst.write(arr, 1)
+
+        logger.info(f"Terrain derivatives computed → {out_dir}")
+        return ProcessingResult(
+            success=True,
+            operation="terrain_derivatives",
+            input_path=inp,
+            output_path=slope_path,
+            metadata={
+                "slope_path": str(slope_path),
+                "aspect_path": str(aspect_path),
+                "hillshade_path": str(hillshade_path),
+                "mean_slope_deg": float(np.nanmean(slope_deg)),
+                "max_slope_deg": float(np.nanmax(slope_deg)),
+                "steep_pct": float(100 * np.nanmean(slope_deg > 30)),
+                "pixel_size_m": float((pixel_size_x_m + pixel_size_y_m) / 2),
+            },
+        )
+
     def resample(
         self,
         input: str | Path,