This repository contains the source code for the Open Water Foundation (OWF) GeoProcessor software. The GeoProcessor is Python software that leverages QGIS Python packages to provide features to automate processing geospatial data.
See the following online user and developer documentation:
- OWF GeoProcessor - download page (with links to versioned software and documentation)
- Latest GeoProcessor user documentation - latest user documentation
- Latest GeoProcessor developer documentation) - latest developer documentation
The following sections provide a summary of the project repository and getting started:
- GeoProcessor Repository Folder Structure
- Links to GeoProcessor Repositories and Online Resources
- Development Environment
- Git Workflow
- Testing
- Contributing
- License
- Maintainers
- Release Notes
The following folder structure is recommended for GeoProcessor development.
Top-level folders should be created as necessary.
The following folder structure clearly separates user files,
development area (owf-dev/),
product (GeoProcessor/), repositories for the product (git-repos/),
and specific repositories for the product (owf-dev-geoprocessor-*/).
C:\Users\user\ User's home folder for Windows.
/c/Users/user/ User's home folder for Git Bash.
/cygdrive/C/Users/user/ User's home folder for Cygwin.
/home/user/ User's home folder for Linux.
owf-dev/ Work done on Open Water Foundation products.
GeoProcessor/ GeoProcessor product.
git-repos/ Git repositories for the GeoProcessor.
owf-app-geoprocessor-python/ GeoProcessor code repository.
owf-app-geoprocessor-python-doc-dev/ GeoProcessor user documentation repository.
owf-app-geoprocessor-python-doc-user/ GeoProcessor developer documentation repository.
owf-app-geoprocessor-python-test/ Functional test repository (GeoProcessor command files).
Separate repositories have been created for documentation and functional tests to
limit each repository's size and complexity and to facilitate contributions by different people.
The owf-util-git utilities are being developed
to facilitate use of Git and useful scripts are copied into build-util/git-util (see below).
The following summarizes the folder structure for this (owf-app-geoprocessor-python) repository.
OWF uses PyCharm Community Edition IDE for development
and configures the repository to ignore PyCharm files, which can be configured for a new developer.
Other developers can use a different Python development environment tool;
however, OWF may not have resources to troubleshoot.
Folders and files in repositories will be automatically created when the repository is cloned
or when PyCharm is used.
Folders that do not contain source files are marked by right-clicking on folders and using
Mark Director as / Excluded.
Only the top-level src folder should be treated as code.
owf-app-geoprocessor-python/ The GeoProcessor code and documentation repository.
.git/ Standard Git folder for repository files (DO NOT TOUCH!).
.gitattributes/ Standard Git configuration file for repository (for portability).
.gitignore/ Standard Git configuration file to ignore dynamic working files.
.idea/ PyCharm project files (ignored using .gitignore).
build-util/ Scripts to help in the GeoProcessor development environment.
LICENSE.md GeoProcessor license (GPL v3).
README.md This README file.
requirements/ Python package requirements lists for GeoProcessor virtual environment.
requirements-qgis-N.N.txt Pytyon package requiremetns lsit for GeoProcessor virtual environment,
QGIS version N.N.
scripts/ Scripts to run GeoProcessor in the development and deployed environments.
src/ Source Python files (root folder for code).
geoprocessor/ Main module folder for GeoProcessor software.
app/ Main GeoProcessor application module.
commands/ Modules containing GeoProcessor commands.
core/ Core GeoProcessor module, containing the processor.
resources/ Resources that support the software.
images/ Images including icons that should be distributed at runtime.
notices/ License notices to be inserted into code files.
qt-stylesheets/ Qt stylesheets that customize the UI, to be distributed.
ui/ User interface modules, using Qt.
util/ Utility modules.
venv/ Virtual environments used by PyCharm (ignored using .gitignore).
venv-qgis-3.10-python37/ Example virtual environment used for development.
x-venv/ Old virtual environments, will be deleted at some point (ignored using .gitignore).
venv-qgis-python37/ Virtual environment used by PyCharm (ignored using .gitignore),
old convention that is being phased out.
z-local-notes/ Use for local files that won't be committed to the repository.
The following are resources related to the GeoProcessor project, listed by repository, with links to source and deployed versions.
| Repository | Description | Deployed Copy |
|---|---|---|
owf-app-geoprocessor-python (this repository) |
GeoProcessor code. | GeoProcessor Downloads |
owf-app-geoprocessor-python-doc-dev |
GeoProcessor developer documentation. | GeoProcessor Developer Documentation |
owf-app-geoprocessor-python-doc-user |
GeoProcessor user documentation. | GeoProcessor User Documentation |
owf-app-geoprocessor-python-test |
GeoProcessor automated tests. | Download from repository using clone or download zip file from GitHub website. |
The development environment consists of the following. OWF has developed the GeoProcessor on Windows using Cygwin but other development environments will be supported as resources allow.
- QGIS (Python 3 version - Python is included with QGIS) - recent version is supported, as resources allow
- Python 3 (used with MkDocs documentation) - compatible with QGIS Python version
- PyCharm Community Edition - latest version if possible
- Git client such as Git for Windows - latest version for operating system
See the published GeoProcessor Developer Documentation.
OWF uses a "feature branching Git workflow" for this project, as illustrated in the following resources.
The master branch contains the most current commits, with functionality tested before committing,
but should not be considered bulletproof.
Periodic releases are made and are indicated by tags on the master branch.
A small number of committers are responsible for maintaining the integrity of the master branch.
A more complex workflow with development branch may be implemented in the future. However, the focus at OWF is not on supporting a large open source development effort but instead to provide a useful product to software users.
Unit testing of module functions has not been a major focus yet but will be implemented using pytest, consistent with normal Python conventions.
The GeoProcessor contains an internal functional testing framework described in the following resources:
- Developer documentation for testing tasks
- owf-app-geoprocessor-python-test functional tests repository
Contributions to this project can be submitted using the following options.
- GeoProcessor software developers with commit privileges can write to this repository as per normal development Git workflow protocols.
- Post an issue on GitHub with suggested change (preferred for small changes).
- Fork the repository, make changes, and do a pull request (preferred for large changes). Contents of the current master branch should be merged with the fork to minimize code review before committing the pull request. OWF developers will review suggestions and implement by whatever means makes sense.
The GeoProcessor is licensed under the GPL v3+ license. See the GPL v3 license.
OWF staff are the lead developers/maintainers for the GeoProcessor.
See the User Documentation Release Notes.