Merge pull request #10 from mpelchat04/7-cleanup

Update  doc, license and add Dockerfile

.dockerignore

@@ -0,0 +1,5 @@
+.pytest_cache
+.vscode
+.git*
+tests*
+examples*

Dockerfile

@@ -0,0 +1,54 @@
+# syntax=docker/dockerfile:1
+FROM nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04
+
+ARG CONDA_PYTHON_VERSION=3
+ARG CONDA_DIR=/opt/conda
+ARG USERNAME=gdl_user
+ARG USERID=1000
+
+
+# Install Mamba directly
+ENV PATH=$CONDA_DIR/bin:$PATH
+
+# RNCAN certificate; uncomment (with right .cer name) if you are building behind a FW
+# COPY NRCan-RootCA.cer /usr/local/share/ca-certificates/cert.crt
+# RUN chmod 644 /usr/local/share/ca-certificates/cert.crt \
+#     && update-ca-certificates 
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends git wget unzip bzip2 build-essential sudo \
+    && apt-key del 7fa2af80 \
+    && wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2004/x86_64/cuda-keyring_1.0-1_all.deb \
+    && sudo dpkg -i cuda-keyring_1.0-1_all.deb \
+    && wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2004/x86_64/cuda-ubuntu2004-keyring.gpg \
+    && sudo mv cuda-ubuntu2004-keyring.gpg /usr/share/keyrings/cuda-archive-keyring.gpg \
+    && rm -f cuda-keyring_1.0-1_all.deb && rm -f /etc/apt/sources.list.d/cuda.list \
+    && wget https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-Linux-x86_64.sh -O /tmp/mamba.sh \
+    && /bin/bash /tmp/mamba.sh -b -p $CONDA_DIR \
+    && rm -rf /tmp/* \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+ENV LD_LIBRARY_PATH=$CONDA_DIR/lib:$LD_LIBRARY_PATH
+
+# Create the user
+RUN useradd --create-home -s /bin/bash --no-user-group -u $USERID $USERNAME \
+    && chown $USERNAME $CONDA_DIR -R \
+    && adduser $USERNAME sudo \
+    && echo "$USERNAME ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
+
+COPY requirements.txt .
+USER $USERNAME
+WORKDIR /home/$USERNAME/
+COPY requirements.txt . /home/$USERNAME/
+RUN cd /home/$USERNAME \
+    && conda config --set ssl_verify no \
+    && mamba create --name geo-inference \ 
+    && mamba install pip \
+    && pip install --upgrade pip \
+    && pip install --no-cache-dir git+https://github.com/NRCan/geo-inference.git \
+    && pip uninstall -y pip \
+    && mamba clean --all
+
+
+ENV PATH=$CONDA_DIR/envs/geo-inference/bin:$PATH
+RUN echo "source activate geo-inference" > ~/.bashrc

LICENSE

@@ -1,21 +1,53 @@
-MIT License
+Open Government License - Canada
 
 Copyright (c) His Majesty the King in Right of Canada, as represented by the Minister of Natural Resources, 2024
 
-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.
+You are encouraged to use the Information that is available under this licence with only a few conditions.
+
+Using Information under this licence
+- Use of any Information indicates your acceptance of the terms below.
+- The Information Provider grants you a worldwide, royalty-free, perpetual, non-exclusive licence to use the Information, including for commercial purposes, subject to the terms below.  
+
+You are free to:
+- Copy, modify, publish, translate, adapt, distribute or otherwise use the Information in any medium, mode or format for any lawful purpose.
+
+You must, where you do any of the above:
+- Acknowledge the source of the Information by including any attribution statement specified by the Information Provider(s) and, where possible, provide a link to this licence.
+- If the Information Provider does not provide a specific attribution statement, or if you are using Information from several information providers and multiple attributions are not practical for your product or application, you must use the following attribution statement:
+
+Contains information licensed under the Open Government Licence – Canada.
+The terms of this licence are important, and if you fail to comply with any of them, the rights granted to you under this licence, or any similar licence granted by the Information Provider, will end automatically.
+
+Exemptions
+This licence does not grant you any right to use:
+- Personal Information;
+- third party rights the Information Provider is not authorized to license;
+- the names, crests, logos, or other official symbols of the Information Provider; and
+- Information subject to other intellectual property rights, including patents, trade-marks and official marks.
+
+Non-endorsement
+This licence does not grant you any right to use the Information in a way that suggests any official status or that the Information Provider endorses you or your use of the Information.
+
+No Warranty
+The Information is licensed “as is”, and the Information Provider excludes all representations, warranties, obligations, and liabilities, whether express or implied, to the maximum extent permitted by law.
+
+The Information Provider is not liable for any errors or omissions in the Information, and will not under any circumstances be liable for any direct, indirect, special, incidental, consequential, or other loss, injury or damage caused by its use or otherwise arising in connection with this licence or the Information, even if specifically advised of the possibility of such loss, injury or damage.
+
+Governing Law
+This licence is governed by the laws of the province of Ontario and the applicable laws of Canada.
+
+Legal proceedings related to this licence may only be brought in the courts of Ontario or the Federal Court of Canada.
+
+Definitions
+In this licence, the terms below have the following meanings:
+
+"Information"
+means information resources protected by copyright or other information that is offered for use under the terms of this licence.
+"Information Provider"
+means His Majesty the King in right of Canada.
+“Personal Information”
+means “personal information” as defined in section 3 of the Privacy Act, R.S.C. 1985, c. P-21.
+"You"
+means the natural or legal person, or body of persons corporate or incorporate, acquiring rights under this licence.
+Versioning
+This is version 2.0 of the Open Government Licence – Canada. The Information Provider may make changes to the terms of this licence from time to time and issue a new version of the licence. Your use of the Information will be governed by the terms of the licence in force as of the date you accessed the information.

README.md

@@ -12,11 +12,45 @@ geo-inference is a Python package designed for feature extraction from geospatia
 
 ## Installation
 
-Geo-inference requires Python 3.11. To install the package, use:
+Geo-inference requires Python 3.11.  
+
+### Linux Installation  
+To install the package, use:
 
 ```
 pip install geo-inference
+```  
+
+### Windows Installation
+The recipe to use cuda-enabled Geo-inference on Windows OS is slightly different than on Linux-based OS.  
+
+- Validate the nvidia drivers version installed on your computer by running `nvcc --version`: 
+``` shell
+PS C:\> nvcc --version
+nvcc: NVIDIA (R) Cuda compiler driver
+Copyright (c) 2005-2024 NVIDIA Corporation
+Built on Tue_Feb_27_16:28:36_Pacific_Standard_Time_2024
+Cuda compilation tools, release 12.4, V12.4.99
+Build cuda_12.4.r12.4/compiler.33961263_0
+```
+> Note: If the command returns an error, you need to download and install the Nvidia-drivers first at https://developer.nvidia.com/cuda-downloads.  
+
+- Install pytorch-cuda following one method suggested here: https://pytorch.org/get-started/locally/.
+> Note: Make sure to select the cuda version matching the driver installed on your computer.  
+- Test the installation:  
+```shell
+PS C:\> python
+>>> import torch
+>>> torch.cuda.is_available()
+>>> True
+```  
+- install geo-inference using `pip`:
 ```
+pip install geo-inference
+```
+
+### Docker installation
+Alternatively, you can build the [Dockerfile](./Dockerfile) to use Geo-Inference.  
 
 ## Usage
 
@@ -32,11 +66,11 @@ expects an input image with the same features. An example notebook for how the p
 
 **Command line**
 ```bash
-python geo_inference -a <args>
+geo_inference -a <args>
 ```
 - `-a`, `--args`: Path to arguments stored in yaml, consult ./config/sample_config.yaml
 ```bash
-python geo_inference -i <image> -br <bands_requested> -m <model> -wd <work_dir> -ps <patch_size> -v <vec> -d <device> -id <gpu_id> -cls <classes> -mg <mgpu>
+geo_inference -i <image> -br <bands_requested> -m <model> -wd <work_dir> -ps <patch_size> -v <vec> -d <device> -id <gpu_id> -cls <classes> -mg <mgpu>
 ```
 - `-i`, `--image`: Path to Geotiff
 - `-bb`, `--bbox`: AOI bbox in this format "minx, miny, maxx, maxy" (Optional)
@@ -56,7 +90,7 @@ python geo_inference -i <image> -br <bands_requested> -m <model> -wd <work_dir>
 You can also use the `-h` option to get a list of supported arguments:
 
 ```bash
-python geo_inference -h
+geo_inference -h
 ```
 
 **Import script**
@@ -80,7 +114,7 @@ geo_inference = GeoInference(
 # Perform feature extraction on a TIFF image
 image_path = "/path/to/image.tif"
 patch_size = 512
-geo_inference(tiff_image = image_path,  bands_requested = bands_requested, patch_size = patch_size,)
+geo_inference(tiff_image = image_path,  bands_requested = bands_requested, patch_size = patch_size)
 ```
 
 ## Parameters
@@ -89,7 +123,7 @@ The `GeoInference` class takes the following parameters:
 
 - `model`: The path or URL to the model file (.pt for PyTorch models) to use for feature extraction.
 - `work_dir`: The path to the working directory. Default is `"~/.cache"`.
-- `patch_size`: The patch size to use for feature extraction. Default is `4`.
+- `patch_size`: The patch size to use for feature extraction. Default is `1024`.
 - `mask_to_vec`: If set to `"True"`, vector data will be created from mask. Default is `"False"`
 - `mask_to_yolo`: If set to `"True"`, vector data will be converted to YOLO format. Default is `"False"`
 - `mask_to_coco`: If set to `"True"`, vector data will be converted to COCO format. Default is `"False"`
@@ -110,7 +144,7 @@ Each file contains the extracted features from the input geospatial imagery.
 
 ## License
 
-Geo Inference is released under the MIT License. See [`LICENSE`](https://github.com/NRCan/geo-inference/blob/main/LICENSE) for more information.
+Geo Inference is released under the Open Government License - Canada. See [`LICENSE`](https://github.com/NRCan/geo-inference/blob/main/LICENSE) for more information.
 
 ## Contact