📝 More docs for nvTIFF/CUDA backend install and usage

docs/index.md

@@ -4,18 +4,39 @@
 
 ## Installation
 
-### Rust
+### Rust 🦀
+
+Stay minimal and pure, or treat yourself to more
+[features](https://docs.rs/crate/cog3pio/latest/features).
 
 ```bash
 cargo add cog3pio
 ```
 
-### Python
+### Python 🐍
+
+The minimal CPU-only wheels using [image-tiff](https://crates.io/crates/tiff) backend.
 
 ```bash
 pip install cog3pio
 ```
 
+add an extra CUDA-based [nvTIFF](https://crates.io/crates/nvtiff-sys) backend
+(pre-built wheels only on Linux `x86_64` and `aarch64`). Requires a
+[patched nvTIFF](#extra-instructions) library.
+
+```
+pip install cog3pio[cuda]
+```
+
+Alternatively, fetch it from
+[conda-forge](https://anaconda.org/channels/conda-forge/packages/cog3pio/overview),
+which will include the CUDA features if you are on a supported platform.
+
+```bash
+conda install --channel conda-forge cog3pio
+```
+
 !!! tip
     The API for this crate/library is still unstable and subject to change, so you may
     want to pin to a specific git commit using either:
@@ -24,4 +45,32 @@ pip install cog3pio
     - `pip install git+https://github.com/weiji14/cog3pio.git@<sha>`
 
     where `<sha>` is a commit hashsum obtained from
-    https://github.com/weiji14/cog3pio/commits/main
+    <https://github.com/weiji14/cog3pio/commits/main>
+
+### Extra instructions
+
+For Linux users who have a CUDA GPU, go and
+[download and install nvTIFF](https://developer.nvidia.com/nvtiff-downloads?target_os=Linux)
+using your system's package manager (recommended).
+
+```bash
+# ... set up nvidia sources before running below
+apt -y install nvtiff-cuda-13  # debian/ubuntu
+dnf install -y nvtiff-cuda-13  # rocky/rhel
+```
+
+or via [conda-forge](https://anaconda.org/channels/conda-forge/packages/libnvtiff-dev)
+(not so recommended unless you know what you're doing)
+
+```bash
+conda install --channel conda-forge libnvtiff-dev
+```
+
+then locate the `nvtiff.h` header file and apply this patch.
+
+```bash
+sed --in-place "s/nvtiffTagDataType type/enum nvtiffTagDataType type/g" /usr/include/nvtiff.h
+```
+
+Getting frustrated?
+Open an [issue](https://github.com/weiji14/cog3pio/issues) (or find one already there)!

docs/quickstart.md

@@ -1,46 +1,72 @@
 # Quickstart
 
-There are two ways to read a GeoTIFF with `cog3pio`'s Python bindings into CPU memory.
+There are a couple of ways to read a GeoTIFF with `cog3pio`'s Python bindings into
+either CPU memory or CUDA GPU memory.
+
 Take your pick:
 
-|  Output   | DLPack protocol | any dtype |
-|:---------:|:---------------:|:---------:|
-| PyCapsule |      ✅         |      ✅    |
-| numpy     |      ✅         |      ❌    |
+|  Output   | CUDA-acceleration | DLPack protocol | any dtype |
+|:---------:|:-----------------:|:---------------:|:---------:|
+| PyCapsule |     ✅ / ❌       |      ✅         |     ✅    |
+| numpy     |       ❌          |      ✅         |     ❌    |
 
 Notes:
 
 - [DLPack - an in-memory tensor structure](https://data-apis.org/array-api/latest/design_topics/data_interchange.html#dlpack-an-in-memory-tensor-structure)
-- Currently supported dtypes include uint (u8/u16/u32/u64), int (i8/i16/i32/i64) and
-  float (f16/f32/f64).
-
+- Currently supported dtypes include:
+    - On CPU: uint (u8/u16/u32/u64), int (i8/i16/i32/i64) and float (f16/f32/f64)
+    - On CUDA: uint (u8/u16/u32/u64), int (i8/i16/i32/i64) and float (f32/f64)
 
 ## PyCapsule (DLPack)
 
-Read a GeoTIFF file from a HTTP url via the [`CogReader`][cog3pio.CogReader] class into
-an object that conforms to the
+Read a GeoTIFF file from a HTTP url via the [`CudaCogReader`][cog3pio.CudaCogReader] or
+[`CogReader`][cog3pio.CogReader] class into an object that conforms to the
 [Python Specification for DLPack](https://dmlc.github.io/dlpack/latest/python_spec.html),
 whereby the `__dlpack__()` method returns a
 [PyCapsule](https://docs.python.org/3/c-api/capsule.html#c.PyCapsule) object containing
 a [`DLManagedTensorVersioned`](https://dmlc.github.io/dlpack/latest/c_api.html#c.DLManagedTensorVersioned)
 object.
 
-```python
-import numpy as np
-from cog3pio import CogReader
-
-cog = CogReader(path="https://github.com/OSGeo/gdal/raw/v3.11.0/autotest/gcore/data/float16.tif")
-assert hasattr(cog, "__dlpack__")
-assert hasattr(cog, "__dlpack_device__")
-
-array: np.ndarray = np.from_dlpack(cog)
-assert array.shape == (1, 20, 20)
-assert array.dtype == "float16"
-
-# or with Pytorch, after https://github.com/pytorch/pytorch/pull/145000
-# tensor: torch.Tensor = torch.from_dlpack(cog)
-# ...
-```
+=== "CUDA"
+    ```python
+    import cupy as cp
+    from cog3pio import CudaCogReader
+
+    cog = CudaCogReader(
+        path="https://github.com/OSGeo/gdal/raw/v3.11.0/autotest/gcore/data/float32.tif",
+        device_id=0
+    )
+    assert hasattr(cog, "__dlpack__")
+    assert hasattr(cog, "__dlpack_device__")
+
+    array: cp.ndarray = cp.from_dlpack(cog)
+    assert array.shape == (400,)  # (1, 20, 20)
+    assert array.dtype == "float32"
+
+    # or with Pytorch>=2.9.0, after https://github.com/pytorch/pytorch/pull/145000
+    # tensor: torch.Tensor = torch.from_dlpack(cog)
+    # ...
+    ```
+
+=== "CPU"
+    ```python
+    import numpy as np
+    from cog3pio import CogReader
+
+    cog = CogReader(
+        path="https://github.com/OSGeo/gdal/raw/v3.11.0/autotest/gcore/data/float16.tif"
+    )
+    assert hasattr(cog, "__dlpack__")
+    assert hasattr(cog, "__dlpack_device__")
+
+    array: np.ndarray = np.from_dlpack(cog)
+    assert array.shape == (1, 20, 20)
+    assert array.dtype == "float16"
+
+    # or with Pytorch>=2.9.0, after https://github.com/pytorch/pytorch/pull/145000
+    # tensor: torch.Tensor = torch.from_dlpack(cog)
+    # ...
+    ```
 
 
 ## NumPy
@@ -63,7 +89,8 @@ assert array.dtype == "float32"
 
 !!! note
 
-    The [`read_geotiff`][cog3pio.read_geotiff] function supports reading single or
-    multi-band GeoTIFF files into a float32 array only. If you wish to read into other
-    dtypes (e.g. uint16), please use the [Xarray](quickstart#xarray) or [DLPack](quickstart#pycapsule-dlpack) methods instead which supports reading into different
-    dtypes.
+    The [`read_geotiff`][cog3pio.read_geotiff] function is a convenience function that
+    supports reading single or multi-band GeoTIFF files into a float32 array only. If
+    you wish to read into other dtypes (e.g. uint16), please use the
+    [DLPack](quickstart#pycapsule-dlpack) method instead which supports reading into
+    different dtypes.

zensical.toml

@@ -72,6 +72,14 @@ logo = "lucide/cloud-cog"
 
 [project.markdown_extensions.pymdownx.superfences]
 
+[project.markdown_extensions.pymdownx.tabbed]
+alternate_style = true
+combine_header_slug = true
+
+[project.markdown_extensions.pymdownx.tabbed.slugify]
+object = "pymdownx.slugs.slugify"
+kwds = { case = "lower" }
+
 [project.markdown_extensions.toc]
 toc_depth = 4
 permalink = "⚓︎"