diff --git a/docs/index.md b/docs/index.md index ee200e3..07ef46e 100644 --- a/docs/index.md +++ b/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@` where `` is a commit hashsum obtained from - 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)! diff --git a/docs/quickstart.md b/docs/quickstart.md index d382fa9..9b07ed1 100644 --- a/docs/quickstart.md +++ b/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. diff --git a/zensical.toml b/zensical.toml index de5a32c..acacd8e 100644 --- a/zensical.toml +++ b/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 = "⚓︎"