Initial commit with all current files, first public release

Author: matscorse

.gitignore

@@ -0,0 +1,172 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+activate
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# PyPI configuration file
+.pypirc

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 British Antarctic Survey
+
+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.

README.md

@@ -0,0 +1,60 @@
+![wildlife from space ai logo](docs/img/wildlife-from-space-ai-logo-small.png)
+
+## **W**ildlife **F**rom **S**pace **AI** - **wfsai**  
+A pip installable python package to help with the AI workflow stages of detecting Wildlife from Space.  
+
+The features of the `wfsai` package include:  
+
+- Handling configuration based AI pipeline workflow/execution.
+- Setting up reproducible file/directory compute environments.
+- Retrieving local and remote datasets/configs.
+- Ortho-rectification of VHR satellite imagery (using GDAL).
+- Pan-sharpening of VHR satellite imagery (using GDAL, "weighted" Brovey algorithm).
+- Tiling of VHR satellite imagery.
+- Masking of VHR satellite imagery to shapefile with optional shapefile dilation.
+
+---
+
+Documentation for this package is temporarily hosted [here]()
+
+---
+
+This python package aims to integrate with the common AI workflow shown in the diagram below:  
+
+![Typical AI Image analysis workflow](docs/img/A.I.-Model-768x432.png)  
+(diagram courtesy of [this](https://blogs.oregonstate.edu/gemmlab/2024/12/23/demystifying-ai-a-brief-overview-of-image-pre-processing-and-a-machine-learning-workflow/) blogpost. original diagram [here](https://osu-wams-blogs-uploads.s3.amazonaws.com/blogs.dir/2115/files/2024/12/A.I.-Model-768x432.png))
+
+---
+
+## Installation
+Requires Python >=3.10
+
+> ### pip
+> `pip install git+https://github.com/antarctica/wfsai.git@main`
+
+> ### conda/mamba
+> `conda/mamba create -n <environment-name> -c conda-forge git pip`  
+> `conda/mamba activate <environment-name>`  
+> `pip install git+https://github.com/antarctica/wfsai.git@main`  
+
+### GDAL
+Some of the modules within this `wfsai` package make use of the **gdal** python implementation, including it's underlying dependencies. We found that the best way to handle **gdal** and it's dependencies is to use a mamba environment with the mamba dependency solver. If you are using a conda/mamba environment in your project then simply include **gdal** as a dependency in your environment.yaml or use the command:  
+> `conda install -n <environment-name> -c conda-forge gdal`  
+
+## Environment Variables
+If retrieving a configuration from a remote repository then specify the `REMOTE_CONFIG_REPO` environment variable.
+```bash
+REMOTE_CONFIG_REPO=<url>
+```  
+With either remote or local config files, you should specify the `CONFIG_FILE` environment variable.
+```bash
+CONFIG_FILE=<config filename>
+```
+
+From the diagram above, often the first step of AI workflow is to obtain a source dataset to answer a scientific question. Datasets may be remote or local to the working environment and it is helpful to set out a framework for how the data will be handled during the workflow.  
+For example:
+- `configuration files -> retrieving/linking of input files -> intermediate files -> outputs.`
+
+## Usage (cli)
+### wfsai **--help**
+*show the built-in help for the wfsai package command line interface (cli)*  

docs/development.md

@@ -0,0 +1,29 @@
+# Development
+
+Depends on:
+
+* Python >=3.10
+
+---
+
+1. Create and activate a python virtual environment of your choice.
+1. Inside the virtual environment or machine:
+    - Install an editable version of simple-action-pipeline.   
+      `git clone https://github.com/antarctica/wfsai ./wfsai`  
+      `cd ./wfsai`  
+      `pip install -e .`  
+    - Use `pip install -e ".[documentation]"` to edit/contribute to the documentation.
+
+## Release/Versioning
+
+Version numbers should be used in tagging commits on the `main` branch and should be of the form `v0.1.7` using the semantic versioning convention.
+
+## Bugs & issues  
+
+If you find a bug, or would like to contribute please [raise an issue](https://github.com/antarctica/wfsai/issues/new) in the first instance.
+
+## Building & deploying the documentation
+
+Run `mkdocs build` to build the docs.
+
+Then run `mkdocs gh-deploy` to deploy to the `gh-pages` branch of the repository. You must have write access to the repo.

docs/img/A.I.-Model-768x432.png

@@ -0,0 +1,56 @@
+# Implementation
+
+## Python package
+`wfsai` is implemented as a pip installable python package. Using python version 3.8 or higher.  
+
+The use of the package is documented in the [Tutorial](tutorial.md) and [API REFERENCE](../autoapi/wfsai/) sections.  
+
+---  
+
+Most python modules are implemented as simple methods with arguments. Although the 'imagery' and 'shape' modules implement object classes as indicated below:  
+
+```python
+from wfsai import imagery
+from wfsai import shapes
+
+# Set up maxar image processor
+m = imagery.maxar()
+
+help(m)
+
+# Set up the image tile processor
+t = imagery.tiling()
+
+help(t)
+
+# Set up the shapefile processor
+s = shapes.shapefile()
+
+help(s)
+
+```  
+
+---  
+
+## Command-Line Interface
+A basic shell command line interface has been implemented.
+
+**`wfsai`** `--help`
+```bash
+usage: wfsai [-h] [-v] [-d DISPLAY] [--remote_config]
+
+Command Line interface for Wildlife from Space AI tools
+
+options:
+  -h, --help                         show this help message and exit
+  -v, --version                      show this package version and exit
+  -d CONF_FILE, --display CONF_FILE  display configuration
+  --remote_config                    retrieve the remote configuration file
+
+```  
+
+From the command-line you can:  
+
+- check the version of the wfsai package  
+- display the formatted contents of a yaml config file  
+- retrieve a remote config file (provided the 'REMOTE_CONFIG_REPO' and 'CONFIG_FILE' environment variables are set).

docs/img/bas-logo-inverse-transparent-64.png

@@ -0,0 +1,10 @@
+![wildlife from space ai logo](img/wildlife-from-space-ai-logo-small.png)
+# wildlife-from-space-ai
+
+A pip installable python package to help with the AI workflow stages of detecting Wildlife from Space.  
+
+
+
+## Using this documentation
+
+Most of these docs are primarily aimed at developers and users of the wfsai python package. These docs can also be useful if you wish to extend or contribute towards this repository.