Merge pull request #373 from miriamsr/tfod_removal

Update TensorFlow References to Color Processing

Author: miriamsr

docs/source/apriltag/vision_portal/vision_processor_init/vision-processor-init.rst

@@ -4,8 +4,8 @@ Vision Processor Initialization
 Processor Initialization - Overview
 -----------------------------------
 
-Your OpMode must **first prepare** for using AprilTag and/or TensorFlow Object
-Detection (TFOD) commands, or methods.
+Your OpMode must **first prepare** for using AprilTag and/or
+Color Processing commands, or methods.
 
 In the INIT portion of your Java or Blocks code, before ``waitForStart()``, use
 these steps:
@@ -18,11 +18,11 @@ these steps:
 
 - **Step 2.** *Required:*  
 
-  - Create the **AprilTag Processor** (or the **TFOD
+  - Create the **AprilTag Processor** (or the **Color Locator or Color Sensor
     Processor**), to analyze frames streaming in from the camera. "Under the
     hood", the Apriltag Processor is attached to an EOCV **pipeline**, which
     performs various steps, in order, to each stream frame. The stream is the
-    input to the pipeline. A similar process happens for TFOD.
+    input to the pipeline. A similar process happens for Color Processing.
 
 - **Step 3.** *Required:*  
 
@@ -141,106 +141,15 @@ Here the object ``myAprilTagProcessorBuilder`` was not created; the build was
 performed directly on ``myAprilTagProcessor``.  The Builder pattern allows the
 "dot" methods to be chained in a single Java statement ending with ``.build()``.
 
-TensorFlow Initialization - Easy
---------------------------------
+Color Processing Initialization
+-------------------------------
 
-**Step 2** is similar for creating the **TensorFlow TFOD Processor**, software
+**Step 2** is similar for creating the **Color Sensor/Locator Processor**, software
 that evaluates frames streaming in from the camera.
 
-The SDK provides an "easy" way to create the processor, using only **defaults**
-and not mentioning a "Builder":
-
-.. tab-set::
-   .. tab-item:: Blocks
-      :sync: blocks
-
-      .. figure:: images/040-TFOD-Processor-easy.png
-         :width: 75%
-         :align: center
-         :alt: Easy TFOD Initialization
-
-         Easy TensorFlow TFOD Processor Initialization without a Builder
-
-   .. tab-item:: Java
-      :sync: java
-
-      Example of TensorFlow TFOD Processor Initialization without a Builder
-
-      .. code-block:: java
-
-         TfodProcessor myTfodProcessor;
-         // Create the TensorFlow Object Detection processor and assign it to a variable.
-         myTfodProcessor = TfodProcessor.easyCreateWithDefaults();
-
-
-TensorFlow Initialization - Builder
------------------------------------
-
-The SDK also provides the "Builder" way to create the processor, allowing
-**custom settings**.
-
-**Builder** is a Java pattern or structure for adding features or parameters,
-finalized with the ``.build()`` command.  Such features are **not** modified
-later during an OpMode.
-
-*Inside the SDK, even the "easy" process uses the Builder pattern to set the default parameters.*
-
-.. tab-set::
-   .. tab-item:: Blocks
-      :sync: blocks
-
-      .. figure:: images/050-TFOD-Processor-builder.png
-         :width: 75%
-         :align: center
-         :alt: TFOD Initialization with Builder
-
-         TensorFlow TFOD Processor Initialization with a Builder
-
-   .. tab-item:: Java
-      :sync: java
-
-      .. code-block:: java
-      
-         TfodProcessor.Builder myTfodProcessorBuilder;
-         TfodProcessor myTfodProcessor;
-
-         // Create a new TFOD Processor Builder object.
-         myTfodProcessorBuilder = new TfodProcessor.Builder();
-
-         // Optional: set other custom features of the TFOD Processor (4 are shown here).
-         myTfodProcessorBuilder.setMaxNumRecognitions(10);  // Max. number of recognitions the network will return
-         myTfodProcessorBuilder.setUseObjectTracker(true);  // Whether to use the object tracker
-         myTfodProcessorBuilder.setTrackerMaxOverlap((float) 0.2);  // Max. % of box overlapped by another box at recognition time
-         myTfodProcessorBuilder.setTrackerMinSize(16);  // Min. size of object that the object tracker will track
-
-         // Create a TFOD Processor by calling build()
-         myTfodProcessor = myTfodProcessorBuilder.build();
-
-This example shows only 4 TFOD Processor Builder features; others are
-available.  Most others relate to custom TFOD Models, beyond this scope of this
-VisionPortal Guide.
-
-TensorFlow Java Builder Chain
------------------------------
-
-The Builder pattern can be implemented in a streamlined manner, using Java.  The following code is equivalent to the above individual method calls.
-
-Comments are omitted here, to clearly illustrate the chaining.
-
-.. code-block:: java
-   
-   TfodProcessor myTfodProcessor;
-
-   myTfodProcessor = new TfodProcessor.Builder()
-       .setMaxNumRecognitions(10)
-       .setUseObjectTracker(true)
-       .setTrackerMaxOverlap((float) 0.2)
-       .setTrackerMinSize(16)
-       .build();
-
-Here the object ``myTfodProcessorBuilder`` was not created; the build was
-performed directly on ``myTfodProcessor``.  The Builder pattern allows the "dot"
-methods to be chained in a single Java statement ending with ``.build()``.
+The Builder is going to look a little different depending on if you are using
+the **Color Sensor** or the **Color Locator**. For more information, see the
+:doc:`Color Processing Documentation </color_processing/index>`.
 
 Enabling and Disabling Processors
 ---------------------------------

docs/source/apriltag/vision_portal/visionportal_previews/visionportal-previews.rst

@@ -4,7 +4,7 @@ VisionPortal Previews
 Introduction
 ------------
 
-Managing AprilTag and TFOD performance is greatly enhanced with visual
+Managing AprilTag and Color Processing performance is greatly enhanced with visual
 feedback of the camera’s view.
 
 .. figure:: images/040-RC-preview-2-webcams-Moto-e4.png
@@ -26,13 +26,13 @@ LiveView refers only to the **Robot Controller** preview (example shown above).
 It’s completely separate from **DS Camera Stream**, which still operates
 normally even if LiveView is stopped (manually or automatically).
 
-Instructions for viewing DS Camera Stream are shown at
-:ref:`ftc-docs <hardware_and_software_configuration/configuring/configuring_external_webcam/configuring-external-webcam:image preview>`.
+Instructions for viewing DS Camera Stream are shown
+:ref:`here <hardware_and_software_configuration/configuring/configuring_external_webcam/configuring-external-webcam:image preview>`.
 
 Camera Stream uses its own frame collection process, which naturally still
 requires the camera/pipeline status to be ``STREAMING``. Disabling the stream
 will prevent the DS preview. Camera status is covered at the **Managing CPU and
-Bandwidth** page, and the **VisionPort Camera Controls** page.
+Bandwidth** page, and the **VisionPortal Camera Controls** page.
 
 Side Note: For SDK 8.2, “LiveView” became the new universal name for the
 RC preview. There remain two instances of old names: 
@@ -62,39 +62,14 @@ do affect the displayed image and the actual recognitions.
 During Camera Stream, manual adjustments to Camera Controls cannot be
 made in real time (with visible feedback) since gamepads are disabled.
 
-Thus teams wanting to optimize AprilTag or TFOD recognitions with Camera
+Thus teams wanting to optimize AprilTag or Color Processing recognitions with Camera
 Controls should use ``scrcpy`` or an HDMI monitor. Doing this via Camera
 Stream (“back and forth”) will be less effective and less efficient.
 
 More information is available at the **VisionPortal Camera Controls** page, and
 at the 
 :ref:`Webcam Control tutorial <programming_resources/vision/webcam_controls/index:webcam controls>`.
 
-Aspect Ratios in Previews
--------------------------
-
-Here’s a Control Hub’s LiveView (via ``scrcpy``) of TFOD recognitions:
-
-.. figure:: images/050-CH-TFOD-preview-grey-bands.png
-   :width: 75%
-   :align: center
-   :alt: Gray Band Aspect Ratio Mismatch
-
-   LiveView demonstrating Grey Bands from Aspect Ratio mismatch
-
-The **greyed bands** at top and bottom are from the **mismatch of aspect
-ratios**:
-
--  4:3 for camera (640x480)
-
--  16:9 for TFOD (per model training)
-
-Both of these ratios are set as defaults, hidden from the user in some
-Sample OpModes. Only the non-greyed region is eligible for TFOD
-recognitions.
-
-Note that the TFOD annotations (text) extend beyond the image.
-
 BIG Previews
 ------------
 
@@ -130,7 +105,7 @@ is rather high.
 
 Note that viewing the video stream from the same orientation as the
 statistics text box will show you the orientation of the stream passed
-to the AprilTag and/or TFOD processors.
+to the AprilTag and/or Color Sensor/Locator processors.
 
 Also note that for RC phone cameras, the LiveView preview is rotated
 (independent of rotation enum) such that the preview is the way you

docs/source/programming_resources/vision/vision_overview/images/33-circleFit-LiveView.png

@@ -14,7 +14,7 @@ computer vision technologies:
    points for autonomous navigation and for assisted navigation and
    identification of points of interest on a game field.
 
-   -  Each season, FIRST provides 2D image tagets that can be used as
+   -  Each season, *FIRST* provides 2D image tagets that can be used as
       navigational reference points.
    -  If the AprilTag system recognizes an AprilTag image, it provides 
       very accurate pose information (assuming the camera used has 
@@ -23,21 +23,20 @@ computer vision technologies:
    -  A robot can use this information to navigate autonomously on the
       field.
 
-2. TensorFlow Lite - `TensorFlow
-   Lite <https://ai.google.dev/edge/litert>`__ is a lightweight version
-   of Google’s `TensorFlow <https://www.tensorflow.org>`__ *machine
-   learning* technology that is designed to run on mobile devices such
-   as an Android smartphone.
-
-   -  Each season FIRST creates a TensorFlow *inference model* that can
-      be used to “look” for specific game elements.
-   -  If TensorFlow recognizes an object, it returns location info about
-      the identified object.
-   -  A robot can use this location information to navigate to the
+2. Color Processing - 
+   :doc:`Color Processing </color_processing/index>` is a
+   feature in the *FIRST* Tech Challenge SDK that provides the ability
+   to process colors using `OpenCV <https://opencv.org/>`__.
+
+   -  Color Sensor can detect the exact color in an image, which can
+      help determine what is in front of a robot.
+   -  Color Locator can look for a specific color and return information
+      about the size, shape and location of the color in the camera frame.
+   -  A robot can use this information to navigate to the
       recognized object.
 
-TensorFlow vs AprilTags
------------------------
+AprilTags vs Color Processing
+-----------------------------
 
 AprilTag Advantages
 ~~~~~~~~~~~~~~~~~~~
@@ -73,53 +72,48 @@ AprilTag Disadvantages
 
    AprilTags not in Tag Library detected, but no pose data available
 
-TensorFlow Advantages
-~~~~~~~~~~~~~~~~~~~~~
+Color Processing Advantages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
--  TensorFlow learns how to recognize target objects, not just specific
-   images.
+-  Color Processing looks for colors, not specific images.
 
    -  Recognizes objects in spite of different backgrounds.
-   -  Recognizes objects in varied lighting conditions.
+   -  Recognizes objects both up close and further away.
    -  Recognizes objects even when objects are oriented in different
       positions.
 
--  TensorFlow can be taught how to distinguish between similar looking
-   (but still distinct) objects, such as a Stone and a Skystone from the
-   2019-2020 challenge.
+-  Pre-defined colors are included in the *FIRST* Tech Challenge SDK
+   that have already been tested on season-specific game elements.
 
-TensorFlow Disadvantages
-~~~~~~~~~~~~~~~~~~~~~~~~
+Color Processing Disadvantages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
--  Training a TensorFlow model can be daunting at first. It requires a
-   lot of understanding of the TensorFlow training metrics and behaviors.
--  TensorFlow is computationally intensive and has a low detection rate
-   (an estimated 1 to 2 detections per second).
--  If TensorFlow recognizes an object in its field of view, it only
+-  Color Processing can be sensitive to different lighting conditions.
+-  If Color Processing recognizes an object in its field of view, it only
    returns location information on where the target object is within its
    field of view.
 
-.. figure:: images/tfodIndirect.jpg
+.. figure:: images/82-targeting.png
    :align: center
    :width: 75%
 
-   TensorFlow can recognize actual objects (and not just 2D image targets).
+   Color Processing can recognize actual objects (and not just 2D image targets).
 
-.. figure:: images/tfodDual.jpg
+.. figure:: images/33-circleFit-LiveView.png
    :align: center
    :width: 75%
 
-   TensorFlow can be taught to distinguish between similar looking objects.
+   Color Processing can recognize the shape of the object.
 
 Which Should I Use?
 ~~~~~~~~~~~~~~~~~~~
 
-The choice of whether to use TensorFlow Lite or AprilTags will be
+The choice of whether to use AprilTags or Color Processing will be
 influenced by factors such as distance-to-target, lighting, accuracy
 required, camera placement and etc.. 
 
 If the object and tag can always be guaranteed to be in a specific orientation
 and the tag fully visible, AprilTags are likely the best solution. However,
 if the object does not belong to you or a tag is not able to be physically 
-placed on the object, TensorFlow can be a good solution.
+placed on the object, Color Processing can be a good solution.