Class Field

java.lang.Object
org.wpilib.fields.Field
public final class Field extends Object
Class for representing a FIRST field, optional field image metadata, and optional tag poses.

The JSON format contains the top-level objects "name", "season", "game", "field-dimensions", and "program", and can optionally contain "field-image" and "field-tags". The "field-dimensions" object stores "length" and "width" in meters. The "field-image" object stores the image path and the field boundaries in image pixels. The "field-tags" object stores all field tags contained within a layout.

Pose3ds in the JSON are measured using the normal FRC coordinate system, NWU with the origin at the bottom-right corner of the blue alliance wall. setOrigin(OriginPosition) can be used to change the poses returned from getTagPose(int) to be from the perspective of a specific alliance.

Tag poses represent the center of the tag, with a zero rotation representing a tag that is upright and facing away from the (blue) alliance wall (that is, towards the opposing alliance).

  • Field Details

    • name

      public String name
      Human-readable field name.

    • season

      public String season
      Field season.

    • game

      public String game
      Game name.

    • fieldImage

      public FieldImage fieldImage
      Field image metadata, or null if this field has no image.

    • length

      public double length
      Field length in meters.

    • width

      public double width
      Field width in meters.

    • program

      public String program
      FIRST program.

    • tags

      public List<FieldTag> tags
      Field tag metadata, or null if this field has no tag layout.

    • resourceFile

      public String resourceFile
      JSON resource path for this field, or null if this field was loaded from a file.

  • Constructor Details

    • Field

      public Field()
      Constructs an empty field object for JSON deserialization.

    • Field

      public Field(String name, String season, String game, FieldImage fieldImage, double fieldLength, double fieldWidth, String program, List<FieldTag> tags)
      Constructs a field object.
      Parameters:
      name - Human-readable field name.
      season - Field season.
      game - Game name.
      fieldImage - Field image metadata, or null if this field has no image.
      fieldLength - Field length in meters.
      fieldWidth - Field width in meters.
      program - FIRST program.
      tags - Field tag metadata, or null if this field has no tag layout.

  • Method Details

    • getName

      public String getName()
      Returns the human-readable field name.
      Returns:
      The human-readable field name.

    • hasImage

      public boolean hasImage()
      Returns true if this field has field image metadata.
      Returns:
      True if this field has field image metadata.

    • getImageResource

      public String getImageResource()
      Gets the resource path of the field image described by this field.
      Returns:
      The image resource path, or null if this field has no image.

    • getImageUrl

      public URL getImageUrl()
      Gets the URL of the field image described by this field.

      This returns null unless this field has an image and the separate field image resources artifact is present on the runtime classpath.

      Returns:
      The image URL, or null if the image resource is not available.

    • getImageAsStream

      public InputStream getImageAsStream()
      Gets an input stream for the field image described by this field.

      This returns null unless this field has an image and the separate field image resources artifact is present on the runtime classpath.

      Returns:
      The image input stream, or null if the image resource is not available.

    • getJson

      public String getJson()
      Returns the original JSON contents for this field.
      Returns:
      The original JSON contents for this field, or null if none were retained.

    • hasTags

      public boolean hasTags()
      Returns true if this field has tag metadata.
      Returns:
      True if this field has tag metadata.

    • getTags

      public List<FieldTag> getTags()
      Returns a List of the FieldTags used by this field.
      Returns:
      The FieldTags used by this field.

    • getFieldLength

      public double getFieldLength()
      Returns the field length in meters.
      Returns:
      The field length in meters.

    • getFieldWidth

      public double getFieldWidth()
      Returns the field width in meters.
      Returns:
      The field width in meters.

    • setOrigin

      public void setOrigin(Field.OriginPosition origin)
      Sets the origin based on a predefined enumeration of coordinate frame origins. The origins are calculated from the field dimensions.

      This transforms the Pose3d objects returned by getTagPose(int) to return the correct pose relative to a predefined coordinate frame.

      Parameters:
      origin - The predefined origin.

    • setOrigin

      public void setOrigin(Pose3d origin)
      Sets the origin for tag pose transformation.

      This transforms the Pose3d objects returned by getTagPose(int) to return the correct pose relative to the provided origin.

      Parameters:
      origin - The new origin for tag transformations.

    • getOrigin

      public Pose3d getOrigin()
      Returns the origin used for tag pose transformation.
      Returns:
      The origin.

    • getTagPose

      public Optional<Pose3d> getTagPose(int ID)
      Gets a tag pose by its ID.
      Parameters:
      ID - The ID of the tag.
      Returns:
      The pose corresponding to the ID passed in or an empty optional if a tag with that ID was not found.

    • serialize

      public void serialize(String path) throws IOException
      Serializes a field to a JSON file.
      Parameters:
      path - The path to write to.
      Throws:
      IOException - If writing to the file fails.

    • serialize

      public void serialize(Path path) throws IOException
      Serializes a field to a JSON file.
      Parameters:
      path - The path to write to.
      Throws:
      IOException - If writing to the file fails.

    • loadField

      public static Field loadField(Fields field)
      Loads a predefined field.
      Parameters:
      field - The predefined field.
      Returns:
      The field.

    • loadFromFile

      public static Field loadFromFile(Path file) throws IOException
      Loads a field from a file on disk.
      Parameters:
      file - The JSON file to load.
      Returns:
      The field.
      Throws:
      IOException - Throws if the file could not be loaded.

    • loadFromResource

      public static Field loadFromResource(String resourcePath) throws IOException
      Loads a field from a resource file located inside the program's jar file.
      Parameters:
      resourcePath - The path to the resource file.
      Returns:
      The field.
      Throws:
      IOException - Throws if the resource could not be loaded.

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object