openrelief 0.1.0__tar.gz

openrelief-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 Naveen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The MIT license above covers the source code of this package only. It is not a
+patent grant and makes no representation about third-party intellectual
+property. See NOTICE for attribution and an intellectual-property note about
+the red-relief visualization technique this software implements.

openrelief-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE
+include NOTICE
+include README.md
+include pyproject.toml
+recursive-include src/openrelief *.py
+include src/openrelief/py.typed

openrelief-0.1.0/NOTICE

@@ -0,0 +1,50 @@
+openrelief
+==========
+
+This software is an independent, open-source implementation of a terrain
+visualization technique that combines topographic slope with positive and
+negative topographic openness, rendered as a red-shaded relief image. The
+technique is commonly known as the "Red Relief Image Map" (RRIM).
+
+Attribution
+-----------
+The red-relief image map method was developed by Tatsuro Chiba, Shin-ichi
+Kaneta and Yusuke Suzuki at Asia Air Survey Co., Ltd. The topographic openness
+measure it builds on was introduced by Ryuzo Yokoyama, Michio Shirasawa and
+Richard J. Pike. This package reimplements those published methods from the
+academic literature; it is not produced, endorsed by, or affiliated with Asia
+Air Survey Co., Ltd.
+
+Trademarks
+----------
+"RRIM", "Red Relief Image Map", and "赤色立体地図" are used or claimed as
+trademarks of Asia Air Survey Co., Ltd. Those names are referenced here only to
+describe the method this software implements (nominative use). This package is
+deliberately named "openrelief" and does not use those marks as its product
+name or branding. Do not market derivatives of this software under those marks.
+
+Intellectual-property note
+--------------------------
+The RRIM method was patented by Asia Air Survey Co., Ltd., with patent family
+members filed in Japan, the United States, China and Taiwan (e.g. JP 3670274).
+These patents derive from filings in the early 2000s and, based on the standard
+~20-year patent term, the relevant patents appear to have expired. Patent
+status is jurisdiction-specific and time-sensitive, and nothing here is legal
+advice. Before publishing, redistributing, or building a commercial product on
+this software, independently verify the current legal status of the relevant
+patents in every jurisdiction that matters to you (e.g. J-PlatPat for Japan,
+the USPTO / Google Patents for the United States), and consult a qualified
+intellectual-property attorney if anything material depends on it.
+
+Citation
+--------
+If you use this software in academic work, please cite the original methods:
+
+  Chiba, T., Kaneta, S., & Suzuki, Y. (2008). Red relief image map: new
+  visualization method for three-dimensional data. International Archives of
+  the Photogrammetry, Remote Sensing and Spatial Information Sciences,
+  XXXVII(B2), 1071-1076.
+
+  Yokoyama, R., Shirasawa, M., & Pike, R. J. (2002). Visualizing topography by
+  openness: a new application of image processing to digital elevation models.
+  Photogrammetric Engineering & Remote Sensing, 68(3), 257-265.

openrelief-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: openrelief
+Version: 0.1.0
+Summary: Red-shaded terrain relief (the Red Relief Image Map / RRIM technique) from Digital Elevation Models, with parallel CPU and optional GPU acceleration.
+Author-email: Naveen <nvnsudharsan@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/nvnsudharsan/openrelief
+Project-URL: Repository, https://github.com/nvnsudharsan/openrelief
+Project-URL: Issues, https://github.com/nvnsudharsan/openrelief/issues
+Keywords: red relief,RRIM,DEM,topographic openness,terrain,hillshade,lidar,GIS,raster,visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: numpy>=1.21
+Requires-Dist: rasterio>=1.3
+Requires-Dist: scipy>=1.7
+Requires-Dist: joblib>=1.4
+Requires-Dist: Pillow>=9.0
+Provides-Extra: gpu
+Requires-Dist: cupy-cuda12x; extra == "gpu"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# openrelief — red-shaded terrain relief from DEMs
+
+`openrelief` turns any Digital Elevation Model into a **red-shaded relief image**
+that combines topographic slope with positive/negative **topographic openness** —
+the visualization widely known as the *Red Relief Image Map* (RRIM). Give it a
+DEM (or a folder/glob of DEM tiles) and it produces a seamless georeferenced RGB
+GeoTIFF plus a PNG preview.
+
+> **Note on naming and IP.** This is an independent, open-source reimplementation
+> of a published method. The package is intentionally named `openrelief` and
+> avoids the *RRIM* / *Red Relief Image Map* trademarks as branding. The RRIM
+> method was developed and patented by Asia Air Survey Co., Ltd.; those patents
+> appear to have expired, but you should verify this yourself before publishing
+> or commercializing. See [NOTICE](NOTICE) for attribution, citation, trademark
+> and patent details, and [LICENSE](LICENSE) for the code license.
+
+* **Any DEM** rasterio can read: GeoTIFF, USGS `.dem`, ERDAS `.img`, ArcInfo
+  `.asc`, `.bil/.flt`, SRTM `.hgt`, `.vrt`, … — CRS, no-data, pixel size and
+  elevation unit are all read from the file, nothing is hard-coded.
+* **Seamless mosaics** — multiple tiles are stitched through an in-memory VRT and
+  processed in overlapping windows (a halo equal to the openness radius), so
+  there are no seams at tile boundaries.
+* **Parallel** across windows on the CPU (joblib) and **GPU-accelerated**
+  automatically when [CuPy](https://cupy.dev) + a CUDA device are present.
+* **Fully tunable** — every visual knob (openness radius, slope clip, gammas,
+  blend opacity, …) is exposed, with defaults matching the classic look.
+
+---
+
+## How the image is built
+
+For every cell the package computes:
+
+1. **Slope** (degrees) → red saturation. Flat = white `(255,255,255)`, steep =
+   pure red `(255,0,0)`.
+2. **Topographic openness** (Yokoyama et al., 2002) in `--directions` azimuths
+   out to `--radius` pixels: positive openness (high on ridges) and negative
+   openness (high in valleys).
+3. **Differential openness** `(positive − negative) / 2` → brightness. Ridges
+   render light, valleys dark — this gives the floating-3D relief.
+4. The grey openness layer is **multiply-blended** onto the red slope layer at
+   `--opacity` (0.5 by default). Method reference: Chiba, Kaneta & Suzuki (2008).
+
+Horizontal distances are converted to **ground metres** automatically (linear
+unit for projected CRSs; degrees→metres at the scene latitude for geographic
+CRSs), so the relief is geometrically correct for any projection. If your
+elevation unit differs from the horizontal unit, set `--z-factor` (e.g. `0.3048`
+for feet-Z over metre-XY).
+
+---
+
+## Install
+
+```bash
+pip install -e .            # from this folder
+```
+
+Core deps: `numpy`, `rasterio`, `scipy`, `joblib`, `Pillow`.
+
+**GPU (optional):** install the CuPy wheel for your CUDA toolkit, e.g.
+
+```bash
+pip install cupy-cuda12x        # CUDA 12.x   (or cupy-cuda11x)
+```
+
+When CuPy and a GPU are present the GPU is used automatically. Check with:
+
+```bash
+openrelief --check-gpu
+```
+
+---
+
+## Command line
+
+```bash
+# Single DEM
+openrelief dem.tif -o relief.tif
+
+# A whole folder of tiles -> one seamless mosaic + preview
+openrelief /path/to/dems/ -o area_relief.tif
+
+# A glob, tuned for flat terrain, forced GPU
+openrelief "tiles/*.dem" -o relief.tif --slope-max 15 --openness-range 12 --radius 40 --gpu
+```
+
+Useful options (`openrelief -h` for all):
+
+| Option | Meaning | Default |
+|---|---|---|
+| `--radius` | openness search length (px) | 30 |
+| `--directions` | azimuths sampled (4/8/16) | 8 |
+| `--openness-range` | diff-openness deg → black..white | 30 |
+| `--slope-max` | slope deg → full red | 50 |
+| `--slope-gamma` / `--openness-gamma` | tone curves | 1.0 |
+| `--opacity` | openness layer blend (0..1) | 0.5 |
+| `--z-factor` | elevation→ground unit multiplier | 1.0 |
+| `--window` | processing window (px) | 2048 |
+| `--jobs` | CPU workers (-1 = all cores) | -1 |
+| `--auto-window` | size windows from the core count | off |
+| `--tiles-per-core` | with `--auto-window`, tiles/core (1 = one tile per processor) | 4 |
+| `--gpu` / `--cpu` | force a backend | auto |
+| `--compress` | deflate/lzw/zstd/none | deflate |
+| `--no-preview` / `--preview-size` | PNG quick-look | on / 4000 |
+
+**Tuning tip:** flatter terrain wants smaller `--slope-max` and
+`--openness-range` (more contrast); rugged terrain wants larger values. A larger
+`--radius` broadens the relief but costs ~linearly more compute.
+
+---
+
+## Python API
+
+```python
+from openrelief import ReliefConfig, relief_from_dems, relief_array
+
+# High-level: DEM(s) -> GeoTIFF + PNG
+relief_from_dems("tiles/", "out.tif",
+                 ReliefConfig(openness_radius=40, slope_max=20))
+
+# Low-level: a NumPy elevation array -> (3, H, W) uint8 relief
+import numpy as np
+rgb = relief_array(dem_array, res_x=1.0, res_y=1.0,
+                   cfg=ReliefConfig(openness_radius=24))
+```
+
+`ReliefConfig` carries every parameter above; `use_gpu=None/True/False` controls
+the backend. You can also force a backend globally with the
+`OPENRELIEF_BACKEND=cpu|gpu` environment variable.
+
+---
+
+## How it scales
+
+Cost is roughly `O(8 · radius · pixels)`. The raster is split into independent
+`--window`-sized tiles with a `radius`-pixel halo:
+
+* **CPU:** windows are distributed over processes with joblib and streamed to the
+  output as they finish, so memory stays bounded regardless of mosaic size. By
+  default there are more windows than cores so a freed worker immediately picks
+  up the next one (dynamic load balancing). `--auto-window` instead sizes the
+  windows from the core count: `--tiles-per-core 1` gives one tile per
+  processor (simplest, but prone to stragglers and high per-worker memory),
+  while the default of 4 keeps every core fed. The pixels produced are identical
+  either way — only the scheduling changes.
+* **GPU:** windows are streamed to the device sequentially; the per-window size
+  keeps GPU memory in check while still giving a large speed-up.
+
+Output GeoTIFFs are tiled and compressed (`BIGTIFF=IF_SAFER`), so very large
+mosaics are handled gracefully. Empty windows in a sparse mosaic are skipped.
+
+---
+
+## Attribution & citation
+
+This package reimplements published methods. Please credit the original authors;
+full details and references are in [NOTICE](NOTICE).
+
+* Chiba, T., Kaneta, S., & Suzuki, Y. (2008). *Red relief image map: new
+  visualization method for three-dimensional data.* ISPRS Archives,
+  XXXVII(B2), 1071–1076.
+* Yokoyama, R., Shirasawa, M., & Pike, R. J. (2002). *Visualizing topography by
+  openness.* PE&RS 68(3), 257–265.
+* Asia Air Survey — https://www.rrim.jp/en/
+
+## License
+
+Source code: MIT (see [LICENSE](LICENSE)). The MIT license covers this code only
+and is not a patent grant; see [NOTICE](NOTICE) for the intellectual-property
+note.

openrelief-0.1.0/README.md

@@ -0,0 +1,170 @@
+# openrelief — red-shaded terrain relief from DEMs
+
+`openrelief` turns any Digital Elevation Model into a **red-shaded relief image**
+that combines topographic slope with positive/negative **topographic openness** —
+the visualization widely known as the *Red Relief Image Map* (RRIM). Give it a
+DEM (or a folder/glob of DEM tiles) and it produces a seamless georeferenced RGB
+GeoTIFF plus a PNG preview.
+
+> **Note on naming and IP.** This is an independent, open-source reimplementation
+> of a published method. The package is intentionally named `openrelief` and
+> avoids the *RRIM* / *Red Relief Image Map* trademarks as branding. The RRIM
+> method was developed and patented by Asia Air Survey Co., Ltd.; those patents
+> appear to have expired, but you should verify this yourself before publishing
+> or commercializing. See [NOTICE](NOTICE) for attribution, citation, trademark
+> and patent details, and [LICENSE](LICENSE) for the code license.
+
+* **Any DEM** rasterio can read: GeoTIFF, USGS `.dem`, ERDAS `.img`, ArcInfo
+  `.asc`, `.bil/.flt`, SRTM `.hgt`, `.vrt`, … — CRS, no-data, pixel size and
+  elevation unit are all read from the file, nothing is hard-coded.
+* **Seamless mosaics** — multiple tiles are stitched through an in-memory VRT and
+  processed in overlapping windows (a halo equal to the openness radius), so
+  there are no seams at tile boundaries.
+* **Parallel** across windows on the CPU (joblib) and **GPU-accelerated**
+  automatically when [CuPy](https://cupy.dev) + a CUDA device are present.
+* **Fully tunable** — every visual knob (openness radius, slope clip, gammas,
+  blend opacity, …) is exposed, with defaults matching the classic look.
+
+---
+
+## How the image is built
+
+For every cell the package computes:
+
+1. **Slope** (degrees) → red saturation. Flat = white `(255,255,255)`, steep =
+   pure red `(255,0,0)`.
+2. **Topographic openness** (Yokoyama et al., 2002) in `--directions` azimuths
+   out to `--radius` pixels: positive openness (high on ridges) and negative
+   openness (high in valleys).
+3. **Differential openness** `(positive − negative) / 2` → brightness. Ridges
+   render light, valleys dark — this gives the floating-3D relief.
+4. The grey openness layer is **multiply-blended** onto the red slope layer at
+   `--opacity` (0.5 by default). Method reference: Chiba, Kaneta & Suzuki (2008).
+
+Horizontal distances are converted to **ground metres** automatically (linear
+unit for projected CRSs; degrees→metres at the scene latitude for geographic
+CRSs), so the relief is geometrically correct for any projection. If your
+elevation unit differs from the horizontal unit, set `--z-factor` (e.g. `0.3048`
+for feet-Z over metre-XY).
+
+---
+
+## Install
+
+```bash
+pip install -e .            # from this folder
+```
+
+Core deps: `numpy`, `rasterio`, `scipy`, `joblib`, `Pillow`.
+
+**GPU (optional):** install the CuPy wheel for your CUDA toolkit, e.g.
+
+```bash
+pip install cupy-cuda12x        # CUDA 12.x   (or cupy-cuda11x)
+```
+
+When CuPy and a GPU are present the GPU is used automatically. Check with:
+
+```bash
+openrelief --check-gpu
+```
+
+---
+
+## Command line
+
+```bash
+# Single DEM
+openrelief dem.tif -o relief.tif
+
+# A whole folder of tiles -> one seamless mosaic + preview
+openrelief /path/to/dems/ -o area_relief.tif
+
+# A glob, tuned for flat terrain, forced GPU
+openrelief "tiles/*.dem" -o relief.tif --slope-max 15 --openness-range 12 --radius 40 --gpu
+```
+
+Useful options (`openrelief -h` for all):
+
+| Option | Meaning | Default |
+|---|---|---|
+| `--radius` | openness search length (px) | 30 |
+| `--directions` | azimuths sampled (4/8/16) | 8 |
+| `--openness-range` | diff-openness deg → black..white | 30 |
+| `--slope-max` | slope deg → full red | 50 |
+| `--slope-gamma` / `--openness-gamma` | tone curves | 1.0 |
+| `--opacity` | openness layer blend (0..1) | 0.5 |
+| `--z-factor` | elevation→ground unit multiplier | 1.0 |
+| `--window` | processing window (px) | 2048 |
+| `--jobs` | CPU workers (-1 = all cores) | -1 |
+| `--auto-window` | size windows from the core count | off |
+| `--tiles-per-core` | with `--auto-window`, tiles/core (1 = one tile per processor) | 4 |
+| `--gpu` / `--cpu` | force a backend | auto |
+| `--compress` | deflate/lzw/zstd/none | deflate |
+| `--no-preview` / `--preview-size` | PNG quick-look | on / 4000 |
+
+**Tuning tip:** flatter terrain wants smaller `--slope-max` and
+`--openness-range` (more contrast); rugged terrain wants larger values. A larger
+`--radius` broadens the relief but costs ~linearly more compute.
+
+---
+
+## Python API
+
+```python
+from openrelief import ReliefConfig, relief_from_dems, relief_array
+
+# High-level: DEM(s) -> GeoTIFF + PNG
+relief_from_dems("tiles/", "out.tif",
+                 ReliefConfig(openness_radius=40, slope_max=20))
+
+# Low-level: a NumPy elevation array -> (3, H, W) uint8 relief
+import numpy as np
+rgb = relief_array(dem_array, res_x=1.0, res_y=1.0,
+                   cfg=ReliefConfig(openness_radius=24))
+```
+
+`ReliefConfig` carries every parameter above; `use_gpu=None/True/False` controls
+the backend. You can also force a backend globally with the
+`OPENRELIEF_BACKEND=cpu|gpu` environment variable.
+
+---
+
+## How it scales
+
+Cost is roughly `O(8 · radius · pixels)`. The raster is split into independent
+`--window`-sized tiles with a `radius`-pixel halo:
+
+* **CPU:** windows are distributed over processes with joblib and streamed to the
+  output as they finish, so memory stays bounded regardless of mosaic size. By
+  default there are more windows than cores so a freed worker immediately picks
+  up the next one (dynamic load balancing). `--auto-window` instead sizes the
+  windows from the core count: `--tiles-per-core 1` gives one tile per
+  processor (simplest, but prone to stragglers and high per-worker memory),
+  while the default of 4 keeps every core fed. The pixels produced are identical
+  either way — only the scheduling changes.
+* **GPU:** windows are streamed to the device sequentially; the per-window size
+  keeps GPU memory in check while still giving a large speed-up.
+
+Output GeoTIFFs are tiled and compressed (`BIGTIFF=IF_SAFER`), so very large
+mosaics are handled gracefully. Empty windows in a sparse mosaic are skipped.
+
+---
+
+## Attribution & citation
+
+This package reimplements published methods. Please credit the original authors;
+full details and references are in [NOTICE](NOTICE).
+
+* Chiba, T., Kaneta, S., & Suzuki, Y. (2008). *Red relief image map: new
+  visualization method for three-dimensional data.* ISPRS Archives,
+  XXXVII(B2), 1071–1076.
+* Yokoyama, R., Shirasawa, M., & Pike, R. J. (2002). *Visualizing topography by
+  openness.* PE&RS 68(3), 257–265.
+* Asia Air Survey — https://www.rrim.jp/en/
+
+## License
+
+Source code: MIT (see [LICENSE](LICENSE)). The MIT license covers this code only
+and is not a patent grant; see [NOTICE](NOTICE) for the intellectual-property
+note.

openrelief-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openrelief"
+version = "0.1.0"
+description = "Red-shaded terrain relief (the Red Relief Image Map / RRIM technique) from Digital Elevation Models, with parallel CPU and optional GPU acceleration."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Naveen", email = "nvnsudharsan@gmail.com" }]
+keywords = ["red relief", "RRIM", "DEM", "topographic openness", "terrain",
+            "hillshade", "lidar", "GIS", "raster", "visualization"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+
+dependencies = [
+    "numpy>=1.21",
+    "rasterio>=1.3",
+    "scipy>=1.7",
+    "joblib>=1.4",
+    "Pillow>=9.0",
+]
+
+[project.optional-dependencies]
+# Install the wheel that matches your CUDA toolkit, e.g. cupy-cuda12x
+gpu = ["cupy-cuda12x"]
+dev = ["pytest", "build", "twine"]
+
+# NOTE: update nvnsudharsan to your GitHub handle before publishing.
+[project.urls]
+Homepage = "https://github.com/nvnsudharsan/openrelief"
+Repository = "https://github.com/nvnsudharsan/openrelief"
+Issues = "https://github.com/nvnsudharsan/openrelief/issues"
+
+[project.scripts]
+openrelief = "openrelief.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+openrelief = ["py.typed"]

openrelief-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

openrelief-0.1.0/src/openrelief/__init__.py

@@ -0,0 +1,22 @@
+"""rrim - Red Relief Image Map generation from Digital Elevation Models.
+
+Public API
+----------
+    from openrelief import ReliefConfig, relief_from_dems, relief_array
+
+`relief_from_dems` is the high-level entry point: give it one or more DEM files
+and it builds a seamless RRIM mosaic GeoTIFF (and optional PNG preview),
+processing windows in parallel and using a GPU automatically when available.
+"""
+from .config import ReliefConfig
+from .backend import gpu_available
+from .core import relief_from_dems, relief_array
+
+__version__ = "0.1.0"
+__all__ = [
+    "ReliefConfig",
+    "relief_from_dems",
+    "relief_array",
+    "gpu_available",
+    "__version__",
+]

openrelief-0.1.0/src/openrelief/backend.py

@@ -0,0 +1,66 @@
+"""Array-backend selection: NumPy (CPU) or CuPy (GPU).
+
+The rest of the package is written against a generic array module ``xp`` so the
+exact same kernels run on CPU and GPU.  GPU is used automatically when CuPy is
+installed *and* a CUDA device is visible, unless the caller forces a backend.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, Tuple
+
+import numpy as np
+
+_FORCE = os.environ.get("OPENRELIEF_BACKEND", "").lower()  # "cpu", "gpu", or ""
+
+
+def gpu_available() -> bool:
+    """True if CuPy is importable and at least one CUDA device is present."""
+    if _FORCE == "cpu":
+        return False
+    try:
+        import cupy as cp  # noqa: F401
+
+        return cp.cuda.runtime.getDeviceCount() > 0
+    except Exception:
+        return False
+
+
+def get_backend(use_gpu: bool | None = None) -> Tuple[Any, bool]:
+    """Return ``(xp, is_gpu)``.
+
+    Parameters
+    ----------
+    use_gpu : bool | None
+        None  -> auto-detect (GPU if available)
+        True  -> require GPU (raises if unavailable)
+        False -> force CPU / NumPy
+    """
+    if _FORCE == "gpu":
+        use_gpu = True
+    elif _FORCE == "cpu":
+        use_gpu = False
+
+    if use_gpu is None:
+        use_gpu = gpu_available()
+
+    if use_gpu:
+        try:
+            import cupy as cp
+
+            if cp.cuda.runtime.getDeviceCount() == 0:
+                raise RuntimeError("No CUDA device visible")
+            return cp, True
+        except Exception as exc:  # pragma: no cover - depends on hardware
+            if _FORCE == "gpu" or use_gpu is True:
+                raise RuntimeError(f"GPU backend requested but unavailable: {exc}")
+            return np, False
+    return np, False
+
+
+def to_cpu(arr: Any) -> "np.ndarray":
+    """Bring an array back to host memory as a NumPy array."""
+    get = getattr(arr, "get", None)
+    if callable(get):
+        return get()
+    return np.asarray(arr)