Allow configuring maximum target count

[2826WaveRobotics]

Description

We wanted to track more than 10 objects in an Object Detection pipeline, so we added a "Maximum Targets" setting for when "Show Multiple Targets" is enabled. The default value is 10, so no existing configuration should change, though a "Show multiple targets" setting is redundant in theory.

None of the documentation mentioned this 10-object limit, so nothing there changed for now.

I also did some homework on if we can at present send more than 127 targets. Across our decode clients

• C++ encodes lists using uint8_t's https://github.com/PhotonVision/photonvision/blob/77457219c72dfa1891e7fc35e22d7d908d0f05ae/photon-targeting/src/main/native/include/photon/dataflow/structures/Packet.h#L152C33-L152C40
• python uses signed chars

  photonvision/photon-lib/py/photonlibpy/packet.py

  Line 109 in 7745721

  return self._decodeGeneric("<b", 1)

• java uses decodeByte which is a "The byte data type is an 8-bit signed two's complement integer. It has a minimum value of -128 and a maximum value of 127 (inclusive)."

So just confirming that the correct current upper limit is 127. Any change to our pack/unpack code and datatypes silently breaks older unpack versions. this is deeply terrifying to me mid season. I should have included a schemaVersion so we can handle this in the protocol, but I didn't and now we're stuck with this until 2027.

• and change all our pack/unpacking code to use unsigned bytes instead of signed. this gets us 255 maximum,
• Change the datatype to uint16_t. This incurs a couple bytes * number of targets worth of overhead. Someone should figure out how many bytes this ends up being. see point 1
• Make the length type itself variable length. If the value of VLA[0]=0xff, then also read in the next byte. This adds a branch instruction but saves one byte

Changes

• New "Maximum Targets" slider in the UI. For apriltag/aruco pipelines, this is disabled and forced to 127 in the UI. For other pipelines this is adjustable between 1 and 127
• Apriltag/aruco pipelines are limited to 127 targets in the backend, and will print a warning if this is ever exceeded
• Adds unit test that slider is respected for colored shape, and apriltag detections are limited to 127 regardless of setting

Meta

Merge checklist:

• Pull Request title is short, imperative summary 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 v2025.3.2
• 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

[2826WaveRobotics]

Moving from #2319 to allow contributors to edit.

[mcm001]

I don't see any tests showing that the upgrade logic works as expected?

[samfreund]

I don't see any tests showing that the upgrade logic works as expected?

I'd like to get #2331 in, then I'll use that config to test.

[Jake-Schuler]

This may be sorta irrelevant as this was a week ago but we did test it and were able to detect ~78ish fuel and we also lowered it down to one and it would choose the closest one. Here's an image of the change working to detect more than 10 (at the time) fuel.

[mcm001]

Also looks to be missing new unit tests showing that the limit is respected. Would accept test evidence instead

[mcm001]

Right now:

• C++ encodes lists using uint8_t's https://github.com/PhotonVision/photonvision/blob/77457219c72dfa1891e7fc35e22d7d908d0f05ae/photon-targeting/src/main/native/include/photon/dataflow/structures/Packet.h#L152C33-L152C40
• python uses signed chars

  photonvision/photon-lib/py/photonlibpy/packet.py

  Line 109 in 7745721

  return self._decodeGeneric("<b", 1)

• java uses decodeByte which is a "The byte data type is an 8-bit signed two's complement integer. It has a minimum value of -128 and a maximum value of 127 (inclusive)."

So just confirming that the correct current upper limit is 127. Any change to our pack/unpack code and datatypes silently breaks older unpack versions. this is deeply terrifying to me mid season. I should have included a schemaVersion so we can handle this in the protocol, but I didn't and now we're stuck with this until 2027.

• and change all our pack/unpacking code to use unsigned bytes instead of signed. this gets us 255 maximum,
• Change the datatype to uint16_t. This incurs a couple bytes * number of targets worth of overhead. Someone should figure out how many bytes this ends up being. see point 1
• Make the length type itself variable length. If the value of VLA[0]=0xff, then also read in the next byte. This adds a branch instruction but saves one byte

[Gold856]

There are a bunch of off-by-one errors.

So just confirming that the correct current upper limit is 127

Sort of incorrect. The max number of targets is 128. The max index, therefore, must be 127. There are several instances of List#size being (incorrectly) directly compared to Byte.MAX_VALUE. The list size should be subtracted by one first.

There's also a bunch of duplicated code checking the list size in various different pipelines. There must be a better place to do that...

[mcm001]

Concur wrt the duplicated code, but j do think that the pipeline is the correct place for the limit to live.

However, there is not an off by one in my implementation. Java bytes max value is 127. 0 means 0 targets, 1 means one target, and 127 means 127 targets. 128 is not representable by a Java byte. Therefore the length of the target list must be on [0,127]. QED