Update docs

VIAME · Feb 7, 2018 · 2f0aa26 · 2f0aa26
1 parent 337e372
commit 2f0aa26
Show file tree

Hide file tree

Showing 12 changed files with 93 additions and 35 deletions.
diff --git a/doc/manuals/index.rst b/doc/manuals/index.rst
@@ -21,6 +21,11 @@ for model training, output detection visualization, groundtruth annotation,
 detector/tracker evaluation (a.k.a. scoring), image/video search, and rapid model
 generation. 
 
+This manual is synced to the VIAME 'master' branch and is updated frequently, you may
+have to press ctrl-F5 to see the latest updates to avoid using your browser cache of
+this webpage.
+
+
 Contents:
 
 .. toctree::

diff --git a/examples/detection_file_conversions/README.rst b/examples/detection_file_conversions/README.rst
@@ -3,10 +3,11 @@
 Detection File Formats and Conversions
 ======================================
 
-This document corresponds to the example located online at:
-https://github.com/Kitware/VIAME/tree/master/examples/detection_file_conversions.
-They can additionally be found in a VIAME installation at:
-[viame-install]/examples/detection_file_conversions.
+This document corresponds to `this example online`_, in addition to the
+[viame-install]/examples/detection_file_conversions folder in a VIAME
+installation.
+
+.. _this example online: https://github.com/Kitware/VIAME/tree/master/examples/detection_file_conversions
 
 This folder contains examples of how to convert between textual
 formats representing object detections, tracks, results, etc. There
@@ -16,7 +17,6 @@ using quick standalone scripts (see scripts). Conversion pipelines
 are simple, containing a detection input node (reader) and output
 node (writer).
 
-
 ****************************
 Integrated Detection Formats
 ****************************
@@ -33,7 +33,7 @@ produces detected_object_sets or object_track_sets.
 |
 |   - 1: frame number
 |   - 2: file name
-|   - 3: TL-x (top left of the image is the origin)
+|   - 3: TL-x (top left of the image is the origin: 0,0)
 |   - 4: TL-y
 |   - 5: BR-x
 |   - 6: BR-y
@@ -61,6 +61,12 @@ produces detected_object_sets or object_track_sets.
 |
 |   For the point type, only 1 set of coordinate is provided
 |
+|   An alternative format that reader supports looks like:
+|
+|     201503.20150517.png,527,scallop,"""line"": [[458, 970], [521, 1021]]"
+|
+|   which is more or less the same, just formatted differently.
+|
 
 *******************
 Example Conversions

diff --git a/examples/detector_pipelines/README.rst b/examples/detector_pipelines/README.rst
@@ -13,13 +13,15 @@ Object Detection
    :target: https://github.com/Kitware/VIAME/tree/master/examples/detector_pipelines
 
 
-This document corresponds to the example located online at:
-https://github.com/Kitware/VIAME/tree/master/examples/detector_pipelines.
+This document corresponds to `this example online`_, in addition to the
+[viame-install]/examples/detector_pipelines folder in a VIAME installation.
+
+.. _this example online: https://github.com/Kitware/VIAME/tree/master/examples/detector_pipelines
+
 This folder contains assorted examples of object detection pipelines
 running different detectors such as YOLOv2, ScallopTK, Faster RCNN, and others.
-
-They can additionally be found in a VIAME installation at:
-[viame-install]/examples/detector_pipelines.
+Several different models are found in the examples, trained on a variety of different
+sensors.
 
 ************
 Requirements

diff --git a/examples/detector_training/README.rst b/examples/detector_training/README.rst
@@ -3,6 +3,11 @@
 Detector Training Examples
 ==========================
 
+This document corresponds to `this example online`_, in addition to the
+[viame-install]/examples/detector_training folder in a VIAME installation.
+
+.. _this example online: https://github.com/Kitware/VIAME/tree/master/examples/detector_training
+
 The common detector training API is used for training multiple object
 detectors from the same input format for both experimentation and
 deployment purposes. By default, each detector has a default training

diff --git a/examples/external_plugin_creation/README.rst b/examples/external_plugin_creation/README.rst
@@ -3,8 +3,13 @@
 External Plugin Creation
 ========================
 
+This document corresponds to `this example online`_, in addition to the
+[viame-install]/examples/external_plugin_creation folder in a VIAME installation.
+
+.. _this example online: https://github.com/Kitware/VIAME/tree/master/examples/external_plugin_creation
+
 This directory contains the source files needed to make a loadable
-detector algorithm implementation external to VIAME, which links
-against it, or in the case of python generates a loadable script.
-This is for cases where we might want to just make a plugin but not
-build all of VIAME itself.
+algorithm plugin implementation external to VIAME, which links
+against an installation, or in the case of python generates a loadable script.
+This is for cases where we might want to just make a plugin against pre-compiled binaries
+but not build all of VIAME itself.
diff --git a/examples/hello_world_pipeline/README.rst b/examples/hello_world_pipeline/README.rst
@@ -3,13 +3,18 @@
 New Module Creation Examples
 ============================
 
-This document corresponds to the example located online at:
-https://github.com/Kitware/VIAME/tree/master/examples/hello_world_pipeline
-and the basic C++/Python/Matlab templates located in:
-https://github.com/Kitware/VIAME/tree/master/plugins/templates
+This document corresponds to `this runable example`_ of `these example simple plugins`_,
+alongside `these example plugin templates`_. Additionally, all of the last can be found in
+[viame-install]/examples/hello_world_pipeline folder,
+[viame-source]/plugins/hello_world folder,
+and [viame-source]/plugins/templates folder in a VIAME installation, respectively.
+Throughout these folders are example object detectors, image filters, and image classifiers
+written in python and C++.
+
+.. _this runable example: https://github.com/Kitware/VIAME/tree/master/examples/hello_world_pipeline
+.. _these example simple plugins: https://github.com/Kitware/VIAME/tree/master/plugins/hello_world
+.. _this example online: https://github.com/Kitware/VIAME/tree/master/plugins/templates
 
-They can additionally be found in a VIAME installation at:
-[viame-install]/examples/hello_world_pipeline.
 
 *******************
 C++ Detector Plugin

diff --git a/examples/image_and_video_search/README.rst b/examples/image_and_video_search/README.rst
@@ -5,7 +5,8 @@ Rapid Model Generation
 
 Rapid model generation can be performed using the same method as image and video search
 (below), just saving out the resultant trained detection models after performing iterative
-query refinement.
+query refinement. These models can then be used in detection pipelines, or further refined
+or used in future video searches.
 
 Additional documentation coming soon.
 
@@ -17,6 +18,11 @@ Image and Video Search Examples
 Overview
 ********
 
+This document corresponds to `this example online`_, in addition to the
+[viame-install]/examples/image_and_video_search folder in a VIAME installation.
+
+.. _this example online: https://github.com/Kitware/VIAME/tree/master/examples/image_and_video_search
+
 This directory contains methods to accomplish two tasks: 
 
 |

diff --git a/examples/image_and_video_search/smqtk_on_chips/README.rst b/examples/image_and_video_search/smqtk_on_chips/README.rst
@@ -8,9 +8,12 @@ Image Search Using SMQTK
    :align: center
    :target: https://github.com/Kitware/VIAME/tree/master/examples/image_and_video_search/smqtk_on_chips
 
+This section corresponds to `this example online`_, in addition to the
+smqtk_on_chips example folder in a VIAME installation. This folder contains examples
+covering image search on top of an archive of images.
 
+.. _this example online: https://github.com/Kitware/VIAME/tree/master/examples/image_and_video_search/smqtk_on_chips
 
-This folder contains examples covering image search on top of an archive of images. 
 
 |
 | Building and running this examples requires: 
@@ -21,8 +24,9 @@ This folder contains examples covering image search on top of an archive of imag
 |        - VIAME_ENABLE_SMQTK
 |        - VIAME_ENABLE_CAFFE
 |        - VIAME_ENABLE_CUDA (Optional, but desired for performance)
-|        - VIAME_ENABLE_YOLO (Optional, for detector ingest example)
-|  (d) An installation of MongoDB to run the web client 
+|        - VIAME_ENABLE_YOLO (Optional, for detector ingest example (c))
+|  (d) An installation of MongoDB to run the web GUI client 
+|      (https://docs.mongodb.com/manual/administration/install-on-linux/)
 |
 | The system can either be configured to perform queries via: 
 |
@@ -34,14 +38,15 @@ This folder contains examples covering image search on top of an archive of imag
 First, reset_database.sh should be called to initialize a new database. 
 
 Next, depending on which indexing paradigm you are using, one of the 3 ingesting shell
-scripts can be called.
+scripts can be called (ingest_[].sh).
 
 Which ingesting paradigm you want to use depends on a few factors: does your object
 take up the entire image? Use (a). Are your object(s) a fixed known size in your image?
-Use (b). Are your objects multiple scales? Use (c).
+Use (b). Are your objects multiple scales and do you have a detector which works decently
+on your dataset? Use (c).
 
 After ingesting data, you want to launch the web-GUI service (launch_gui_backend.sh), and connect
-to the GUI via going to the default website 'http://0.0.0.0:5000/' if you didn't change any
+to the GUI via going to the default website 'http://0.0.0.0:5000/', at least if you didn't change any
 hosting settings. The default GUI log in is username: demo, password: demo after which
 you can log in, perform image queries, and iterative refinement on the results to generate
-an improved model for your query.
+an improved model for your initial query.
diff --git a/examples/image_and_video_search/video_ingest/README.rst b/examples/image_and_video_search/video_ingest/README.rst
@@ -8,22 +8,27 @@ Video Search using VIAME
    :align: center
    :target: https://github.com/Kitware/VIAME/tree/master/examples/image_and_video_search/video_ingest
 
+This section corresponds to `this example online`_, in addition to the
+video_ingest example folder in a VIAME installation. This folder contains examples
+covering image search on top of an archive of videos.
 
-
-This folder contains an example for video search. 
+.. _this example online: https://github.com/Kitware/VIAME/tree/master/examples/image_and_video_search/video_ingest
 
 |
 | WARNING: This example is a work in progress, and should only be attempted
-  by advanced users for the time being. 
+  by advanced users and developers for the time being. 
 |
 | Building and running this examples requires: 
 |
-|  (a) The python packages: 
-|  (b) A VIAME build with VIAME_ENABLE_SMQTK, BURNOUT, YOLO, OPENCV, VXL and VIVIA. 
+|  (a) The python packages: numpy
+|  (b) A VIAME build with VIAME_ENABLE_SMQTK, BURNOUT, YOLO, OPENCV, VXL and VIVIA enabled.
 |
 
 An arbitrary tracking pipeline is used to first generate spatio-temporal object tracks
 representing object candidate locations in video. Descriptors are generated around these
 object tracks, which get indexed into a database and can be queried upon. By indicating
 which query results are correct, a model can be trained for a new object category and
 saved to an output file to be reused again in future pipelines or query requests.
+
+First, db_init.sh should be called to initialize a new database. Next 'ingest_video.sh'
+in order to pre-process a video or image sequence of your choice.
diff --git a/examples/measurement_using_stereo/README.rst b/examples/measurement_using_stereo/README.rst
@@ -7,6 +7,13 @@ Length Measurement Examples
    :scale: 60
    :align: center
 
+This section corresponds to `this example online`_, in addition to the
+measurement_using_stereo example folder in a VIAME installation. This folder contains
+examples covering image search on top of an archive of images.
+
+.. _this example online: https://github.com/Kitware/VIAME/tree/master/examples/measurement_using_stereo
+
+
 `Coming Soon`_  on Pull Request 25
 
 .. _Coming Soon: https://github.com/Kitware/VIAME/pull/25
diff --git a/examples/scoring_and_roc_generation/README.rst b/examples/scoring_and_roc_generation/README.rst
@@ -14,12 +14,15 @@ metrics such as ROC curves, specificity, sensitivities, etc. The input to
 these tools must be in the Kitware kw18 format. Several scripts are provided to
 convert other formats (such as habcam annotations and Scallop-tk outputs) to
 kw18 format. The format is very simple so additional converters can be easily
-created.
+created. 
 
+An example of running scoring tools can be found `here`_.
 The scoring tool takes two files: the actual detections in the truth
 file and the computed detections. The computed detections are scored
 against the truth file to give a set of statistics as shown below:
 
+.. _here: https://github.com/Kitware/VIAME/blob/master/examples/scoring_and_roc_generation/
+
 ::
 
   HADWAV Scoring Results:

diff --git a/examples/visualizing_detections_in_gui/README.rst b/examples/visualizing_detections_in_gui/README.rst
@@ -8,6 +8,10 @@ GUIs for Visualization and Annotation
    :align: center
    :target: https://github.com/Kitware/VIAME/blob/master/examples/visualizing_detections_in_gui/README.rst
 
+This document corresponds to `this example online`_, in addition to the
+[viame-install]/examples/visualizing_detections_in_gui folder in a VIAME installation.
+
+.. _this example online: https://github.com/Kitware/VIAME/blob/master/examples/visualizing_detections_in_gui
 
 There are a number of GUIs in the system. As part of the VIVIA package, the vpView and vsPlay
 GUIs are useful for displaying detections, their respective probabilities, and for making