Class Limelight.PoseEstimateConfig

java.lang.Object
com.limelightvision.Limelight.PoseEstimateConfig
Enclosing class:
Limelight
public static class Limelight.PoseEstimateConfig extends Object
A reusable configuration object for rejection filters and standard deviation scaling. Start from a factory (defaultMT1(), defaultMT2(), noFiltering()) or from a new instance. Chain the with* methods. Attach the result with Limelight.withPoseEstimateConfig_MT1(Limelight.PoseEstimateConfig) or Limelight.withPoseEstimateConfig_MT2(Limelight.PoseEstimateConfig).

A new instance accepts every structurally valid estimate that has at least one fielded tag. It uses the same standard deviation model as defaultMT2(). 

new Limelight("limelight")
    .withPoseEstimateConfig_MT1(PoseEstimateConfig.defaultMT1()
        .withMinTagCount(2)
        .withFieldBounds(17.55, 8.05))
    .withPoseEstimateConfig_MT2(PoseEstimateConfig.defaultMT2()
        .withMaxAvgTagDistance(4.0)
        .withFieldBounds(17.55, 8.05));

  • Field Details

    • REJECT_TAG_COUNT

      public static final int REJECT_TAG_COUNT
      Rejection flag: too few contributing tags.
      See Also:

    • REJECT_AMBIGUITY

      public static final int REJECT_AMBIGUITY
      Rejection flag: single-tag ambiguity above the configured maximum.
      See Also:

    • REJECT_TAG_DISTANCE

      public static final int REJECT_TAG_DISTANCE
      Rejection flag: tag distance above a configured maximum.
      See Also:

    • REJECT_TAG_AREA

      public static final int REJECT_TAG_AREA
      Rejection flag: average tag area below the configured minimum.
      See Also:

    • REJECT_FIELD_BOUNDS

      public static final int REJECT_FIELD_BOUNDS
      Rejection flag: pose outside the configured field bounds.
      See Also:

    • REJECT_DECODE_ERROR

      public static final int REJECT_DECODE_ERROR
      Rejection flag set by the library: the source envelope had a decode error.
      See Also:

    • REJECT_NONFINITE

      public static final int REJECT_NONFINITE
      Rejection flag set by the library: a value needed for fusion was NaN or infinite.
      See Also:

    • REJECT_NO_TIMESTAMP

      public static final int REJECT_NO_TIMESTAMP
      Rejection flag set by the library: no usable capture timestamp. For example, an envelope decoded with Limelight.decode(byte[]) has no receive time
      See Also:

    • REJECT_MISSING_POSE

      public static final int REJECT_MISSING_POSE
      Rejection flag set by the library: the pose array was absent or too short, or it was the all-zero value the camera sends when it has no estimate.
      See Also:

    • REJECT_BAD_METADATA

      public static final int REJECT_BAD_METADATA
      Rejection flag set by the library: tags contributed but the reported tag distance was zero or negative.
      See Also:

    • REJECT_NO_FIELDED_TAGS

      public static final int REJECT_NO_FIELDED_TAGS
      Rejection flag set by the library: fiducials were visible but none contributed to pose estimation.
      See Also:

    • UNTRUSTED

      public static final double UNTRUSTED
      A standard deviation so large that a pose estimator ignores the measurement.
      See Also:

    • MIN_THETA_STD_DEV

      public static final double MIN_THETA_STD_DEV
      Smallest heading standard deviation this configuration produces, in radians.
      See Also:

  • Constructor Details

    • PoseEstimateConfig

      public PoseEstimateConfig()
      Creates a configuration with the default values.

    • PoseEstimateConfig

      public PoseEstimateConfig(Limelight.PoseEstimateConfig other)
      Creates an independent copy of another configuration.
      Parameters:
      other - The configuration to copy. Null gives the default values

  • Method Details

    • withMinTagCount

      public Limelight.PoseEstimateConfig withMinTagCount(int minTagCount)
      Requires at least this many contributing tags. The count uses the Limelight.FiducialTarget.fielded flags. At least one fielded tag is always required. Use withMinTagCount(2) to ignore single-tag MT1 estimates.

    • withMaxSingleTagAmbiguity

      public Limelight.PoseEstimateConfig withMaxSingleTagAmbiguity(double maxSingleTagAmbiguity)
      Rejects single-tag estimates when the ambiguity of the fielded tag is above this value (0-1). A value of 1 disables this check.

    • withMaxSingleTagDistance

      public Limelight.PoseEstimateConfig withMaxSingleTagDistance(double maxSingleTagDistanceMeters)
      Rejects single-tag estimates when the tag is farther than this distance in meters. Single-tag estimates lose accuracy with distance faster than multi-tag estimates. Set this value tighter than withMaxAvgTagDistance(double). For example, allow multi-tag estimates to 6 m and single-tag estimates to 2.5 m. Applies only when exactly one tag contributes. 0 disables this check.

    • withMaxAvgTagDistance

      public Limelight.PoseEstimateConfig withMaxAvgTagDistance(double maxAvgTagDistanceMeters)
      Rejects estimates when the average tag distance is above this value in meters. A value of 0 disables this check.

    • withMinAvgTagArea

      public Limelight.PoseEstimateConfig withMinAvgTagArea(double minAvgTagArea)
      Rejects estimates when the average tag area (percentage of image) is below this value. A value of 0 disables this check.

    • withFieldBounds

      public Limelight.PoseEstimateConfig withFieldBounds(double fieldLengthMeters, double fieldWidthMeters)
      Rejects estimates outside the field. The bounds depend on the coordinate origin of the estimate. Corner origins (wpiblue, wpired) span [0, length] x [0, width]. Centered origins span +/-length/2 x +/-width/2.

      A zero length or width disables this check.

      Parameters:
      fieldLengthMeters - Field length (x extent) in meters
      fieldWidthMeters - Field width (y extent) in meters

    • withFieldBoundsMargin

      public Limelight.PoseEstimateConfig withFieldBoundsMargin(double marginMeters)
      Sets the margin for the field bounds check. The default is 0.5. A positive margin accepts poses up to that distance outside the field. This allows small localization errors at the walls. A negative margin requires poses at least that distance inside the field walls.
      Parameters:
      marginMeters - Margin in meters. Negative values are an inset. NaN becomes 0. Infinite values clamp to the largest finite margin

    • describeRejection

      public static String describeRejection(int flags)
      Returns the rejection flags as readable text, for example "TAG_COUNT|AMBIGUITY".
      Returns:
      The rejection flags as readable text, for example "TAG_COUNT|AMBIGUITY". Empty if the estimate was accepted

    • defaultMT1

      public static Limelight.PoseEstimateConfig defaultMT1()
      The MegaTag1 defaults. The library uses these when you do not provide an MT1 configuration. Single-tag estimates must pass the ambiguity gate (0.7) and the distance gate (3 m). MT1 computes the full pose from tag geometry only. Heading is not fused. XY standard deviation = 0.5 * tagDistanceMeters / sqrt(fieldedTagCount), with a minimum of 0.0001 m. These are untuned initial values. Tune them on your robot. Start from this configuration and chain changes: PoseEstimateConfig.defaultMT1().withFieldBounds(...).

    • defaultMT2

      public static Limelight.PoseEstimateConfig defaultMT2()
      The MegaTag2 defaults. The library uses these when you do not provide an MT2 configuration. There are no acceptance gates. Gyro-fused MT2 is robust, and structural validation still applies. Heading is not fused. XY standard deviation = 0.3 * tagDistanceMeters / sqrt(fieldedTagCount), with a minimum of 0.0001 m. These are untuned initial values. Tune them on your robot. Start from this configuration and chain changes.

    • noFiltering

      public static Limelight.PoseEstimateConfig noFiltering()
      Accepts every structurally valid pose. Uses a fixed 0.5 m XY standard deviation. Heading is untrusted.

    • noFiltering

      public static Limelight.PoseEstimateConfig noFiltering(double xyStdDevMeters, double thetaStdDevRadians)
      Accepts every structurally valid pose. Uses the fixed standard deviations that you select.
      Parameters:
      xyStdDevMeters - Fixed XY standard deviation in meters
      thetaStdDevRadians - Fixed heading standard deviation in radians. Pass UNTRUSTED to exclude vision heading from fusion

    • withStdDevXY

      public Limelight.PoseEstimateConfig withStdDevXY(double baseMeters)
      Sets the base XY standard deviation in meters. When distance scaling is active, this value is per meter of average tag distance.

    • withStdDevXY

      public Limelight.PoseEstimateConfig withStdDevXY(double baseMeters, double minMeters, double maxMeters)
      Sets the base XY standard deviation. Clamps the computed value to [min, max] meters.

    • withStdDevTheta

      public Limelight.PoseEstimateConfig withStdDevTheta(double baseRadians)
      Sets the base heading standard deviation in radians. The default excludes vision heading from fusion. Lower this value only to fuse vision heading. The minimum is MIN_THETA_STD_DEV radians.

    • withStdDevTheta

      public Limelight.PoseEstimateConfig withStdDevTheta(double baseRadians, double minRadians, double maxRadians)
      Sets the base heading standard deviation. Clamps the computed value to [min, max] radians. The minimum is MIN_THETA_STD_DEV radians.

    • withStdDevDistanceScaling

      public Limelight.PoseEstimateConfig withStdDevDistanceScaling(double exponent)
      Scales the standard deviations by avgTagDistance^exponent. 1 = linear (default). 2 = quadratic. 0 = no distance scaling.

    • withStdDevDistanceScaling

      public Limelight.PoseEstimateConfig withStdDevDistanceScaling(double exponent, double minMeters, double maxMeters)
      Same as withStdDevDistanceScaling(double). Clamps the tag distance to [min, max] meters before the exponent applies. Tags closer than min scale as if at min. Tags farther than max scale as if at max.

    • withStdDevTagCountDivision

      public Limelight.PoseEstimateConfig withStdDevTagCountDivision(double exponent)
      Divides the standard deviations by fieldedTagCount^exponent. The default 0.5 divides by the square root of the fielded tag count. 0 disables this.