Update documentation

doc/manuals/index.rst

@@ -29,7 +29,7 @@ Contents:
    example_links/example_capabilities
    Core C++/Python Object Types <http://kwiver.readthedocs.io/en/latest/vital/architecture.html>
    Core Pipelining Architecture <http://kwiver.readthedocs.io/en/latest/sprokit/architecture.html>
-   Basic Processing Nodes <http://kwiver.readthedocs.io/en/latest/arrows/architecture.html>
+   Basic Pipeline Nodes <http://kwiver.readthedocs.io/en/latest/arrows/architecture.html>
    example_links/hello_world_pipeline
    example_links/detector_pipelines
    example_links/tracking_pipeline

examples/detection_file_conversions/README.rst

@@ -3,7 +3,12 @@
 Detection File Formats and Conversions
 ======================================
 
-A folder containing misc examples of how to convert between textual
+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 folder contains examples of how to convert between textual
 formats representing object detections, tracks, results, etc. There
 are multiple ways to perform format conversions, either using KWIVER
 pipelines with reader/writer nodes (e.g. see pipelines directory) or
@@ -12,24 +17,57 @@ are simple, containing a detection input node (reader) and output
 node (writer).
 
 
-**********************************
-VIAME Integrated Detection Formats
-**********************************
+****************************
+Integrated Detection Formats
+****************************
+
+A subset of the output ASCII formats already integrated into VIAME is listed below.
+New formats can be integrated to the system by implementing a derived version of the
+vital::algo::detected_object_set_input class in C++, or via making a python process which
+produces detected_object_sets or object_track_sets.
+
 |
-| CSV - Comma Seperated Value Detection Formats
+| CSV - Default Comma Seperated Value Detection Format
 | 
-|   detection1, detection2, detection3, 
+|  The default CSV format contains 1 detection per line, with each line as follows:
+|
+|   - 1: frame number
+|   - 2: file name
+|   - 3: TL-x (top left of the image is the origin)
+|   - 4: TL-y
+|   - 5: BR-x
+|   - 6: BR-y
+|   - 7: detection confidence
+|   - 8,9+  : class-name  score (this pair may be omitted or repeated)
 |
 | KW18 - Kitware KW18 Column Seperated Track Format
 |
-|   detection2, detection3, 
+|   KW18s are a space seperated file format for representing detections or tracks.
+|
+|   Each KW18 file has a header stating its contents, as follows: # 1:Track-id
+|   2:Track-length 3:Frame-number 4:Tracking-plane-loc(x) 5:Tracking-plane-loc(y)
+|   6:velocity(x) 7:velocity(y) 8:Image-loc(x) 9:Image-loc(y) 10:Img-bbox(TL_x)
+|   11:Img-bbox(TL_y) 12:Img-bbox(BR_x) 13:Img-bbox(BR_y) 14:Area 15:World-loc(x)
+|   16:World-loc(y) 17:World-loc(z) 18:timestamp 19:track-confidence
 |
 | HABCAM - Annotation format used by the HabCam project
 |
-|   v1
+|   A typical habcam annotation looks like:
+|
+|     201503.20150517.png 527 201501 boundingBox 458 970 521 1021
 |
+|   Which corresponds to image_name, species_id (species id to labels seperate),
+|   date, annot_type [either boundingBox, line, or point], tl_x, tl_y, bl_x, bl_y
+|
+|   For the point type, only 1 set of coordinate is provided
 |
 
 *******************
 Example Conversions
 *******************
+
+There are multiple ways to perform format conversions, either using KWIVER
+pipelines with reader/writer nodes (e.g. see pipelines directory) or
+using quick standalone scripts (see scripts). Conversion pipelines
+are simple, containing a detection input node (reader) and output
+node (writer).

examples/detector_pipelines/README.rst

@@ -1,10 +1,15 @@
 
-================
-Object Detection
-================
+=========================
+Object Detection Examples
+=========================
 
-This folder contains assorted examples of object detection pipelines running different
-detectors such as YOLOv2, ScallopTK, Faster RCNN, etc...
+This document corresponds to the example located online at:
+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.
 
 ************
 Requirements
@@ -17,14 +22,31 @@ Requirements
 |
 | Per-Example:
 |
-| run_habcam - VIAME_ENABLE_OPENCV, VIAME_ENABLE_SCALLOP_TK
-| run_yolo - VIAME_ENABLE_DARKNET
-| run_lanl - VIAME_ENABLE_MATLAB
+| run_habcam.sh/bat - VIAME_ENABLE_OPENCV, VIAME_ENABLE_YOLO, VIAME_ENABLE_SCALLOP_TK
+| run_yolo.sh/bat - VIAME_ENABLE_YOLO
+| run_lanl.sh/bat - VIAME_ENABLE_MATLAB
+
+
+**************************************
+Running the object detection exammples
+**************************************
+
+Each run script contains 2 calls. A first ('source setup_viame.sh') which
+runs a script configuring all paths required to run VIAME calls, and a second
+to 'pipeline_runner' running the desired detection pipeline. For more information
+about pipeline configuration, see the pipeline examples. Each example processes
+a list of images and produces detections in various format as output, as configured
+in the pipeline files.
+
+Each pipeline contains 2-10 nodes, including a imagery source, in this case an image
+list loader, the actual detector, detection filters, and detection writers. In the
+habcam example an additional split processes is added early in the pipeline, as
+habcam imagery has stereo pairs typically encoded in the same png.
 
 
-***************************************
-Running a single detector from C++ code
-***************************************
+********************************
+Running a detector from C++ code
+********************************
 
 We will be using a Hough circle detector as an and example of the
 mechanics of implementing a VIAME detector in cxx code.
@@ -138,9 +160,9 @@ Note that log messages do not need an end-of-line at the end.
 
 Refer to the separate logger documentation for more details.
 
-*********************
-Configuration Support
-*********************
+******************************
+Detector configuration support
+******************************
 
 In our detector example we just used the detector in its default state
 without specifying any configuration options. This works well in this
@@ -368,9 +390,9 @@ algorithms can be in the same file, which is exactly how more
 complicated applications are configured.
 
 
-********************************************
-Sequencing Multiple Algorithms in a Pipeline
-********************************************
+***********************************************
+Sequencing one or more algorithms in a pipeline
+***********************************************
 
 In a real application, the input images may come from places other
 than a file on the disk and there may be algorithms applied to

examples/hello_world_pipeline/README.rst

@@ -3,15 +3,17 @@
 New Module Creation Examples
 ============================
 
-See the platform-specific guides below, though the process is similar for each.
 This document corresponds to the example located online at:
-https://github.com/Kitware/VIAME/tree/master/examples/building_viame
-and also to the following directory in your VIAME installation:
-[viame-install]/examples/building_viame.
+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
 
-**********************************
-Example C++ Object Detector Plugin
-**********************************
+They can additionally be found in a VIAME installation at:
+[viame-install]/examples/hello_world_pipeline.
+
+*******************
+C++ Detector Plugin
+*******************
 
 A new detector plugin is added by creating a class that implements the
 kwiver::vital::algo::image_object_detector interface. This interface
@@ -48,7 +50,7 @@ VIAME framework is to convert the input image from the VIAME format to
 the format needed by the detector, and to convert the detections to a
 detected_object_set as needed by the framework.
 
-Most detectors take images in OpenCV MAT format. This data structure
+Many detectors take images in OpenCV MAT format. This data structure
 can be extracted from the image_container_sptr that is available using
 the following code:
 
@@ -93,3 +95,11 @@ be converted to a detected_object_set using the following pseudo-code.
     // When all detections have been processed, the detected object set for this input
     // image is just returned from the detect() method
     return detected_objects;
+
+**********************
+Python Detector Plugin
+**********************
+
+Similarly to the above C++ object detector, the python templates in the above directory
+can be copied into a new plugin module, and the template keywords replaced with a module
+name of your choosing.

examples/measurement_using_stereo/README.rst

@@ -1,12 +1,12 @@
 
-=====================================
-Size Measurement Using Stereo Cameras
-=====================================
+===========================
+Length Measurement Examples
+===========================
 
 .. image:: http://www.viametoolkit.org/wp-content/uploads/2018/02/fish_measurement_example.png
    :scale: 60
    :align: center
 
-`Coming Soon`_
+`Coming Soon, Pull Request 25`_
 
 .. _Coming Soon: https://github.com/Kitware/VIAME/pull/25