Allow custom WIC batch sizes, added new documentation, and GitHub Docker build and publish

.dockerignore

@@ -1,14 +1,3 @@
-examples/0d4e4df2-7b69-91b1-1985-c8421f2f3253.jpg
-examples/18cef191-74ed-2b5e-55a5-f58bd3d483ff.jpg
-examples/1be4d40a-6fd0-42ce-da6c-294e45781f41.jpg
-examples/1d3c85e9-ee24-f290-e7e1-6e338f2eaebb.jpg
-examples/3e043302-af1c-75a7-4057-3a2f25c123bf.jpg
-examples/43ecc08d-502a-7a51-9d68-3e40a76439a2.jpg
-examples/479058af-e774-e6aa-a2b0-9a42dd6ff8b1.jpg
-examples/7c910b87-ae3a-f580-d431-03cd89793803.jpg
-examples/8fa04489-cd94-7d8f-7e2e-5f0fe2f7ae76.jpg
-examples/bb7b4345-b98a-c727-4c94-6090f0aa4355.jpg
-
 docs/
 tests/
 

.github/workflows/docker-publish.yaml

@@ -0,0 +1,81 @@
+name: Docker
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+    tags:
+      - v*
+  schedule:
+    - cron: '0 16 * * *' # Every day at 16:00 UTC (~09:00 PT)
+
+jobs:
+  # Push container image to GitHub Packages and Docker Hub.
+  # See also https://docs.docker.com/docker-hub/builds/
+  deploy:
+    name: Docker image build
+    runs-on: ubuntu-latest
+
+    env:
+      DOCKER_BUILDKIT: 1
+      DOCKER_CLI_EXPERIMENTAL: enabled
+
+    steps:
+      - uses: actions/checkout@v2
+        if: github.event_name == 'schedule'
+        with:
+          ref: main
+
+      - uses: actions/checkout@v2
+        if: github.event_name != 'schedule'
+
+      - uses: docker/setup-qemu-action@v1
+        name: Set up QEMU
+        id: qemu
+        with:
+          image: tonistiigi/binfmt:latest
+          platforms: all
+
+      - uses: docker/setup-buildx-action@v1
+        name: Set up Docker Buildx
+        id: buildx
+
+      - name: Available platforms
+        run: echo ${{ steps.buildx.outputs.platforms }}
+
+      # Log into container registries
+      - name: Login to DockerHub
+        uses: docker/login-action@v1
+        with:
+          username: wildmebot
+          password: ${{ secrets.WBIA_WILDMEBOT_DOCKER_HUB_TOKEN }}
+
+      # Push tagged image (version tag + latest) to registries
+      - name: Tagged Docker Hub
+        if: ${{ github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/v') }}
+        run: |
+          echo "IMAGE_TAG=latest >> $GITHUB_ENV
+
+      # Push bleeding-edge image (main tag) to registries
+      - name: Bleeding Edge Docker Hub
+        if: github.ref == 'refs/heads/main'
+        run: |
+          echo "IMAGE_TAG=main >> $GITHUB_ENV
+
+      # Push nightly image (nightly tag) to registries
+      - name: Nightly Docker Hub
+        if: github.event_name == 'schedule'
+        run: |
+          echo "IMAGE_TAG=nightly >> $GITHUB_ENV
+
+      # Build images
+      - name: Build Codex
+        run: |
+          docker buildx build \
+              -t wildme/scoutbot:${{ env.IMAGE_TAG }} \
+              --platform linux/amd64 \
+              --push \
+              .

.github/workflows/testing.yml

@@ -13,9 +13,12 @@ jobs:
       matrix:
         # Use the same Python version used the Dockerfile
         python-version: [3.9]
+
     env:
       OS: ubuntu-latest
       PYTHON: ${{ matrix.python-version }}
+      WIC_BATCH_SIZE: 16
+
     steps:
       # Checkout and env setup
       - name: Checkout code

README.rst

@@ -12,32 +12,17 @@ Wild Me ScoutBot
 How to Install
 --------------
 
-You need to first install Anaconda on your machine.  Below are the instructions on how to install Anaconda on an Apple macOS machine, but it is possible to install on a Windows and Linux machine as well.  Consult the `official Anaconda page <https://www.anaconda.com>`_ to download and install on other systems.
-
 .. code-block:: console
 
-   # Install Homebrew
-   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
-
-   # Install Anaconda and expose conda to the terminal
-   brew install anaconda
-   export PATH="/opt/homebrew/anaconda3/bin:$PATH"
-   conda init zsh
-   conda update conda
+    (.venv) $ pip install scoutbot
 
-Once Anaconda is installed, you will need an environment and the following packages installed
+or, from source:
 
 .. code-block:: console
 
-   # Create Environment
-   conda create --name scoutbot
-   conda activate scoutbot
-
-   # Install Python dependencies
-   conda install pip
-
-   pip install -r requirements.txt
-   # conda install pytorch torchvision -c pytorch-nightly
+   git clone https://github.com/WildMeOrg/scoutbot
+   cd scoutbot
+   (.venv) $ pip install -e .
 
 How to Run
 ----------
@@ -57,7 +42,7 @@ or, you can run the image-base Gradio demo with:
 Docker
 ------
 
-The application can also be built into a Docker image and hosted on Docker Hub.
+The application can also be built into a Docker image and is hosted on Docker Hub as ``wildme/scoutbot:latest``.
 
 .. code-block:: console
 
@@ -73,7 +58,7 @@ The application can also be built into a Docker image and hosted on Docker Hub.
         --push \
         .
 
-To run:
+To run with Docker:
 
 .. code-block:: console
 
@@ -84,45 +69,57 @@ To run:
        --name scoutbot \
        wildme/scoutbot:latest
 
-Unit Tests
-----------
+Tests and Coverage
+------------------
+
+You can run the automated tests in the ``tests/`` folder by running:
+
+.. code-block:: console
 
-You can run the automated tests in the `tests/` folder by running `pytest`.  This will give an output of which tests have failed.  You may also get a coverage percentage by running `coverage html` and loading the `coverage/html/index.html` file in your browser.
-pytest
+    (.venv) $ pip install -r requirements.optional.txt
+    (.venv) $ pytest
+
+You may also get a coverage percentage by running:
+
+.. code-block:: console
+
+    (.venv) $ coverage html
+
+and open the `coverage/html/index.html` file in your browser.
 
 Building Documentation
 ----------------------
 
-There is Sphinx documentation in the `docs/` folder, which can be built with the code below:
+There is Sphinx documentation in the ``docs/`` folder, which can be built by running:
 
 .. code-block:: console
 
-    cd docs/
-    sphinx-build -M html . build/
+    (.venv) $ cd docs/
+    (.venv) $ pip install -r requirements.optional.txt
+    (.venv) $ sphinx-build -M html . build/
 
 Logging
 -------
 
-The script uses Python's built-in logging functionality called `logging`.  All print functions are replaced with `log.info` within this script, which sends the output to two places: 1) the terminal window, 2) the file `scoutbot.log`.  Get into the habit of writing text logs and keeping date-specific versions for comparison and debugging.
+The script uses Python's built-in logging functionality called ``logging``.  All print functions are replaced with :func:``log.info``, which sends the output to two places:
+
+    - 1. the terminal window, and
+    - 2. the file `scoutbot.log`
 
 Code Formatting
 ---------------
 
 It's recommended that you use ``pre-commit`` to ensure linting procedures are run
-on any code you write. (See also `pre-commit.com <https://pre-commit.com/>`_)
+on any code you write.  See `pre-commit.com <https://pre-commit.com/>`_ for more information.
 
 Reference `pre-commit's installation instructions <https://pre-commit.com/#install>`_ for software installation on your OS/platform. After you have the software installed, run ``pre-commit install`` on the command line. Now every time you commit to this project's code base the linter procedures will automatically run over the changed files.  To run pre-commit on files preemtively from the command line use:
 
 .. code-block:: console
 
-    git add .
-    pre-commit run
-
-    # or
-
-    pre-commit run --all-files
+    (.venv) $ pip install -r requirements.optional.txt
+    (.venv) $ pre-commit run --all-files
 
-The code base has been formatted by Brunette, which is a fork and more configurable version of Black (https://black.readthedocs.io/en/stable/).  Furthermore, try to conform to PEP8.  You should set up your preferred editor to use flake8 as its Python linter, but pre-commit will ensure compliance before a git commit is completed.  This will use the flake8 configuration within ``setup.cfg``, which ignores several errors and stylistic considerations.  See the ``setup.cfg`` file for a full and accurate listing of stylistic codes to ignore.
+The code base has been formatted by `Brunette <https://pypi.org/project/brunette/>`_, which is a fork and more configurable version of `Black <https://black.readthedocs.io/en/stable/>`_.  Furthermore, try to conform to ``PEP8``.  You should set up your preferred editor to use ``flake8`` as its Python linter, but pre-commit will ensure compliance before a git commit is completed.  This will use the ``flake8`` configuration within ``setup.cfg``, which ignores several errors and stylistic considerations.  See the ``setup.cfg`` file for a full and accurate listing of stylistic codes to ignore.
 
 
 .. |Tests| image:: https://github.com/WildMeOrg/scoutbot/actions/workflows/testing.yml/badge.svg?branch=main

docs/scoutbot.rst

@@ -5,6 +5,66 @@ ScoutBot API
    :maxdepth: 3
    :caption: Contents:
 
+ScoutBot is the machine learning interface for the Wild Me Scout project.  This page specifies
+the Python API to interact with all of the algorithms and machine learning models that have been
+pretrained for inference in a production environment.
+
+Overview
+--------
+
+In general, the structure of this API is to expose four main processing components for the Scout project.
+These components are, in order: ``TILE``, ``WIC``, ``LOC``, and ``AGG``.
+
+   1. ``TILE``: A module to convert images to tiles
+   2. ``WIC``: A module to classify tiles as relevant for further processing (i.e., does it likely have an elephant?)
+   3. ``LOC``: A module to detect elephants in tiles
+   4. ``AGG``: A module to aggregate the tile-level detections back onto the original image
+
+The ``TILE`` step and ``AGG`` steps are heuristic-based algorithms and do not need to use any
+machine learning (ML) models or GPU offload.  In contrast, the ``WIC`` and ``LOC`` steps both require
+their own ML models and can be computed on CPU or GPU (if available).
+
+The non-ML components (``TILE`` and ``AGG``) both expose :func:`compute` functions, which is the single
+point of interaction as the developer:
+
+   - :meth:`scoutbot.tile.compute`
+   - :meth:`scoutbot.agg.compute`
+
+The ML components (``WIC`` and ``LOC``), in contrast, is a bit more complex and exposes three functions:
+
+   - :func:`pre` (preprocessing)
+   - :func:`predict` (inference)
+   - :func:`post` (postprocessing)
+
+For the WIC, these functions are:
+
+   - :meth:`scoutbot.wic.pre`
+   - :meth:`scoutbot.wic.predict`
+   - :meth:`scoutbot.wic.post`
+
+and for the LOC, these functions are:
+
+   - :meth:`scoutbot.loc.pre`
+   - :meth:`scoutbot.loc.predict`
+   - :meth:`scoutbot.loc.post`
+
+CDN Model Download (ONNX)
+-------------------------
+
+All of the machine learning models are hosted on GitHub as LFS files.  The two modules (``WIC`` and ``LOC``)
+however need those files downloaded to the local machine prior to running inference.  These models are
+hosted on a separate CDN for convenient access and can be fetched by running the following functions:
+
+   - :meth:`scoutbot.wic.fetch`
+   - :meth:`scoutbot.loc.fetch`
+
+These functions will download the following files and will store them in your Operating System's default
+cache folder:
+
+   - ``WIC``: ``https://wildbookiarepository.azureedge.net/models/scout.wic.5fbfff26.3.0.onnx`` (81MB)
+      SHA256 checksum: ``cbc7f381fa58504e03b6510245b6b2742d63049429337465d95663a6468df4c1``
+   - ``LOC``: ``https://wildbookiarepository.azureedge.net/models/scout.loc.5fbfff26.0.onnx`` (209MB)
+      SHA256 checksum: ``85a9378311d42b5143f74570136f32f50bf97c548135921b178b46ba7612b216``
 
 Tiles (TILE)
 ------------
@@ -39,6 +99,14 @@ Aggregation (AGG)
    :undoc-members:
    :show-inheritance:
 
+Pipeline (PIPE)
+---------------
+
+.. automodule:: scoutbot.__init__
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Utilities
 ---------
 

notes.txt

@@ -0,0 +1,31 @@
+detection_config = {
+    'algo': 'tile_aggregation',
+    'config_filepath': 'variant3-32',
+    'weight_filepath': 'densenet+lightnet;scout-5fbfff26-boost3,0.400,scout_5fbfff26_v0,0.4',
+    'nms_thresh': 0.8,
+    'sensitivity': 0.5077,
+}
+
+(
+    wic_model_tag,
+    wic_thresh,
+    weight_filepath,
+    nms_thresh,
+) = 'scout-5fbfff26-boost3,0.400,scout_5fbfff26_v0,0.4'
+
+
+wic_confidence_list = ibs.scout_wic_test(
+    gid_list, classifier_algo='densenet', model_tag=wic_model_tag
+)
+config = {
+    'grid': False,
+    'algo': 'lightnet',
+    'config_filepath': weight_filepath,
+    'weight_filepath': weight_filepath,
+    'nms': True,
+    'nms_thresh': nms_thresh,
+    'sensitivity': 0.0,
+}
+prediction_list = depc.get_property(
+    'localizations', gid_list_, None, config=config
+)

scoutbot/__init__.py

@@ -1,38 +1,47 @@
 # -*- coding: utf-8 -*-
 '''
-ScoutBot is the machine learning interface for the Wild Me Scout project.
-
-Notes:
-    detection_config = {
-        'algo': 'tile_aggregation',
-        'config_filepath': 'variant3-32',
-        'weight_filepath': 'densenet+lightnet;scout-5fbfff26-boost3,0.400,scout_5fbfff26_v0,0.4',
-        'nms_thresh': 0.8,
-        'sensitivity': 0.5077,
-    }
-
-    (
-        wic_model_tag,
-        wic_thresh,
-        weight_filepath,
-        nms_thresh,
-    ) = 'scout-5fbfff26-boost3,0.400,scout_5fbfff26_v0,0.4'
-
-
-    wic_confidence_list = ibs.scout_wic_test(
-        gid_list, classifier_algo='densenet', model_tag=wic_model_tag
+The above components must be run in the correct order, but ScoutbBot also offers a single pipeline.
+
+All of the ML models can be pre-downloaded and fetched in a single call to :func:`scoutbot.fetch` and
+the unified pipeline -- which uses the 4 components correctly -- can be run by the function
+:func:`scoutbot.pipeline`.  Below is example code for how these components interact.
+
+Furthermore, there are two application demo files (``app.py`` and ``app2.py``) that shows
+how the entire pipeline can be run on tiles or images, respectively.
+
+.. code-block:: python
+
+    # Get image filepath
+    filepath = '/path/to/image.ext'
+
+    # Run tiling
+    img_shape, tile_grids, tile_filepaths = tile.compute(filepath)
+
+    # Run WIC
+    wic_outputs = wic.post(wic.predict(wic.pre(tile_filepaths)))
+
+    # Threshold for WIC
+    flags = [wic_output.get('positive') >= wic_thresh for wic_output in wic_outputs]
+    loc_tile_grids = ut.compress(tile_grids, flags)
+    loc_tile_filepaths = ut.compress(tile_filepaths, flags)
+
+    # Run localizer
+    loc_data, loc_sizes = loc.pre(loc_tile_filepaths)
+    loc_preds = loc.predict(loc_data)
+    loc_outputs = loc.post(
+        loc_preds,
+        loc_sizes,
+        loc_thresh=loc_thresh,
+        nms_thresh=loc_nms_thresh
     )
-    config = {
-        'grid': False,
-        'algo': 'lightnet',
-        'config_filepath': weight_filepath,
-        'weight_filepath': weight_filepath,
-        'nms': True,
-        'nms_thresh': nms_thresh,
-        'sensitivity': 0.0,
-    }
-    prediction_list = depc.get_property(
-        'localizations', gid_list_, None, config=config
+
+    # Run Aggregation and get final detections
+    detects = agg.compute(
+        img_shape,
+        loc_tile_grids,
+        loc_outputs,
+        agg_thresh=agg_thresh,
+        nms_thresh=agg_nms_thresh,
     )
 '''
 from scoutbot import agg, loc, tile, wic
@@ -43,6 +52,22 @@ __version__ = VERSION
 
 
 def fetch(pull=False):
+    """
+    Fetch the WIC and Localizer ONNX model files from a CDN if they do not exist locally.
+
+    This function will throw an AssertionError if either download fails or the
+    files otherwise do not exist locally on disk.
+
+    Args:
+        pull (bool, optional): If :obj:`True`, use the downloaded versions stored in
+            the local system's cache.  Defaults to :obj:`False`.
+
+    Returns:
+        None
+
+    Raises:
+        AssertionError: If any model cannot be fetched.
+    """
     wic.fetch(pull=pull)
     loc.fetch(pull=pull)
 
@@ -55,6 +80,29 @@ def pipeline(
     agg_thresh=agg.AGG_THRESH,
     agg_nms_thresh=agg.NMS_THRESH,
 ):
+    """
+    Run the ML pipeline on a given image filepath and return the detections
+
+    The final output is a list of dictionaries, each representing a single detection.
+    Each dictionary has a structure with the following keys:
+
+        ::
+
+            {
+                'l': class_label (str)
+                'c': confidence (float)
+                'x': x_top_left (float)
+                'y': y_top_left (float)
+                'w': width (float)
+                'h': height (float)
+            }
+
+    Args:
+        filepath (str): image filepath (relative or absolute)
+
+    Returns:
+        list ( dict ): list of predictions
+    """
     import utool as ut
 
     # Run tiling

scoutbot/loc/__init__.py

@@ -60,7 +60,7 @@ def fetch(pull=False):
 
     Args:
         pull (bool, optional): If :obj:`True`, use a downloaded version stored in
-            sthe local system's cache.  Defaults to :obj:`False`.
+            the local system's cache.  Defaults to :obj:`False`.
 
     Returns:
         str: local ONNX model file path.
@@ -94,8 +94,9 @@ def pre(inputs):
         inputs (list(str)): list of tile image filepaths (relative or absolute)
 
     Returns:
-        list ( list ( list ( list ( float ) ) ) ), list ( tuple ( int ) ): list of
-        transformed image data, and a list of each tile's original size
+        tuple ( list ( list ( list ( list ( float ) ) ) ), list ( tuple ( int ) ) ):
+            - list of transformed image data.
+            - list of each tile's original size.
     """
     transform = torchvision.transforms.ToTensor()
 

scoutbot/tile/__init__.py

@@ -17,7 +17,26 @@ TILE_BORDERS = True
 
 def compute(img_filepath, grid1=True, grid2=True, ext=None, **kwargs):
     """
-    Compute the tiles for a given input image
+    Compute the tiles for a given input image and saves them to disk.
+
+    If a given tile has already been rendered to disk, it will not be recomputed.
+
+    Args:
+        img_filepath (str): image filepath (relative or absolute) to compute tiles for.
+        grid1 (bool, optional): If :obj:`True`, create a dense grid of tiles on the image.
+            Defaults to :obj:`True`.
+        grid2 (bool, optional): If :obj:`True`, create a secondary dense grid of tiles
+            on the image with a 50% offset.  Defaults to :obj:`True`.
+        ext (str, optional): The file extension of the resulting tile files.  If this value is
+            not specified, it will use the same extension as `img_filepath`.  Defaults
+            to :obj:`None`.
+        **kwargs: keyword arguments passed to :meth:`scoutbot.tile.tile_grid`
+
+    Returns:
+        tuple ( tuple ( int ), list ( dict ), list ( str ) ):
+            - the original image's shape as ``(h, w, c)``.
+            - list of grid coordinates as the output of :meth:`scoutbot.tile.tile_grid`.
+            - list of tile filepaths as the output of :meth:`scoutbot.tile.tile_filepath`.
     """
     assert exists(img_filepath)
     img = cv2.imread(img_filepath)
@@ -25,9 +44,9 @@ def compute(img_filepath, grid1=True, grid2=True, ext=None, **kwargs):
 
     grids = []
     if grid1:
-        grids += tile_grid(shape)
+        grids += tile_grid(shape, **kwargs)
     if grid2:
-        grids += tile_grid(shape, offset=TILE_WIDTH // 2, borders=False)
+        grids += tile_grid(shape, offset=TILE_WIDTH // 2, borders=False, **kwargs)
 
     filepaths = [tile_filepath(img_filepath, grid, ext=ext) for grid in grids]
     for grid, filepath in zip(grids, filepaths):
@@ -48,7 +67,6 @@ def tile_write(img, grid, filepath):
 
     Returns:
         bool: returns :obj:`True` if the tile's filepath exists on disk.
-
     """
     if exists(filepath):
         return True

scoutbot/wic/dataloader.py

@@ -1,11 +1,13 @@
 # -*- coding: utf-8 -*-
+import os
+
 import numpy as np
 import PIL
 import torch
 import torchvision
 import utool as ut
 
-BATCH_SIZE = 16
+BATCH_SIZE = int(os.getenv('WIC_BATCH_SIZE', 256))
 INPUT_SIZE = 224