Examples Clean-Up (#1408)

docs/source/docs/integration/advancedStrategies.md

@@ -1,8 +1,12 @@
 # Advanced Strategies
 
-Advanced strategies for using vision processing results involve working with the robot's *pose* on the field. A *pose* is a combination an X/Y coordinate, and an angle describing where the robot's front is pointed. It is always considered *relative* to some fixed point on the field.
+Advanced strategies for using vision processing results involve working with the robot's *pose* on the field.
 
-WPILib provides a [Pose2d](https://docs.wpilib.org/en/stable/docs/software/advanced-controls/geometry/pose.html)  class to describe poses in software.
+A *pose* is a combination an X/Y coordinate, and an angle describing where the robot's front is pointed. A pose is always considered *relative* to some fixed point on the field.
+
+WPILib provides a [Pose2d](https://docs.wpilib.org/en/stable/docs/software/advanced-controls/geometry/pose.html) class to describe poses in software.
+
+PhotonVision can supply correcting information to keep estimates of *pose* accurate over a full match.
 
 ## Knowledge and Equipment Needed
 
@@ -12,30 +16,53 @@ WPILib provides a [Pose2d](https://docs.wpilib.org/en/stable/docs/software/advan
   \- Sufficient sensors to measure wheel rotation
   \- Capable of closed-loop velocity control
 - A gyroscope or IMU measuring actual robot heading
-- Experience using some path-planning library (WPILib is our recommendation)
+- Experience using some path-planning library
 
-## Path Planning in a Target-Centered Reference Frame
+## Robot Poses from the Camera
 
-When using 3D mode in PhotonVision, the [SolvePNP Algorithm](https://en.wikipedia.org/wiki/Perspective-n-Point)  is used to deduce the *camera's* position in a 3D coordinate system centered on the target itself.
+When using 3D mode in PhotonVision, an additional step is run to estimate the 3D position of camera, relative to one or more AprilTags.
 
-A simple algorithm for using this measurement is:
+This process does not produce a *unique* solution. There are multiple possible camera positions which might explain the image it observed. Additionally, the camera is rarely mounted in the exact center of a robot.
 
-1. Assume your robot needs to be at a fixed `Pose2D` *relative to the target*.
-2. When triggered:
-   #. Read the most recent vision measurement - this is your *actual* pose.
-   #. Generate a simple trajectory to the goal position
-   #. Execute the trajectory
+For these reasons, the 3D information must be filtered and transformed before they can describe the robot's pose.
 
-:::{note}
-There is not currently an example demonstrating this technique.
-:::
+PhotonLib provides {ref}`a utility class to assist with this process on the roboRIO <docs/programming/photonlib/robot-pose-estimator:AprilTags and PhotonPoseEstimator>`. Alternatively, {ref}`a "multi-tag" strategy can do this process on the coprocessor. <docs/apriltag-pipelines/multitag:Enabling MultiTag>`.
 
-## Global Pose Estimation
+## Field-Relative Pose Estimation
 
-A more complex way to utilize a camera-supplied `Pose2D` is to incorporate it into an estimation of the robot's `Pose2D` in a global field reference frame.
+The camera's guess of the robot pose generally should be *fused* with other sensor readings.
 
-When using this strategy, the measurements made by the camera are *fused* with measurements from other sensors, a model of expected robot behavior, and a matrix of weights that describes how trustworthy each sensor is. The result is a *best-guess* at the current pose on the field.
+WPILib provides [a set of pose estimation classes](https://docs.wpilib.org/en/stable/docs/software/advanced-controls/state-space/state-space-pose-estimators.html) for doing this work.
 
-In turn, this best-guess position is used to path plan to the known positions on the field, which may or may not have vision targets nearby.
+## I have a Pose Estimate, Now What?
 
-See the  {ref}`Pose Estimation <docs/examples/simposeest:Knowledge and Equipment Needed>` example for more information.
+### Triggering Actions Automatically
+
+A simple way to use a pose estimate is to activate robot functions automatically when in the correct spot on the field.
+
+```{eval-rst}
+.. tab-set-code::
+
+   .. code-block:: Java
+
+      Pose3d robotPose;
+      boolean launcherSpinCmd;
+
+      // ...
+
+      if(robotPose.X() < 1.5){
+        // Near blue alliance wall, start spinning the launcher wheel
+        launcherSpinCmd = True;
+      } else {
+        // Far away, no need to run launcher.
+        launcherSpinCmd = False;
+      }
+
+      // ...
+```
+
+### PathPlanning
+
+A common, but more complex usage of a pose estimate is an input to a path-following algorithm. Specifically, the pose estimate is used to correct for the robot straying off of the pre-defined path.
+
+See the {ref}`Pose Estimation <docs/examples/poseest:Knowledge and Equipment Needed>` example for details on integrating this.

docs/source/docs/integration/aprilTagStrategies.md

@@ -1,46 +0,0 @@
-# AprilTag Strategies
-
-:::{note}
-The same strategies covered in the simple and advanced strategy sections still apply to AprilTags, and we encourage you to read them first. This page will discuss the specific nuances to using AprilTags.
-:::
-
-## Simple Strategies
-
-Prior to the introduction of AprilTags, the most common vision strategy for teams was to use the yaw of the detected target in order to turn to the target, and then score. This is still possible with AprilTags as the yaw of the tag is reported. Similarly, getting the distance to the target via trigonometry will also work. This is discussed in greater detail in the previous page.
-
-## Advanced Strategies
-
-AprilTags allows you find the robot pose on the field using data from the tags. A pose is a combination an X/Y coordinate, and an angle describing where the robot’s front is pointed. It is always considered relative to some fixed point on the field.
-
-### Knowledge and Equipment Needed
-
-Knowledge
-
-- How to tune an AprilTag Pipeline (found in the pipeline tuning section)
-
-Equipment
-
-- A Coprocessor running PhotonVision - Accurate camera calibration to support “3D mode” required
-- A Drivetrain with wheels and sensors (Sufficient sensors to measure wheel rotation and capable of closed-loop velocity control)
-- A gyroscope or IMU measuring actual robot heading
-
-### Global Pose Estimation / Pose Estimation Strategies
-
-:::{note}
-See the previous page for more general information. Most of the information is the same except now the camera is supplying a `Pose3D`.
-:::
-
-The nature of how AprilTags will be laid out makes it very likely that you will get multiple pose measurements within a single frame from seeing multiple targets. This requires strategies to fuse these observations together and get a "best guess" as to where your robot is. The best way to do this is to use the corners from all visible AprilTags to estimate the robot's pose. This is done by using the `PhotonPoseEstimator` class and the "MULTI_TAG_PNP_ON_COPROCESSOR" strategy. Additional strategies include:
-
-- A camera seeing multiple targets, taking the average of all the returned poses
-- A camera seeing one target, with an assumed height off the ground, picking the pose which places it to the assumed height
-- A camera seeing one target, and picking a pose most similar to the most recently observed pose
-- A camera seeing one target, and picking a pose most similar to one provided externally (ie, from previous loop's odometry)
-- A camera seeing one target, and picking the pose with the lowest ambiguity.
-
-PhotonVision supports all of these different strategies via our `PhotonPoseEstimator` class that allows you to select one of the strategies above and get the relevant pose estimation.
-
-### Tuning Pose Estimators
-
-Coming soon!
-TODO: Add this back in once simposeest example is added.

docs/source/docs/integration/index.md

@@ -6,5 +6,4 @@
 background
 simpleStrategies
 advancedStrategies
-aprilTagStrategies
 ```

docs/source/docs/integration/simpleStrategies.md

@@ -1,36 +1,32 @@
 # Simple Strategies
 
-Simple strategies for using vision processor outputs involve using the target's position in the 2D image to infer *range* and *angle* to the target.
+Simple strategies for using vision processor outputs involve using the target's position in the 2D image to infer *range* and *angle* to a particular AprilTag.
 
 ## Knowledge and Equipment Needed
 
 - A Coprocessor running PhotonVision
 - A Drivetrain with wheels
+- An AprilTag to aim at
 
 ## Angle Alignment
 
-The simplest way to use a vision processing result is to first determine how far left or right in the image the vision target should be for your robot to be "aligned" to the target. Then,
+The simplest way to align a robot to an AprilTag is to rotate the drivetrain until the tag is centered in the camera image. To do this,
 
-1. Read the current angle to the target from the vision Coprocessor.
-2. If too far in one direction, command the drivetrain to rotate in the opposite direction to compensate.
+1. Read the current yaw angle to the AprilTag from the vision Coprocessor.
+2. If too far off to one side, command the drivetrain to rotate in the opposite direction to compensate.
 
 See the  {ref}`Aiming at a Target <docs/examples/aimingatatarget:Knowledge and Equipment Needed>` example for more information.
 
-:::{note}
-Sometimes, these strategies have also involved incorporating a gyroscope. This can be necessary due to the high latency of vision processing algorithms. However, advancements in the tools available (including PhotonVision) has made that unnecessary for most applications.
-:::
+NOTE: This works if the camera is centered on the robot. This is easiest from a software perspective. If the camera is not centered, take a peek at the next example - it shows how to account for an offset.
 
-## Range Alignment
+## Adding Range Alignment
 
-By looking at the position of the target in the "vertical" direction in the image, and applying some trigonometry, the distance between the robot and the camera can be deduced.
+By looking at the position of the AprilTag in the "vertical" direction in the image, and applying some trigonometry, the distance between the robot and the camera can be deduced.
 
-1. Read the current distance to the target from the vision coprocessor.
+1. Read the current pitch angle to the AprilTag from the vision coprocessor.
+2. Do math to calculate the distance to the AprilTag.
 2. If too far in one direction, command the drivetrain to travel in the opposite direction to compensate.
 
-See the {ref}`Getting in Range of the Target <docs/examples/gettinginrangeofthetarget:Knowledge and Equipment Needed>` example for more information.
-
-## Angle + Range
-
-Since the previous two alignment strategies work on independent axes of the robot, there's no reason you can't do them simultaneously.
+This can be done simultaneously while aligning to the desired angle.
 
 See the {ref}`Aim and Range <docs/examples/aimandrange:Knowledge and Equipment Needed>` example for more information.