Move docs in-source (#1357)

docs/source/docs/pipelines/about-pipelines.rst

@@ -0,0 +1,52 @@
+:orphan:
+
+About Pipelines
+===============
+
+What is a pipeline?
+^^^^^^^^^^^^^^^^^^^
+
+A vision pipeline represents a series of steps that are used to acquire an image, process it, and analyzing it to find a target. In most FRC games, this means processing an image in order to detect a piece of retroreflective tape or an AprilTag.
+
+Types of Pipelines
+^^^^^^^^^^^^^^^^^^
+
+Reflective
+----------
+
+This is the most common pipeline type and it is based on detecting targets with retroreflective tape. In the contours tab of this pipeline type, you can filter the area, width/height ratio, fullness, degree of speckle rejection.
+
+Colored Shape
+-------------
+
+This pipeline type is based on detecting different shapes like circles, triangles, quadrilaterals, or a polygon. An example usage would be detecting yellow PowerCells from the 2020 FRC game. You can read more about the specific settings available in the contours page.
+
+AprilTag / AruCo
+----------------
+
+This pipeline type is based on detecting AprilTag fiducial markers. More information about AprilTags can be found in the WPILib documentation. While being more performance intensive than the reflective and colored shape pipeline, it has the benefit of providing easy to use 3D pose information which allows localization.
+
+.. note:: In order to get 3D Pose data about AprilTags, you are required to :ref:`calibrate your camera<docs/calibration/calibration:Calibrating Your Camera>`.
+
+Note About Multiple Cameras and Pipelines
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When using more than one camera, it is important to keep in mind that all cameras run one pipeline each, all publish to NT, and all send both streams. This will have a noticeable affect on performance and we recommend users limit themselves to 1-2 cameras per coprocessor.
+
+Pipeline Steps
+^^^^^^^^^^^^^^
+Reflective and Colored Shape Pipelines have 4 steps (represented as 4 tabs):
+
+1. Input: This tab allows the raw camera image to be modified before it gets processed. Here, you can set exposure, brightness, gain, orientation, and resolution.
+
+2. Threshold (Only Reflective and Colored Shape): This tabs allows you to filter our specific colors/pixels in your camera stream through HSV tuning. The end goal here is having a black and white image that will only have your target lit up.
+
+3. Contours: After thresholding, contiguous white pixels are grouped together, and described by a curve that outlines the group. This curve is called a "contour" which represent various targets on your screen. Regardless of type, you can filter how the targets are grouped, their intersection, and how the targets are sorted. Other available filters will change based on different pipeline types.
+
+4. Output: Now that you have filtered all of your contours, this allows you to manipulate the detected target via orientation, the offset point, and offset.
+
+AprilTag / AruCo Pipelines have 3 steps:
+
+1. Input: This is the same as the above.
+2. AprilTag: This step include AprilTag specific tuning parameters, such as decimate, blur, threads, pose iterations, and more.
+3. Output: This is the same as the above.

docs/source/docs/pipelines/index.rst

@@ -0,0 +1,8 @@
+Pipelines
+=========
+
+.. toctree::
+
+   about-pipelines
+   input
+   output

docs/source/docs/pipelines/input.rst

@@ -0,0 +1,47 @@
+Camera Tuning / Input
+=====================
+
+PhotonVision's "Input" tab contains settings that affect the image captured by the currently selected camera. This includes camera exposure and brightness, as well as resolution and orientation.
+
+Resolution
+----------
+
+Resolution changes the resolution of the image captured. While higher resolutions are often more accurate than lower resolutions, they also run at a slower update rate.
+
+When using the reflective/colored shape pipeline, detection should be run as low of a resolution as possible as you are only trying to detect simple contours (essentially colored blobs).
+
+When using the AprilTag pipeline, you should try to use as high of a resolution as you can while still maintaining a reasonable FPS measurement. This is because higher resolution allows you to detect tags with higher accuracy and from larger distances.
+
+Exposure and brightness
+-----------------------
+
+Camera exposure and brightness control how bright the captured image will be, although they function differently. Camera exposure changes how long the camera shutter lets in light, which changes the overall brightness of the captured image. This is in contrast to brightness, which is a post-processing effect that boosts the overall brightness of the image at the cost of desaturating colors (making colors look less distinct).
+
+.. important:: For all pipelines, exposure time should be set as low as possible while still allowing for the target to be reliably tracked. This allows for faster processing as decreasing exposure will increase your camera FPS.
+
+For reflective pipelines, after adjusting exposure and brightness, the target should be lit green (or the color of the vision tracking LEDs used). The more distinct the color of the target, the more likely it will be tracked reliably.
+
+.. note:: Unlike with retroreflective tape, AprilTag tracking is not very dependent on lighting consistency. If you have trouble detecting tags due to low light, you may want to try increasing exposure, but this will likely decrease your achievable framerate.
+
+
+AprilTags and Motion Blur
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For AprilTag pipelines, your goal is to reduce the "motion blur" as much as possible. Motion blur is the visual streaking/smearing on the camera stream as a result of movement of the camera or object of focus. You want to mitigate this as much as possible because your robot is constantly moving and you want to be able to read as many tags as you possibly can. The possible solutions to this include:
+
+1. Cranking your exposure as low as it goes and increasing your gain/brightness. This will decrease the effects of motion blur and increase FPS.
+2. Using a global shutter (as opposed to rolling shutter) camera. This should eliminate most, if not all motion blur.
+3. Only rely on tags when not moving.
+
+.. image:: images/motionblur.gif
+    :align: center
+
+Orientation
+-----------
+
+Orientation can be used to rotate the image prior to vision processing. This can be useful for cases where the camera is not oriented parallel to the ground. Do note that this operation can in some cases significantly reduce FPS.
+
+Stream Resolution
+-----------------
+
+This changes the resolution which is used to stream frames from PhotonVision. This does not change the resolution used to perform vision processing. This is useful to reduce bandwidth consumption on the field. In some high-resolution cases, decreasing stream resolution can increase processing FPS.

docs/source/docs/pipelines/output.rst

@@ -0,0 +1,25 @@
+Output
+======
+
+The output card contains sections for target manipulation and offset modes.
+
+Target Manipulation
+-------------------
+
+In this section, the Target Offset Point changes where the "center" of the target is. This can be useful if the pitch/yaw of the middle of the top edge of the target is desired, rather than the center of mass of the target. The "top"/"bottom"/"left"/"right" of the target are defined by the Target Orientation selection. For example, a 400x200px target in landscape mode would have the "top" offset point located at the middle of the uppermost long edge of the target, while in portrait mode the "top" offset point would be located in the middle of the topmost short edge (in this case, either the left or right sides).
+
+This section also includes a switch to enable processing and sending multiple targets, up to 5, simultaneously. This information is available through PhotonLib. Note that the :code:`GetPitch`/:code:`GetYaw` methods will report the pitch/yaw of the "best" (lowest indexed) target.
+
+.. raw:: html
+
+        <video width="85%" controls>
+            <source src="../../_static/assets/offsetandmultiple.mp4" type="video/mp4">
+            Your browser does not support the video tag.
+        </video>
+
+Robot Offset
+------------
+
+PhotonVision offers both single and dual point offset modes. In single point mode, the "Take Point" button will set the crosshair location to the center of the current "best" target.
+
+In dual point mode, two snapshots are required. Take one snapshot with the target far away, and the other with the target closer. The position of the crosshair will be linearly interpolated between these two points based on the area of the current "best" target. This might be useful if single point is not accurate across the range of the tracking distance, or for significantly offset cameras.