create usage guide

Dockerfile

@@ -1,6 +1,3 @@
-# read the doc: https://huggingface.co/docs/hub/spaces-sdks-docker
-# you will also find guides on how best to write your Dockerfile
-
 FROM python:3.10
 
 WORKDIR /code

MANIFEST.in

@@ -1,2 +1,4 @@
-include eggcount/assets/*.jpg
-include eggcount/assets/*.png
+include larvaecount/assets/*.jpg
+include larvaecount/assets/*.png
+include larvaecount/assets/*.css
+include larvaecount/docs/*.md

larvaecount/assets/wiki_style.css

@@ -0,0 +1,3 @@
+.wiki h2, .wiki h3, .wiki h4, .wiki h5, .wiki h6, .wiki p, .wiki li {
+    text-align: left;
+}

larvaecount/docs/user_guide.md

@@ -0,0 +1,96 @@
+# Larvae Counter User Guide
+
+Welcome! This is a web-app that is equipped with a variety of tools to automate the counting
+of mosquito larvae and pupae (although mostly pupae at this stage) from images. Currently, this
+larvae counting tool has three automatic pupae counting tools based on "old-school" computer
+vision techniques. However, a deep-learning method based off of the `YoloV8` architecture
+is currently in development. Hypothetically, this deep learning method should be much less
+susceptible to noise and allow the simultaneous counting of larvae and pupae, and maybe even
+other stages of the mosquito life cycle. See below for a quick getting started guide.
+
+## Workflow
+
+Below is the general workflow used to count mosquito larvae present in an image.
+
+### Step 1: Upload an Image
+
+The first step is to upload an image containing pupae to be counted. This is done by either
+clicking on or dragging an image file to the camera icon on the page. If this app is being
+used on a smartphone an image can also be taken directly from the smartphone's camera by
+tapping on the camera icon. After uploading an image, you can begin tunning parameters.
+
+### Step 2: Parameter Tuning
+
+The next step is select your counting method and begin tuning the counting parameters. The
+counting method can be selected in the drop-down list below the image upload box. The 
+`Gradient CC w/ filter` is recommended as the default counting algorithm. The parameters
+for the selected counting method can be found in the box below the counting method drop-down
+list.
+
+It is recommend to click the `count` button with the default parameters to get a general
+idea of how the parameters need to be changed in order to get better results. After changing
+the parameters, click the `count` button again to re-run the selected algorithm with a new
+set of parameters.
+
+In general, parameters should be tuned from top down - meaning that the first parameter from the
+top should be tuned to get satisfactory results, then the second parameter, and so on. The
+images provided in the `Visualization` section of the results box (below the parameters box)
+should be used to tune the parameters. More details will be given on each counting method and
+its parameters below.
+
+### Step 3: Check Results
+
+After the parameters have been tuned, the final results are available in the results box - which
+is situated just below the counting parameters box.
+
+## Counting Algorithms
+
+The larvae-count tool currently has three counting algorithms available, `Gradient CC w/ Filter`,
+`Gradient CC`, and `Countour`. 
+
+### Gradient CC w/ filter
+
+`Gradient CC w/ Filter` (short for Gradient Connected Components with Elliptical Filter) counts
+the pupae present in an image utilizing clusters. The algorithm first creates a gray scale image
+from the provided image and applies a simple threshold in order to find pixels that are in a region
+containing pupae. A filter is then applied to filter out any pixels flagged as pupae that aren't part
+of a roughly elliptical pixel region. The algorithm than iterates over each overlapping cluster of 
+pupae (hence the connected components) and calculated the number of pupae in each cluster by
+the area of the cluster in pixels.
+
+#### Parameters
+
+- `Color Threshold`: Cutoff below which a pixel in the gray-scale image will be considered to be
+    in a region containing pupae. The allowed values range from (0-255).
+- `Average Area`: Average area (in pixels) of one pupae.
+- `Max Pupae Per Cluster (Optional)`: Maximum number of pupae per cluster, used to filter out any
+    large dark blobs in the image.
+- `Filter Kernel Width (Pixels)`: Width (in pixels) of the elliptical filter.
+- `Filter Kernel Height (Pixels)`: Height (in pixels) of the elliptical filter.
+
+### Gradient CC
+
+Same as `Gradient CC w/ Filter` but without the elliptical filter.
+
+#### Parameters
+
+- `Color Threshold`: Cutoff below which a pixel in the gray-scale image will be considered to be
+    in a region containing pupae. The allowed values range from (0-255).
+- `Average Area`: Average area (in pixels) of one pupae.
+- `Max Pupae Per Cluster (Optional)`: Maximum number of pupae per cluster, used to filter out any
+    large dark blobs in the image.
+
+### Gradient Contour w/ Filter
+
+Similar to `Gradient CC w/ Filter`, but instead of iterating over every blob of "pupae pixels"
+it iterates over regions contained within (an) elliptical contour(s).
+
+#### Parameters
+
+- `Color Threshold`: Cutoff below which a pixel in the gray-scale image will be considered to be
+    in a region containing pupae. The allowed values range from (0-255).
+- `Average Area`: Average area (in pixels) of one pupae.
+- `Max Pupae Per Cluster (Optional)`: Maximum number of pupae per cluster, used to filter out any
+    large dark blobs in the image.
+- `Filter Kernel Width (Pixels)`: Width (in pixels) of the elliptical filter.
+- `Filter Kernel Height (Pixels)`: Height (in pixels) of the elliptical filter.

larvaecount/gradient.py

@@ -65,6 +65,7 @@ def component_filter_thresh(
             "Num-Eggs": num_eggs
         },
         "vis": {
+            "Gray-Scale": img_gray.astype(np.uint8),
             "Egg-Mask": bin_mask.astype(np.uint8),
             "Ellipse-Filter": close.astype(np.uint8),
             "Visualization": visualization_img.astype(np.uint8)
@@ -131,6 +132,7 @@ def component_thesh(
             "Num-Eggs": num_eggs
         },
         "vis": {
+            "Gray-Scale": img_gray.astype(np.uint8),
             "Egg-Mask": bin_mask.astype(np.uint8),
             "Visualization": visualization_img.astype(np.uint8)
         }
@@ -183,6 +185,7 @@ def contour_thresh(
             "Num-Eggs": num
         },
         "vis": {
+            "Gray-Scale": img_gray.astype(np.uint8),
             "Egg-Mask": bin_mask.astype(np.uint8),
             "Ellipse-Filter": close.astype(np.uint8),
             "Visualization": visualization_img.astype(np.uint8)

larvaecount/pages/guide.py

@@ -0,0 +1,26 @@
+from dash import html, dcc, callback, Input, Output, State
+from larvaecount.ui.ui_utils import read_md_file
+
+import dash
+import dash_bootstrap_components as dbc
+import os
+
+dash.register_page(__name__, path = "/guide")
+
+USER_GUIDE_PATH = os.path.abspath(
+    os.path.join(
+        os.path.dirname(__file__),
+        os.pardir,
+        "docs",
+        "user_guide.md"
+    )
+)
+
+layout = dbc.Container(
+    children = dcc.Markdown(
+        children = read_md_file(USER_GUIDE_PATH),
+        className = "wiki"
+    ),
+    class_name = "text-center mt-3"
+)
+

larvaecount/pages/home.py

@@ -31,11 +31,11 @@ UPLOAD_HEIGHT = "25vh"
 
 COUNT_FUNCS = {
     "Gradient CC": get_cc_ui,
-    "Gradient CC w/ filter": get_cc_filter_ui,
-    "Contour": get_contour_ui
+    "Gradient CC w/ Filter": get_cc_filter_ui,
+    "Gradient Contour w/ Filter": get_contour_ui
 }
 
-DEFAULT_STRATEGY = "Gradient CC"
+DEFAULT_STRATEGY = "Gradient CC w/ Filter"
 
 def get_initial_upload_container() -> dbc.Container:
     return dcc.Upload(
@@ -64,7 +64,10 @@ def get_new_upload_container(
     image_data = BytesIO(decoded_bytes)
     pil_img = Image.open(image_data)
     img = np.array(pil_img)
-    image_fig = px.imshow(img)
+    image_fig = px.imshow(
+        img,
+        height = 750,
+    )
 
     return dbc.Container(
         children = [
@@ -72,7 +75,9 @@ def get_new_upload_container(
                 children = file_name,
                 className = "p-2 text-start",
             ),
-            dcc.Graph(figure = image_fig),
+            dcc.Graph(
+                figure = image_fig,
+            ),
             dbc.Container(
                 children = dcc.Upload(
                     children = dbc.Button(

larvaecount/ui/ui_utils.py

@@ -1,5 +1,6 @@
 from dash import html, dcc
 from typing import Dict
+from os import PathLike
 
 import plotly.express as px
 import numpy as np
@@ -33,13 +34,6 @@ def get_navbar() -> dbc.Nav:
                     href = "/guide",
                     class_name = "text-light"
                 )
-            ),
-            dbc.NavItem(
-                children = dbc.NavLink(
-                    children = "About",
-                    href = "/about",
-                    class_name = "text-light"
-                )
             )
         ],
         className = "bg-dark d-flex flex-row justify-content-start align-items-center",
@@ -247,7 +241,10 @@ def get_results_container(result: Dict) -> dbc.Container:
 
     for vis_name, vis_pic in result["vis"].items():
         children.append(html.H4(vis_name.replace("-", " ")))
-        image_fig = px.imshow(vis_pic)
+        image_fig = px.imshow(
+            vis_pic,
+            height = 750
+        )
         children.append(
             dcc.Graph(
                 figure = image_fig,
@@ -259,3 +256,7 @@ def get_results_container(result: Dict) -> dbc.Container:
         children = children,
         className = "p-3 m-0 border border-dark d-flex flex-column justify-content-center align-items-center"
     )
+
+def read_md_file(md_file_path: PathLike) -> str:
+    with open(md_file_path, "r") as file:
+        return file.read()

setup.py

@@ -4,5 +4,12 @@ setup(
     name = "larvaecount",
     version = "0.1",
     packages = find_packages(),
-    package_data={"larvaecount": ["assets/*.jpg", "assets/*.png"]}
+    package_data = {
+        "larvaecount": [
+            "assets/*.jpg",
+            "assets/*.png",
+            "assets/*.css",
+            "docs/*.md"
+        ]
+    }
 )