some yapping

Author: stwiggy

docs/section-7/apriltag_image1.png

@@ -1,17 +1,17 @@
 ## What is a Limelight?
-A [Limelight](https://andymark-weblinc.netdna-ssl.com/product_images/limelight-2-plus/5e15fe1480289d6162f285cd/zoom.jpg?c=1578499604) is a small, on-board computer and camera system that performs computer vision. Many FRC teams, including us, use a Limelight for the autonomous period of competition games. Limelights are expensive and should be handled carefully.
+A [Limelight](https://andymark-weblinc.netdna-ssl.com/product_images/limelight-2-plus/5e15fe1480289d6162f285cd/zoom.jpg?c=1578499604) is a small, on-board computer and camera system that performs computer vision. Many FRC teams, including us, use a Limelight assisting the driver in multiple tasks such as auto aiming and auto movement. Limelights are expensive and should be handled carefully.
 
-How does it work? Well, the principles are simple. Several places on the field are marked by special tape known as retroreflective vision tape. This tape reflects all light that hits it directly back at the source, as shown in the image below (the photo was taken with flash). The tape is the only visible object in the image because all the light from the flash was reflected by the vision tape right back at the camera.
+Take a look at the instructions [here](https://docs.limelightvision.io/en/latest/getting_started.html) for setting up the Limelight. As well, you should read how to build and configure a vision pipeline [here](https://docs.limelightvision.io/en/latest/vision_pipeline_tuning.html).
 
-![Vision Tape](vision_tape.JPG)
+There are two main pipelines ("modes") we use with Limelight: AprilTags and Neural Networks.
 
-![Vision Tape 2](vision_tape2.JPG)
+![Apriltag](apriltag_image1.png)
 
-The limelight shines green light continuously and captures images using a camera. If the limelight shines green light onto retroreflective vision tape, the tape will show up brightly in the camera image. The limelight then determines the brightest object in the image, draws bounding boxes around it, finds the center of the bounding box, and determines the difference between that center and the crosshair of the camera alongside other important variables.
+![Apriltag in the wild](apriltag_image2.png)
 
-Take a look at the instructions [here](https://docs.limelightvision.io/en/latest/getting_started.html) for setting up the Limelight. As well, you should read how to build and configure a vision pipeline [here](https://docs.limelightvision.io/en/latest/vision_pipeline_tuning.html).
+Apriltags are essentially QR codes. These are placed throughout the field, such as on scoring targets.
 
-There are two important interfaces for the limelight: http://limelight.local:5801 and http://limelight.local:5800 (you need to be connected to the limelight to use these links). The first one is for configuring the Limelight pipeline and the second one is for displaying the camera feed.
+There are two important interfaces for the limelight: http://limelight.local:5801 and http://limelight.local:5800 (you need to be connected to the limelight via the radio to use these links). The first one is for configuring the Limelight pipeline and the second one is for displaying the camera feed.
 
 ## Limelight NetworkTables values
 [`NetworkTables`](https://first.wpi.edu/FRC/roborio/release/docs/java/edu/wpi/first/networktables/NetworkTable.html) might seem like a new concept, but you have already been working with `NetworkTables` because it includes `SmartDashboard` as one of its keys. Whenever you put or read values using SmartDashboard, you were working with `NetworkTables`. You can think of every instance of `SmartDashboard` as `NetworkTableInstance.getDefault().getTable("SmartDashboard")`. You can find a full description of `NetworkTables` [here](https://docs.wpilib.org/en/stable/docs/software/networktables/index.html?highlight=networktables),
@@ -22,59 +22,45 @@ Most important for this section is the fact that the Limelight puts many useful
 NetworkTableInstance.getDefault().getTable("limelight").getEntry("<variablename>").getDouble(0);
 ```
 
+Important keys that you will use often includes but not limited to: `tv`, `tx`, `ty`, `ta`, and etc. You may want to store the Limelight `NetworkTable` as a variable depending on how often you plan on accessing its entries. You can find a full list of keys [here](https://docs.limelightvision.io/docs/docs-limelight/apis/complete-networktables-api).
+
 !!! tip
-    **You can find the full list of keys [here](https://docs.limelightvision.io/docs/docs-limelight/apis/complete-networktables-api).**
-    
-Important keys that you will use often includes but not limited to: `tv`, `tx`, `ty`, `ta`, and etc. You may want to store the Limelight `NetworkTable` as a variable depending on how often you plan on accessing its entries.
+    **Instead of using this long mess every time, consider copy-pasting the [LimelightHelpers](https://github.com/LimelightVision/limelightlib-wpijava/blob/main/LimelightHelpers.java) class into the subsystem file and using its methods**
 
 ## Distance Estimation and Angle Alignment
-There are several "Case Studies" in the [Limelight documentation](https://docs.limelightvision.io/en/latest). I will highlight a few and compare/contrast with the Limelight code used for the 2020 Build Season. I highly recommend watching the gifs of the code in action for each of the case studies.
+Here's some example code. There are more examples in the [Limelight documentation](https://docs.limelightvision.io/en/latest).
 
-First up, aiming. Here is the featured code for aiming at a vision target (it is written in C++, but the math is the same regardless of the syntax):
+First, finding the ground distance from the limelight to a target:
 ``` Java
-float Kp = -0.1f;
-float min_command = 0.05f;
-
-std::shared_ptr<NetworkTable> table = NetworkTable::GetTable("limelight");
-float tx = table->GetNumber("tx");
-
-if (joystick->GetRawButton(9))
-{
-        float heading_error = -tx;
-        float steering_adjust = 0.0f;
-        if (tx > 1.0)
-        {
-                steering_adjust = Kp*heading_error - min_command;
-        }
-        else if (tx < 1.0)
-        {
-                steering_adjust = Kp*heading_error + min_command;
-        }
-        left_command += steering_adjust;
-        right_command -= steering_adjust;
+public double getDistance() {
+    Rotation2d angleToGoal = Rotation2d.fromDegrees(LIMELIGHT_MOUNT_ANGLE)
+    .plus(Rotation2d.fromDegrees(LimelightHelpers.getTX("limelight")));
+    double distance = (TARGET_HEIGHT - LIMELIGHT_HEIGHT) / angleToGoal.getTan();
+    return distance;
 }
 ```
 
-The code is active while a specific button is pressed. It gets the current horizontal offset and uses that as the error for a PID loop with a setpoint of zero. The idea is that the robot will be "aligned" if the offset is near zero. Since the Limelight is fixed in place on the robot, the only way to control the horizontal crosshair offset is to turn left/right.
-
-The second segment of code is for moving to a particular distance:
-
-``` Java
-float KpDistance = -0.1f;
+Let's predefine some constants:
+`LIMELIGHT_MOUNT_ANGLE` - the angle that the limelight is mounted from 
+`TARGET_HEIGHT` - the height of the target
+`LIMELIGHT_HEIGHT` - the height of the limelight from the ground
 
-std::shared_ptr<NetworkTable> table = NetworkTable::GetTable("limelight");
-float distance_error = table->GetNumber("ty");
+This code uses basic trigonometry to calculate the floor distance. This method can be used to move to some location.
 
-if (joystick->GetRawButton(9))
-{
-        driving_adjust = KpDistance * distance_error;
 
-        left_command += distance_adjust;
-        right_command += distance_adjust;
+We can also align to something with Limelight:
+``` Java
+public double getRotation() {
+    double cameraLensHorizontalOffset = -LimelightHelpers.getTY("limelight") / getDistance();
+    double realHorizontalOffset = Math.atan(cameraLensHorizontalOffset / getDistance());
+    double rotationError = Math.atan(realHorizontalOffset / getDistance());
 }
 ```
 
-The idea here is the same as before: a PID loop with a setpoint at zero and a crosshair offset as the error. Since the Limelight is fixed in place on the robot, the only way to control the vertical crosshair offset is to move forward/backward. So, to set a particular distance, one would need to experiment with varying setpoints until the robot drives to the specified distance.
+This returns the angle (in radians!) that the drivetrain must turn to align to its target. It also uses basic trigonometry.
+
+!!! tip
+    **Code with Limelight often involves a lot of math, especially trig. If that's not your cup of tea, try the tea again :P**
 
 Now take a look at [Limelight.java](https://github.com/DeepBlueRobotics/RobotCode2020/blob/unifiedcode/src/main/java/org/team199/lib/Limelight.java) from RobotCode2020. In particular, take a look at [`distanceAssist()`](https://github.com/DeepBlueRobotics/RobotCode2020/blob/unifiedcode/src/main/java/org/team199/lib/Limelight.java#L111), [`steeringAssist()`](https://github.com/DeepBlueRobotics/RobotCode2020/blob/unifiedcode/src/main/java/org/team199/lib/Limelight.java#L127), and [`autoTarget()`](https://github.com/DeepBlueRobotics/RobotCode2020/blob/unifiedcode/src/main/java/org/team199/lib/Limelight.java#L172). Some things I will point about about the code, especially `steeringAssist()`, are:
 
@@ -84,8 +70,15 @@ Now take a look at [Limelight.java](https://github.com/DeepBlueRobotics/RobotCod
 
 3. When `steeringAssist()` does not see a bounding box, it turns in the direction of the last `tx` value. This is to make sure that if it overshoots or if the target changes direction, it will take the shortest path to try to face the target again.
 
+Some notes to keep in mind:
+- Make sure you keep stay consistent with units
+
 The programming team had some fun with this code during the 2019-2020 Pre-Season:
 
 <iframe width="560" height="315" src="https://www.youtube.com/embed/TjksUg227QQ" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 
-<iframe width="560" height="315" src="https://www.youtube.com/embed/cFZtFT6d0g0" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+<iframe width="560" height="315" src="https://www.youtube.com/embed/cFZtFT6d0g0" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+
+In 2024, we used Limelight to autoalign then intake the game piece. Check out [this code](https://github.com/DeepBlueRobotics/RobotCode2024/blob/master/src/main/java/org/carlmontrobotics/commands/AutoMATICALLYGetNote.java) to see how we did it!
+
+TODO: neural network pipeline explanation