added content for vision tutorials.

Computer-Vision-Overview.md

@@ -0,0 +1,49 @@
+## Introduction
+The FTC control system software has built-in support for two computer vision technologies:
+
+1. Vuforia - [Vuforia](https://www.ptc.com/en/products/augmented-reality/vuforia) is PTC's _augmented reality_ technology.  Teams can use Vuforia to identify two-dimensional (2D) _image targets_ and use these targets as reference points for autonomous navigation.
+    - Each season, FIRST provides 2D image tagets that can be used as navigational reference points.
+    - If Vuforia recognizes an image target, it provides very accurate information about the robot's location relative to the target.
+    - A robot can use this information to navigate autonomously on the field.
+    - Special Vuforia image targets, known as _VuMarks_, can also be used to encode hidden game information on the field.
+
+2. TensorFlow Lite - [TensorFlow Lite](https://www.tensorflow.org/lite/) 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 recognized object.
+    - Note that in the FTC control system, the TensorFlow software uses the Vuforia software to "grab" images from the camera while it is looking for or tracking game elements. 
+        * TensorFlow only uses Vuforia to get the camera images.  
+        * TensorFlow does all its own object detection and tracking independently, without any other help from Vuforia.
+
+## TensorFlow vs Vuforia
+### Vuforia Advantages
+* Very efficient with a fast detection rate (estimated 15 to 20 detections per second).
+* Provides accurate, relative location of robot to target in field coordinates.
+### Vuforia Disadvantages
+* Only looks for 2D image targets.
+* Image targets must have a large amount of detail and uniqueness in order to be accurate and useful.
+* Vuforia must see the image target clearly in order to calculate location to the target.
+
+<p align="center">[[/images/Using-Computer-Vision/vuforiaDirectIndirect.jpg]]<p>
+<p align="center">Vuforia provides accurate location info, but requires a clear view of the image target.<p>
+
+### TensorFlow Advantages
+* TensorFlow learns how to recognize target objects, not just specific images.
+    - Recognizes objects in spite of different backgrounds.
+    - Recognizes objects in varied lighting conditions.
+    - 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.
+### TensorFlow Disadvantages
+* 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 returns location information on where the target object is within its field of view.
+
+<p align="center">[[/images/Using-Computer-Vision/tfodIndirect.jpg]]<p>
+<p align="center">TensorFlow can recognize actual objects (and not just 2D image targets).<p>
+
+<p align="center">[[/images/Using-Computer-Vision/tfodDual.jpg]]<p>
+<p align="center">TensorFlow can be taught to distinguish between similar looking objects.<p>
+
+### Which Should I Use?
+The choice of whether to use TensorFlow Lite or Vuforia will be influenced by factors such as distance-to-target, lighting, accuracy required, camera placement and etc..  
+
+In the 2019-2020 challenge, the Skystone game element can be identified and tracked using either technology.  Vuforia requires that the 2D image target on the face of the Skystone be visible for detection and tracking.  TensorFlow can also recognize Stones in the 2019-2020 challenge in addition to the Skystone elements.  Either can be used to identify and track Skystones during a match.

TensorFlow-for-Blocks.md

@@ -0,0 +1,370 @@
+## Background
+FTC robots have many ways to autonomously navigate the game field. This tutorial introduces TensorFlow Lite, a software tool that can identify and track certain game elements as 3D objects. TensorFlow Lite uses input from Vuforia, a software tool (described in a separate tutorial) that processes 2D camera images.
+
+These two tools combine several high-impact technologies: vision processing, machine learning, and autonomous navigation. Awareness of this software can spark further interest and exploration by FTC students as they prepare for future studies and careers in high technology.
+
+## TensorFlow Introduction
+[TensorFlow Lite](https://www.tensorflow.org/lite/) 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. Support for TensorFlow Lite was introduced to FTC in 2018.  For the 2019-2020 FTC game, SKYSTONE, a trained _inference model_ was developed to recognize the Stone and Skystone game pieces.
+
+This Tensorflow inference model has been integrated into the FTC software and can be used to identify and track these game pieces during a match.  The software can report the object’s location and orientation relative to the robot’s camera.  This allows autonomous navigation, an essential element of modern robotics.
+
+## Important Note on Phone Compatibility
+The TensorFlow Lite technology for object detection works on all FTC approved phones except the ZTE Speed.  TensorFlow Lite requires Android 6.0 (Marshmallow) or higher.  The REV Expansion Hub and REV Control Hub both support using this technology.
+
+For Blocks programmers using an older Android phone that is not running Marshmallow or higher, the TensorFlow Object Detection (TFOD) category of Blocks will automatically _be missing_ from the Blocks design palette.
+
+## Sample Op Mode for Blocks
+
+This tutorial describes the Op Modes provided in the FTC Blocks sample menu for TensorFlow Object Detection (TFOD).
+
+On a laptop connected via Wifi to the Robot Controller (RC) phone or REV Control Hub, at the Blocks screen, click Create New Op Mode.  Type a name for your example program, and choose the appropriate TensorFlow sample.  If using the **RC phone’s camera**, choose the first Sample shown below.  
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0010-create-sample.png|Create sample.]]<p>
+
+If using a **webcam**, with REV Expansion Hub or REV Control Hub, choose the second Sample.  
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0020-create-sample-webcam.png|Create webcam sample.]]<p>
+
+Then click OK to enter the programming screen.
+
+Your new Op Mode will appear on the Blocks programming screen, including the Blocks needed for TensorFlow Object Detection (TFOD).
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0030-sample-open-half.png|Sample open.]]<p>
+
+This Op Mode has a simple structure.  The first section of Blocks is the main program, followed by one _function_.  A _function_ is a named collection of Blocks to do a certain task.  This organizes and reduces the size of the main program, making it easier to read and edit.  In Java these functions are called <u>methods</u>.
+
+This program shows various Blocks for basic use of TensorFlow.  Other related Blocks can be found in the TensorFlow Object Detection folder, under the Utilities menu at the left side.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0040-TFOD-menu.png|TFOD menu.]]<p>
+
+The heading ‘Optimized for SKYSTONE’ contains many of the game-specific Blocks in this sample.  The other heading 'Recognition' provides a variety of available TFOD variables or data fields.
+
+ ## Vuforia Initialization
+
+Using TensorFlow requires the background use of Vuforia, because they work together to provide TFOD results.
+ 
+The first section of an Op Mode is called initialization.  These commands are run one time only, when the INIT button is pressed on the Driver Station (DS) phone.   Besides the Telemetry messages, this section has only three actions: <u>initialize</u> Vuforia (specify its settings), <u>initialize</u> TFOD (specify its settings), and <u>activate</u> TFOD (turn it on).  This "init" section ends with the command waitForStart.
+
+The first Block initiates Vuforia, which will provide the camera's image data to TensorFlow.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0052-Vuforia-init-monitor-false.png|Vuforia initialize without monitoring.]]<p>
+
+When using the **RC phone camera**, the FTC Vuforia software has 11 available settings to indicate your preferred usage and the camera’s location.  Set Camera Monitoring to <i>false</i>; the Vuforia display is not needed since TensorFlow offers its own monitoring display.  If you definitely want to also monitor Vuforia, try setting this to <i>true</i>; some RC phones have trouble displaying both videos together.
+
+This example uses the phone’s BACK camera, requiring the phone to be rotated -90 degrees about its long Y axis.  For this sample Op Mode, the RC phone is used in Landscape mode.
+
+**Important Note:** Although the phone rotation values are important if you are planning to use the Vuforia software for image detection and tracking, these rotation values are not used by the TensorFlow software.  TensorFlow only uses the Vuforia software to provide the stream of camera images.  When using TensorFlow, it is more important that when you initialize the TensorFlow library, the camera is oriented in the mode (portrait or landscape) that you want to use during your op mode run (see the section entitled [Important Note Regarding Image Orientation](TensorFlow-for-Blocks#important-note-regarding-image-orientation) below).
+
+When using a **webcam**, Vuforia has 12 available settings.  The RC cameraDirection setting is replaced with two others related to the webcam: its configured name, and an optional calibration filename.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0062-Vuforia-webcam-init-monitor-false.png|Vuforia webcam init without monitoring.]]<p>
+
+Also for webcams, set ‘Camera Monitoring’ to <i>false</i>; the Vuforia display is not needed since TensorFlow offers its own monitoring display.  If you definitely want to also monitor Vuforia, try setting this to <i>true</i>; some RC phones have trouble displaying both videos together.
+
+For Control Hubs, ‘Camera Monitoring’ would enable display on an external monitor or video device plugged into the HDMI port (not allowed in competition).
+
+If ‘Camera Monitoring’ is used, the ‘Feedback’ setting can display AXES, showing Vuforia’s X, Y, Z axes of the reference frame local to the image.
+
+‘Translation’ and 'rotation' specify the phone’s position and orientation on the robot.  These allow Vuforia-specific navigation and are not used for TensorFlow Object Detection (TFOD).
+
+ ## TensorFlow Initialization
+
+The next Block initializes the TFOD software.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0070-TFOD-initialize.png|TFOD initialize.]]<p>
+
+The key setting is the minimum Confidence, the minimum level of certainty required to declare that a <u>trained object</u> has been recognized in the camera's field of view.  A higher value (but under 100%) causes the software to be more selective in identifying a trained object, either a Stone or a Skystone for the 2019-2020 FTC game.  Teams should adjust this parameter for a good result based on distance, angle, lighting, surrounding objects, and other factors.
+
+Note that for the 2019-2020 FTC Game, people have reported that using a lower confidence threshold (on the order of 50% or so) results more accurate detections when the game elements (Stones and Skystones) are placed side-by-side.
+
+The Object Tracker parameter set to <i>true</i> means the software will use an object tracker in addition to the TensorFlow interpreter, to keep track of the on-screen locations of detected objects. The object tracker <u>interpolates</u> object recognitions for results that are smoother than using only the TensorFlow interpreter.
+
+The Camera Monitoring parameter opens a camera preview window on the RC phone, or enables a webcam preview through the Control Hub's HDMI port on an external monitor or device (not allowed in competition).  This video preview shows the camera or webcam image with superimposed TensorFlow data, including bounding boxes for detected objects.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0100-RC-TFOD-preview.png|TFOD preview.]]<p>
+
+A static preview is also available on the DS screen, with the REV Expansion Hub and the REV Control Hub.  To see it, choose the main menu’s Camera Stream when the Op Mode has initialized (but not started).  Touch to refresh the image as needed, and select Camera Stream again to close the preview and continue the Op Mode.  This is described further in the tutorial [Using an External Webcam with Control Hub](Using-an-External-Webcam-with-Control-Hub).
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0110-DS-TFOD-preview-half.png|DS TFOD preview.]]<p>
+
+In the TensorFlow camera monitor window, the confidence level for a detected target appears near the bounding box of the identified object (when Object Tracker is enabled). For example, a value of 0.95 indicates a 95% confidence that the object has been identified correctly.
+
+The origin of the coordinate system is in the upper left corner of the image. The horizontal (X) coordinate value increases when moving from left to right. The vertical (Y) coordinate value increases when moving from top to bottom.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0130-RC-axis-system.png|RC axis system.]]<p>
+
+When an object is identified by TensorFlow, the FTC software can provide 'Left', 'Right', 'Top' and 'Bottom' variables associated with the detected object. These values, in units of <u>pixel coordinates</u>, indicate the location of the left, right, top and bottom boundaries of the detection box for that object.
+
+This and other information about the detected object can be used to navigate towards the object, such as a Stone or Skystone.  The values are available from the Blocks menu, under the Recognition submenu described above.  This robot driving action is not part of the sample Op Mode, but is described below in "Navigation Example".
+
+## Important Note Regarding Image Orientation
+The system interprets images based on the phone's orientation (Portrait or Landscape) at the time that the TensorFlow object detector was created and initialized. In our example, if you execute the TensorFlowObjectDetection.initialize block while the phone is in Portrait mode, then the images will be processed in Portrait mode.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/tfodDSPortrait.png]]<br/>If you initialize the detector in Portrait mode, then the images are processed in Portrait mode.<p>
+
+The "Left" and "Right" values of an object's bounding box correspond to horizontal coordinate values, while the "Top" and "Bottom" values of an object's bounding box correspond to vertical coordinate values.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/tfodBoundaries.png]]<br/>The "Left" and "Top" boundaries of a detection box when the image is in Portrait mode.<p>
+
+If you want to use your smartphone in Landscape mode, then make sure that your phone is in Landscape mode when the TensorFlow object detector is initialized.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/tfodLandscape.png]]<br/>The system can also be run in Landscape mode.<p>
+
+If the phone is in Landscape mode when the object detector is initialized, then the images will be interpreted in Landscape mode.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/tfodBoundariesLandscape.png]]<br/>The "Left" and "Top" boundaries of a detection box when the image is in Landscape mode.<p>
+
+Note that Android devices can be locked into Portrait Mode so that the screen image will not rotate even if the phone is held in a Landscape orientation.  If your phone is locked in Portrait Mode, then the TensorFlow object detector will interpret all images as Portrait images.  If you would like to use the phone in Landscape mode, then you need to make sure your phone is set to "Auto-rotate" mode.  In Auto-rotate mode, if the phone is held in a Landscape orientation, then the screen will auto rotate to display the contents in Landscape form.
+
+For webcam users, the images should be provided in landscape mode.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/autorotate.png]]<br/>Auto-rotate must be enabled in order to operate in Landscape mode.<p>
+
+## TensorFlow Activation
+
+Lastly, in the main program’s initialization section, there remains only the command to activate TensorFlow Object Detection (TFOD).
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0160-TFOD-initialize.png|TFOD initialize.]]<p>
+
+This starts the TensorFlow software and opens or enables the Monitoring images if specified.  It also enables the static preview on the DS phone.  The REV Control Hub offers a video feed only through its HDMI port, not allowed during competition.
+
+The video and static previews both show TensorFlow data superimposed on the image, including any boundary boxes and labels for recognized objects.  The colors of the boxes, dots and squiggly lines are not relevant for FTC interpretation.
+
+## Run Section
+
+The ‘run’ section begins when the Start button (large arrow icon) is pressed on the DS phone.
+ 
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0170-waitForStart.png|Start.]]<p>
+
+The first IF structure encompasses the entire program, to ensure the Op Mode was properly activated.  This is an optional safety measure.
+
+Next the Op Mode enters a Repeat loop that includes all the TFOD-related commands.  In this Sample, the loop continues while the Op Mode is active, namely until the Stop button is pressed. 
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0180-repeat-while.png|Repeat while.]]<p>
+
+In a competition Op Mode, you will add other conditions to end the loop.   Examples might be: loop until TensorFlow finds what you seek, loop until a time limit is reached, loop until the robot reaches the detected object.  After the loop, your main program will continue with other tasks.
+
+Inside the loop, the program checks whether TensorFlow has found specific trained objects.  This is done with a single line of code.  To understand this first command, read it from right to left.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0190-get-Recognitions-1.png|get Recognitions 1.]]<p>
+
+The FTC software contains a TFOD method called ‘getRecognitions'.  This is the central task; looking for trained objects using image data provided by Vuforia.  The recognized objects, if any, might be distant (small), at an angle (distorted), in poor lighting (darker), etc.   In any case, the ‘getRecognitions' method provides, or <u>returns</u>, various pieces of information from its analysis.
+ 
+That returned information is passed to the left side of the command line.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0200-get-Recognitions-2.png|get Recognitions 2.]]<p>
+ 
+This Blocks Op Mode uses a Variable called 'recognitions'.  This is a special variable holding multiple pieces of information, not just one number, or one text string, or one Boolean value.  The yellow-circled command <u>sets</u> that variable to store the entire group of results passed from the TFOD method.  You can think of ‘recognitions’ by an informal name such as “all recognitions in this evaluation”, or just “allRecognitions”.
+
+In Blocks, 'recognitions' is a type of variable called a List.  In Java it would be called an array or vector.  A List contains some number of items, and thus has a 'length'.  In this case, 'length' is the number of detected objects returned by the TFOD method.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0210-IF-no-recognitions.png|IF no recognitions.]]<p>
+
+If the 'length' of 'recognitions' is zero, the Op Mode builds a Telemetry message (line of text for the DS phone) that no trained objects were found in the current cycle of the Repeat loop.
+
+Otherwise, or ELSE, one or more trained objects were found.  The number of objects is not known in advance, and the Op Mode must inspect each item one by one.
+
+## Evaluation with FOR loop
+
+This Blocks OpMode uses a <u>FOR loop</u> to cycle through the list called 'recognitions'.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0220-ELSE-recognitions-1.png|ELSE recognitions 1.]]<p>
+
+A FOR loop is a special type of loop that processes a list of items in order, with or without a <u>counter</u>.  Here a counter is used for Telemetry only.  It is a variable called 'index', set to zero before entering the loop.
+
+The first time through the FOR loop, the Op Mode examines the first item in the list called 'recognitions'.  This first item is itself a special variable called 'recognition', containing multiple pieces of data about that first detected object.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0230-ELSE-recognitions-2.png|ELSE recognitions 2.]]<p>
+
+To clarify: 'recognition' contains data about **one object**, while 'recognitions' is a **list of all items**, each called 'recognition'.  Unique names or numbering is not needed here, since the FOR loop handles only one set of recognition data at a time.
+
+If the FOR loop cycles a second time, the Op Mode examines the data for only the second recognition.  Likewise for a third, and so on.  When every item in the list 'recognitions' has been processed, the FOR loop ends and the Op Mode continues.
+
+Next, still inside the FOR loop, this Op Mode uses a Function called 'displayInfo' to show the data for the current recognition.  As noted above, a Function is a named collection of Blocks to do a certain task.  In Java, functions are called <u>methods</u>.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0240-ELSE-recognitions-3.png|ELSE recognitions 3.]]<p>
+
+The Function 'displayInfo' appears below the main program.  The above yellow-circled <u>call</u> to the Function needs an input or <u>parameter</u>.  The parameter, named simply 'i', is displayed by the Function along with the recognition data, allowing the user to distinguish among multiple identified objects.
+
+> **Programming tip:** when building a new Function in Blocks, click the blue gear icon to add one or more ‘input names’ or parameters.
+
+The parameter 'i' receives the value of the loop's counter, called 'index'.  For the first cycle through the FOR loop, 'index' is zero, so 'i' is zero, and the number 0 will appear with the first set of recognition data.  A description of the Function 'displayInfo' is provided later in this tutorial.
+
+The last step of the FOR loop is to <u>increment</u> the counter 'index'.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0250-ELSE-recognitions-4.png|ELSE recognitions 4.]]<p>
+
+> **Programming note:** In this Op Mode, incrementing 'index' does not **cause** this FOR loop to examine the next item in the list of recognitions.  It simply keeps track of the automatic process of cycling through the entire list, for Telemetry.  In Java, a traditional FOR loop typically does use the counter for cycling.
+
+Now the current cycle of the FOR loop is complete.  If there is another recognition to process, the program returns to the top of the FOR loop.  If not, the program continues after the FOR loop.
+
+## Completing the Repeat loop
+
+But the program is still looping inside the green Repeat loop.  After collecting all the recognitions in this Repeat loop cycle, the last action of the Repeat loop is to provide, or <u>update</u>, the DS phone with all Telemetry messages built during this loop cycle.  Such messages might have been created in the main program or in a Function that was used, or <u>called</u>, during the loop.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0260-Telemetry-update.png|Telemetry update.]]<p>
+
+Further below is an example of Telemetry displayed by this command, following the description of the 'displayInfo' Function.
+
+Now the Repeat loop begins again at the top, running the TFOD software to look for the trained objects.  The FOR loop is processed with each Repeat cycle.  This overall Repeat cycle continues, with updated Telemetry, until the Op Mode is no longer active (user presses Stop).
+
+This example Op Mode ends by turning off the FTC TFOD software.  When your competition Op Mode is finished using TFOD, immediate deactivation will free up computing resources for the remainder of your program.
+ 
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0270-deactivate-TFOD.png|deactivate TFOD.]]<p>
+
+## Function displayInfo
+
+This sample Op Mode uses one function, called 'displayInfo'.  Recall that this function was given, or <u>passed</u>, a parameter called 'index'.  This contains the counting number of the recognition now being processed by the FOR loop.  This counter is passed to the function's internal parameter called 'i'.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0300-displayInfo.png|displayInfo.]]<p>
+
+> **Programming tip:** in Blocks, function’s parameters are automatically created as <u>Variables</u>.  This makes its contents available to use inside the function and elsewhere.
+  
+This function only builds Telemetry messages for display on the DS phone.  The first message gives the name of the identified object, using a <u>method</u> called 'Label', in a TFOD class instance called 'Recognition'.  
+ 
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0310-recognition-label.png|recognition label.]]<p>
+
+That TFOD method uses a multi-element parameter (coincidentally) called 'recognition' (in green), which is passed the data from the FOR loop's current identified object.  As discussed above, that group of data is the variable also called 'recognition' (in purple); you may consider its informal name to be "currentRecognitionData".
+
+> **Programming note:** the sole purpose of the Label method is to extract, or <u>get</u>, the text field with the designated name of this trained object.  Namely, "Stone" or "Skystone" for the 2019-2020 game.
+
+The next message gives the pixel coordinates of the left edge (X value) and top edge (Y value) of the bounding box around the identified object.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0320-recognition-left-top.png|recognition left top.]]<p>
+
+The method 'Left' extracts or <u>gets</u> the left edge value from the current recognition data.  The method 'Top' gets the top edge value.
+
+> **Programming tip:** the 'create text' Block allows multiple text items to be joined as a single string of text.  Click the blue gear icon to select how many text items are desired.
+
+The last message gives the pixel coordinates of the right edge (X value) and bottom edge (Y value) of the bounding box around the identified object.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0330-recognition-right-bottom.png|recognition right bottom.]]<p>
+
+The Function does **not** send the built messages to the DS phone using the Telemetry.update command.  If it did, each detected item in the FOR loop would erase the previous message.  Instead the 'update' command appears after the FOR loop to display all recognitions, each with its 'index' counter.
+
+## Running the Op Mode
+
+Select the Op Mode and press INIT.  If the DS preview is opened, it must be closed using the Camera Stream menu option.  After this, pressing the Start button begins the looping, with Telemetry messages appearing on the DS phone.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0400-DS-TFOD-recognition-circle-half.png|DS TFOD recognition.]]<p>
+
+In this example, the camera is pointed at a single Stone.  Its bounding box has a left edge at 290 pixels, top edge at 387 pixels, right edge at 635 pixels, and bottom edge at 844 pixels.
+
+As the camera moves, the TFOD results will update with varying pixel coordinates, and possibly finding or losing recognitions.  This process can be viewed on the RC screen or HDMI monitor, if used, but your Op Mode can react only to the data provided by the TFOD software.
+
+Other available data includes: confidence level, width of bounding box, height of bounding box, width of overall screen image (typically 1280 pixels), height of overall screen image (typically 720 pixels), and the estimated angle to the object.  The <u>getter</u> methods for this data can be found in the Recognitions section of the TensorFlow Object Detection menu, under Utilities.
+
+## Sample Previews and Data
+
+Stones and Skystones may appear together in the camera's view.  Here is an example preview on the RC phone, followed by a close-up.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0450-RC-screenshot-Stones.png|RC screenshot Stones.]]<p>
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0452-RC-screenshot-Stones-zoom.png|RC screenshot Stones zoom.]]<p>
+
+The FTC software displays the Label and Confidence in very small characters at the bottom left corner of the bounding box.  This information is more readily available with Telemetry as shown below.  The box colors vary randomly, to distinguish one recognition from another.
+
+A static preview is also available on the DS phone, for REV Expansion Hubs and REV Control Hubs.  Here is the DS preview of the same camera view shown above on the RC phone, with its close-up.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0460-DS-screenshot-preview-half.png|DS screenshot preview.]]<p>
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0462-DS-screenshot-preview-zoom.png|DS screenshot preview zoom.]]<p>
+
+The DS and RC previews provide the same TFOD graphics and information.
+
+After closing the DS preview and pressing the Start button, this sample Op Mode provides Telemetry.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0470-DS-screenshot-data-half.png|DS screenshot data.]]<p>
+
+Here the Skystone is the first recognition (index = 0) in the List called 'recognitions'.  Its bounding box X values span 314 to 626 (width of 312 pixels), and its Y values span 145 to 376 (height of 231 pixels).
+
+The Stone is the second recognition (index = 1) in the List called 'recognitions'.  Its bounding box X values span 16 to 346 (width of 330 pixels), and its Y values span 154 to 389 (height of 235 pixels).
+
+These figures seem to agree with the preview images, with high confidence levels, and can be used by your Op Mode for analysis and robot action.
+
+## Testing and Using TFOD
+
+Learn and assess the characteristics of this navigation tool.  You may find that certain distances, angles, and object groupings give better results.  Compare this to the Skystone 2D image recognition provided by Vuforia alone, described in a separate tutorial.
+
+You may also notice some readings are slightly erratic or ‘jumpy’, like the raw data from many advanced sensors.  An FTC programming challenge is to smooth out such data to make it more useful.  Ignoring rogue values, simple average, moving average, weighted average, PID control, and many other methods are available.  It’s also possible to combine TFOD results with other sensor data, for a blended source of navigation input.
+
+This is the end of reviewing the sample Op Mode.  With the data provided by TFOD, your competition Op Mode can autonomously navigate on the field.  The next section gives a simple example.
+
+## Navigation Example
+
+For illustration only, consider a simplified SKYSTONE navigation task.  The robot is 24 inches from the Red Alliance perimeter wall, front camera facing the Blue Alliance side, beside the Red Skybridge and just beyond the last Stone in the undisturbed Quarry. **The task: drive sideways (to the left) until a Skystone is centered in the camera image.**
+
+The sample Op Mode looped until the DS Stop button was pressed.  Now the Op Mode will contain driving, and the main loop must end when the center of the Skystone bounding box reaches the center of the image.
+
+> **Programming tip:** Plan your programs first using plain language, also called <u>pseudocode</u>.  This can be done with Blocks, by creating empty Functions.  The name of each Function describes the action.
+
+> **Programming tip:** Later, each team member can work on the inner details of a Function.  When ready, Functions can be combined using a laptop’s Copy and Paste functions (e.g. Control-C and Control-V).
+
+A very simple pseudocode approach might look like this: 
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0500-pseudo-first.png|Pseudocode simple.]]<p>
+
+The central task 'Analyze Camera Image' can be expanded to several smaller tasks.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0510-pseudo-analyze-half.png|Pseudocode analyze.]]<p>
+
+The sample Op Mode shows that 'Get TFOD Image Data' is done with one TFOD Blocks command.  The old variable 'recognitions' now has a slightly more descriptive name 'allRecognitions', as suggested in the tutorial above.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0520-get-recognitions.png|Get recognitions.]]<p>
+
+The next question is whether TFOD found any recognitions, including a Skystone.  If so, get some Skystone position data.  Here are steps used by the sample Op Mode, except the old variable 'recognition' now has a slightly more descriptive name 'currentRecognitionData'.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0530-analyze-recognitions.png|Analyze recognitions.]]<p>
+
+The FOR loop cycles through the list of all recognitions, processing one at a time.  Inside that loop, get the bounding box position only if the current item is a Skystone.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0540-get-box-data.png|Get box data.]]<p>
+
+The X center position of any recognized Skystone is easily calculated as Left edge plus (Width / 2), measured in pixels.
+
+Putting these pieces together, here is the pseudocode developed so far.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0550-central-process.png|Central process.]]<p>
+
+The Repeat loop should end when SkystoneCenter has reached the center of the camera's image.  The robot is moving to the left, so the Skystone will enter the camera's view from the left.  Its X position values will start low and increase.  The X-axis center of the overall image is a constant number, simply 1/2 of the image's known width.  So the beginning of the Repeat loop can look like this:
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0560-loop-to-target.png|Loop to target.]]<p>
+
+This presumes the image width was previously verified to be 1280 pixels.
+
+The center of the Skystone box is initialized to X=0 pixels, expecting the box to enter from the left side of the camera image.  This will be updated inside the loop, as soon as a Skystone is recognized.  Until then, the initial value of X=0 will keep the robot driving sideways.
+
+## Program Completion
+
+When completed, this pseudocode should place the robot's camera directly in front of the first Skystone found.  Of course certain tasks must be done in the initialize section, before waitForStart.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0580-pseudo-initialize.png|Pseudocode initialize.]]<p>
+
+And don't forget to turn off TFOD when not being used.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0590-pseudo-deactivate.png|Pseudocode deactivate.]]<p>
+
+For safety, all Repeat loops need a second condition, "while opModeIsActive".  This allows safe recovery from problems or <u>exceptions</u>.  Also add Telemetry inside the FOR loop, similar to the sample Op Mode.
+
+Putting all this together, here is a possible pseudocode solution.
+
+<p align="center">[[/images/Using-Computer-Vision/TensorFlow-for-Blocks/0600-pseudo-complete.png|Pseudocode complete.]]<p>
+
+Always add many short (blue Block) and detailed (in-Block) comments, to document your work for others and yourself.  This has a very high priority in the programming world.
+
+> **Programming tip:** action loops should also have <u>safety time-outs</u>.  Add another loop condition, “while ElapsedTime.Time is less than your time limit”.  Otherwise your robot could sit idle, or keep driving and crash.
+
+> **Programming tip:** optional to set a <u>Boolean</u> true/false variable indicating that the loop ended from a time-out, then take action accordingly.
+
+> **Programming tip:** Right-click on a Logic Boolean Block (AND, OR) and choose External Inputs, for a vertical arrangement of Repeat loop conditions as shown in the pseudocode above.  Also available for Logic Compare Blocks (=, <, >).
+
+## Summary
+
+This example showed how to navigate by using several pieces of information generated by TFOD, including the Label of a recognized object, and its Left edge and Width.  As noted in this tutorial, many other data items are also available.
+
+Overall, TFOD applies vision processing and machine learning to allow autonomous navigation relative to trained objects.  If the field position of the recognized object is known, TFOD can also help with general navigation, not relying only on the robot's frame of reference.
+
+<i>Questions, comments and corrections to: westsiderobotics@verizon.net</i>
+
+## Acknowledgements
+A special Thank You! is in order for [Chris Johannesen](mailto:westsiderobotics@verizon.net) of Westside Robotics (Los Angeles) for putting together this tutorial.  Thanks Chris!

Using-Computer-Vision-in-FTC.md

@@ -0,0 +1,10 @@
+Teams who compete in the _FIRST_ Tech Challenge (FTC) can use computer vision (CV) to help their robots navigate autonomously during a match.  The FTC software can "grab" images from a camera and use these images to look for and track objects on the field.  
+
+This tutorial provides information about how you can use the computer vision libraries that are included with the FTC control system software:
+
+* [Vuforia for Blocks](Vuforia-for-Blocks) - This section demonstrates how you can use Vuforia and Blocks to detect and track image targets in the _FIRST_ Tech Challenge.
+* [Vuforia for Java](Vuforia-for-Java) - This section demonstrates how you can use Vuforia and Java to detect and track image targets in the _FIRST_ Tech Challenge.
+* [Computer Vision Overview](Computer-Vision-Overview) - This section provides a basic overview of the CV technologies that are included with the FTC software.  It also compares the strengths and weaknesses of the respective technologies.
+* [TensorFlow for Blocks](TensorFlow-for-Blocks) - This section demonstrates how you can use TensorFlow and Blocks to detect and track game elements in the _FIRST_ Tech Challenge.
+* [TensorFlow for Java](TensorFlow-for-Java) - This section demonstrates how you can use TensorFlow and Java to detect and track game elements in the _FIRST_ Tech Challenge.
+

Vuforia-for-Blocks.md

@@ -0,0 +1,275 @@
+
+## Background
+
+FTC robots have many ways to autonomously navigate the game field.  This tutorial introduces Vuforia, a software tool that can use camera images to determine the robot’s location on the field.  A [separate tutorial](TensorFlow-for-Blocks-.) describes TensorFlow Lite, a tool that supplements Vuforia to identify and track certain game elements as 3D objects.
+
+These two tools combine several high-impact technologies: vision processing, machine learning, and autonomous navigation.  Awareness of this software can spark further interest and exploration by FTC students as they prepare for future studies and careers in high technology.
+
+## Vuforia introduction
+
+[Vuforia](https://www.ptc.com/en/products/augmented-reality/vuforia) is [PTC's](https://www.ptc.com/) augmented reality (AR) technology that includes image detection and image tracking capabilities.  Vuforia has been available to FTC students since 2016.  Each season, the FTC software is pre-loaded with 2D image targets that are placed in well-defined locations on the game field.  Using Vuforia, if a robot "sees" one of these image targets, the robot can determine its location on the game field in an absolute or <u>global</u> frame of reference.
+
+<p align="center">
+[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF003-field-axes-text.png|Field axes.]]<br><sub><i>Image credit: Phil Malone</i></sub></p>
+
+For the 2019-2020 SKYSTONE season, the 13 pre-loaded image targets are:
+- 8 pictures (8.5 x 11 inches) on the field perimeter, 2 per wall
+- 4 pictures (10 x 2 inches) on the narrow vertical pillars of the Skybridge
+- 1 picture (4 x 7 inches) on one side of each Skystone (2 per Alliance)
+ 
+Most of these pictures remain in a fixed location, allowing a team’s Op Mode to read and process data on the robot’s global field location and orientation.  This allows autonomous navigation, an essential element of modern robotics.
+ 
+For the image on the Skystone, which can move on the field, Vuforia reports the robot’s location and orientation relative to the Skystone.  This can allow approach and retrieval.  Note that Google's TensorFlow technology can also be used to locate and navigate to Skystone game elements, as described in a separate tutorial called [TensorFlow for Blocks](TensorFlow-for-Blocks).
+
+## Blocks and Java samples
+
+This tutorial describes the Op Modes provided in the FTC Blocks sample menu:
+
+_ConceptVuforiaNavSkystone.blk_<br>
+<u>and</u><br>
+_ConceptVuforiaNavSkystoneWebcam.blk_
+
+Java samples are also available in OnBot Java and Android Studio:
+
+_ConceptVuforiaSkyStoneNavigation.java_<br>
+<u>and</u><br>
+_ConceptVuforiaSkyStoneNavigationWebcam.java_
+
+The Java samples are much more detailed, revealing the underlying programming to manage the Vuforia software and to transform the picture location to a global field location.  Before working with that code, Java programmers may benefit from reading this Blocks tutorial and testing the Blocks Op Mode on a game field.  The Java sample programs are well documented with clear, detailed comments.
+
+## Op Mode Logic
+The Blocks and the Java sample op modes share the same programming logic.  Before looking at the details of the sample op modes, it is helpful to step back and get a "big picture" view on what the Vuforia op modes do:
+
+* Initialize the Vuforia software (including specifying the location and orientation of the phone on the robot).
+* Activate the Vuforia software (i.e., begin "looking" for known 2D image targets).
+* Loop while the op mode is still active
+     - Check to see if any image targets have been detected in the camera's current field of view
+     - If so, extract and display location (X, Y, and Z coordinates) and orientation (rotation about the Z axis) information for the robot
+ 
+## Setting up for Vuforia
+
+On a laptop connected via Wifi to the RC phone or REV Control Hub, at the Blocks screen, click Create New Op Mode.  Type a name for your example program, and choose the appropriate Vuforia sample.  If using the **RC phone’s camera**, choose the first Sample shown below.
+
+<p align="center">
+[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF005-create-new-op-mode.png|Sample.]]</p>
+
+If using a **webcam**, with REV Expansion Hub or REV Control Hub, choose the second Sample.  Then click OK to enter the programming screen.
+
+<p align="center">
+[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF006-create-new-op-mode-webcam.png|Webcam sample.]]</p>
+
+This Op Mode may appear long, but has a simple structure.  The first section of Blocks is the main program, followed by four shorter functions.  A function is a named collection of Blocks to do a certain task.  This organizes and reduces the size of the main program, making it easier to read and edit.  In Java these functions are called <u>methods</u>.
+
+This program shows various Blocks for basic use of Vuforia.  Other related Blocks can be found in the Vuforia folder, under the Utilities menu at the left side.  ‘Optimized for SKYSTONE’ contains many of the game-specific Blocks in this sample.  The other headings have a full suite of Vuforia commands for broader, advanced use.
+
+ ## Initialization Section
+
+The first section of an Op Mode is called initialization.  These commands are run one time only, when the INIT button is pressed on the Driver Station (DS) phone.   This section ends with the command waitForStart.
+
+<p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF011-initialization-circles.png|Initialization.]]</p>
+
+Besides the Telemetry messages, this section has only two actions, circled above: <u>initialize</u> Vuforia (specify your settings), and <u>activate</u> Vuforia (turn it on).  The first action’s Block is long enough to justify its own Function called ‘initVuforia’, shown below the main program.
+
+<p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF016-initVuforia-circles.png|Initialize Vuforia.]]</p>
+
+When using the **RC phone camera**, the FTC Vuforia software has 11 available settings to indicate your preferred usage and the camera’s location.  This example uses the phone’s BACK camera, requiring the phone to be rotated -90 degrees about its long Y axis.  For this sample Op Mode, the RC phone is used in Portrait mode.
+
+When using a **webcam**, Vuforia has 12 available settings.  The RC cameraDirection setting is replaced with two others related to the webcam: its configured name, and an optional calibration filename.
+
+ <p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF018-initVuforia-webcam-circles.png|Initialize Vuforia with webcam.]]</p>
+
+Other settings include ‘Monitoring’, which creates a live video feed on the RC phone and enables a preview image on the DS phone.  This is useful for initial camera pointing, and to verify Vuforia’s recognition.
+
+‘Feedback’ can display AXES, showing Vuforia’s X, Y, Z axes of the reference frame local to the image.  The 3 colored lines indicate Vuforia has recognized and is analyzing the image.  This local data is transformed by the FTC software to report the robot’s location in a <u>global</u> (field) reference frame.
+
+‘Translation’ allows you to specify the phone’s location on the robot.  Using these offsets, the FTC software can report the field position of a specific place on the robot itself (not the camera).  Likewise, ‘rotation’ takes into account the phone’s angled/tilted orientation.
+
+Lastly, in the main program’s initialization section, there remains only the command to activate Vuforia.
+
+ <p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF020-activate-Vuforia.png|Activate Vuforia.]]</p>
+
+This starts the Vuforia software and opens or enables the Monitoring images if specified.  The REV Control Hub offers a video feed only through its HDMI port, not allowed during competition.
+
+At this point in the Op Mode, it is not required for Vuforia to recognize a stored image.  This can happen in the next section.
+
+## Run Section
+
+The ‘run’ section begins when the Start button (large arrow icon) is pressed on the DS phone.
+
+ <p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF025-if-opModeIsActive.png|opModeIsActive.]]</p>
+
+
+The first IF structure encompasses the entire program, to ensure the Op Mode was properly activated.  This is an optional safety measure.
+
+Next the Op Mode enters a Repeat loop that includes all the Vuforia-related commands.  In this Sample, the loop continues while the Op Mode is active, namely until the Stop button is pressed.
+ 
+ <p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF030-repeat-loop.png|Repeat loop.]]</p>
+
+In a competition Op Mode, you will add other conditions to end the loop.   Examples might be: loop until Vuforia finds what you seek, loop until a time limit is reached, loop until the robot reaches a location on the field.  After the loop, your main program will continue with other tasks.
+
+Inside the loop, the program checks whether Vuforia has found specific pre-loaded images.  This example Op Mode checks one at a time, in the order listed, re-using a Function called ‘isTargetVisible’.  If a match is found, this program performs an action with another Function called ‘processTarget’.  The first two searches are shown here:
+
+ <p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF035-if-target-visible.png|If Target Visible.]]</p>
+
+The first search is for an image called Stone Target, the dark picture applied to a Skystone.  The FTC Vuforia software calls this label TrackableName.  The name is given as a <u>parameter</u> to the function called ‘isTargetVisible’.
+
+> **Programming tip:** when building a new Function in Blocks, click the blue gear icon to add one or more ‘input names’ or parameters.
+
+The Op Mode’s second function ‘isTargetVisible’ will send, or <u>return</u>, to this IF block a <u>Boolean</u> value, namely True or False.  If the reply is True, the DO branch will be performed.  In this case, the DO command is to run the function called ‘processTarget’.
+
+If the reply is False, the camera’s view did not include the Stone Target.  The program moves to the ELSE IF branch, now seeking an image called Blue Front Bridge (picture on the front side of the Blue Alliance Skybridge support).  If the function isTargetVisible returns a True value, the processTarget function will be run.  Otherwise the Op Mode will seek the next image, and so on.
+
+If no matches were found after checking all the desired images, the Op Mode reaches the final ELSE branch.
+ 
+<p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF040-else-no-targets.png|Else no targets.]]</p>
+
+This builds a Telemetry message (line of text for the DS phone) that none of the desired images were found in the current cycle of the Repeat loop.
+
+The last action of the loop is to provide, or <u>update</u>, the DS phone with all Telemetry messages built during this loop cycle.  Those messages might have been created in a Function that was used, or <u>called</u>, during the loop.
+
+<p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF045-telemetry-update.png|Telemetry update.]]</p>
+
+During this Repeat loop, two Functions were called; their descriptions follow below.
+
+This example Op Mode ends by turning off the Vuforia software.  When your competition Op Mode is finished using Vuforia, deactivation will free up computing resources for the remainder of your program.
+ 
+<p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF050-Vuforia-deactivate.png|Deactivate Vuforia.]]</p>
+
+## Function isTargetVisible
+
+Recall that this second function was given, or <u>passed</u>, a parameter called ‘trackableName’.  This contains the name of the pre-loaded image currently being sought by the main program.
+
+> **Programming tip:** By passing the name as a parameter, this same function can be reused 13 times, to look for each of the images.  This is more efficient than 13 similar functions, each seeking 1 particular image.
+
+> **Programming tip:** in Blocks, a Function’s parameters are automatically created as Variables.  This makes its contents available to use inside the functions and elsewhere.
+  
+ <p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF055-isTargetVisible.png|Is Target Visible.]]</p>
+
+To understand this function’s first command, read it from right to left.
+ 
+<p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF060-track-method.png|Track method.]]</p>
+
+The FTC Vuforia software contains a <u>method</u> called ‘track’.  This is the central task; it looks for a specific image named as an input parameter.  The yellow-circled command calls that method, passing it the same parameter from the main program: trackableName.
+
+The ‘track’ method examines the current camera image, to see if it contains any form of the named pre-stored picture.  The recognized image, if any, might be distant (small), at an angle (distorted), in poor lighting (darker), etc.   In any case, the ‘track’ method returns various pieces of information about its analysis.
+ 
+All of that returned information is passed to the left side of the command line.
+ <p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF065-set-vuforiaResults.png|Set Vuforia results.]]</p>
+
+This Blocks Op Mode uses a Variable called vuforiaResults.  This is a special variable holding multiple pieces of information, not just one number, or one text string, or one Boolean value.  The yellow-circled command <u>sets</u> that variable to store the entire group of results passed from the Vuforia ‘track’ method.
+
+This function is interested in only one thing: was there a match?
+
+ <p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF070-if-IsVisible.png|If IsVisible.]]</p>
+
+The yellow-circled command calls a different Vuforia method called ‘IsVisible’.  This method examines the full set of tracking results, now stored in the variable ‘vuforiaResults’, and determines whether a target was recognized in the camera image.  It returns a Boolean value of True or False.
+
+Finally, the Op Mode can set a simple Boolean variable with similar name, called ‘isVisible’.
+ 
+<p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF075-set-isVisible.png|Set isVisible.]]</p>
+
+This true/false answer is sent, or <u>returned</u>, to the main program.
+
+ <p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF080-return-isVisible.png|Return isVisible.]]</p>
+
+> **Programming tip:** when creating a new Function in Blocks, look for the separate menu choice with a return feature, as shown above.
+
+## Function processTarget
+
+This third function is called by the main program, only if the named target was recognized.  Now the Op Mode can take action based on a recognized image.
+  
+<p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF085-processTarget.png|Function processTarget.]]</p>
+
+This example Op Mode does not take physical action, such as operating motors or servos.  In a competition Op Mode, you will program the robot to react to a successful recognition, probably to continue navigating on the field.
+
+Instead this program simply displays Telemetry, showing some contents of the tracking results.  Those results are still stored in the special variable called vuforiaResults, and can be extracted using other Vuforia methods besides ‘IsVisible’.  This example Op Mode calls these 5 basic methods:
+
+* Name: returns the name of the recognized target
+* X: returns the X coordinate of robot’s estimated location on the field
+* Y: returns the Y coordinate of robot’s estimated location on the field
+* Z: returns the Z coordinate of robot’s estimated location on the field
+* ZAngle: returns the estimated orientation of the robot on the field
+
+The Testing and Navigation sections below will discuss how to use this data.
+
+## Function displayValue
+
+The fourth and last function receives a Vuforia distance value (in millimeters) as a parameter and converts it to another unit, specified as a second parameter.
+ 
+<p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF090-displayValue.png|Function displayValue.]]</p>
+
+The converted value, in the requested units, is returned to the calling program or function.
+
+## Testing the Op Mode
+
+The FTC software’s global frame of reference is defined from the viewpoint of the Red Alliance station.  The center of the game field is the <u>origin</u>: X=0, Y=0, Z=0.  Positive X extends to the right, and Positive Y extends forward or away.  Thus on the SKYSTONE game field, Positive X extends to the rear, away from the Audience side; while Positive Y extends to the Blue Alliance station.
+
+<p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF100-field-axes-text.png|Field axes.]]<br><sub><i>Image credit: Phil Malone</i></sub>
+
+Positive Z extends upwards from the foam tile surface.  Rotation about each axis follows the right-hand rule, namely clockwise when looking in the positive direction.  Z-Angle begins at 0 degrees on the positive X axis.  In the image shown above, if you were floating over the field looking from a "birds eye" video down onto the field (in the negative Z direction) the positive Z-Angle direction is in the counterclockwise direction with 0 degrees coinciding with the +X axis, and 90 degrees coinciding with the +Y axis.
+
+Try this on an FTC SKYSTONE game field.  An RC phone in Portrait mode can be tested loose or mounted on a robot.  From a low place inside the perimeter, point the phone’s camera or webcam at a fixed target image (perimeter or Skybridge).  Initialize the sample Op Mode, and use the RC video feed to confirm Vuforia’s recognition (3 colored local axes on the picture).
+
+<p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF105-RC-video-axes-half.png|RC video axes.]]</p>
+
+A preview is also available on the DS screen, with the REV Expansion Hub and the REV Control Hub.  To see it, choose the main menu’s Camera Stream when the Op Mode has initialized (but not started).  Touch to refresh the image as needed, and select Camera Stream again to close the preview and continue the Op Mode.  This is described further in the tutorial [Using an External Webcam with Control Hub](Using-an-External-Webcam-with-Control-Hub).
+
+<p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF110-DS-preview-axes-half.png|DS preview axes.]]</p>
+
+Close the DS preview (if used), and press the Start button.  The DS phone should show Telemetry with the name of that image, and the estimated location and orientation of the camera.
+
+<p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF115-DS-Telemetry-screen-circle-half.png|DS Telemetry screen.]]</p>
+
+Carefully move the camera around the field, trying to keep a navigation image in the field of view.  Verify whether the X, Y and Z-Angle values respond and seem reasonable.  Swiveling the phone from right to left should increase Z-Angle (Rotation about Z).  Move the camera from one image to another; observe the results.
+
+## Testing and Using Vuforia
+
+Learn and assess the characteristics of this navigation tool.  You will notice that after initially recognizing a picture, Vuforia can easily track the full or partial image as the camera moves.  You may find that certain zones give better results.
+
+You may also notice some readings are slightly erratic or ‘jumpy’, like the raw data from many advanced sensors.  An FTC programming challenge is to smooth out such data to make it more useful.  Ignoring rogue values, simple average, moving average, weighted average, PID control, and many other methods are available.  It’s also possible to combine Vuforia results with other sensor data, for a blended source of navigation input.
+
+This is the end of reviewing the sample Op Mode.  With the data provided by Vuforia, your competition Op Mode can autonomously navigate on the field.  The next section gives a simple example.
+
+## Navigation Example
+
+For illustration only, consider an extremely simple SKYSTONE navigation task.  With the robot near the Blue midline (approximately X = 0), front camera directly facing the rear left target image, **drive 6 inches towards the image**.
+
+The sample Op Mode looped until the DS Stop button was pressed.  Now the navigation loop will contain driving, and the loop ends when X reaches 6 inches.
+
+> **Programming tip:** Plan your programs first using plain language, also called <u>pseudocode</u>.  This can be done with Blocks, by creating empty Functions.  The name of each Function describes the action.
+
+> **Programming tip:** Later, each team member can work on the inner details of a Function.  When ready, Functions can be combined using a laptop’s Copy and Paste functions (e.g. Control-C and Control-V).
+
+A simple pseudocode solution might look like this: 
+
+ <p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF205-pseudocode-01.png|Pseudocode 1.]]</p>
+
+To stay very close to the Sample Op Mode described above, the pseudocode might be altered as follows:
+
+ <p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF210-pseudocode-02.png|Pseudocode 2.]]</p>
+
+This version has the added safety feature of driving forward only if the target is in view.
+
+Lastly, to use exactly the same Functions from the Sample Op Mode:
+
+ <p align="center">[[/images/Using-Computer-Vision/Vuforia-for-Blocks/VF215-pseudocode-03.png|Pseudocode 3.]]</p>
+
+This code could directly replace the Repeat loop in the Sample Op Mode.  This version has the added safety feature of looping only while the Op Mode is active.
+
+> **Programming tip:** action loops should also have <u>safety time-outs</u>.  Add another loop condition, while ElapsedTime.Time is less than your time limit.  Otherwise your robot could sit idle, or keep driving and crash.
+
+> **Programming tip:** optional to set a Boolean variable indicating that the loop ended from a time-out, then take action accordingly.
+
+## Summary
+
+This example showed how to extract and use a single number generated by Vuforia, in this case the current X position.  It could be used in proportional control, where larger deviation, or <u>error</u>, is corrected faster.  X and Y error could control steering, or forward motion combined with sideways motion (crab drive or strafing).  Z-Angle could be used for spins and angled drives.
+
+Overall, Vuforia allows autonomous navigation to global field locations and orientations, not relying only on the robot’s frame of reference and on-board sensor data.  It also allows a robot to recognize and approach a movable image, like a Skystone, with or without TensorFlow Lite.
+
+<i>Questions, comments and corrections to: westsiderobotics@verizon.net</i>
+
+## Acknowledgements
+A special Thank You! is in order for [Chris Johannesen](mailto:westsiderobotics@verizon.net) of Westside Robotics (Los Angeles) for putting together this tutorial.  Thanks Chris!
+
+
+