Package: pyopenrivercam
pyOpenRiverCampyorc, short for "pyOpenRiverCam" is a fully Open Source library for performing image-based river flow analysis. It is the underlying library for
computations on the fully open software stack OpenRiverCam.pyorccan only be successful if the underlying methods
are made available openly for all. Currentlypyorcimplements Large-scale Particle Image Velocimetry (LSPIV) based
flow analysis using the OpenPIV library and reprojections and image pre-processing with OpenCV. We wish to extend this
to Large-scale Particle Tracking Velocimetry (LSPTV) and Space-Time Image Velocimetry (STIV) for conditions that are less favourable for LSPIV using open
libraries or extensions to this code.Image: Example of pyorc velocimetry over Ngwerere river at the Zambezi Road crossing - Lusaka, Zambia.Current capabilities are:Reading of frames and reprojection to surfaceVelocimetry estimation at user-defined resolutionDischarge estimation over provided cross-sectionPlotting of velocimetry results and cross-section flows in camera, geographical and orthoprojected perspectives.We use the well-knownxarraydata models and computation pipelines (with dask) throughout the entire library to
guarantee an easy interoperability with other tools and methods, and allow for lazy computing.We are seeking funding for the following frequently requested functionalities:A command-line interface for processing single or batch videosImplementation of better filtering in pre-processingImproved efficiency of processingEstablishing on-site edge computation through a raspberry-pi camera setupImplementation of additional processing algorithms (STIV and LSPTV)If you wish to fund this or other work on features, please contact us atinfo@rainbowsensing.com.note:For instructions how to get Anaconda (with lots of pre-installed libraries) or Miniconda (light weight) installed, please go tohttps://docs.conda.io/projects/conda/en/latest/manual:Please go tohttps://localdevices.github.io/pyorcfor the latest documentationcompatibility:At this momentpyorcworks with any video compatible with OpenCV as long as it has proper metadata.InstallationTo get started withpyorc, we recommend to setup a python virtual environment.
We recommend using a Miniconda or Anaconda environment as this will ease installation, and will allow you to use all
functionalities without any trouble. Especially geographical plotting withcartopycan be difficult to get installed.
With acondaenvironment and ourconda-forgepackage this is solved. In the subsections below, you can find specific
instructions for different use cases.Installation for direct useIf you simply want to addpyorcto an existing python installation or virtual environment, then follow these
instructions.First activate the environment you wantpyorcto be installed in (if you don't care about virtual environments, then
simply skip this step). You can simply install pyorc with all its dependencies as follows:conda activate <name-of-your-environment>
conda install -c conda-forge pyopenrivercamIf you use mamba as a package mananager, then the steps are the same, except for the installation step, which is:mamba install pyopenrivercamInstallation from latest code baseTo installpyorcfrom scratch in a new virtual environment from the code base, go through these steps. Logical cases
when you wish to install from the code base are when you wish to have the very latest non-released version.First, clone the code withgitand move into the cloned folder.git clone https://github.com/localdevices/pyorc.git
cd pyorcSetup a virtual environment with all dependencies as follows:conda env create -f envs/pyorc-dev.yml
conda activate pyorc-devthen installpyorcfrom the code base as follows:pip install .note:pyorcis now installed in a virtual environment calledpyorc-dev. This means that if you wish to run
python withpyorc. You need to always first activate this environment before running python (or jupyter). This is
done with the following command:conda activate pyorc-devInstallation from latest code base as developerClone the repository with ssh and move into the cloned folder.git clone git@github.com:localdevices/pyorc.git
cd pyorcSetup a virtual developers environment and install the package as follows:conda env create -f envs/pyorc-dev.yml
conda activate pyorc-dev
pip install -e .Using pyorcTo usepyorc, you can use the API for processing. A command-line interface is forthcoming pending funding.
A manual is also still in the making.AcknowledgementThe first development of pyorc has been supported by the World Meteorological Organisation - HydroHub.Licensepyorcis licensed under AGPL Version 3 (seeLICENSEfile).pyorcuses the following libraries and software with said licenses.PackageVersionLicensenumpy1.23.2BSD Licenseopencv24.6.0MIT Licenseopenpiv0.23.8GPLv3matplotlib3.5.3Python Software Foundation Licensegeopandas0.10.2BSD Licensepandas1.4.3BSD LicenseProject organisation.
├── README.md
├── LICENSE
├── setup.py            <- setup script compatible with pip
├── environment.yml     <- YML-file for setting up a conda environment with dependencies
├── docs                <- Sphinx documentation source code
    ├── ...             <- Sphinx source code files
├── examples            <- Jupyter notebooks with examples how to use the API
    ├── ...             <- individual notebooks and folder with example data files
├── pyorc               <- pyorc library
    ├── ...             <- pyorc functions and API files
├── tests               <- pytest suite
    ├── ...             <- pytest functions on API level