Add question about method of powering to bug issue template (#1947)

## Description

A common question is the way that people are powering their coprocs when
we're trying to help debug. Therefore, it would be useful to know when
people open a bug report.

## Meta

Merge checklist:
- [x] Pull Request title is [short, imperative
summary](https://cbea.ms/git-commit/) of proposed changes
- [x] The description documents the _what_ and _why_
- [x] If this PR changes behavior or adds a feature, user documentation
is updated
- [x] If this PR touches photon-serde, all messages have been
regenerated and hashes have not changed unexpectedly
- [x] If this PR touches configuration, this is backwards compatible
with settings back to v2024.3.1
- [x] If this PR touches pipeline settings or anything related to data
exchange, the frontend typing is updated
- [x] If this PR addresses a bug, a regression test for it is added

---------

Co-authored-by: Matt Morley <matthew.morley.ca@gmail.com>

.gitattributes

@@ -35,3 +35,6 @@
 *.so binary
 *.dll binary
 *.webp binary
+
+# autogenerated constrained solve pnp code
+photon-targeting/src/main/native/cpp/photon/constrained_solvepnp/generate/**/* linguist-generated

.github/CODEOWNERS

@@ -1,2 +1,6 @@
 # These owners will be the default owners for everything in the repo.
 *	@PhotonVision/program-devs
+docs/* @PhotonVision/doc-maintainers
+photonlib-java-examples/* @PhotonVision/doc-maintainers
+photonlib-cpp-examples/* @PhotonVision/doc-maintainers
+photonlib-python-examples/* @PhotonVision/doc-maintainers

.github/ISSUE_TEMPLATE/bug_report.md

@@ -22,6 +22,7 @@ If applicable, add screenshots to help explain your problem. Additionally, provi
 
 **Platform:**
  - Hardware Platform (ex. Raspberry Pi 4, Windows x64):
+   - How is it powered? (ex. Zinc-V, Pololu Buck Converter, Battery Bank):
  - Network Configuration (Connection between the Radio and any devices in between, such as a Network Switch):
  - PhotonVision Version:
  - Browser (with Version) (Chrome, Edge, Firefox, etc.):

.github/ISSUE_TEMPLATE/docs_issue.md

@@ -0,0 +1,17 @@
+---
+name: Documentation Request
+about: Something needs to be documented/updated in the documentation
+title: ''
+labels: documentation
+assignees: ''
+
+---
+
+**Are you requesting documentation for a new feature, or updated documentation for an old feature?**
+Put the feature you are requesting documentation for here, along with whether the documentation is stale and needs to be updated, or whether the documentation does not exist, and needs to be created.
+
+**Where is it?**
+Put the location of the documentation that needs to be updated here.  If you're requesting documenation for a new feature, put where you think it should go.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/pull_request_template.md

@@ -0,0 +1,18 @@
+## Description
+
+<!-- What changed? Why? (the code + comments should speak for itself on the "how") -->
+
+<!-- Fun screenshots or a cool video or something are super helpful as well. If this touches platform-specific behavior, this is where test evidence should be collected. -->
+
+<!-- Any issues this pull request closes or pull requests this supersedes should be linked with `Closes #issuenumber`. -->
+
+## Meta
+
+Merge checklist:
+- [ ] Pull Request title is [short, imperative summary](https://cbea.ms/git-commit/) of proposed changes
+- [ ] The description documents the _what_ and _why_
+- [ ] If this PR changes behavior or adds a feature, user documentation is updated
+- [ ] If this PR touches photon-serde, all messages have been regenerated and hashes have not changed unexpectedly
+- [ ] If this PR touches configuration, this is backwards compatible with settings back to v2024.3.1
+- [ ] If this PR touches pipeline settings or anything related to data exchange, the frontend typing is updated
+- [ ] If this PR addresses a bug, a regression test for it is added

.github/workflows/build.yml

@@ -1,15 +1,19 @@
 name: Build
 
 on:
-  # Run on pushes to master and pushed tags, and on pull requests against master, but ignore the docs folder
+  # Run on pushes to main and pushed tags, and on pull requests against main, but ignore the docs folder
   push:
-    branches: [ master ]
+    branches: [ main ]
     tags:
       - 'v*'
   pull_request:
-    branches: [ master ]
+    branches: [ main ]
   merge_group:
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build-client:
     name: "PhotonClient Build"
@@ -205,7 +209,7 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - container: wpilib/roborio-cross-ubuntu:2024-22.04
+          - container: wpilib/roborio-cross-ubuntu:2025-24.04
             artifact-name: Athena
             build-options: "-Ponlylinuxathena"
           - container: wpilib/raspbian-cross-ubuntu:bullseye-22.04
@@ -387,7 +391,7 @@ jobs:
           - os: ubuntu-22.04
             artifact-name: LinuxArm64
             image_suffix: RaspberryPi
-            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.0-beta-4/photonvision_raspi.img.xz
+            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.3/photonvision_raspi.img.xz
             cpu: cortex-a7
             image_additional_mb: 0
             extraOpts: -Djdk.lang.Process.launchMechanism=vfork
@@ -426,55 +430,61 @@ jobs:
           - os: ubuntu-22.04
             artifact-name: LinuxArm64
             image_suffix: RaspberryPi
-            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.0-beta-6/photonvision_raspi.img.xz
+            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.3/photonvision_raspi.img.xz
             cpu: cortex-a7
             image_additional_mb: 0
           - os: ubuntu-22.04
             artifact-name: LinuxArm64
             image_suffix: limelight2
-            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.0-beta-6/photonvision_limelight.img.xz
+            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.3/photonvision_limelight.img.xz
             cpu: cortex-a7
             image_additional_mb: 0
           - os: ubuntu-22.04
             artifact-name: LinuxArm64
             image_suffix: limelight3
-            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.0-beta-6/photonvision_limelight3.img.xz
+            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.3/photonvision_limelight3.img.xz
+            cpu: cortex-a7
+            image_additional_mb: 0
+          - os: ubuntu-22.04
+            artifact-name: LinuxArm64
+            image_suffix: limelight3G
+            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.3/photonvision_limelight3g.img.xz
             cpu: cortex-a7
             image_additional_mb: 0
           - os: ubuntu-22.04
             artifact-name: LinuxArm64
             image_suffix: orangepi5
-            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.0-beta-6/photonvision_opi5.img.xz
+            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.3/photonvision_opi5.img.xz
             cpu: cortex-a8
             image_additional_mb: 1024
           - os: ubuntu-22.04
             artifact-name: LinuxArm64
             image_suffix: orangepi5b
-            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.0-beta-6/photonvision_opi5b.img.xz
+            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.3/photonvision_opi5b.img.xz
             cpu: cortex-a8
             image_additional_mb: 1024
           - os: ubuntu-22.04
             artifact-name: LinuxArm64
             image_suffix: orangepi5plus
-            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.0-beta-6/photonvision_opi5plus.img.xz
+            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.3/photonvision_opi5plus.img.xz
             cpu: cortex-a8
             image_additional_mb: 1024
           - os: ubuntu-22.04
             artifact-name: LinuxArm64
             image_suffix: orangepi5pro
-            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.0-beta-6/photonvision_opi5pro.img.xz
+            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.3/photonvision_opi5pro.img.xz
             cpu: cortex-a8
             image_additional_mb: 1024
           - os: ubuntu-22.04
             artifact-name: LinuxArm64
             image_suffix: orangepi5max
-            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.0-beta-6/photonvision_opi5max.img.xz
+            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.3/photonvision_opi5max.img.xz
             cpu: cortex-a8
             image_additional_mb: 1024
           - os: ubuntu-22.04
             artifact-name: LinuxArm64
             image_suffix: rock5c
-            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.0-beta-7/photonvision_rock5c.img.xz
+            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.3/photonvision_rock5c.img.xz
             cpu: cortex-a8
             image_additional_mb: 1024
 
@@ -547,7 +557,8 @@ jobs:
           rm: true
           files: |
             **/*.xz
-            **/*.jar
+            **/*linux*.jar
+            **/*win*.jar
             **/photonlib*.json
             **/photonlib*.zip
         if: github.event_name == 'push'
@@ -557,16 +568,14 @@ jobs:
       - uses: softprops/action-gh-release@v2.0.9
         with:
           files: |
-            **/*orangepi5*.xz
-            **/*rock5*.xz
+            **/@(*orangepi5*|*rock5*).xz
         if: startsWith(github.ref, 'refs/tags/v')
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - uses: softprops/action-gh-release@v2.0.9
         with:
           files: |
-            **/!(*orangepi5*).xz
-            **/!(*rock5*).xz
+            **/!(*orangepi5*|*rock5*).xz
             **/*.jar
             **/photonlib*.json
             **/photonlib*.zip

.github/workflows/lint-format.yml

@@ -1,13 +1,13 @@
 name: Lint and Format
 
 on:
-  # Run on pushes to master and pushed tags, and on pull requests against master, but ignore the docs folder
+  # Run on pushes to main and pushed tags, and on pull requests against main, but ignore the docs folder
   push:
-    branches: [ master ]
+    branches: [ main ]
     tags:
       - 'v*'
   pull_request:
-    branches: [ master ]
+    branches: [ main ]
   merge_group:
 
 concurrency:
@@ -24,13 +24,13 @@ jobs:
         run: |
           git fetch --prune --unshallow
           git checkout -b pr
-          git branch -f master origin/master
+          git branch -f main origin/main
       - name: Set up Python 3.8
         uses: actions/setup-python@v4
         with:
           python-version: 3.11
       - name: Install wpiformat
-        run: pip3 install wpiformat==2024.45
+        run: pip3 install wpiformat==2025.33
       - name: Run
         run: wpiformat
       - name: Check output
@@ -84,6 +84,6 @@ jobs:
         run: |
           git fetch --prune --unshallow
           git checkout -b pr
-          git branch -f master origin/master
+          git branch -f main origin/main
       - name: Check index.html not changed
-        run: git --no-pager diff --exit-code origin/master photon-server/src/main/resources/web/index.html
+        run: git --no-pager diff --exit-code origin/main photon-server/src/main/resources/web/index.html

.github/workflows/photon-api-docs.yml

@@ -0,0 +1,112 @@
+name: Photon API Documentation
+
+on:
+  # Run on pushes to main and pushed tags, and on pull requests against main, but ignore the docs folder
+  push:
+    branches: [ main ]
+    tags:
+      - 'v*'
+  pull_request:
+    branches: [ main ]
+  merge_group:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build_demo:
+    name: Build PhotonClient Demo
+    defaults:
+      run:
+        working-directory: photon-client
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18
+      - name: Install Dependencies
+        run: npm ci
+      - name: Build Production Client
+        run: npm run build-demo
+      - uses: actions/upload-artifact@v4
+        with:
+          name: built-demo
+          path: photon-client/dist/
+
+  run_api_docs:
+    name: Build API Docs
+    runs-on: "ubuntu-22.04"
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - name: Fetch tags
+      run: git fetch --tags --force
+    - name: Install Java 17
+      uses: actions/setup-java@v4
+      with:
+        java-version: 17
+        distribution: temurin
+    - name: Build javadocs/doxygen
+      run: |
+        chmod +x gradlew
+        ./gradlew photon-docs:generateJavaDocs photon-docs:doxygen
+    - uses: actions/upload-artifact@v4
+      with:
+        name: built-docs
+        path: photon-docs/build/docs
+
+  publish_api_docs:
+    name: Publish API Docs
+    needs: [run_api_docs]
+    runs-on: ubuntu-22.04
+    steps:
+      # Download docs artifact
+      - uses: actions/download-artifact@v4
+        with:
+          name: built-docs
+      - run: find .
+      - name: Publish Docs To Development
+        if: github.ref == 'refs/heads/main'
+        uses: up9cloud/action-rsync@v1.4
+        env:
+          HOST: ${{ secrets.WEBMASTER_SSH_HOST }}
+          USER: ${{ secrets.WEBMASTER_SSH_USERNAME }}
+          KEY: ${{secrets.WEBMASTER_SSH_KEY}}
+          TARGET: /var/www/html/photonvision-docs/development
+      - name: Publish Docs To Release
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: up9cloud/action-rsync@v1.4
+        env:
+          HOST: ${{ secrets.WEBMASTER_SSH_HOST }}
+          USER: ${{ secrets.WEBMASTER_SSH_USERNAME }}
+          KEY: ${{ secrets.WEBMASTER_SSH_KEY }}
+          TARGET: /var/www/html/photonvision-docs/release/
+
+  publish_demo:
+      name: Publish PhotonClient Demo
+      needs: [build_demo]
+      runs-on: ubuntu-22.04
+      steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: built-demo
+      - run: find .
+      - name: Publish demo
+        if: github.ref == 'refs/heads/main'
+        uses: up9cloud/action-rsync@v1.4
+        env:
+          HOST: ${{ secrets.WEBMASTER_SSH_HOST }}
+          USER: ${{ secrets.WEBMASTER_SSH_USERNAME }}
+          KEY: ${{ secrets.WEBMASTER_SSH_KEY }}
+          TARGET: /var/www/html/photonvision-demo

.github/workflows/photon-code-docs.yml

@@ -1,89 +0,0 @@
-name: Photon Code Documentation
-
-on:
-  # Run on pushes to master and pushed tags, and on pull requests against master, but ignore the docs folder
-  push:
-    branches: [ master ]
-    tags:
-      - 'v*'
-  pull_request:
-    branches: [ master ]
-  merge_group:
-
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  build-client:
-    name: "PhotonClient Build"
-    defaults:
-      run:
-        working-directory: photon-client
-    runs-on: ubuntu-22.04
-    steps:
-      - uses: actions/checkout@v4
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 18
-      - name: Install Dependencies
-        run: npm ci
-      - name: Build Production Client
-        run: npm run build-demo
-      - uses: actions/upload-artifact@v4
-        with:
-          name: built-client
-          path: photon-client/dist/
-
-  run_docs:
-    runs-on: "ubuntu-22.04"
-    steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
-      with:
-        fetch-depth: 0
-    - name: Fetch tags
-      run: git fetch --tags --force
-    - name: Install Java 17
-      uses: actions/setup-java@v4
-      with:
-        java-version: 17
-        distribution: temurin
-
-    - name: Build javadocs/doxygen
-      run: |
-        chmod +x gradlew
-        ./gradlew photon-docs:generateJavaDocs photon-docs:doxygen
-
-    - uses: actions/upload-artifact@v4
-      with:
-        name: built-docs
-        path: photon-docs/build/docs
-
-  release:
-    needs: [build-client, run_docs]
-
-    runs-on: ubuntu-22.04
-    steps:
-
-      # Download literally every single artifact.
-      - uses: actions/download-artifact@v4
-
-      - run: find .
-      - name: copy file via ssh password
-        if: github.ref == 'refs/heads/master'
-        uses: appleboy/scp-action@v0.1.7
-        with:
-          host: ${{ secrets.WEBMASTER_SSH_HOST }}
-          username: ${{ secrets.WEBMASTER_SSH_USERNAME }}
-          password: ${{ secrets.WEBMASTER_SSH_KEY }}
-          port: ${{ secrets.WEBMASTER_SSH_PORT }}
-          source: "*"
-          target: /var/www/html/photonvision-docs/

.github/workflows/photonvision-rtd.yml

@@ -1,17 +1,22 @@
-name: PhotonVision Sphinx Documentation Checks
+name: PhotonVision ReadTheDocs Checks
 
 on:
   push:
-    branches: [ master ]
+    branches: [ main ]
   pull_request:
-    branches: [ master ]
+    branches: [ main ]
   merge_group:
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
 env:
   GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
 jobs:
   build:
+    name: Build and Check Docs
     runs-on: ubuntu-22.04
 
     steps:

.github/workflows/python.yml

@@ -5,13 +5,17 @@ permissions:
 
 on:
   push:
-    branches: [ master ]
+    branches: [ main ]
     tags:
       - 'v*'
   pull_request:
-    branches: [ master ]
+    branches: [ main ]
   merge_group:
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
 jobs:
   buildAndDeploy:
     runs-on: ubuntu-22.04

.github/workflows/website.yml

@@ -0,0 +1,48 @@
+name: Website
+
+on:
+  push:
+    # For now, run on all commits to main
+    branches: [ main ]
+    tags:
+      - 'v*'
+  pull_request:
+    branches: [ main ]
+  merge_group:
+
+jobs:
+  rsync:
+    name: Build and Sync Files
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+      - name: Install packages
+        run: npm ci
+        working-directory: website
+      - name: Build project
+        run: npm run build
+        working-directory: website
+      - uses: up9cloud/action-rsync@v1.4
+        if: github.ref == 'refs/heads/main'
+        env:
+          HOST: ${{ secrets.WEBMASTER_SSH_HOST }}
+          USER: ${{ secrets.WEBMASTER_SSH_USERNAME }}
+          KEY: ${{secrets.WEBMASTER_SSH_KEY}}
+          SOURCE: website/dist/*
+          TARGET: /var/www/html/photonvision-website
+
+  format-check:
+    name: Check Formatting
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+      - name: Install Packages
+        run: npm ci
+        working-directory: website
+      - name: Run Formatting Check
+        run: npx prettier -c .
+        working-directory: website

.gitignore

@@ -1,19 +1,13 @@
-Python/__pycache__/WebSiteHandler\.cpython-37\.pyc
-
 \.idea/
 
 *.pyc
-
-Python/app/__pycache__/
-
-Python/app/handlers/__pycache__/
-
-\.vscode/
+__pycache__/
 
 /.vs
-
 backend/settings/
-/.vscode/
+.vscode/
+# Docs
+_build
 # Compiled class file
 *.class
 
@@ -109,7 +103,6 @@ fabric.properties
 
 # Temporary build files
 **/.gradle
-**/target
 **/src/main/java/META-INF
 **/.settings
 **/.classpath
@@ -125,8 +118,6 @@ compile_commands.json
 .clangd/
 .cache/
 
-New client/photon-client/*
-
 *.prefs
 *.jfr
 .DS_Store
@@ -146,7 +137,12 @@ photonlib-cpp-examples/*/vendordeps/*
 photonlib-cpp-examples/*/networktables.json.bck
 photonlib-java-examples/*/networktables.json.bck
 *.sqlite
-photon-server/src/main/resources/web/*
 venv
 .venv/*
 .venv
+networktables.json
+# Web stuff
+photon-server/src/main/resources/web/*
+node_modules
+dist
+components.d.ts

.styleguide

@@ -19,8 +19,12 @@ modifiableFileExclude {
   \.webp$
   \.ico$
   \.rknn$
+  \.mp4$
+  \.ttf$
+  \.woff2$
   gradlew
   photon-lib/py/photonlibpy/generated/
+  photon-targeting/src/main/native/cpp/photon/constrained_solvepnp/generate/
   photon-targeting/src/generated/
 }
 

README.md

@@ -1,6 +1,6 @@
 # PhotonVision
 
-[![CI](https://github.com/PhotonVision/photonvision/workflows/CI/badge.svg)](https://github.com/PhotonVision/photonvision/actions?query=workflow%3ACI) [![codecov](https://codecov.io/gh/PhotonVision/photonvision/branch/master/graph/badge.svg)](https://codecov.io/gh/PhotonVision/photonvision) [![Discord](https://img.shields.io/discord/725836368059826228?color=%23738ADB&label=Join%20our%20Discord&logo=discord&logoColor=white)](https://discord.gg/wYxTwym)
+[![Discord](https://img.shields.io/discord/725836368059826228?color=%23738ADB&label=Join%20our%20Discord&logo=discord&logoColor=white)](https://discord.gg/wYxTwym)
 
 PhotonVision is the free, fast, and easy-to-use computer vision solution for the *FIRST* Robotics Competition. You can read an overview of our features [on our website](https://photonvision.org). You can find our comprehensive documentation [here](https://docs.photonvision.org).
 
@@ -42,6 +42,7 @@ Note that these are case sensitive!
     * linuxathena
 - `-PtgtIP`: Specifies where `./gradlew deploy` should try to copy the fat JAR to
 - `-Pprofile`: enables JVM profiling
+- `-PwithSanitizers`: On Linux, enables `-fsanitize=address,undefined,leak`
 
 If you're cross-compiling, you'll need the wpilib toolchain installed. This can be done via Gradle: for example `./gradlew installArm64Toolchain` or `./gradlew installRoboRioToolchain`
 
@@ -67,7 +68,7 @@ sudo apt install libcholmod3 liblapack3 libsuitesparseconfig5
 
 PhotonVision was forked from [Chameleon Vision](https://github.com/Chameleon-Vision/chameleon-vision/). Thank you to everyone who worked on the original project.
 
-* [WPILib](https://github.com/wpilibsuite) - Specifically [cscore](https://github.com/wpilibsuite/allwpilib/tree/master/cscore), [CameraServer](https://github.com/wpilibsuite/allwpilib/tree/master/cameraserver), [NTCore](https://github.com/wpilibsuite/allwpilib/tree/master/ntcore), and [OpenCV](https://github.com/wpilibsuite/thirdparty-opencv).
+* [WPILib](https://github.com/wpilibsuite) - Specifically [cscore](https://github.com/wpilibsuite/allwpilib/tree/main/cscore), [CameraServer](https://github.com/wpilibsuite/allwpilib/tree/main/cameraserver), [NTCore](https://github.com/wpilibsuite/allwpilib/tree/main/ntcore), and [OpenCV](https://github.com/wpilibsuite/thirdparty-opencv).
 
 * [Apache Commons](https://commons.apache.org/) - Specifically [Commons Math](https://commons.apache.org/proper/commons-math/), and [Commons Lang](https://commons.apache.org/proper/commons-lang/)
 

build.gradle

@@ -1,14 +1,17 @@
 import edu.wpi.first.toolchain.*
 
 plugins {
-    id "java"
     id "cpp"
     id "com.diffplug.spotless" version "6.24.0"
     id "edu.wpi.first.wpilib.repositories.WPILibRepositoriesPlugin" version "2020.2"
-    id "edu.wpi.first.GradleRIO" version "2025.1.1-beta-3"
+    id "edu.wpi.first.GradleRIO" version "2025.3.2"
     id 'edu.wpi.first.WpilibTools' version '1.3.0'
     id 'com.google.protobuf' version '0.9.3' apply false
     id 'edu.wpi.first.GradleJni' version '1.1.0'
+    id "org.ysb33r.doxygen" version "1.0.4" apply false
+    id 'com.gradleup.shadow' version '8.3.4' apply false
+    id "com.github.node-gradle.node" version "7.0.1" apply false
+    id "org.hidetake.ssh" version "2.11.2" apply false
 }
 
 allprojects {
@@ -30,14 +33,13 @@ ext.allOutputsFolder = file("$project.buildDir/outputs")
 apply from: "versioningHelper.gradle"
 
 ext {
-    wpilibVersion = "2025.1.1-beta-3"
+    wpilibVersion = "2025.3.2"
     wpimathVersion = wpilibVersion
     openCVYear = "2025"
     openCVversion = "4.10.0-3"
-    joglVersion = "2.4.0"
     javalinVersion = "5.6.2"
-    libcameraDriverVersion = "v2025.0.0"
-    rknnVersion = "v2025.0.0"
+    libcameraDriverVersion = "v2025.0.3"
+    rknnVersion = "dev-v2025.0.0-1-g33b6263"
     frcYear = "2025"
     mrcalVersion = "v2025.0.0";
 
@@ -87,16 +89,6 @@ spotless {
         trimTrailingWhitespace()
         endWithNewline()
     }
-    format 'xml', {
-        target fileTree('.') {
-            include '**/*.xml'
-            exclude '**/build/**', '**/build-*/**', "**/.idea/**"
-        }
-        eclipseWtp('xml')
-        trimTrailingWhitespace()
-        indentWithSpaces(2)
-        endWithNewline()
-    }
     format 'misc', {
         target fileTree('.') {
             include '**/*.md', '**/.gitignore'

docs/.gitignore

@@ -1,9 +0,0 @@
-build/*
-.DS_Store
-.vscode/*
-.idea/*
-source/_build
-source/docs/_build
-
-venv/*
-.venv/*

docs/.styleguide

@@ -12,5 +12,6 @@ modifiableFileExclude {
   \.ico$
   \.rknn$
   \.svg$
+  \.woff2$
   gradlew
 }

docs/README.MD

@@ -6,4 +6,4 @@ PhotonVision is a free open-source vision processing software for FRC teams.
 
 This repository is the source code for our ReadTheDocs documentation, which can be found [here](https://docs.photonvision.org).
 
-[Contribution and formatting guidelines for this project](https://docs.photonvision.org/en/latest/docs/contributing/photonvision-docs/index.html)
+[Contribution and formatting guidelines for this project](https://docs.photonvision.org/en/latest/docs/contributing/index.html)

docs/requirements.txt

@@ -1,44 +1,59 @@
-alabaster==0.7.13
-Babel==2.13.1
-beautifulsoup4==4.12.2
-certifi==2023.11.17
-charset-normalizer==3.3.2
+alabaster==1.0.0
+anyio==4.9.0
+babel==2.17.0
+beautifulsoup4==4.13.3
+certifi==2025.1.31
+charset-normalizer==3.4.1
+click==8.1.8
 colorama==0.4.6
-doc8==0.11.2
+doc8==1.1.2
 docopt==0.6.2
-docutils==0.18.1
-furo==2023.9.10
-idna==3.4
+docutils==0.21.2
+furo==2024.8.6
+h11==0.14.0
+idna==3.10
 imagesize==1.4.1
-Jinja2==3.0.3
-MarkupSafe==2.1.3
-packaging==23.2
-pbr==6.0.0
+Jinja2==3.1.6
+markdown-it-py==3.0.0
+MarkupSafe==3.0.2
+mdit-py-plugins==0.4.2
+mdurl==0.1.2
+myst-parser==4.0.1
+packaging==24.2
+pbr==6.1.1
 pipreqs==0.4.13
-Pygments==2.17.1
-requests==2.31.0
-restructuredtext-lint==1.4.0
-six==1.16.0
+Pygments==2.19.1
+PyYAML==6.0.2
+requests==2.32.3
+restructuredtext_lint==1.4.0
+roman-numerals-py==3.1.0
+setuptools==77.0.3
+six==1.17.0
+sniffio==1.3.1
 snowballstemmer==2.2.0
-soupsieve==2.5
-Sphinx==7.2.6
+soupsieve==2.6
+Sphinx==8.2.3
+sphinx-autobuild==2024.10.3
 sphinx-basic-ng==1.0.0b2
-sphinx-notfound-page==1.0.0
-sphinx-rtd-theme==1.3.0
-sphinx-tabs==3.4.4
-sphinx_design==0.5.0
-sphinxcontrib-applehelp==1.0.7
-sphinxcontrib-devhelp==1.0.5
+sphinx-notfound-page==1.1.0
+sphinx-rtd-theme==3.0.2
+sphinx-tabs==3.4.7
+sphinx_design==0.6.1
+sphinxcontrib-applehelp==2.0.0
+sphinxcontrib-devhelp==2.0.0
 sphinxcontrib-ghcontributors==0.2.3
-sphinxcontrib-htmlhelp==2.0.4
+sphinxcontrib-htmlhelp==2.1.0
 sphinxcontrib-jquery==4.1
 sphinxcontrib-jsmath==1.0.1
-sphinxcontrib-qthelp==1.0.6
-sphinxcontrib-serializinghtml==1.1.9
-sphinxext-opengraph==0.9.0
-sphinxext-remoteliteralinclude==0.4.0
-stevedore==5.1.0
-urllib3==2.1.0
-yarg==0.1.9
-sphinx-autobuild==2024.4.16
-myst_parser==3.0.1
+sphinxcontrib-qthelp==2.0.0
+sphinxcontrib-serializinghtml==2.0.0
+sphinxext-opengraph==0.9.1
+sphinxext-remoteliteralinclude==0.5.0
+starlette==0.46.1
+stevedore==5.4.1
+typing_extensions==4.12.2
+urllib3==2.3.0
+uvicorn==0.34.0
+watchfiles==1.0.4
+websockets==15.0.1
+yarg==0.1.10

docs/source/_static/css/pv-icons.css

@@ -1,16 +1,3 @@
-/*!
- *  Font Awesome 4.7.0 by @davegandy - http://fontawesome.io - @fontawesome
- *  License - http://fontawesome.io/license (Font: SIL OFL 1.1, CSS: MIT License)
- */
-
-@font-face {
-    font-family: FontAwesome;
-    src: url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713);
-    src: url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix&v=4.7.0) format("embedded-opentype"), url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"), url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"), url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"), url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#fontawesomeregular) format("svg");
-    font-weight: 400;
-    font-style:normal
-}
-
 .code-block-caption>.headerlink, dl dt>.headerlink, h1>.headerlink, h2>.headerlink, h3>.headerlink, h4>.headerlink, h5>.headerlink, h6>.headerlink, p.caption>.headerlink, table>caption>.headerlink {
     font-family: FontAwesome;
     font-size: 0.75em;

docs/source/_static/css/v4-font-face.min.css

@@ -0,0 +1,6 @@
+/*!
+ * Font Awesome Free 6.7.2 by @fontawesome - https://fontawesome.com
+ * License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License)
+ * Copyright 2024 Fonticons, Inc.
+ */
+@font-face{font-family:"FontAwesome";font-display:block;src:url(../webfonts/fa-solid-900.woff2) format("woff2"),url(../webfonts/fa-solid-900.ttf) format("truetype")}@font-face{font-family:"FontAwesome";font-display:block;src:url(../webfonts/fa-brands-400.woff2) format("woff2"),url(../webfonts/fa-brands-400.ttf) format("truetype")}@font-face{font-family:"FontAwesome";font-display:block;src:url(../webfonts/fa-regular-400.woff2) format("woff2"),url(../webfonts/fa-regular-400.ttf) format("truetype");unicode-range:u+f003,u+f006,u+f014,u+f016-f017,u+f01a-f01b,u+f01d,u+f022,u+f03e,u+f044,u+f046,u+f05c-f05d,u+f06e,u+f070,u+f087-f088,u+f08a,u+f094,u+f096-f097,u+f09d,u+f0a0,u+f0a2,u+f0a4-f0a7,u+f0c5,u+f0c7,u+f0e5-f0e6,u+f0eb,u+f0f6-f0f8,u+f10c,u+f114-f115,u+f118-f11a,u+f11c-f11d,u+f133,u+f147,u+f14e,u+f150-f152,u+f185-f186,u+f18e,u+f190-f192,u+f196,u+f1c1-f1c9,u+f1d9,u+f1db,u+f1e3,u+f1ea,u+f1f7,u+f1f9,u+f20a,u+f247-f248,u+f24a,u+f24d,u+f255-f25b,u+f25d,u+f271-f274,u+f278,u+f27b,u+f28c,u+f28e,u+f29c,u+f2b5,u+f2b7,u+f2ba,u+f2bc,u+f2be,u+f2c0-f2c1,u+f2c3,u+f2d0,u+f2d2,u+f2d4,u+f2dc}@font-face{font-family:"FontAwesome";font-display:block;src:url(../webfonts/fa-v4compatibility.woff2) format("woff2"),url(../webfonts/fa-v4compatibility.ttf) format("truetype");unicode-range:u+f041,u+f047,u+f065-f066,u+f07d-f07e,u+f080,u+f08b,u+f08e,u+f090,u+f09a,u+f0ac,u+f0ae,u+f0b2,u+f0d0,u+f0d6,u+f0e4,u+f0ec,u+f10a-f10b,u+f123,u+f13e,u+f148-f149,u+f14c,u+f156,u+f15e,u+f160-f161,u+f163,u+f175-f178,u+f195,u+f1f8,u+f219,u+f27a}

docs/source/conf.py

@@ -45,7 +45,7 @@ extensions = [
 
 ogp_site_url = "https://docs.photonvision.org/en/latest/"
 ogp_site_name = "PhotonVision Documentation"
-ogp_image = "https://raw.githubusercontent.com/PhotonVision/photonvision-docs/master/source/assets/RectLogo.png"
+ogp_image = "https://raw.githubusercontent.com/PhotonVision/photonvision-docs/main/source/assets/RectLogo.png"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -79,6 +79,7 @@ source_suffix = [".rst", ".md"]
 
 
 def setup(app):
+    app.add_css_file("css/v4-font-face.min.css")
     app.add_css_file("css/pv-icons.css")
 
 
@@ -86,6 +87,9 @@ pygments_style = "sphinx"
 
 html_theme_options = {
     "sidebar_hide_name": True,
+    "top_of_page_buttons": ["view", "edit"],
+    "source_edit_link": "https://github.com/PhotonVision/photonvision/edit/main/docs/source/{filename}",
+    "source_view_link": "https://github.com/PhotonVision/photonvision/blob/main/docs/source/{filename}",
     "light_logo": "assets/PhotonVision-Header-onWhite.png",
     "dark_logo": "assets/PhotonVision-Header-noBG.png",
     "light_css_variables": {

docs/source/docs/additional-resources/best-practices.md

@@ -3,27 +3,35 @@
 ## Before Competition
 
 - Ensure you have spares of the relevant electronics if you can afford it (switch, coprocessor, cameras, etc.).
-- Download the latest release .jar onto your computer and update your Pi if necessary (only update if the release is labeled "critical" or similar, we do not recommend updating right before an event in case there are unforeseen bugs).
-- Test out PhotonVision at your home setup.
-- Ensure that you have set up SmartDashboard / Shuffleboard to view your camera streams during matches.
-- Follow all the recommendations under the Networking section in installation (network switch and static IP).
-- Use high quality ethernet cables that have been rigorously tested.
-- Set up port forwarding using the guide in the Networking section in installation.
+- Stay on the latest version of PhotonVision until you have tested your full robot system to be functional.
+- Some time before the competition, lock down the version you are using and do not upgrade unless you encounter a critical bug.
+- Have a copy of the installation image for the version you are using on your programming laptop, in case re-imaging (without internet) is needed.
+- Extensively test at your home setup. Practice tuning from scratch under different lighting conditions.
+- Confirm you have followed all the recommendations under the {ref}`Networking<docs/quick-start/networking:Networking>` documentation (network switch and static IP).
+- Only use high quality ethernet cables that have been rigorously tested.
+
+## Camera Streaming
+- All camera streams are published under the NetworkTables table `CameraPublisher`.
+- The only subtable under `CameraPublisher` that will work for viewing a driver mode camera stream is the one that contains `Output` in the name.
+- To view a camera stream in a dashboard, drag the correct subtable from the NetworkTables tree into your dashboard.
+- Use the latest driver dashboard recommended by [WPILib](https://docs.wpilib.org/en/stable/docs/software/dashboards/dashboard-intro.html) on your driver station laptop.
 
 ## During the Competition
 
-- Make sure you take advantage of the field calibration time given at the start of the event:
-    - Bring your robot to the field at the allotted time.
-    - Turn on your robot and pull up the dashboard on your driver station.
-    - Point your robot at the AprilTags(s) and ensure you get a consistent tracking (you hold one AprilTag consistently, the ceiling lights aren't detected, etc.).
-    - If you have problems with your pipeline, go to the pipeline tuning section and retune the pipeline using the guide there.
-    - Move the robot close, far, angled, and around the field to ensure no extra AprilTags are found.
-    - Go to a practice match to ensure everything is working correctly.
+- Use the field calibration time given at the start of the event:
+  - Bring your robot to the field at the allotted time.
+  - Make sure the field has match-accurate lighting conditions active.
+  - Turn on your robot and pull up the dashboard on your driver station.
+  - Point your robot at the targets and ensure you get a consistent tracking (you hold one targets consistently, the ceiling lights aren't detected, etc.).
+  - If you have problems with your pipeline, retune the pipeline following the {ref}`camera tuning <docs/pipelines/input:Camera Tuning / Input>` documentation.
+  - Move the robot close, far, angled, and around the field to ensure no extra targets are found.
+  - Monitor camera feeds during a practice match to ensure everything is working correctly.
 - After field calibration, use the "Export Settings" button in the "Settings" page to create a backup.
-    - Do this for each coprocessor on your robot that runs PhotonVision, and name your exports with meaningful names.
-    - This will contain camera information/calibration, pipeline information, network settings, etc.
-    - In the event of software/hardware failures (IE lost SD Card, broken device), you can then use the "Import Settings" button and select "All Settings" to restore your settings.
-    - This effectively works as a snapshot of your PhotonVision data that can be restored at any point.
-- Before every match, check the ethernet connection going into your coprocessor and that it is seated fully.
-- Ensure that exposure is as low as possible and that you don't have the dashboard up when you don't need it to reduce bandwidth.
+  - Do this for each coprocessor on your robot that runs PhotonVision, and name your exports with meaningful names.
+  - This will contain camera information/calibration, pipeline information, network settings, etc.
+  - In the event of software/hardware failures (IE lost SD Card, broken device), you can then use the "Import Settings" button and select "All Settings" to restore your settings.
+  - This effectively works as a snapshot of your PhotonVision data that can be restored at any point.
+- Before every match:
+  - Check the ethernet and USB connectors are seated fully.
+  - Close streaming dashboards when you don't need them to reduce bandwidth.
 - Stream at as low of a resolution as possible while still detecting AprilTags to stay within field bandwidth limits.

docs/source/docs/additional-resources/config.md

@@ -48,3 +48,6 @@ A variety of files can be imported back into PhotonVision:
     - {code}`hardwareSettings.json`
     - {code}`networkSettings.json`
   - Useful for simple hardware or network configuration tasks without overwriting all settings.
+
+
+

docs/source/docs/advanced-installation/prerelease-software.md

@@ -1,12 +1,12 @@
 # Installing Pre-Release Versions
 
-Pre-release/development version of PhotonVision can be tested by installing/downloading artifacts from Github Actions (see below), which are built automatically on commits to open pull requests and to PhotonVision's `master` branch, or by {ref}`compiling PhotonVision locally <docs/contributing/building-photon:Build Instructions>`.
+Pre-release/development version of PhotonVision can be tested by installing/downloading artifacts from Github Actions (see below), which are built automatically on commits to open pull requests and to PhotonVision's `main` branch, or by {ref}`compiling PhotonVision locally <docs/contributing/building-photon:Build Instructions>`.
 
 :::{warning}
 If testing a pre-release version of PhotonVision with a robot, PhotonLib must be updated to match the version downloaded! If not, packet schema definitions may not match and unexpected things will occur. To update PhotonLib, refer to {ref}`installing specific version of PhotonLib<docs/programming/photonlib/adding-vendordep:Install Specific Version - Java/C++>`.
 :::
 
-GitHub Actions builds pre-release version of PhotonVision automatically on PRs and on each commit merged to master. To test a particular commit to master, navigate to the [PhotonVision commit list](https://github.com/PhotonVision/photonvision/commits/master/) and click on the check mark (below). Scroll to "Build / Build fat JAR - PLATFORM", click details, and then summary. From here, JAR and image files can be downloaded to be flashed or uploaded using "Offline Update".
+GitHub Actions builds pre-release version of PhotonVision automatically on PRs and on each commit merged to main. To test a particular commit to main, navigate to the [PhotonVision commit list](https://github.com/PhotonVision/photonvision/commits/main/) and click on the check mark (below). Scroll to "Build / Build fat JAR - PLATFORM", click details, and then summary. From here, JAR and image files can be downloaded to be flashed or uploaded using "Offline Update".
 
 ```{image} images/gh_actions_1.png
 :alt: Github Actions Badge

docs/source/docs/advanced-installation/sw_install/mac-os.md

@@ -23,7 +23,7 @@ Using a JDK other than JDK17 will cause issues when running PhotonVision and is
 Go to the [GitHub releases page](https://github.com/PhotonVision/photonvision/releases) and download the relevant .jar file for your coprocessor.
 
 :::{note}
-If you have an M1/M2 Mac, download the macarm64.jar file.
+If you have an M Series Mac, download the macarm64.jar file.
 
 If you have an Intel based Mac, download the macx64.jar file.
 :::

docs/source/docs/advanced-installation/sw_install/romi.md

@@ -15,12 +15,12 @@ SSH into the Raspberry Pi (using Windows command line, or a tool like [Putty](ht
 :::{attention}
 The version of WPILibPi for the Romi is 2023.2.1, which is not compatible with the current version of PhotonVision. **If you are using WPILibPi 2023.2.1 on your Romi, you must install PhotonVision v2023.4.2 or earlier!**
 
-To install a compatible version of PhotonVision, enter these commands in the SSH terminal connected to the Raspberry Pi. This will download and run the install script, which will intall PhotonVision on your Raspberry Pi and configure it to run at startup.
+To install a compatible version of PhotonVision, enter these commands in the SSH terminal connected to the Raspberry Pi. This will download and run the install script, which will install PhotonVision on your Raspberry Pi and configure it to run at startup.
 
 ```bash
 $ wget https://git.io/JJrEP -O install.sh
 $ sudo chmod +x install.sh
-$ sudo ./install.sh -v 2023.4.2
+$ sudo ./install.sh -v v2023.4.2
 ```
 The install script requires an internet connection, so connecting the Raspberry Pi to an internet-connected router via an Ethernet cable will be the easiest solution. The pi must remain writable while you are following these steps!
 :::
@@ -32,7 +32,7 @@ Next, from the SSH terminal, run `sudo nano /home/pi/runCamera` then arrow down
 
 ```
 
-After the Romi reboots, you should be able to open the PhotonVision UI at: [`http://10.0.0.2:5800/`](http://10.0.0.2:5800/). From here, you can adjust {ref}`Settings <docs/settings:Settings>` and configure {ref}`Pipelines <docs/pipelines/index:Pipelines>`.
+After the Romi reboots, you should be able to open the PhotonVision UI at: [`http://10.0.0.2:5800/`](http://10.0.0.2:5800/). From here, you can adjust settings and configure {ref}`Pipelines <docs/pipelines/index:Pipelines>`.
 
 :::{warning}
 In order for settings, logs, etc. to be saved / take effect, ensure that PhotonVision is in writable mode.

docs/source/docs/advanced-installation/sw_install/windows-pc.md

@@ -12,7 +12,7 @@ Bonjour provides more stable networking when using Windows PCs. Install [Bonjour
 
 ## Installing Java
 
-PhotonVision requires a JDK installed and on the system path. **JDK 17 is needed. Windows Users must use the JDK that ships with WPILib.** [Download and install it from here.](https://github.com/wpilibsuite/allwpilib/releases/tag/v2025.1.1-beta-3) Either ensure the only Java on your PATH is the WPILIB Java or specify it to gradle with `-Dorg.gradle.java.home=C:\Users\Public\wpilib\2025\jdk`:
+PhotonVision requires a JDK installed and on the system path. **JDK 17 is needed. Windows Users must use the JDK that ships with WPILib.** [Download and install it from here.](https://github.com/wpilibsuite/allwpilib/releases/tag/v2025.3.2) Either ensure the only Java on your PATH is the WPILIB Java or specify it to gradle with `-Dorg.gradle.java.home=C:\Users\Public\wpilib\2025\jdk`:
 
 ```
 > ./gradlew run "-Dorg.gradle.java.home=C:\Users\Public\wpilib\2025\jdk"

docs/source/docs/apriltag-pipelines/2D-tracking-tuning.md

@@ -21,7 +21,9 @@ AprilTag pipelines come with reasonable defaults to get you up and running with
 
 ### Target Family
 
-Target families are defined by two numbers (before and after the h). The first number is the number of bits the tag is able to encode (which means more tags are available in the respective family) and the second is the hamming distance. Hamming distance describes the ability for error correction while identifying tag ids. A high hamming distance generally means that it will be easier for a tag to be identified even if there are errors. However, as hamming distance increases, the number of available tags decreases. The 2024 FRC game will be using 36h11 tags, which can be found [here](https://github.com/AprilRobotics/apriltag-imgs/tree/master/tag36h11).
+Target families are defined by two numbers (before and after the h). The first number is the number of bits the tag is able to encode (which means more tags are available in the respective family) and the second is the hamming distance. Hamming distance describes the ability for error correction while identifying tag ids. A high hamming distance generally means that it will be easier for a tag to be identified even if there are errors. However, as hamming distance increases, the number of available tags decreases.
+
+The 2025 FRC game will be using 36h11 tags, which can be found [here](https://github.com/AprilRobotics/apriltag-imgs/tree/main/tag36h11).
 
 ### Decimate
 

docs/source/docs/apriltag-pipelines/3D-tracking.md

@@ -1,10 +1,10 @@
 # 3D Tracking
 
-3D AprilTag tracking will allow you to track the real-world position and rotation of a tag relative to the camera's image sensor. This is useful for robot pose estimation and other applications like autonomous scoring. In order to use 3D tracking, you must first {ref}`calibrate your camera <docs/calibration/calibration:Calibrating Your Camera>`. Once you have, you need to enable 3D mode in the UI and you will now be able to get 3D pose information from the tag! For information on getting and using this information in your code, see {ref}`the programming reference. <docs/programming/index:Programming Reference>`.
+3D AprilTag tracking will allow you to track the real-world position and rotation of a tag relative to the camera's image sensor. This is useful for robot pose estimation and other applications like autonomous scoring. In order to use 3D tracking, you must first {ref}`calibrate your camera <docs/calibration/calibration:Calibrating Your Camera>`. Once you have, you need to enable 3D mode in the UI and you will now be able to get 3D pose information from the tag! For information on getting and using this information in your code, see {ref}`the programming reference <docs/programming/index:Programming Reference>`.
 
 ## Ambiguity
 
-Translating from 2D to 3D using data from the calibration and the four tag corners can lead to "pose ambiguity", where it appears that the AprilTag pose is flipping between two different poses. You can read more about this issue `here. <https://docs.wpilib.org/en/stable/docs/software/vision-processing/apriltag/apriltag-intro.html#d-to-3d-ambiguity>` Ambiguity is calculated as the ratio of reprojection errors between two pose solutions (if they exist), where reprojection error is the error corresponding to the image distance between where the apriltag's corners are detected vs where we expect to see them based on the tag's estimated camera relative pose.
+Translating from 2D to 3D using data from the calibration and the four tag corners can lead to "pose ambiguity", where it appears that the AprilTag pose is flipping between two different poses. You can read more about this issue [here](https://docs.wpilib.org/en/stable/docs/software/vision-processing/apriltag/apriltag-intro.html#d-to-3d-ambiguity). Ambiguity is calculated as the ratio of reprojection errors between two pose solutions (if they exist), where reprojection error is the error corresponding to the image distance between where the apriltag's corners are detected vs where we expect to see them based on the tag's estimated camera relative pose.
 
 There are a few steps you can take to resolve/mitigate this issue:
 

docs/source/docs/apriltag-pipelines/about-apriltags.md

@@ -10,5 +10,5 @@ AprilTags are a common type of visual fiducial marker. Visual fiducial markers a
 A more technical explanation can be found in the [WPILib documentation](https://docs.wpilib.org/en/latest/docs/software/vision-processing/apriltag/apriltag-intro.html).
 
 :::{note}
-You can get FIRST's [official PDF of the targets used in 2024 here](https://firstfrc.blob.core.windows.net/frc2024/FieldAssets/Apriltag_Images_and_User_Guide.pdf).
+You can get FIRST's [official PDF of the targets used in 2025 here](https://firstfrc.blob.core.windows.net/frc2025/FieldAssets/Apriltag_Images_and_User_Guide.pdf).
 :::

docs/source/docs/apriltag-pipelines/detector-types.md

@@ -12,4 +12,4 @@ The AprilTag pipeline type is based on the [AprilTag](https://april.eecs.umich.e
 
 ## AruCo
 
-The AruCo pipeline is based on the [AruCo](https://docs.opencv.org/4.8.0/d9/d6a/group__aruco.html) library implementation from OpenCV. It is ~2x higher fps and ~2x lower latency than the AprilTag pipeline type, but is less accurate. We recommend this pipeline type for teams that need to run at a higher framerate or have a lower powered device. This pipeline type is new for the 2024 season and is not as well tested as AprilTag.
+The AruCo pipeline is based on the [AruCo](https://docs.opencv.org/4.8.0/d9/d6a/group__aruco.html) library implementation from OpenCV. It is ~2x higher fps and ~2x lower latency than the AprilTag pipeline type, but is less accurate. We recommend this pipeline type for teams that need to run at a higher framerate or have a lower powered device. This pipeline type was new for the 2024 season.

docs/source/docs/apriltag-pipelines/multitag.md

@@ -6,6 +6,10 @@ PhotonVision can combine AprilTag detections from multiple simultaneously observ
 MultiTag requires an accurate field layout JSON to be uploaded! Differences between this layout and the tags' physical location will drive error in the estimated pose output.
 :::
 
+:::{warning}
+For the 2025 Reefscape Season, there are two different field layouts. The first is the [welded field layout](https://github.com/wpilibsuite/allwpilib/blob/main/apriltag/src/main/native/resources/edu/wpi/first/apriltag/2025-reefscape-welded.json), which photonvision ships with. The second is the [Andymark field layout](https://github.com/wpilibsuite/allwpilib/blob/main/apriltag/src/main/native/resources/edu/wpi/first/apriltag/2025-reefscape-andymark.json). It is very important to ensure that you use the correct field layout, both in the [PhotonPoseEstimator](https://docs.photonvision.org/en/latest/docs/programming/photonlib/robot-pose-estimator.html#apriltags-and-photonposeestimator) and on the [coprocessor](https://docs.photonvision.org/en/latest/docs/apriltag-pipelines/multitag.html#updating-the-field-layout).
+:::
+
 ## Enabling MultiTag
 
 Ensure that your camera is calibrated and 3D mode is enabled. Navigate to the Output tab and enable "Do Multi-Target Estimation". This enables MultiTag to use the uploaded field layout JSON to calculate your camera's pose in the field. This 3D transform will be shown as an additional table in the "targets" tab, along with the IDs of AprilTags used to compute this transform.
@@ -19,30 +23,41 @@ Ensure that your camera is calibrated and 3D mode is enabled. Navigate to the Ou
 By default, enabling multi-target will disable calculating camera-to-target transforms for each observed AprilTag target to increase performance; the X/Y/angle numbers shown in the target table of the UI are instead calculated using the tag's expected location (per the field layout JSON) and the field-to-camera transform calculated using MultiTag. If you additionally want the individual camera-to-target transform calculated using SolvePNP for each target, enable "Always Do Single-Target Estimation".
 :::
 
-This multi-target pose estimate can be accessed using PhotonLib. We suggest using {ref}`the PhotonPoseEstimator class <docs/programming/photonlib/robot-pose-estimator:AprilTags and PhotonPoseEstimator>` with the `MULTI_TAG_PNP_ON_COPROCESSOR` strategy to simplify code, but the transform can be directly accessed using `getMultiTagResult`/`MultiTagResult()` (Java/C++).
+This multi-target pose estimate can be accessed using PhotonLib. We suggest using {ref}`the PhotonPoseEstimator class <docs/programming/photonlib/robot-pose-estimator:AprilTags and PhotonPoseEstimator>` with the `MULTI_TAG_PNP_ON_COPROCESSOR` strategy to simplify code, but the transform can be directly accessed using `getMultiTagResult`/`MultiTagResult()`/`multitagResult` (Java/C++/Python).
 
 ```{eval-rst}
 .. tab-set-code::
 
     .. code-block:: Java
 
-        var result = camera.getLatestResult();
-        if (result.getMultiTagResult().estimatedPose.isPresent) {
-          Transform3d fieldToCamera = result.getMultiTagResult().estimatedPose.best;
+        var results = camera.getAllUnreadResults();
+        for (var result : results) {
+          var multiTagResult = result.getMultiTagResult();
+          if (multiTagResult.isPresent()) {
+            var fieldToCamera = multiTagResult.get().estimatedPose.best;
+          }
         }
 
 
     .. code-block:: C++
 
-        auto result = camera.GetLatestResult();
-        if (result.MultiTagResult().result.isPresent) {
-          frc::Transform3d fieldToCamera = result.MultiTagResult().result.best;
+      auto results = camera.GetAllUnreadResults();
+      for (auto &result : results)
+      {
+        auto multiTagResult = result.MultiTagResult();
+        if (multiTagResult.has_value()) {
+          frc::Transform3d fieldToCamera = multiTagResult->estimatedPose.best;
         }
+      }
+
 
     .. code-block:: Python
 
-        # Coming Soon!
-
+      results = camera.getAllUnreadResults()
+      for result in results:
+          multitagResult = result.multitagResult
+          if multitagResult is not None:
+            fieldToCamera = multitagResult.estimatedPose.best
 ```
 
 :::{note}
@@ -51,7 +66,7 @@ The returned field to camera transform is a transform from the fixed field origi
 
 ## Updating the Field Layout
 
-PhotonVision ships by default with the [2024 field layout JSON](https://github.com/wpilibsuite/allwpilib/blob/main/apriltag/src/main/native/resources/edu/wpi/first/apriltag/2024-crescendo.json). The layout can be inspected by navigating to the settings tab and scrolling down to the "AprilTag Field Layout" card, as shown below.
+PhotonVision ships by default with the [2025 welded field layout JSON](https://github.com/wpilibsuite/allwpilib/blob/main/apriltag/src/main/native/resources/edu/wpi/first/apriltag/2025-reefscape-welded.json). The layout can be inspected by navigating to the settings tab and scrolling down to the "AprilTag Field Layout" card, as shown below.
 
 ```{image} images/field-layout.png
 :alt: The currently saved field layout in the Photon UI

docs/source/docs/calibration/calibration.md

@@ -18,7 +18,7 @@ The calibration data collected during calibration is specific to each physical c
 
 Accurate camera calibration is required in order to get accurate pose measurements when using AprilTags and 3D mode. The tips below should help ensure success:
 
-01. Ensure your the images you take have the target in different positions and angles, with as big of a difference between angles as possible. It is important to make sure the target overlay still lines up with the board while doing this. Tilt no more than 45 degrees.
+01. Ensure the images you take have the target in different positions and angles, with as big of a difference between angles as possible. It is important to make sure the target overlay still lines up with the board while doing this. Tilt no more than 45 degrees.
 02. Use as big of a calibration target as your printer can print.
 03. Ensure that your printed pattern has enough white border around it.
 04. Ensure your camera stays in one position during the duration of the calibration.
@@ -51,6 +51,10 @@ We'll next select a resolution to calibrate and populate our pattern spacing, ma
 :::{warning} Old OpenCV Pattern selector. This should be used in the case that the calibration image is generated from a version of OpenCV before version 4.6.0. This would include targets created by calib.io. If this selector is not set correctly the calibration will be completely invalid. For more info view [this GitHub issue](https://github.com/opencv/opencv_contrib/issues/3291).
 :::
 
+:::{note}
+If you have a [calib.io](https://calib.io/) CharuCo Target you will have to enter the paramaters of your target. For example if your target says "9x12 | Checker Size: 30 mm | Marker Size: 22 mm | Dictionary: AruCo DICT 5x5", you would have to set the board type to Dict_5x5_1000, the pattern spacing to 1.1811 in (30 mm converted to inches), the marker size 0.866142 in (22 mm converted to inches), the board width to 12 and the board height to 9. If you chose the wrong tag family the board wont be detected during calibration. If you swap the width and height your calibration will have a very high error.
+:::
+
 ### 4. Take at calibration images from various angles.
 
 Now, we'll capture images of our board from various angles. It's important to check that the board overlay matches the board in your image. The further the overdrawn points are from the true position of the chessboard corners, the less accurate the final calibration will be. We'll want to capture enough images to cover the whole camera's FOV (with a minimum of 12). Once we've got our images, we'll click "Finish calibration" and wait for the calibration process to complete. If all goes well, the mean error and FOVs will be shown in the table on the right. The FOV should be close to the camera's specified FOV (usually found in a datasheet) usually within + or - 10 degrees. The mean error should also be low, usually less than 1 pixel.
@@ -83,7 +87,7 @@ More info on what these parameters mean can be found in [OpenCV's docs](https://
 
 Below these outputs are the snapshots collected for calibration, along with a per-snapshot mean reprojection error. A snapshot with a larger reprojection error might indicate a bad snapshot, due to effects such as motion blur or misidentified chessboard corners.
 
-Calibration images can also be extracted from the downloaded JSON file using [this Python script](https://raw.githubusercontent.com/PhotonVision/photonvision/master/devTools/calibrationUtils.py). This script will unpack calibration images, and also generate a VNL file for use [with mrcal](https://mrcal.secretsauce.net/).
+Calibration images can also be extracted from the downloaded JSON file using [this Python script](https://raw.githubusercontent.com/PhotonVision/photonvision/main/devTools/calibrationUtils.py). This script will unpack calibration images, and also generate a VNL file for use [with mrcal](https://mrcal.secretsauce.net/).
 
 ```
 python3 /path/to/calibrationUtils.py path/to/photon_calibration.json /path/to/output/folder

docs/source/docs/camera-specific-configuration/arducam-cameras.md

@@ -17,6 +17,6 @@ Arducam cameras are supported for setups with multiple devices. This is possible
 3. **Save Settings**: Ensure that you save the settings after selecting the appropriate camera model for each device.
 
 ```{image} images/setArducamModel.png
-:alt: The camera model can be selected from the Arudcam model selector in the cameras tab
+:alt: The camera model can be selected from the Arducam model selector in the cameras tab
 :align: center
 ```

docs/source/docs/camera-specific-configuration/index.md

@@ -0,0 +1,8 @@
+# Camera-Specifc Configuration
+
+```{toctree}
+:maxdepth: 2
+
+arducam-cameras
+picamconfig
+```

docs/source/docs/camera-specific-configuration/picamconfig.md

@@ -1,5 +1,7 @@
 # Pi Camera Configuration
 
+This page covers specifics about the _Raspberry Pi_ CSI camera configuration.
+
 ## Background
 
 The Raspberry Pi CSI Camera port is routed through and processed by the GPU. Since the GPU boots before the CPU, it must be configured properly for the attached camera. Additionally, this configuration cannot be changed without rebooting.
@@ -21,6 +23,7 @@ Windows may report "There is a problem with this drive". This should be ignored.
 Locate `config.txt` in the folder, and open it with your favorite text editor.
 
 ```{image} images/bootConfigTxt.png
+
 ```
 
 Within the file, find this block of text:

docs/source/docs/contributing/building-photon.md

@@ -69,6 +69,16 @@ In the root directory:
       ``gradlew buildAndCopyUI``
 ```
 
+### Using hot reload on the UI
+
+In the photon-client directory:
+
+```bash
+npm run dev
+```
+
+This allows you to make UI changes quickly without having to spend time rebuilding the jar. Hot reload is enabled, so changes that you make and save are reflected in the UI immediately. Running this command will give you the URL for accessing the UI, which is on a different port than normal. You must use the printed URL to use hot reload.
+
 ### Build and Run PhotonVision
 
 To compile and run the project, issue the following command in the root directory:
@@ -167,30 +177,31 @@ repositories {
 }
 ```
 
+### VSCode Test Runner Extension
+
+With the VSCode [Extension Pack for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack), you can get the Test Runner for Java and Gradle for Java extensions. This lets you easily run specific tests through the IDE:
+
+```{image} assets/vscode-runner-tests.png
+:alt: An image showing how unit tests can be ran in VSCode through the Test Runner for Java extension.
+```
+
+To correctly run PhotonVision tests this way, you must [delegate the tests to Gradle](https://code.visualstudio.com/docs/java/java-build#_delegate-tests-to-gradle). Debugging tests like this will [**not** currently](https://github.com/microsoft/build-server-for-gradle/issues/119) collect outputs.
+
 ### Debugging PhotonVision Running Locally
 
-One way is by running the program using gradle with the {code}`--debug-jvm` flag. Run the program with {code}`./gradlew run --debug-jvm`, and attach to it with VSCode by adding the following to {code}`launch.json`. Note args can be passed with {code}`--args="foobar"`.
+Unit tests can instead be debugged through the ``test`` Gradle task for a specific subproject in VSCode, found in the Gradle tab:
 
-```
-{
-   // Use IntelliSense to learn about possible attributes.
-   // Hover to view descriptions of existing attributes.
-   // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
-   "version": "0.2.0",
-   "configurations": [
-      {
-            "type": "java",
-            "name": "Attach to Remote Program",
-            "request": "attach",
-            "hostName": "localhost",
-            "port": "5005",
-            "projectName": "photon-core",
-      }
-   ]
-}
+```{image} assets/vscode-gradle-tests.png
+:alt: An image showing how unit tests can be debugged in VSCode through the Gradle for Java extension.
 ```
 
-PhotonVision can also be run using the gradle tasks plugin with {code}`"args": "--debug-jvm"` added to launch.json.
+However, this will run all tests in a subproject.
+
+Similarly, a local instance of PhotonVision can be debugged in the same way using the Gradle ``run`` task. In both cases, additional arguments can be specified:
+
+```{image} assets/vscode-gradle-args.png
+:alt: An image showing how VSCode gradle tasks can specify additional arguments.
+```
 
 ### Debugging PhotonVision Running on a CoProcessor
 
@@ -272,3 +283,9 @@ Using the [GitHub CLI](https://cli.github.com/), we can download artifacts from
 ```
 ~/photonvision$ gh run download 11759699679 -n jar-Linux
 ```
+
+#### MacOS Builds
+
+MacOS builds are not published to releases as MacOS is not an officially
+supported platform. However, MacOS builds are still available from the MacOS
+build action, which can be found [here](https://github.com/PhotonVision/photonvision/actions/workflows/build.yml).

docs/source/docs/contributing/design-descriptions/camera-matching.md

@@ -0,0 +1,112 @@
+# Camera Matching
+
+Diagrams generated by the [PlantUML UML editor](https://www.plantuml.com/plantuml/). Copy the image URLs below and decode in the editor to make changes.
+
+## Initial Setup
+
+When PhotonVision first starts, settings are loaded from disk and [VisionSources](https://javadocs.photonvision.org/release/org/photonvision/vision/processes/VisionSource.html) are created for every serialized & active [Camera Configuration](https://javadocs.photonvision.org/release/org/photonvision/common/configuration/CameraConfiguration.html)
+
+![](https://www.plantuml.com/plantuml/png/VP5FQnin4CNl-XI3JotK-DAJAI6fIw6GfOMbFkKoramSqTKVfF6MVFkETfKsei6trVpUldbwkYs2MIv-CeI29omCcn5d9XXPn8LpsG0MAErWaggTTGc3m6P05nRizQD7HrTS3336IxOC0mOySrwqS_5lIeT8bubxgVTNN9jRhpYCXvXNP8lLpokxsWvZNcwtlQaNsSDzH8B773sGAxzC7MvlDFSUxeXWKie4DeP7futelC8z73AZCDnPSJD35xKOh5F5DR31IU3d-1aiUive06PTlSRTm_V4eH4uFJ-4Aamn2xmxFMyJojDx0x2AjtNn-WSJ73_UltRyzC_o2mjRQH1IZecpE4t5WPOmX_5R7sPof_NyVvwghNbK-LVL1sbErTneFLqxNxF27pdEZZXNs8gjbJFrhHdYLxMredrx1Obm70QZvnUBtKxdJE2NnosxNVj3qIYO1GB_Rb3DEZAlQxKPowMuS7u8oIMUNE0F84-PaOgvvK0NF_q1)
+
+## UI Workflow
+
+A [background thread](https://javadocs.photonvision.org/org/photonvision/common/util/TimedTaskManager.html) will periodically query CSCore and Libcamera for what cameras we currently see connected. This list is provided to the web UI for display.
+
+![](https://www.plantuml.com/plantuml/svg/POvDJyCm343l-HLMxnFt7j14uJ099AHkSCvSCopoCSLE-FjaxQW8kpbwpy_PYjgasJk3qJb2vHW4kZrxcc1lvGjURB0dIXrO0LLlpBakCFBP1eNkZQLkm1XpGchS8hvLXt68YMQ6WdLiyJCVqNfATZRSxwkLtka8XzriP3P6rM_kww4U7hac2oK8z0qJ5KOIKwJYvLOFJo5VUafm61zWYOjPwEPQ6M88X4fJuyoPzKD_IyEuMwrLk8rLhOrbxk4rooVWwbmvE1Rz9rbKBdJ7OHakInzy4hEbC6NlVW00)
+
+![](images/matching_ui.png)
+
+This UI allows users to "Activate" a camera that's never been seen before, or activate a CameraConfiguration we've seen before but was disabled. Allowing camera configurations to be saved but not loaded by default lets us support temporarily disabling/unplugging a camera without flooding log files.
+
+Since our backend logic intentionally does not protect users from plugging camera B into the port that camera A was active on, the UI shall show a warning but vision processing will (attempt to) continue like normal.
+
+### Activate New Camera
+
+When a new camera (ie, one we can't match by-path to a deserialized CameraConfiguration) is activated, we'll create a spin up a new Vision Module for it
+
+![](https://www.plantuml.com/plantuml/svg/VL7B3jCm4BpxArOzWKIK2wSALOKWf4gDG8fQBhquzggrY1_u4TI_PvCufGRKK-ATySpiU1yYzp7fWJdwAg4SDn4stx67qs43F41I9NHMGLa3dKrU8BJSy2lwcJa6_LzgQsKQ_g9g_K8rgvMCfckiNo0H1FsMy57rWclqV6OCw-b5e1o4iQIg7MNVmaSfeRz3CkfdGZ0am6YUmOuR5UyWRYX-X7M-XSOZZmX5_i2uY6ga-RG5uqE4K_S9SYAWORLRTjZ2LuSc8-HzCHFHMH_XJN-l78-tjmpomjNakDn02UVtnrKHZPnDckvGcZng-DU7kBCFCH-imk1PdDRzy2VoPumeuYhcl7L87UDKIj795q-CRzwEIgAVmDpaqNA9igoCINpgBDUhyvj42-UsPNHU9UgQvgIXvvSCTRtUe7UAt4Sm-2k395OWus9BiGM6eCprOfnoE2Y3xo3UF78Ps1wDJ7hu3G00)
+
+### Deactivate Camera
+
+Deactivating a camera will release the native resources it owns, and return the CameraConfiguration to the pool of currently disabled cameras we can re-enable later.
+
+![](https://www.plantuml.com/plantuml/svg/ROxBJiCm44Nt_efHLtIH7yWYgWWB8gYeI0eRDXDdW97yABQd5N-FvV1G8bOUppdNrxkOC2InHftooPfFw19idcc4OxS1Z22yH4ySsJlelGHDi4U7RnIAUOxsNtNl9p4hrQxKjczzeC9qr7bSudiUDLeAM0ppSrDAk6foRmqtX3hn6HD16GXcvSMDdo2EFuJ0vOtATexO77aawxDdo_TKNbLLCvVNq1eV_vwuwbxXs5zllwNV_Xe6mZ3vYrkeRTzjvvv6k8Q3n7TmT86OC541LG6tmt20Xpkr8pU9DLy0)
+
+### Reactivate a CameraConfig
+
+When a new camera (ie, one we can't match by-path to a deserialized CameraConfiguration) is activated, we'll create and spin up a new Vision Module for it.
+
+![](https://www.plantuml.com/plantuml/svg/VP9BYnD158NtzIikirAmoSPL8s5YH1n8SB1duYQRsrtNcGlrAElHadzlLVgXXP9LACvNvvmwwViGqSUabN3vbmTsQ2BSVQSUdX_k00CahgKJ1xO6EflyG714Wo_ah-GOz7_HevL9KOrgVSDrTgk9VRUtVfA6C5XFjNpWVa1D7g-4Maut2ir5X4ZSR7Ft5huH3f57Z0II0_QA94msPzDV81d-cGWCQX82LOJdxYCuwoEmWHH8G9cWsIPkuSlJqoFyG5R9ao0ZXIXIZcbXxwaax4eKGVNm8DO2OrWpvWvN-sOxFRw5huxCh41_EPkrp9l-qZYChsy5m0GtKt2vGH9Exm-BOobMGlRTGnsoxlTlJc5BJYPNgWgOuUNL7_vK_aIHXhYOEMyT-SWKCbLDyzbduj7RaINv8ix_py6Y95bF9YJzjTcyiixmJag85ax7eyZdnMApsSdYeQ-VGDXibXijT15z14E_5b6CbJ9EiRdsG26mUJaRnuuK6te7yTKJoY3koSYarMy0)
+
+# Camera Matching Requirements
+
+## Definitions
+- VALID USB PATH: a path in the form `/dev/v4l/by-path/[UUID]`
+- VIDEO DEVICE PATH: a CSCore-provided identifier derived from the V4L path `/dev/video[N]` on Linux, or an opaque string on Windows
+- UNIQUE NAME: an identifier that is unique within the set of all deserialized CameraConfigurations and unmatched USB cameras
+  - I don't love this, it means that a USB camera matched to a VisionModule will share a UNIQUE NAME, right?
+- DESERIALIZED CAMERA CONFIGURATIONS: The set of camera configurations loaded from disk and provided to the VisionSourceManager. This configuration data structure includes the UNIQUE NAME
+- CURRENTLY ACTIVE CAMERAS: The set of VisionModules currently active and processing vision data, and associated metadata
+
+## Startup:
+
+- GIVEN An empty set of deserialized Camera Configurations
+<br>WHEN PhotonVision starts
+<br>THEN no VisionModules will be started
+
+- GIVEN A valid set of deserialized Camera Configurations
+<br>WHEN PhotonVision starts
+<br>THEN VisionModules will be started FOR EACH un-DISABLED config
+
+- GIVEN A valid set of deserialized Camera Configurations
+<br>WHEN PhotonVision starts
+<br>THEN VisionModules will NOT be started FOR EACH DISABLED config
+
+- GIVEN A CameraConfiguration with a VALID USB PATH
+<br>WHEN a VisionModule is created
+<br>THEN The VisionModule shall open the camera using the USB path
+
+- GIVEN A CameraConfiguration without a valid USB path
+<br>WHEN a VisionModule is created
+<br>THEN The VisionModule shall open the camera using the VIDEO DEVICE PATH
+
+## Camera (re)enumeration:
+
+- GIVEN a NEW USB CAMERA is available for enumeration
+<br>WHEN a USB camera is discovered by VisionSourceManager
+<br>AND the USB camera's VIDEO DEVICE PATH is not in the set of DESERIALIZED CAMERA CONFIGURATIONS
+<br>THEN a UNIQUE NAME will be assigned to the camera info
+
+- GIVEN a NEW USB CAMERA is available for enumeration
+<br>WHEN a USB camera is discovered by VisionSourceManager
+<br>AND the USB camera's VIDEO DEVICE PATH is in the set of DESERIALIZED CAMERA CONFIGURATIONS
+<br>THEN a UNIQUE NAME equal to the matching DESERIALIZED CAMERA CONFIGURATION will be assigned to the camera info
+  - This is a weird case. How -should- we handle this? see above
+
+## Creating from a new camera
+
+- Given: A UNIQUE NAME from a NEW USB CAMERA
+<br>WHEN I request a new VisionModule is created for this NEW USB CAMERA
+<br>AND the camera has a VALID USB PATH
+<br>AND the camera's VALID USB PATH is not in use by any CURRENTLY ACTIVE CAMERAS
+<br>THEN a NEW VisionModule will be started for the NEW USB CAMERA using the VALID USB PATH
+
+- Given: A UNIQUE NAME from a NEW USB CAMERA
+<br>WHEN I request a new VisionModule is created for this NEW USB CAMERA
+<br>AND the camera does not have a VALID USB PATH
+<br>AND the camera's VIDEO DEVICE PATH is not in use by any CURRENTLY ACTIVE CAMERAS
+<br>THEN a NEW VisionModule will be started for the NEW USB CAMERA using the VIDEO DEVICE PATH
+
+## Deactivate
+
+- Given: A UNIQUE NAME from a CURRENTLY ACTIVE CAMERA
+<br>WHEN I request the VisionModule be DEACTIVATED
+<br>THEN the VisionModule will be stopped for the given CURRENTLY ACTIVE CAMERA
+<br>AND the CameraConfiguration DISABLED flag will be set to TRUE
+
+## Reactivate
+
+- Given: A UNIQUE NAME from a DESERIALIZED CAMERA CONFIGURATIONS
+<br>WHEN I request the VisionModule be ACTIVATED
+<br>AND the CameraConfiguration's DISABLED flag is TRUE
+<br>THEN a VisionModule will be created and started for the camera

docs/source/docs/contributing/design-descriptions/e2e-latency.md

@@ -0,0 +1,136 @@
+# Latency Characterization
+
+
+## A primer on time
+
+Especially starting around 2022 with AprilTags making localization easier, providing a way to know when a camera image was captured at became more important for localization.
+Since the [creation of USBFrameProvider](https://github.com/PhotonVision/photonvision/commit/f92bf670ded52b59a00352a4a49c277f01bae305), we used the time [provided by CSCore](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/cscore/CvSink.html#grabFrame(org.opencv.core.Mat)) to tell when a camera image was captured at, but just keeping track of "CSCore told us frame N was captured 104.21s after the Raspberry Pi turned on" isn't very helpful. We can decompose this into asking:
+
+- At what time was a particular image captured at, in the coprocessor's timebase?
+- How do I convert a time in a coprocessor's timebase into the RoboRIO's timebase, so I can integrate the measurement with my other sensor measurements (like encoders)?
+
+The first one seems easy - CSCore tells us the time, so just keep track of that? Should be easy. For the second, translating this time, as measured by the coprocessor's clock, into a timebase also used by user code on the RoboRIO, is actually a [fairly hard problem](time-sync.md) that involved reinventing [PTP](https://en.wikipedia.org/wiki/PTP).
+
+And on latency vs timestamps - PhotonVision has exposed a magic "latency" number since forever, but latency (as in, the time from image capture to acting on data) can be useful for benchmarking code, but robots actually want to answer "what time was this image from, relative to "?
+
+
+## CSCore's Frame Time
+
+WPILib's CSCore is a platform-agnostic wrapper around Windows, Linux, and MacOS camera APIs. On Linux, CSCore uses [Video4Linux](https://en.wikipedia.org/wiki/Video4Linux) to access USB Video Class (UVC) devices like webcams, as well as CSI cameras on some platforms. At a high level, CSCore's [Linux USB Camera driver](https://github.com/wpilibsuite/allwpilib/blob/17a03514bad6de195639634b3d57d5ac411d601e/cscore/src/main/native/linux/UsbCameraImpl.cpp) works by:
+
+- Opening a camera with `open`
+- Creating and `mmap`ing a handful of buffers V4L will fill with frame data into program memory
+- Asking V4L to start streaming
+- While the camera is running:
+  - Wait for new frames
+  - Dequeue one buffer
+  - Call `SourceImpl::PutFrame`, which will copy the image out and convert as needed
+  - Return the buffer to V4L to fill again
+
+Prior to https://github.com/wpilibsuite/allwpilib/pull/7609, CSCore used the [time it dequeued the buffer at](https://github.com/wpilibsuite/allwpilib/blob/17a03514bad6de195639634b3d57d5ac411d601e/cscore/src/main/native/linux/UsbCameraImpl.cpp#L559) as the image capture time. But this doesn't account for exposure time or latency introduced by the camera + USB stack + Linux itself.
+
+V4L does expose (with some [very heavy caveats](https://github.com/torvalds/linux/blob/fc033cf25e612e840e545f8d5ad2edd6ba613ed5/drivers/media/usb/uvc/uvc_video.c#L600) for some troublesome cameras) its best guess at the time an image was captured at via [buffer flags](https://www.kernel.org/doc/html/v4.9/media/uapi/v4l/buffer.html#buffer-flags). In my testing, all my cameras were able to provide timestamps with both these flags set:
+- `V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC`: The buffer timestamp has been taken from the CLOCK_MONOTONIC clock [...] accessible via `clock_gettime()`.
+- `V4L2_BUF_FLAG_TSTAMP_SRC_SOE`: Start Of Exposure. The buffer timestamp has been taken when the exposure of the frame has begun.
+
+I'm sure that we'll find a camera that doesn't play nice, because we can't have nice things :). But until then, using this timestamp gets us a free accuracy bump.
+
+Other things to note: This gets us an estimate at when the camera *started* collecting photons. The camera's sensor will remain collecting light for up to the total integration time, plus readout time for rolling shutter cameras.
+
+## Latency Testing
+
+Here, I've got a RoboRIO with an LED, an Orange Pi 5, and a network switch on a test bench. The LED is assumed to turn on basically instantly once we apply current, and based on DMA testing, the total time to switch a digital output on is on the order of 10uS. The RoboRIO is running a TimeSync Server, and the Orange Pi is running a TimeSync Client.
+
+### Test Setup
+
+<details>
+<summary>Show RoboRIO Test Code</summary>
+
+```java
+package frc.robot;
+
+import org.photonvision.PhotonCamera;
+
+import edu.wpi.first.wpilibj.DigitalOutput;
+import edu.wpi.first.wpilibj.TimedRobot;
+import edu.wpi.first.wpilibj.Timer;
+import edu.wpi.first.wpilibj.smartdashboard.SmartDashboard;
+
+public class Robot extends TimedRobot {
+    PhotonCamera camera;
+    DigitalOutput light;
+
+    @Override
+    public void robotInit() {
+        camera = new PhotonCamera("Arducam_OV9782_USB_Camera");
+
+        light = new DigitalOutput(0);
+        light.set(false);
+    }
+
+    @Override
+    public void robotPeriodic() {
+        super.robotPeriodic();
+
+        try {
+            light.set(false);
+            for (int i = 0; i < 50; i++) {
+                Thread.sleep(20);
+                camera.getAllUnreadResults();
+            }
+
+            var t1 = Timer.getFPGATimestamp();
+            light.set(true);
+            var t2 = Timer.getFPGATimestamp();
+
+
+            for (int i = 0; i < 100; i++) {
+                for (var result : camera.getAllUnreadResults()) {
+                    if (result.hasTargets()) {
+                        var t3 = result.getTimestampSeconds();
+                        var t1p5 = (t1 + t2) / 2;
+                        var error = t3-t1p5;
+                        SmartDashboard.putNumber("blink_error_ms", error * 1000);
+                        return;
+                    }
+                }
+
+                Thread.sleep(20);
+            }
+        } catch (InterruptedException e) {
+            e.printStackTrace();
+        }
+    }
+}
+```
+</details>
+
+I've decreased camera exposure as much as possible (so we know with reasonable confidence that the image was collected right at the start of the exposure time reported by V4L), but we only get back new images at 60fps. So we don't know when between frame N and N+1 the LED turned on - just that sometime between now and 1/60th of a second a go, the LED turned on.
+
+The test coprocessor was an Orange Pi 5 running a PhotonVision 2025 (Ubuntu 24.04 based) image, with an ArduCam OV9782 at 1280x800, 60fps, MJPG running a reflective pipeline.
+
+
+### Test Results
+
+The videos above show the difference between when the RoboRIO turned the LED on and when PhotonVision first seeing a camera frame with the LED on, what I've called error and plotted in yellow with units of seconds. This error decreases when I use the frame time reported by V4L from a mean delta of 26 ms to a mean delta of 11 ms (below the maximum temporal resolution of my camera).
+
+Old CSCore:
+```{raw} html
+<video width="85%" controls>
+    <source src="../../../_static/assets/latency-tests/ov9782_1280x720x60xMJPG_old.mp4" type="video/mp4">
+    Your browser does not support the video tag.
+</video>
+```
+CSCore using V4L frame time:
+```{raw} html
+<video width="85%" controls>
+    <source src="../../../_static/assets/latency-tests/ov9782_1280x720x60xMJPG_new.mp4" type="video/mp4">
+    Your browser does not support the video tag.
+</video>
+```
+
+With the camera capturing at 60fps, the time between successive frames is only ~16.7 ms, so I don't expect to be able to resolve anything smaller. Given sufficient time and with perfect latency compensation, and with more noise in the robot program to make sure we vary LED toggle times, I'd expect the error to converge to ~half the interval between frames - so being within this frame interval with CSCore updates is a very good sign.
+
+### Future Work
+
+This test also makes no effort to isolate error from time synchronization from error introduced by frame time measurement - we're just interested in overall error. Future work could investigate the latency contribution

docs/source/docs/contributing/design-descriptions/index.md

@@ -4,4 +4,6 @@
 :maxdepth: 1
 image-rotation
 time-sync
+camera-matching
+e2e-latency
 ```

docs/source/docs/contributing/design-descriptions/time-sync.md

@@ -76,7 +76,7 @@ Communication between server and clients shall occur over the User Datagram Prot
 
 ## Message Format
 
-The message format forgoes CRCs (as these are provided by the Ethernet physical layer) or packet delimination (as our packetsa are assumed be under the network MTU). **TSP Ping** and **TSP Pong** messages shall be encoded in a manor compatible with a WPILib packed struct with respect to byte alignment and endienness.
+The message format forgoes CRCs (as these are provided by the Ethernet physical layer) or packet delineation (as our packets are assumed be under the network MTU). **TSP Ping** and **TSP Pong** messages shall be encoded in a manor compatible with a WPILib packed struct with respect to byte alignment and endianness.
 
 ### TSP Ping
 
@@ -98,7 +98,7 @@ The message format forgoes CRCs (as these are provided by the Ethernet physical
 
 ## Optional Protocol Extensions
 
-Clients may publish statistics to NetworkTables. If they do, they shall publish to a key that is globally unique per participant in the Time Synronization network. If a client implements this, it shall provide the following publishers:
+Clients may publish statistics to NetworkTables. If they do, they shall publish to a key that is globally unique per participant in the Time Synchronization network. If a client implements this, it shall provide the following publishers:
 
 | Key | Type | Notes |
 | ------ | ------ | ---- |

docs/source/docs/description.md

@@ -2,7 +2,7 @@
 
 ## Description
 
-PhotonVision is a free, fast, and easy-to-use vision processing solution for the _FIRST_ Robotics Competition. PhotonVision is designed to get vision working on your robot _quickly_, without the significant cost of other similar solutions.
+PhotonVision is a free, fast, and easy-to-use vision processing solution for the _FIRST_ Robotics Competition. PhotonVision is designed to get vision working on your robot _quickly_, but with lower cost than other solutions.
 Using PhotonVision, teams can go from setting up a camera and coprocessor to detecting and tracking AprilTags and other targets by simply tuning sliders. With an easy to use interface, comprehensive documentation, and a feature rich vendor dependency, no experience is necessary to use PhotonVision. No matter your resources, using PhotonVision is easy compared to its alternatives.
 
 ## Advantages
@@ -11,7 +11,7 @@ PhotonVision has a myriad of advantages over similar solutions, including:
 
 ### Affordable
 
-Compared to alternatives, PhotonVision is much cheaper to use (at the cost of your coprocessor and camera) compared to alternatives that cost \$400. This allows your team to save money while still being competitive.
+PhotonVision offers a more affordable solution to vision, with costs being from your coprocessor(s) and camera(s). Teams may choose to run multiple cameras from one coprocessor. This makes it a great solution for teams with limited budgets.
 
 ### Easy to Use User Interface
 
@@ -19,19 +19,15 @@ The PhotonVision user interface is simple and modular, making things easier for
 
 ### PhotonLib Vendor Dependency
 
-The PhotonLib vendor dependency allows you to easily get necessary target data (without having to work directly with NetworkTables) while also providing utility methods to get distance and position on the field. This helps your team focus less on getting data and more on using it to do cool things. This also has the benefit of having a structure that ensures all data is from the same timestamp, which is helpful for latency compensation.
+The PhotonLib vendor dependency allows you to easily get necessary target data (without having to work directly with NetworkTables) while also providing utility methods to get distance and position on the field. A serialization strategy is used to guarantees data coherency, which is helpful for latency compensation. This helps your team focus less on getting data and more on using it to do cool things.
 
 ### User Calibration
 
 Using PhotonVision allows the user to calibrate for their specific camera, which will get you the best tracking results. This is extremely important as every camera (even if it is the same model) will have it's own quirks and user calibration allows for those to be accounted for.
 
-### High FPS Processing
+### Low Latency, High FPS Processing
 
-Compared to alternative solutions, PhotonVision boasts higher frames per second which allows for a smoother video stream and detection of targets to ensure you aren't losing out on any performance.
-
-### Low Latency
-
-PhotonVision provides low latency processing to make sure you get vision measurements as fast as possible, which makes complex vision tasks easier. We guarantee that all measurements are sent from the same timestamp, making life easier for your programmers.
+PhotonVision exposes specialized hardware on select coprocessors to maximize processing speed. This allows for lower-latency detection of targets to ensure you aren't losing out on any performance.
 
 ### Fully Open Source and Active Developer Community
 

docs/source/docs/driver-mode/index.md

@@ -0,0 +1,27 @@
+# Driver Mode
+
+Driver Mode is a type of pipeline that doesn't run any vision processing, intended for viewing from a human.
+
+## Enabling Driver Mode
+
+To enable Driver Mode, toggle the switch at the top of the Dashboard page for a selected camera.
+
+```{image} images/driver-mode-dashboard.png
+:align: center
+:alt: Driver Mode Toggle in the Dashboard Page
+```
+
+Alternatively, visit the camera settings page and toggle the "Driver Mode" switch for a selected camera.
+
+```{image} images/driver-mode-camera-settings.png
+:align: center
+:alt: Driver Mode Toggle in the Camera Settings Page
+```
+
+## Hiding the Crosshair
+When Driver Mode is enabled, a green crosshair will be shown at the center of the camera stream. If you do not want to show the green crosshair at the center of the camera stream, toggle the "Crosshair" switch under the Input tab, as shown in the image below.
+
+```{image} images/crosshair-switch.png
+:align: center
+:alt: Crosshair Switch
+```

docs/source/docs/examples/aimandrange.md

@@ -1,6 +1,6 @@
 # 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)).
+The following example is from the PhotonLib example repository ([Java](https://github.com/PhotonVision/photonvision/tree/main/photonlib-java-examples/aimandrange)/[C++](https://github.com/PhotonVision/photonvision/tree/main/photonlib-cpp-examples/aimandrange)/[Python](https://github.com/PhotonVision/photonvision/tree/main/photonlib-python-examples/aimandrange))
 
 ## Knowledge and Equipment Needed
 
@@ -10,7 +10,7 @@ The following example is from the PhotonLib example repository ([Java](https://g
 
 Now that you know how to aim toward the AprilTag, let's also drive the correct distance from the AprilTag.
 
-To do this, we'll use the *pitch* of the target in the camera image and trigonometry to figure out how far away the robot is from the AprilTag. Then, like before, we'll use the P term of a PID controller to drive the robot to the correct distance.
+To do this, we'll use the _pitch_ of the target in the camera image and trigonometry to figure out how far away the robot is from the AprilTag. Then, like before, we'll use the P term of a PID controller to drive the robot to the correct distance.
 
 ```{eval-rst}
 .. tab-set::
@@ -43,8 +43,8 @@ To do this, we'll use the *pitch* of the target in the camera image and trigonom
 
        .. rli:: https://raw.githubusercontent.com/PhotonVision/photonvision/abe95dfaa055bbe3609f72cfcaaba0f96ee7978c/photonlib-python-examples/aimandrange/robot.py
          :language: python
-         :lines: 44-95
+         :lines: 52-91
          :linenos:
-         :lineno-start: 44
+         :lineno-start: 52
 
 ```

docs/source/docs/examples/aimingatatarget.md

@@ -1,19 +1,19 @@
 # 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)).
+The following example is from the PhotonLib example repository ([Java](https://github.com/PhotonVision/photonvision/tree/main/photonlib-java-examples/aimattarget)).
 
 ## Knowledge and Equipment Needed
 
 - A Robot
-- A camera mounted rigidly to the robot's frame, cenetered and pointed forward.
-- A coprocessor running PhotonVision with an AprilTag or Aurco 2D Pipeline.
-- [A printout of AprilTag 7](https://firstfrc.blob.core.windows.net/frc2024/FieldAssets/Apriltag_Images_and_User_Guide.pdf), mounted on a rigid and flat surface.
+- A camera mounted rigidly to the robot's frame, centered and pointed forward.
+- A coprocessor running PhotonVision with an AprilTag or Aruco 2D Pipeline.
+- [A printout of AprilTag 7](https://firstfrc.blob.core.windows.net/frc2025/FieldAssets/Apriltag_Images_and_User_Guide.pdf), mounted on a rigid and flat surface.
 
 ## Code
 
 Now that you have properly set up your vision system and have tuned a pipeline, you can now aim your robot at an AprilTag using the data from PhotonVision. The _yaw_ of the target is the critical piece of data that will be needed first.
 
-Yaw is reported to the roboRIO over Network Tables. PhotonLib, our vender dependency, is the easiest way to access this data. 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?>`.
+Yaw is reported to the roboRIO over Network Tables. PhotonLib, our vendor dependency, is the easiest way to access this data. 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?>`.
 
 In this example, while the operator holds a button down, the robot will turn towards the AprilTag 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).
 

docs/source/docs/examples/poseest.md

@@ -1,6 +1,6 @@
 # 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/poseest)/[C++](https://github.com/PhotonVision/photonvision/tree/master/photonlib-cpp-examples/poseest)/[Python](https://github.com/PhotonVision/photonvision/tree/master/photonlib-python-examples/poseest)).  Full code is available at that links.
+The following example comes from the PhotonLib example repository ([Java](https://github.com/PhotonVision/photonvision/tree/main/photonlib-java-examples/poseest)/[C++](https://github.com/PhotonVision/photonvision/tree/main/photonlib-cpp-examples/poseest)/[Python](https://github.com/PhotonVision/photonvision/tree/main/photonlib-python-examples/poseest)).  Full code is available at that links.
 
 ## Knowledge and Equipment Needed
 
@@ -205,7 +205,9 @@ During simulation, we periodically update the simulated vision system.
 
 The rest is done behind the scenes.
 
-```{image} images/poseest_demo.gif
-:alt: Simulated swerve drive and vision system working together in teleoperated mode.
-:width: 1200
+```{raw} html
+<video width="85%" controls>
+    <source src="../../_static/assets/poseest_demo.mp4" type="video/mp4">
+    Your browser does not support the video tag.
+</video>
 ```

docs/source/docs/hardware/index.md

@@ -4,6 +4,5 @@
 :maxdepth: 2
 
 selecting-hardware
-picamconfig
 customhardware
 ```

docs/source/docs/hardware/selecting-hardware.md

@@ -1,11 +1,10 @@
 # Selecting Hardware
 
 :::{note}
-It is highly recommended that you read the {ref}`quick start guide<docs/quick-start/common-setups:Common Hardware Setups>`, and use the hardware recommended there that
-is not touched on here.
+See the {ref}`quick start guide<docs/quick-start/common-setups:Common Hardware Setups>`, for latest, specific recommendations on hardware to use for PhotonVision.
 :::
 
-In order to use PhotonVision, you need a coprocessor and a camera. Other than the recommended hardware found in the {ref}`quick start guide<docs/quick-start/common-setups:Common Hardware Setups>`, this page will help you select hardware that should work for photonvision even though it is not supported/recommended.
+In order to use PhotonVision, you need a coprocessor and a camera. This page discusses the specifics of why that hardware is recommended.
 
 ## Choosing a Coprocessor
 
@@ -22,41 +21,76 @@ In order to use PhotonVision, you need a coprocessor and a camera. Other than th
     - Note that we only support using the Raspberry Pi's MIPI-CSI port, other MIPI-CSI ports from other coprocessors will probably not work.
   - Ethernet port for networking
 
+Note these are bare minimums. Most high-performance vision processing will require higher specs.
+
 ### Coprocessor Recommendations
 
-When selecting a coprocessor, it is important to consider various factors, particularly when it comes to AprilTag detection. Opting for a coprocessor with a more powerful CPU can generally result in higher FPS AprilTag detection, leading to more accurate pose estimation. However, it is important to note that there is a point of diminishing returns, where the benefits of a more powerful CPU may not outweigh the additional cost. Other coprocessors can be used but may require some extra work / command line usage in order to get it working properly.
+Vision processing on one camera stream is usually a CPU-bound operation. Some operations are able to be done in parallel, but not all. USB bandwidth and network data transfer also cause a fixed overhead.
+
+Faster CPU's generally result in lower latency, but eventually with diminishing returns. More cores allow for some improvement, especially if multiple camera streams are being processed.
+
+PhotonVision is most commonly tested around Raspbian (Debian-based) operating systems.
+
+Other coprocessors can be used but may require some extra work / command line usage in order to get it working properly.
+
+### Power Supply
+
+Coprocessors need a steady, regulated power supply. Under-volting the processor will result in CPU throttling, low performance, unexpected reboots, and sometimes electrical damage. Many coprocessors draw 5-10 amps of current.
+
+Be sure to select a power supply which regulate's the robot's variable battery voltage into something steady that the robot can use.
+
+### Storage Media
+
+Most single-board computer coprocessors use micro SD cards as their storage media.
+
+Three important considerations include total storage space, read/write speed, and robustness.
+
+PhotonVision is not usually disk-bound, other than during coprocessor boot-up and initial startup. Some disk writing is done at runtime for logging, settings, and saving camera images on command.
+
+Better storage space and read/write speed mostly matter if image capture is used frequently on the field.
+
+Industrial-grade SD cards are recommended for their stability under shock, vibration, variable voltage, and power-off. Raspberry Pi and Orange Pi coprocessors are generally robust against robot power interruptions, teams have anecdotally reported that Sandisk industrial SD cards reduce the chances of an unexpected settings or log file corruption on shutdown.
+
 
 ## Choosing a Camera
 
-PhotonVision works with Pi Cameras and most USB Cameras. Other cameras such as webcams, virtual cameras, etc. are not officially supported and may not work. It is important to note that fisheye cameras should only be used as a driver camera / gamepeice detection and not for detecting targets / AprilTags.
+PhotonVision relies on [CSCore](https://github.com/wpilibsuite/allwpilib/tree/main/cscore) to detect and process cameras, so camera support is determined based off compatibility with CScore along with native support for the camera within your OS (ex. [V4L compatibility](https://en.wikipedia.org/wiki/Video4Linux)).
 
-PhotonVision relies on [CSCore](https://github.com/wpilibsuite/allwpilib/tree/main/cscore) to detect and process cameras, so camera support is determined based off compatibility with CScore along with native support for the camera within your OS (ex. [V4L compatibility](https://en.wikipedia.org/wiki/Video4Linux) if using a Linux machine like a Raspberry Pi).
+PhotonVision attempts to support most USB Cameras. Exceptions include:
 
-:::{note}
-Logitech Cameras and integrated laptop cameras will not work with PhotonVision due to oddities with their drivers. We recommend using a different camera.
-:::
+- All Logitech brand cameras
+  - Logitech uses a non-standard driver which is not currently supported
+- Built-in webcams
+  - Driver support is too varied. Some may happen to work, but most have been found to be non-functional
+- virtual cameras (OBS, Snapchat camera, etc.)
+  - PhotonVision assumes the camera has real physical hardware to control - these do not expose the minimum number of controls.
+
+Use caution when using multiple identical cameras, as only the physical USB port they are plugged into can differentiate them. PhotonVision provides a "strict matching" setting which can reduce errors related to identical cameras. Arducam has a [tool that allows for identical cameras to be renamed](https://docs.arducam.com/UVC-Camera/Serial-Number-Tool-Guide/) by their physical location or purpose.
 
-:::{note}
-We do not currently support the usage of two of the same camera on the same coprocessor. You can only use two or more cameras if they are of different models or they are from Arducam, which has a [tool that allows for cameras to be renamed](https://docs.arducam.com/UVC-Camera/Serial-Number-Tool-Guide/).
-:::
 
 ### Cameras Attributes
 
-For colored shape detection, any non-fisheye camera supported by PhotonVision will work. We recommend a high fps USB camera.
+For colored shape detection, any non-fisheye camera supported by PhotonVision will work.
 
-For driver camera, we recommend a USB camera with a fisheye lens, so your driver can see more of the field.
+For driver camera, we recommend a USB camera with a fisheye lens, so your driver can see more of the field. Use the minimum acceptable resolution to help keep latency low.
 
-For AprilTag detection, we recommend you use a global shutter camera that has ~100 degree diagonal FOV. This will allow you to see more AprilTags in frame, and will allow for more accurate pose estimation. You also want a camera that supports high FPS, as this will allow you to update your pose estimator at a higher frequency.
+For AprilTag detection, we recommend you use a camera that has ~100 degree diagonal FOV. This will allow you to see more AprilTags in frame, and will allow for more accurate pose estimation. You also want a camera that supports high FPS, as this will allow you to update your pose estimator at a higher frequency.
 
-Another cause of image distortion is 'rolling shutter.' This occurs when the camera captures pixels sequentially from top to bottom, which can also lead to distortion if the camera or object is moving.
+For object detection, we recommend a USB camera. Some fisheye lenses may be ok, but very wide angle cameras may distort the gamepiece beyond recognition.
+
+Global shutter cameras are recommended in all cases, to reduce rolling-shutter image sheer while the robot is moving.
 
 ```{image} images/rollingshutter.gif
 :align: center
 ```
 
+Cameras capable of capturing a good image with very short exposures will also help reduce image blur. Usually, high-FPS-capable cameras designed for computer vision are better at this than "consumer-grade" USB webcams.
+
 ### Using Multiple Cameras
 
-Using multiple cameras on your robot will help you detect more AprilTags at once and improve your pose estimation as a result. In order to use multiple cameras, you will need to create multiple PhotonPoseEstimators and add all of their measurements to a single drivetrain pose estimator. Please note that the accuracy of your robot to camera transform is especially important when using multiple cameras as any error in the transform will cause your pose estimations to "fight" each other. For more information, see {ref}`the programming reference. <docs/programming/index:programming reference>`.
+Keeping the target(s) in view of the robot often requires more than one camera. PhotonVision has no hardcoded limit on the number of cameras supported. The limit is usually dependant on CPU (can all frames be processed fast enough?) and USB bandwidth (Can all cameras send their images without overwhelming the bus?).
+
+Note that cameras are not synchronized together. Frames are captured and processed asynchronously. Robot Code must fuse estimates together. For more information, see {ref}`the programming reference. <docs/programming/index:programming reference>`.
 
 ## Performance Matrix
 

docs/source/docs/objectDetection/about-object-detection.md

@@ -2,22 +2,18 @@
 
 ## How does it work?
 
-PhotonVision supports object detection using neural network accelerator hardware built into Orange Pi 5/5+ coprocessors. The Neural Processing Unit, or NPU, is [used by PhotonVision](https://github.com/PhotonVision/rknn_jni/tree/main) to massively accelerate certain math operations like those needed for running ML-based object detection.
+PhotonVision supports object detection using neural network accelerator hardware built into Orange Pi 5/5+ coprocessors. Please note that the Orange Pi 5/5+ are the only coprocessors that are currently supported. The Neural Processing Unit, or NPU, is [used by PhotonVision](https://github.com/PhotonVision/rknn_jni/tree/main) to massively accelerate certain math operations like those needed for running ML-based object detection.
 
-For the 2024 season, PhotonVision ships with a **pre-trained NOTE detector** (shown above), as well as a mechanism for swapping in custom models. Future development will focus on enabling lower friction management of multiple custom models.
-
-```{image} images/notes-ui.png
-
-```
+For the 2025 season, PhotonVision ships with a pretrained ALGAE model. A model to detect coral is not currently stable, and interested teams should ask in the Photonvision discord.
 
 ## Tracking Objects
 
 Before you get started with object detection, ensure that you have followed the previous sections on installation, wiring, and networking. Next, open the Web UI, go to the top right card, and switch to the “Object Detection” type. You should see a screen similar to the image above.
 
-PhotonVision currently ships with a NOTE detector based on a [YOLOv5 model](https://docs.ultralytics.com/yolov5/). This model is trained to detect one or more object "classes" (such as cars, stoplights, or in our case, NOTES) in an input image. For each detected object, the model outputs a bounding box around where in the image the object is located, what class the object belongs to, and a unitless confidence between 0 and 1.
+Models are trained to detect one or more object "classes" (such as cars, stoplights) in an input image. For each detected object, the model outputs a bounding box around where in the image the object is located, what class the object belongs to, and a unitless confidence between 0 and 1.
 
 :::{note}
-This model output means that while its fairly easy to say that "this rectangle probably contains a NOTE", we don't have any information about the NOTE's orientation or location. Further math in user code would be required to make estimates about where an object is physically located relative to the camera.
+This model output means that while its fairly easy to say that "this rectangle probably contains an object", we don't have any information about the object's orientation or location. Further math in user code would be required to make estimates about where an object is physically located relative to the camera.
 :::
 
 ## Tuning and Filtering
@@ -39,14 +35,29 @@ Photonvision will letterbox your camera frame to 640x640. This means that if you
 
 ## Training Custom Models
 
-Coming soon!
+:::{warning}
+Power users only. This requires some setup, such as obtaining your own dataset and installing various tools. It's additionally advised to have a general knowledge of ML before attempting to train your own model. Additionally, this is not officially supported by Photonvision, and any problems that may arise are not attributable to Photonvision.
+:::
+
+Before beginning, it is necessary to install the [rknn-toolkit2](https://github.com/airockchip/rknn-toolkit2). Then, install the relevant [Ultralytics repository](https://github.com/airockchip?tab=repositories&q=yolo&type=&language=&sort=) from this list. After training your model, export it to `rknn`. This will give you an `onnx` file, formatted for conversion. Copy this file to the relevant folder in [rknn_model_zoo](https://github.com/airockchip/rknn_model_zoo), and use the conversion script located there to convert it. If necessary, modify the script to provide the path to your training database for quantization.
 
 ## Uploading Custom Models
 
 :::{warning}
-PhotonVision currently ONLY supports YOLOv5 models trained and converted to `.rknn` format for RK3588 CPUs! Other models require different post-processing code and will NOT work. The model conversion process is also highly particular. Proceed with care.
+PhotonVision currently ONLY supports 640x640 Ultralytics YOLOv5, YOLOv8, and YOLOv11 models trained and converted to `.rknn` format for RK3588 CPUs! Other models require different post-processing code and will NOT work. The model conversion process is also highly particular. Proceed with care.
 :::
 
-Our [pre-trained NOTE model](https://github.com/PhotonVision/photonvision/blob/master/photon-server/src/main/resources/models/note-640-640-yolov5s.rknn) is automatically extracted from the JAR when PhotonVision starts, only if a file named “note-640-640-yolov5s.rknn” and "labels.txt" does not exist in the folder `photonvision_config/models/`. This technically allows power users to replace the model and label files with new ones without rebuilding Photon from source and uploading a new JAR.
+:::{warning}
+Non-quantized models are not supported! If you have the option, make sure quantization is enabled when exporting to .rknn format. This will represent the weights and activations of the model as 8-bit integers, instead of 32-bit floats which PhotonVision doesn't support. Quantized models are also much faster.
+:::
 
-Use a program like WinSCP or FileZilla to access your coprocessor's filesystem, and copy the new `.rknn` model file into /home/pi. Next, SSH into the coprocessor and `sudo mv /path/to/new/model.rknn /opt/photonvision/photonvision_config/models/note-640-640-yolov5s.rknn`. Repeat this process with the labels file, which should contain one line per label the model outputs with no training newline. Next, restart PhotonVision via the web UI.
+In the settings, under `Device Control`, there's an option to upload a new object detection model. Naming convention
+should be `name-verticalResolution-horizontalResolution-yolovXXX`. The
+`name` should only include alphanumeric characters, periods, and underscores. Additionally, the labels
+file ought to have the same name as the RKNN file, with `-labels` appended to the end. For
+example, if the RKNN file is named `Algae_1.03.2025-640-640-yolov5s.rknn`, the labels file should be
+named `Algae_1.03.2025-640-640-yolov5s-labels.txt`.
+
+:::{note}
+Currently there is no way to delete custom models in the GUI, though this is a planned feature. To do this, you have to SSH into the coprocessor and delete the files manually from `/opt/photonvision/photonvision_config/models`.
+:::

docs/source/docs/pipelines/about-pipelines.md

@@ -10,37 +10,61 @@ A vision pipeline represents a series of steps that are used to acquire an image
 
 ## Types of Pipelines
 
-### Reflective
+### AprilTag / AruCo
 
-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.
+This pipeline type is based on detecting AprilTag fiducial markers. More information about AprilTags can be found in the [WPILib documentation](https://docs.wpilib.org/en/stable/docs/software/vision-processing/apriltag/apriltag-intro.html). This pipeline provides 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>`.
+:::
+
+### Object Detection
+
+This pipeline type is based on detecting objects using a neural network. The object detection pipeline uses a pre-trained model to detect objects in the camera stream.
+
+:::{note}
+This pipeline type is only supported on the Orange Pi 5/5+ coprocessors due to its Neural Processing Unit used by PhotonVision to support running ML-based object detection.
+:::
+
+### Driver Mode
+
+Driver Mode is a type of pipeline that doesn't run any vision processing, intended for human viewing. For more information about Driver Mode, see the {ref}`Driver Mode documentation<docs/driver-mode/index:Driver Mode>`.
 
 ### 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
+### Reflective
 
-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.
+This pipeline type is based on detecting targets with reflective tape. In the contours tab of this pipeline type, you can filter the area, width/height ratio, fullness, degree of speckle rejection.
 
 :::{note}
-In order to get 3D Pose data about AprilTags, you are required to {ref}`calibrate your camera<docs/calibration/calibration:Calibrating Your Camera>`.
+This pipeline type is not used anymore due to FRC's removal of retro-reflective tape from the game. It is still available as a pipeline for legacy purposes.
 :::
 
 ## 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
+## Pipeline Configuration
 
-Reflective and Colored Shape Pipelines have 4 steps (represented as 4 tabs):
+Each pipeline has a set of tabs that are used to configure the pipeline. All pipelines follow a similar structure with an Input and Output tab, as well as a set of tabs that are specific to the pipeline type.
 
-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.
+- 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.
 
-AprilTag / AruCo Pipelines have 3 steps:
+- Output: This allows you to manipulate the detected target via the target offset point (for calculating pitch/yaw) and robot (crosshair) offset. In addition, it allows users to send additional (up to 5) outputs through PhotonLib.
 
-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.
+Pipielines also have additional tabs that are specific to the pipeline type. Listed below are the tabs for each pipeline type.
+
+### AprilTag / AruCo Pipelines
+
+- AprilTag: This tab includes AprilTag specific tuning parameters, such as decimate, blur, threads, pose iterations, and more.
+
+### Object Detection Pipelines
+
+- Object Detection: This tab allows you to filter results from the neural network, such as confidence, area, and width/height ratio. The end goal of this tab is to filter out any false positives.
+
+### Reflective and Colored Shape Pipelines
+
+- Threshold: This tab allows you to filter out 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.
+- 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.