mirror of
https://github.com/PhotonVision/photonvision
synced 2026-06-20 00:51:41 +00:00
Move docs in-source (#1357)
This commit is contained in:
Matt
41
docs/source/docs/examples/aimandrange.rst
Normal file
41
docs/source/docs/examples/aimandrange.rst
Normal file
@@ -0,0 +1,41 @@
|
||||
Combining Aiming and Getting in Range
|
||||
=====================================
|
||||
|
||||
|
||||
The following example is from the PhotonLib example repository (`Java <https://github.com/PhotonVision/photonvision/tree/master/photonlib-java-examples/aimandrange>`_/`C++ <https://github.com/PhotonVision/photonvision/tree/master/photonlib-cpp-examples/aimandrange>`_).
|
||||
|
||||
Knowledge and Equipment Needed
|
||||
-----------------------------------------------
|
||||
|
||||
- Everything required in :ref:`Aiming at a Target <docs/examples/aimingatatarget:Knowledge and Equipment Needed>` and :ref:`Getting in Range of the Target <docs/examples/gettinginrangeofthetarget:Knowledge and Equipment Needed>`.
|
||||
|
||||
Code
|
||||
-------
|
||||
|
||||
Now that you know how to both aim and get in range of the target, it is time to combine them both at the same time. This example will take the previous two code examples and make them into one function using the same tools as before. With this example, you now have all the knowledge you need to use PhotonVision on your robot in any game.
|
||||
|
||||
.. tab-set::
|
||||
|
||||
.. tab-item:: Java
|
||||
|
||||
.. rli:: https://raw.githubusercontent.com/PhotonVision/photonvision/ebef19af3d926cf87292177c9a16d01b71219306/photonlib-java-examples/aimandrange/src/main/java/frc/robot/Robot.java
|
||||
:language: java
|
||||
:lines: 42-111
|
||||
:linenos:
|
||||
:lineno-start: 42
|
||||
|
||||
.. tab-item:: C++ (Header)
|
||||
|
||||
.. rli:: https://raw.githubusercontent.com/PhotonVision/photonvision/ebef19af3d926cf87292177c9a16d01b71219306/photonlib-cpp-examples/aimandrange/src/main/include/Robot.h
|
||||
:language: cpp
|
||||
:lines: 27-71
|
||||
:linenos:
|
||||
:lineno-start: 27
|
||||
|
||||
.. tab-item:: C++ (Source)
|
||||
|
||||
.. rli:: https://raw.githubusercontent.com/PhotonVision/photonvision/ebef19af3d926cf87292177c9a16d01b71219306/photonlib-cpp-examples/aimandrange/src/main/cpp/Robot.cpp
|
||||
:language: cpp
|
||||
:lines: 25-67
|
||||
:linenos:
|
||||
:lineno-start: 25
|
||||
46
docs/source/docs/examples/aimingatatarget.rst
Normal file
46
docs/source/docs/examples/aimingatatarget.rst
Normal file
@@ -0,0 +1,46 @@
|
||||
Aiming at a Target
|
||||
==================
|
||||
|
||||
The following example is from the PhotonLib example repository (`Java <https://github.com/PhotonVision/photonvision/tree/master/photonlib-java-examples/aimattarget>`_/`C++ <https://github.com/PhotonVision/photonvision/tree/master/photonlib-cpp-examples/aimattarget>`_).
|
||||
|
||||
Knowledge and Equipment Needed
|
||||
------------------------------
|
||||
|
||||
- Robot with a vision system running PhotonVision
|
||||
- Target
|
||||
- Ability to track a target by properly tuning a pipeline
|
||||
|
||||
Code
|
||||
-------
|
||||
|
||||
Now that you have properly set up your vision system and have tuned a pipeline, you can now aim your robot/turret at the target using the data from PhotonVision. This data is reported over NetworkTables and includes: latency, whether there is a target detected or not, pitch, yaw, area, skew, and target pose relative to the robot. This data will be used/manipulated by our vendor dependency, PhotonLib. The documentation for the Network Tables API can be found :ref:`here <docs/additional-resources/nt-api:Getting Target Information>` and the documentation for PhotonLib :ref:`here <docs/programming/photonlib/adding-vendordep:What is PhotonLib?>`.
|
||||
|
||||
For this simple example, only yaw is needed.
|
||||
|
||||
In this example, while the operator holds a button down, the robot will turn towards the goal using the P term of a PID loop. To learn more about how PID loops work, how WPILib implements them, and more, visit `Advanced Controls (PID) <https://docs.wpilib.org/en/stable/docs/software/advanced-control/introduction/index.html>`_ and `PID Control in WPILib <https://docs.wpilib.org/en/stable/docs/software/advanced-controls/controllers/pidcontroller.html#pid-control-in-wpilib>`_.
|
||||
|
||||
.. tab-set::
|
||||
|
||||
.. tab-item:: Java
|
||||
|
||||
.. rli:: https://raw.githubusercontent.com/PhotonVision/photonvision/ebef19af3d926cf87292177c9a16d01b71219306/photonlib-java-examples/aimattarget/src/main/java/frc/robot/Robot.java
|
||||
:language: java
|
||||
:lines: 41-98
|
||||
:linenos:
|
||||
:lineno-start: 41
|
||||
|
||||
.. tab-item:: C++ (Header)
|
||||
|
||||
.. rli:: https://raw.githubusercontent.com/PhotonVision/photonvision/ebef19af3d926cf87292177c9a16d01b71219306/photonlib-cpp-examples/aimattarget/src/main/include/Robot.h
|
||||
:language: c++
|
||||
:lines: 27-53
|
||||
:linenos:
|
||||
:lineno-start: 27
|
||||
|
||||
.. tab-item:: C++ (Source)
|
||||
|
||||
.. rli:: https://raw.githubusercontent.com/PhotonVision/photonvision/ebef19af3d926cf87292177c9a16d01b71219306/photonlib-cpp-examples/aimattarget/src/main/cpp/Robot.cpp
|
||||
:language: c++
|
||||
:lines: 25-52
|
||||
:linenos:
|
||||
:lineno-start: 25
|
||||
54
docs/source/docs/examples/gettinginrangeofthetarget.rst
Normal file
54
docs/source/docs/examples/gettinginrangeofthetarget.rst
Normal file
@@ -0,0 +1,54 @@
|
||||
Getting in Range of the Target
|
||||
==============================
|
||||
|
||||
The following example is from the PhotonLib example repository (`Java <https://github.com/PhotonVision/photonvision/tree/master/photonlib-java-examples/getinrange>`_/`C++ <https://github.com/PhotonVision/photonvision/tree/master/photonlib-cpp-examples/getinrange>`_).
|
||||
|
||||
|
||||
Knowledge and Equipment Needed
|
||||
-----------------------------------------------
|
||||
|
||||
- Everything required in :ref:`Aiming at a Target <docs/examples/aimingatatarget:Knowledge and Equipment Needed>`.
|
||||
- Large space where your robot can move around freely
|
||||
|
||||
Code
|
||||
-------
|
||||
|
||||
In FRC, a mechanism usually has to be a certain distance away from its target in order to be effective and score. In the previous example, we showed how to aim your robot at the target. Now we will show how to move to a certain distance from the target.
|
||||
|
||||
For proper functionality of just this example, ensure that your robot is pointed towards the target.
|
||||
|
||||
While the operator holds down a button, the robot will drive towards the target and get in range.
|
||||
|
||||
This example uses P term of the PID loop and PhotonLib and the distance function of PhotonUtils.
|
||||
|
||||
.. warning:: The PhotonLib utility to calculate distance depends on the camera being at a different vertical height than the target. If this is not the case, a different method for estimating distance, such as target width or area, should be used. In general, this method becomes more accurate as range decreases and as the height difference increases.
|
||||
|
||||
.. note:: There is no strict minimum delta-height necessary for this method to be applicable, just a requirement that a delta exists.
|
||||
|
||||
.. tab-set::
|
||||
|
||||
.. tab-item:: Java
|
||||
|
||||
.. rli:: https://raw.githubusercontent.com/PhotonVision/photonvision/ebef19af3d926cf87292177c9a16d01b71219306/photonlib-java-examples/getinrange/src/main/java/frc/robot/Robot.java
|
||||
:language: java
|
||||
:lines: 42-107
|
||||
:linenos:
|
||||
:lineno-start: 42
|
||||
|
||||
.. tab-item:: C++ (Header)
|
||||
|
||||
.. rli:: https://raw.githubusercontent.com/PhotonVision/photonvision/ebef19af3d926cf87292177c9a16d01b71219306/photonlib-cpp-examples/getinrange/src/main/include/Robot.h
|
||||
:language: c++
|
||||
:lines: 27-67
|
||||
:linenos:
|
||||
:lineno-start: 27
|
||||
|
||||
.. tab-item:: C++ (Source)
|
||||
|
||||
.. rli:: https://raw.githubusercontent.com/PhotonVision/photonvision/ebef19af3d926cf87292177c9a16d01b71219306/photonlib-cpp-examples/getinrange/src/main/cpp/Robot.cpp
|
||||
:language: c++
|
||||
:lines: 25-58
|
||||
:linenos:
|
||||
:lineno-start: 25
|
||||
|
||||
.. hint:: The accuracy of the measurement of the camera's pitch (:code:`CAMERA_PITCH_RADIANS` in the above example), as well as the camera's FOV, will determine the overall accuracy of this method.
|
||||
11
docs/source/docs/examples/index.rst
Normal file
11
docs/source/docs/examples/index.rst
Normal file
@@ -0,0 +1,11 @@
|
||||
Code Examples
|
||||
=============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
aimingatatarget
|
||||
gettinginrangeofthetarget
|
||||
aimandrange
|
||||
simaimandrange
|
||||
simposeest
|
||||
94
docs/source/docs/examples/simaimandrange.rst
Normal file
94
docs/source/docs/examples/simaimandrange.rst
Normal file
@@ -0,0 +1,94 @@
|
||||
Simulating Aiming and Getting in Range
|
||||
======================================
|
||||
|
||||
The following example comes from the PhotonLib example repository (`Java <https://github.com/PhotonVision/photonvision/tree/661f8b2c0495474015f6ea9a89d65f9788436a05/photonlib-java-examples/src/main/java/org/photonlib/examples/simaimandrange>`_/`C++ <https://github.com/PhotonVision/photonvision/tree/661f8b2c0495474015f6ea9a89d65f9788436a05/photonlib-cpp-examples/src/main/cpp/examples/simaimandrange>`_). Full code is available at those links.
|
||||
|
||||
|
||||
Knowledge and Equipment Needed
|
||||
-----------------------------------------------
|
||||
|
||||
- Everything required in :ref:`Combining Aiming and Getting in Range <docs/examples/aimandrange:Knowledge and Equipment Needed>`.
|
||||
|
||||
Background
|
||||
----------
|
||||
|
||||
The previous examples show how to run PhotonVision on a real robot, with a physical robot drivetrain moving around and interacting with the software.
|
||||
|
||||
This example builds upon that, adding support for simulating robot motion and incorporating that motion into a :code:`SimVisionSystem`. This allows you to test control algorithms on your development computer, without requiring access to a real robot.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<video width="85%" controls>
|
||||
<source src="../../_static/assets/simaimandrange.mp4" type="video/mp4">
|
||||
Your browser does not support the video tag.
|
||||
</video>
|
||||
|
||||
Walkthrough
|
||||
-----------
|
||||
|
||||
First, in the main :code:`Robot` source file, we add support to periodically update a new simulation-specific object. This logic only gets used while running in simulation:
|
||||
|
||||
.. tab-set-code::
|
||||
|
||||
.. rli:: https://raw.githubusercontent.com/PhotonVision/photonvision/ebef19af3d926cf87292177c9a16d01b71219306/photonlib-java-examples/simaimandrange/src/main/java/frc/robot/Robot.java
|
||||
:language: java
|
||||
:lines: 118-128
|
||||
:linenos:
|
||||
:lineno-start: 118
|
||||
|
||||
Then, we add in the implementation of our new `DrivetrainSim` class. Please reference the `WPILib documentation on physics simulation <https://docs.wpilib.org/en/stable/docs/software/wpilib-tools/robot-simulation/physics-sim.html>`_.
|
||||
|
||||
Simulated Vision support is added with the following steps:
|
||||
|
||||
Creating the Simulated Vision System
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
First, we create a new :code:`SimVisionSystem` to represent our camera and coprocessor running PhotonVision.
|
||||
|
||||
.. tab-set-code::
|
||||
|
||||
.. rli:: https://raw.githubusercontent.com/PhotonVision/photonvision/ebef19af3d926cf87292177c9a16d01b71219306/photonlib-java-examples/simaimandrange/src/main/java/frc/robot/sim/DrivetrainSim.java
|
||||
:language: java
|
||||
:lines: 73-93
|
||||
:linenos:
|
||||
:lineno-start: 72
|
||||
|
||||
Next, we create objects to represent the physical location and size of the vision targets we are calibrated to detect. This example models the down-field high goal vision target from the 2020 and 2021 games.
|
||||
|
||||
.. tab-set-code::
|
||||
|
||||
.. rli:: https://raw.githubusercontent.com/PhotonVision/photonvision/ebef19af3d926cf87292177c9a16d01b71219306/photonlib-java-examples/simaimandrange/src/main/java/frc/robot/sim/DrivetrainSim.java
|
||||
:language: java
|
||||
:lines: 95-111
|
||||
:linenos:
|
||||
:lineno-start: 95
|
||||
|
||||
Finally, we add our target to the simulated vision system.
|
||||
|
||||
.. tab-set-code::
|
||||
|
||||
.. rli:: https://raw.githubusercontent.com/PhotonVision/photonvision/ebef19af3d926cf87292177c9a16d01b71219306/photonlib-java-examples/simaimandrange/src/main/java/frc/robot/sim/DrivetrainSim.java
|
||||
:language: java
|
||||
:lines: 116-117
|
||||
:linenos:
|
||||
:lineno-start: 113
|
||||
|
||||
|
||||
If you have additional targets you want to detect, you can add them in the same way as the first one.
|
||||
|
||||
|
||||
Updating the Simulated Vision System
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Once we have all the properties of our simulated vision system defined, the work to do at runtime becomes very minimal. Simply pass in the robot's pose periodically to the simulated vision system.
|
||||
|
||||
.. tab-set-code::
|
||||
|
||||
.. rli:: https://raw.githubusercontent.com/PhotonVision/photonvision/ebef19af3d926cf87292177c9a16d01b71219306/photonlib-java-examples/simaimandrange/src/main/java/frc/robot/sim/DrivetrainSim.java
|
||||
:language: java
|
||||
:lines: 124-142
|
||||
:linenos:
|
||||
:lineno-start: 122
|
||||
|
||||
|
||||
The rest is done behind the scenes.
|
||||
129
docs/source/docs/examples/simposeest.rst
Normal file
129
docs/source/docs/examples/simposeest.rst
Normal file
@@ -0,0 +1,129 @@
|
||||
Using WPILib Pose Estimation, Simulation, and PhotonVision Together
|
||||
===================================================================
|
||||
|
||||
The following example comes from the PhotonLib example repository (`Java <https://github.com/PhotonVision/photonvision/tree/master/photonlib-java-examples/>`_). Full code is available at that links.
|
||||
|
||||
Knowledge and Equipment Needed
|
||||
-----------------------------------------------
|
||||
|
||||
- Everything required in :ref:`Combining Aiming and Getting in Range <docs/examples/aimandrange:Knowledge and Equipment Needed>`, plus some familiarity with WPILib pose estimation functionality.
|
||||
|
||||
Background
|
||||
----------
|
||||
|
||||
This example builds upon WPILib's `Differential Drive Pose Estimator <https://github.com/wpilibsuite/allwpilib/tree/main/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/differentialdriveposeestimator>`_. It adds a :code:`PhotonCamera` to gather estimates of the robot's position on the field. This in turn can be used for aligning with vision targets, and increasing accuracy of autonomous routines.
|
||||
|
||||
To support simulation, a :code:`SimVisionSystem` is used to drive data into the :code:`PhotonCamera`. The far high goal target from 2020 is modeled.
|
||||
|
||||
Walkthrough
|
||||
-----------
|
||||
|
||||
WPILib's :code:`Pose2d` class is used to represent robot positions on the field.
|
||||
|
||||
Three different :code:`Pose2d` positions are relevant for this example:
|
||||
|
||||
1) Desired Pose: The location some autonomous routine wants the robot to be in.
|
||||
2) Estimated Pose: The location the software `believes` the robot to be in, based on physics models and sensor feedback.
|
||||
3) Actual Pose: The locations the robot is actually at. The physics simulation generates this in simulation, but it cannot be directly measured on the real robot.
|
||||
|
||||
Estimating Pose
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
The :code:`DrivetrainPoseEstimator` class is responsible for generating an estimated robot pose using sensor readings (including PhotonVision).
|
||||
|
||||
Please reference the `WPILib documentation <https://docs.wpilib.org/en/stable/docs/software/advanced-controls/state-space/state-space-pose_state-estimators.html>`_ on using the :code:`DifferentialDrivePoseEstimator` class.
|
||||
|
||||
For both simulation and on-robot code, we create objects to represent the physical location and size of the vision targets we are calibrated to detect. This example models the down-field high goal vision target from the 2020 and 2021 games.
|
||||
|
||||
.. tab-set::
|
||||
|
||||
.. tab-item:: Java
|
||||
:sync: java
|
||||
|
||||
.. rli:: https://raw.githubusercontent.com/PhotonVision/photonvision/80e16ece87c735e30755dea271a56a2ce217b588/photonlib-java-examples/simposeest/src/main/java/frc/robot/Constants.java
|
||||
:language: java
|
||||
:lines: 83-106
|
||||
:linenos:
|
||||
:lineno-start: 83
|
||||
|
||||
|
||||
To incorporate PhotonVision, we need to create a :code:`PhotonCamera`:
|
||||
|
||||
.. tab-set::
|
||||
|
||||
.. tab-item:: Java
|
||||
:sync: java
|
||||
|
||||
.. rli:: https://raw.githubusercontent.com/PhotonVision/photonvision/80e16ece87c735e30755dea271a56a2ce217b588/photonlib-java-examples/simposeest/src/main/java/frc/robot/DrivetrainPoseEstimator.java
|
||||
:language: java
|
||||
:lines: 46
|
||||
:linenos:
|
||||
:lineno-start: 46
|
||||
|
||||
During periodic execution, we read back camera results. If we see a target in the image, we pass the camera-measured pose of the robot to the :code:`DifferentialDrivePoseEstimator`.
|
||||
|
||||
.. tab-set::
|
||||
|
||||
.. tab-item:: Java
|
||||
:sync: java
|
||||
|
||||
.. rli:: https://raw.githubusercontent.com/PhotonVision/photonvision/80e16ece87c735e30755dea271a56a2ce217b588/photonlib-java-examples/simposeest/src/main/java/frc/robot/DrivetrainPoseEstimator.java
|
||||
:language: java
|
||||
:lines: 81-92
|
||||
:linenos:
|
||||
:lineno-start: 81
|
||||
|
||||
|
||||
That's it!
|
||||
|
||||
Simulating the Camera
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
First, we create a new :code:`SimVisionSystem` to represent our camera and coprocessor running PhotonVision.
|
||||
|
||||
.. tab-set::
|
||||
|
||||
.. tab-item:: Java
|
||||
:sync: java
|
||||
|
||||
.. rli:: https://raw.githubusercontent.com/PhotonVision/photonvision/80e16ece87c735e30755dea271a56a2ce217b588/photonlib-java-examples/simposeest/src/main/java/frc/robot/DrivetrainSim.java
|
||||
:language: java
|
||||
:lines: 76-95
|
||||
:linenos:
|
||||
:lineno-start: 76
|
||||
|
||||
|
||||
Then, we add our target to the simulated vision system.
|
||||
|
||||
.. tab-set::
|
||||
|
||||
.. tab-item:: Java
|
||||
:sync: java
|
||||
|
||||
.. rli:: https://raw.githubusercontent.com/PhotonVision/photonvision/80e16ece87c735e30755dea271a56a2ce217b588/photonlib-java-examples/simposeest/src/main/java/frc/robot/DrivetrainSim.java
|
||||
:lines: 97-99
|
||||
:linenos:
|
||||
:lineno-start: 97
|
||||
|
||||
|
||||
If you have additional targets you want to detect, you can add them in the same way as the first one.
|
||||
|
||||
|
||||
Updating the Simulated Vision System
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Once we have all the properties of our simulated vision system defined, the remaining work is minimal. Periodically, pass in the robot's pose to the simulated vision system.
|
||||
|
||||
.. tab-set::
|
||||
|
||||
.. tab-item:: Java
|
||||
:sync: java
|
||||
|
||||
.. rli:: https://raw.githubusercontent.com/PhotonVision/photonvision/80e16ece87c735e30755dea271a56a2ce217b588/photonlib-java-examples/simposeest/src/main/java/frc/robot/DrivetrainSim.java
|
||||
:language: java
|
||||
:lines: 138-139
|
||||
:linenos:
|
||||
:lineno-start: 138
|
||||
|
||||
|
||||
The rest is done behind the scenes.
|
||||
Reference in New Issue
Block a user