Add documentation

.gitignore

@@ -11,3 +11,5 @@ coverage/
 gradio_cached_examples/
 __pycache__/
 docs/build/
+
+docs/_build/

README.rst

@@ -14,7 +14,7 @@ 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:: bash
+.. code-block:: console
 
    # Install Homebrew
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
@@ -27,7 +27,7 @@ You need to first install Anaconda on your machine.  Below are the instructions
 
 Once Anaconda is installed, you will need an environment and the following packages installed
 
-.. code:: bash
+.. code-block:: console
 
    # Create Environment
    conda create --name scoutbot
@@ -42,19 +42,24 @@ Once Anaconda is installed, you will need an environment and the following packa
 How to Run
 ----------
 
-It is recommended to use `ipython` and to copy sections of code into and inspecting the
+You can run the tile-base Gradio demo with:
 
-.. code:: bash
+.. code-block:: console
 
-   # Run the live demo
-   python app.py
+   (.venv) $ python app.py
+
+or, you can run the image-base Gradio demo with:
+
+.. code-block:: console
+
+   (.venv) $ python app2.py
 
 Docker
 ------
 
 The application can also be built into a Docker image and hosted on Docker Hub.
 
-.. code:: bash
+.. code-block:: console
 
     # linux/amd64
 
@@ -72,7 +77,7 @@ The application can also be built into a Docker image and hosted on Docker Hub.
 
 To run:
 
-.. code:: bash
+.. code-block:: console
 
     docker run \
        -it \
@@ -92,7 +97,7 @@ Building Documentation
 
 There is Sphinx documentation in the `docs/` folder, which can be built with the code below:
 
-.. code:: bash
+.. code-block:: console
 
     cd docs/
     sphinx-build -M html . build/
@@ -110,7 +115,7 @@ on any code you write. (See also `pre-commit.com <https://pre-commit.com/>`_)
 
 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:: bash
+.. code-block:: console
 
     git add .
     pre-commit run
@@ -127,7 +132,7 @@ The code base has been formatted by Brunette, which is a fork and more configura
     :alt: GitHub CI
 
 .. |Codecov| image:: https://codecov.io/gh/WildMeOrg/scoutbot/branch/main/graph/badge.svg?token=FR6ITMWQNI
-    :target: https://codecov.io/gh/WildMeOrg/scoutbot
+    :target: https://app.codecov.io/gh/WildMeOrg/scoutbot
     :alt: Codecov
 
 .. |Wheel| image:: https://github.com/WildMeOrg/scoutbot/actions/workflows/python-publish.yml/badge.svg

docs/conf.py

@@ -32,12 +32,19 @@ extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.intersphinx',
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.coverage',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.imgmath',
+    'sphinx.ext.napoleon',
 ]
 
 intersphinx_mapping = {
     'rtd': ('https://docs.readthedocs.io/en/stable/', None),
     'python': ('https://docs.python.org/3/', None),
     'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+    'cv2': ('https://docs.opencv.org/2.4.13.7/', None),
 }
 intersphinx_disabled_domains = ['std']
 
@@ -51,6 +58,8 @@ epub_show_urls = 'footnote'
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+autosectionlabel_prefix_document = True
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -58,6 +67,20 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 #
 html_theme = 'sphinx_rtd_theme'
 
+html_theme_path = [
+    '_themes',
+]
+
+html_sidebars = {
+    '**': [
+        'about.html',
+        'navigation.html',
+        'relations.html',
+        'searchbox.html',
+        'donate.html',
+    ]
+}
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".

docs/index.rst

@@ -10,6 +10,5 @@ Contents
 .. toctree::
 
    Home <self>
-   usage
    scoutbot
    cli

docs/scoutbot.rst

@@ -6,8 +6,8 @@ ScoutBot API
    :caption: Contents:
 
 
-Tiles
------
+Tiles (TILE)
+------------
 
 .. automodule:: scoutbot.tile
    :members:
@@ -31,6 +31,14 @@ Localizer (LOC)
    :undoc-members:
    :show-inheritance:
 
+Aggregation (AGG)
+-----------------
+
+.. automodule:: scoutbot.agg
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Utilities
 ---------
 

docs/usage.rst

@@ -1,19 +0,0 @@
-Usage
-=====
-
-.. _installation:
-
-Installation
-------------
-
-To use this code, first install its dependencies using pip:
-
-.. code-block:: console
-
-   (.venv) $ pip install -r requirements.txt
-
-then, you can run the application via:
-
-.. code-block:: console
-
-   (.venv) $ python app.py

scoutbot/__init__.py

@@ -37,7 +37,7 @@ Notes:
 '''
 from scoutbot import agg, loc, tile, wic
 
-VERSION = '0.1.0'
+VERSION = '0.1.1'
 version = VERSION
 __version__ = VERSION
 

scoutbot/loc/__init__.py

@@ -47,6 +47,22 @@ ONNX_MODEL_HASH = '85a9378311d42b5143f74570136f32f50bf97c548135921b178b46ba7612b
 
 
 def fetch(pull=False):
+    """
+    Fetch the Localizer ONNX model file from a CDN if it does not exist locally.
+
+    This function will throw an AssertionError if the download fails or the
+    file otherwise does not exists locally on disk.
+
+    Args:
+        pull (bool, optional): If :obj:`True`, use a downloaded version stored in
+            sthe local system's cache.  Defaults to :obj:`False`.
+
+    Returns:
+        str: local ONNX model file path.
+
+    Raises:
+        AssertionError: If the model cannot be fetched.
+    """
     if not pull and exists(ONNX_MODEL_PATH):
         onnx_model = ONNX_MODEL_PATH
     else:
@@ -61,6 +77,21 @@ def fetch(pull=False):
 
 
 def pre(inputs):
+    """
+    Load a list of filepaths and return a corresponding list of the image
+    data as a 4-D list of floats.  The image data is loaded from disk, transformed
+    as needed, and is normalized to the input ranges that the Localizer ONNX model
+    expects.
+
+    This function will throw an error if any of the filepaths do not exist.
+
+    Args:
+        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
+    """
     transform = torchvision.transforms.ToTensor()
 
     data = []
@@ -80,6 +111,17 @@ def pre(inputs):
 
 
 def predict(data, fill=True):
+    """
+    Run neural network inference using the Localizer's ONNX model on preprocessed data.
+
+    Args:
+        data (list): list of transformed image data, the first return of :meth:`scoutbot.loc.pre`
+        fill (bool, optional): If :obj:`True`, fill any partial batches to the LOC `BATCH_SIZE`,
+            and then trim them after inference.  Defaults to :obj:`True`.
+
+    Returns:
+        list ( list ( float ) ): list of raw ONNX model outputs
+    """
     onnx_model = fetch()
 
     ort_session = ort.InferenceSession(
@@ -106,6 +148,38 @@ def predict(data, fill=True):
 
 
 def post(preds, sizes, loc_thresh=LOC_THRESH, nms_thresh=NMS_THRESH):
+    """
+    Apply a post-processing normalization of the raw ONNX network outputs.
+
+    The final output is a list of lists 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)
+            }
+
+    The ``l`` label is the string class as used when the original
+    ONNX model was trained.
+
+    The ``c`` confidence value is a bounded float between ``0.0`` and
+    ``1.0`` (inclusive), but should not be treated as a probability.
+
+    The ``x``, ``y``, ``w``, ``h`` bounding box keys are in real pixel values.
+
+    Args:
+        preds (list): list of raw ONNX model outputs, the return of :meth:`scoutbot.loc.predict`
+        sizes (list): list of original tile sizes, the second return of :meth:`scoutbot.loc.pre`
+
+    Returns:
+        list ( list ( dict ) ): nested list of Localizer predictions
+    """
     postprocess = Compose(
         [
             GetBoundingBoxes(NUM_CLASSES, ANCHORS, loc_thresh),

scoutbot/scoutbot.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 """
-The lecture materials for Lecture 1: Dataset Prototyping and Visualization
+ScoutBot CLI executable
 """
 import click
 

scoutbot/tile/__init__.py

@@ -16,7 +16,9 @@ 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
+    """
     assert exists(img_filepath)
     img = cv2.imread(img_filepath)
     shape = img.shape
@@ -35,6 +37,19 @@ def compute(img_filepath, grid1=True, grid2=True, ext=None, **kwargs):
 
 
 def tile_write(img, grid, filepath):
+    """
+    Write a single image's tile to disk using its grid coordinates and an output path.
+
+    Args:
+        img (numpy.ndarray): 3-dimentional Numpy array, the return from :func:`cv2.imread`
+        grid (dict): the grid coordinate dictionary, one of the returned dictionaries
+            from :meth:`scoutbot.tile.tile_grid`
+        filepath (str): the tile's full output filepath (relative or absolute)
+
+    Returns:
+        bool: returns :obj:`True` if the tile's filepath exists on disk.
+
+    """
     if exists(filepath):
         return True
 

scoutbot/wic/__init__.py

@@ -1,6 +1,10 @@
 # -*- coding: utf-8 -*-
-'''
-2022 Wild Me
+'''The Whole Image Classifier (WIC) returns confidence scores for image tiles.
+
+This module defines how WIC models are downloaded from an external CDN,
+how to load an image and prepare it for inference, demonstrates how to run the
+WIC ONNX model on this input, and finally how to convert this raw CNN output
+into usable confidence scores.
 '''
 from os.path import exists, join
 from pathlib import Path
@@ -29,6 +33,22 @@ WIC_THRESH = 0.2
 
 
 def fetch(pull=False):
+    """
+    Fetch the WIC ONNX model file from a CDN if it does not exist locally.
+
+    This function will throw an AssertionError if the download fails or the
+    file otherwise does not exists locally on disk.
+
+    Args:
+        pull (bool, optional): If :obj:`True`, use a downloaded version stored in
+            sthe local system's cache.  Defaults to :obj:`False`.
+
+    Returns:
+        str: local ONNX model file path.
+
+    Raises:
+        AssertionError: If the model cannot be fetched.
+    """
     if not pull and exists(ONNX_MODEL_PATH):
         onnx_model = ONNX_MODEL_PATH
     else:
@@ -43,6 +63,20 @@ def fetch(pull=False):
 
 
 def pre(inputs):
+    """
+    Load a list of filepaths and return a corresponding list of the image
+    data as a 4-D list of floats.  The image data is loaded from disk, transformed
+    as needed, and is normalized to the input ranges that the WIC ONNX model
+    expects.
+
+    This function will throw an error if any of the filepaths do not exist.
+
+    Args:
+        inputs (list(str)): list of tile image filepaths (relative or absolute)
+
+    Returns:
+        list ( list ( list ( list ( float ) ) ) ): list of transformed image data
+    """
     transform = _init_transforms()
     dataset = ImageFilePathList(inputs, transform=transform)
     dataloader = torch.utils.data.DataLoader(
@@ -57,6 +91,17 @@ def pre(inputs):
 
 
 def predict(data, fill=False):
+    """
+    Run neural network inference using the WIC's ONNX model on preprocessed data.
+
+    Args:
+        data (list): list of transformed image data, the return of :meth:`scoutbot.wic.pre`
+        fill (bool, optional): If :obj:`True`, fill any partial batches to the WIC `BATCH_SIZE`,
+            and then trim them after inference.  Defaults to :obj:`False`.
+
+    Returns:
+        list ( list ( float ) ): list of raw ONNX model outputs
+    """
     onnx_model = fetch()
 
     ort_session = ort.InferenceSession(
@@ -83,5 +128,17 @@ def predict(data, fill=False):
 
 
 def post(preds):
+    """
+    Apply a post-processing normalization of the raw ONNX network outputs.
+
+    The final output is a dictionary where the key values are the predicted labels
+    and the values are their corresponding confidence values.
+
+    Args:
+        preds (list): list of raw ONNX model outputs, the return of :meth:`scoutbot.wic.predict`
+
+    Returns:
+        list ( dict ): list of WIC predictions
+    """
     outputs = [dict(zip(ONNX_CLASSES, pred)) for pred in preds]
     return outputs

scoutbot/wic/dataloader.py

@@ -5,7 +5,7 @@ import torch
 import torchvision
 import utool as ut
 
-BATCH_SIZE = 2048
+BATCH_SIZE = 512
 INPUT_SIZE = 224