readme.md, user guide

README.md

@@ -1,11 +1,60 @@
----
-title: Larvae Counter
-emoji: 📚
-colorFrom: indigo
-colorTo: blue
-sdk: docker
-pinned: false
-license: mit
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Larvae Counter
+
+Welcome to the Larvae Counter repo! This web-app utilizes several computer vision techniques to
+automate mosquito larvae and pupae counting tasks in a lab setting. To get started visit
+the web-app [here](https://lilferrit.github.io/larvaecount/).
+
+## About
+
+The Larvae Counter web-app is implemented purely in python. Most image processing is done using
+the [OpenCV](https://opencv.org/) library and the web-ui is written using Plotly's
+[Dash](https://dash.plotly.com/) library. The web-app is currently hosted on Huggingface
+[here](https://huggingface.co/spaces/lilferrit/larvae-counter).
+
+## Running Locally
+
+To run the larvae counter app locally first clone the repo. Next, navigate to the repo folder using:
+
+```
+cd larvaecount
+```
+
+or your system's equivalent. Next, install the project dependencies (you may choose
+to so in a virtual environment):
+
+```
+pip install -r requirements.txt
+```
+
+Then install the larvaecount package itself:
+
+```
+pip install .
+```
+
+to run the web app run
+
+```
+python3 -m larvaecount.app --debug=<True/False> --port="<port>" --host="<host-addr>"
+```
+
+Note: The debug, port, and host arguments are optional and default to `False`, `8080` and
+`127.0.0.1` respectively.
+
+## Using the CLI
+
+All of the counting methods are also available via the command line. To run the CLI run the
+command:
+
+```
+python3 -m larvaecount.cli <counting_method> <args>
+```
+
+The command line arguments are passed directly to the functions in 
+[larvaecount/cli.py](larvaecount/cli.py) using the 
+[python-fire](https://github.com/google/python-fire) library. See 
+[larvaecount/cli.py](larvaecount/cli.py) for usage instructions.
+
+## License
+
+This project uses the MIT license, see [license.txt](license.txt)

larvaecount/docs/user_guide.md

@@ -93,4 +93,10 @@ it iterates over regions contained within (an) elliptical contour(s).
 - `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.
+- `Filter Kernel Height (Pixels)`: Height (in pixels) of the elliptical filter.
+
+### YoloV8 (Coming Soon!!)
+
+Deep learning implementation of the larvae/pupae counter. Not only should a deep learning
+approach have far less parameters to tune, it should perform **much** better than the old-school
+computer vision approaches currently in use.

license.txt

@@ -0,0 +1,18 @@
+
+
+Copyright 2024 Gavin Straub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and 
+associated documentation files (the “Software”), to deal in the Software without restriction, 
+including without limitation the rights to use, copy, modify, merge, publish, distribute, 
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is 
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or 
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, 
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE 
+AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, 
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.