[wpimath] Alliance Coordinate Symmetry Utility

[oh-yes-0-fps]

Motivations behind this pr:

• First and foremost is to provide a way for teams to flip Pose2d based on the alliance, this is borderline required for modern autos and having to reset odometry.
• A standard API for this type of "flipping" action, other things besides the geometry types can be flipped. For example, there are quite a few types in choreolib that can be "flipped" and keeping API continuity for doing the same action would be nice.
• Most code works year to year, you could have used most 2023 vendordeps and wpilib in 2024 if it weren't for the fact of version requirements in places. One place this could change is with vendordeps that handle alliance flipping for you, this allows teams to specify old years for flipping functionality. This isn't a massive concern, it's unlikely teams will update old bots code to a new years vendordeps but it is a good thing to consider.

The reason I made Flippable an interface, beyond what is said above abt API continuity, is to help with discoverability. Having a flip() method on these objects will make it much easier to find this functionality than locking it behind a utility class(also helps with verbosity). Moving to this interface meant moving the utility to be part of wpimath instead of wpilibj/c.

I am unsure if all of the flipping in this is mathematically correct, they were just put together quickly to show what would go in this util.

[Starlight220]

This should throw or something if there isn't an alliance color, not assume blue.

[oh-yes-0-fps]

I disagree, the driver station is often not available when robot code is first booting. This would result in many ds connectivity checks or the user bypassing these functions altogether to prevent silly crashes. So it's really either they don't throw or we don't include these methods.

[rzblue]

this would result in many ds connectivity checks or the user bypassing these functions altogether to prevent silly crashes.

No, that's exactly the point. Throwing and then the code restarting while the DS is disconnected is far better than the code starting up and latching to the wrong alliance. See #5229, #5230

[calcmogul]

This library addition seems a bit overly complex. The minimum API you could get away with is 6 AllianceFlipper member functions, one for each geometry type.

public class AllianceFlipper {
  public AllianceFlipper(int year);
  public Rotation2d flip(Rotation2d);
  ...
};

template <int Year>
class AllianceFlipper {
 public:
  static Rotation2d Flip(const Rotation2d&) const;
  ...
};

In Java, they'd use an if statement on the year to decide which flipping method to use. In C++, they can use constexpr if.

Here's the usage (note that we recommend sampling the alliance color when autonomous starts, not when the robot program starts):

constexpr AllianceFlipper<2024> flipper;
Rotation2d rot = ...;
if (auto alliance = frc::DriverStation::GetAlliance(); alliance.has_value() && alliance.value() == kRed) {
  rot = flipper.Flip(rot);
}

I don't see a reason to support custom flippers because unlike custom AprilTag field layouts at home, alliance flipping only really makes sense to do on regulation fields. Also, if your regulation field isn't in-spec, you'll have other problems like the provided AprilTagFieldLayouts not working.

[pjreiniger]

I like the simplicity of commit 1 as opposed to tendriling this to all of the geometry classes

[pjreiniger]

The other libraries (fieldImages / AprilTagLayout) do this with a game enum.

[pjreiniger]

I don't think this should be part of the library. It doesn't buy the user / vendordep much over having the user control it.

[oh-yes-0-fps]

Moved text to first comment

[oh-yes-0-fps]

/format

[katzuv]

I think this is cool! Perhaps add another flip() method that uses the current year? It will be much simpler to not need to include the year everywhere.

[oh-yes-0-fps]

It will be much simpler to not need to include the year everywhere.

As of the current implementation, the user never has to provide the year if they don't want to, the year is set as static and defaults to the current year.