Vision Sensor C API¶

Note

Additional example code for this module can be found in its Tutorial.

Functions ¶

vision_clear_led ¶

Clears the vision sensor LED color, resetting it back to its default behavior, displaying the most prominent object signature color.

This function uses the following values of errno when an error state is reached:

ENXIO - The given value is not within the range of V5 ports (1-21).
ENODEV - The device cannot be configured as a vision sensor

int32_t vision_clear_led ( uint8_t port )

#define VISION_PORT 1

void initialize() {
  vision_clear_led(VISION_PORT);
}

Parameters
port	The V5 port number from 1-21

Returns: 0 if no errors occurred, PROS_ERR otherwise

vision_signature_from_utility ¶

Creates a signature from the Vision Sensor utility

This function is parameter-equivalent to the functions used in VCS and RMS for constructing vision signatures.

vision_signature_s_t vision_signature_from_utility ( const int32_t id,
                                                     const int32_t u_min,
                                                     const int32_t u_max,
                                                     const int32_t u_mean,
                                                     const int32_t v_min,
                                                     const int32_t v_max,
                                                     const int32_t v_mean,
                                                     const float range,
                                                     const int32_t type )

#define VISION_PORT 1
#define EXAMPLE_SIG 1

void opcontrol() {
  // values acquired from the vision utility
  vision_signature_s_t RED_SIG =
    vision_signature_from_utility(EXAMPLE_SIG, 8973, 11143, 10058, -2119, -1053, -1586, 5.4, 0);

  vision_set_signature(VISION_PORT, EXAMPLE_SIG, &RED_SIG);
  while (true) {
    vision_signature_s_t rtn = vision_get_by_sig(VISION_PORT, 0, EXAMPLE_SIG);
    // Gets the largest object of the EXAMPLE_SIG signature
    printf("sig: %d", rtn.signature);
    // Prints "sig: 1"
    delay(2);
  }
}

Parameters
id	The signature ID
u_min	Minimum value on U axis
u_max	Maximum value on U axis
u_mean	Mean value on U axis
v_min	Minimum value on V axis
v_max	Maximum value on V axis
v_mean	Mean value on V axis
range	Signature range scale factor
type	The signature type

Returns: A vision_signature_s_t initialized with the given values

vision_create_color_code ¶

Creates a color code that represents a combination of the given signature IDs. If fewer than 5 signatures are to be a part of the color code, pass 0 for the additional function parameters.

This function uses the following values of errno when an error state is reached:

EINVAL - Fewer than two signatures have been provided or one of the

signatures is out of its [1-7] range (or 0 when omitted)

vision_color_code_t vision_create_color_code ( uint8_t port,
                                               const uint32_t sig_id1,
                                               const uint32_t sig_id2,
                                               const uint32_t sig_id3,
                                               const uint32_t sig_id4,
                                               const uint32_t sig_id5 )

#define VISION_PORT 1
#define EXAMPLE_SIG 1
                        #define OTHER_SIG 2

void opcontrol() {
  vision_color_code_t code1 = vision_create_color_code(VISION_PORT, EXAMPLE_SIG, OTHER_SIG);
}

Parameters
port	The V5 port number from 1-21
sig_id1	The first signature id [1-7] to add to the color code
sig_id2	The second signature id [1-7] to add to the color code
sig_id3	The third signature id [1-7] to add to the color code
sig_id4	The fourth signature id [1-7] to add to the color code
sig_id5	The fifth signature id [1-7] to add to the color code

Returns: A vision_color_code_t object containing the color code information.

vision_get_by_sig ¶

Gets the nth largest object of the given signature according to size_id.

This function uses the following values of errno when an error state is reached:

ENXIO - The given value is not within the range of V5 ports (1-21).
ENODEV - The device cannot be configured as a vision sensor (e.g. it has been reconfigured)
EINVAL - sig_id is outside the range [1-7]
EDOM - size_id is greater than the number of available objects.
EAGAIN - Reading the vision sensor failed for an unknown reason.

vision_object_s_t vision_get_by_sig ( uint8_t port,
                                      const uint32_t size_id,
                                      const uint8_t sig_id )

#define VISION_PORT 1
#define EXAMPLE_SIG 1

void opcontrol() {
  while (true) {
    vision_object_s_t rtn = vision_get_by_sig(VISION_PORT, 0, EXAMPLE_SIG);
    // Gets the largest object of the EXAMPLE_SIG signature
    printf("sig: %d", rtn.signature);
    // Prints "sig: 1"
    delay(2);
  }
}

Parameters
port	The V5 port number from 1-21
size_id	The object to read from a list roughly ordered by object size (0 is the largest item, 1 is the second largest, etc.)
sig_id	The signature number for which an object will be returned

Returns: The vision_object_s_t object corresponding to the given signature and size_id, or PROS_ERR if an error occurred.

vision_get_by_size ¶

Gets the nth largest object according to size_id.

This function uses the following values of errno when an error state is reached:

ENXIO - The given value is not within the range of V5 ports (1-21).
ENODEV - The device cannot be configured as a vision sensor (e.g. it has been reconfigured)
EDOM - size_id is greater than the number of available objects.
EHOSTDOWN - Reading the vision sensor failed for an unknown reason.

vision_object_s_t vision_get_by_size ( uint8_t port,
                                       const uint32_t size_id )

#define VISION_PORT 1

void opcontrol() {
  while (true) {
    vision_object_s_t rtn = vision_get_by_size(VISION_PORT, 0);
    // Gets the largest object
    printf("sig: %d", rtn.signature);
    delay(2);
  }
}

Parameters
port	The V5 port number from 1-21
size_id	The object to read from a list roughly ordered by object size (0 is the largest item, 1 is the second largest, etc.)

Returns: The vision_object_s_t object corresponding to the given size id, or PROS_ERR if an error occurred.

vision_get_by_code ¶

Gets the nth largest object of the given color code according to size_id.

This function uses the following values of errno when an error state is reached:

ENXIO - The given value is not within the range of V5 ports (1-21).
ENODEV - The device cannot be configured as a vision sensor (e.g. it has been reconfigured)
EAGAIN - Reading the vision sensor failed for an unknown reason.

vision_object_s_t vision_get_by_code ( uint8_t port,
                                       const uint32_t size_id,
                                       const vision_color_code_t color_code )

#define VISION_PORT 1
#define EXAMPLE_SIG 1
#define OTHER_SIG 2

void opcontrol() {
  vision_color_code_t code1 = vision_create_color_code(VISION_PORT, EXAMPLE_SIG, OTHER_SIG);
  while (true) {
    vision_object_s_t rtn = vision_get_by_code(VISION_PORT, 0, code1);
    // Gets the largest object
    printf("sig: %d", rtn.signature);
    delay(2);
  }
}

Parameters
port	The V5 port number from 1-21
size_id	The object to read from a list roughly ordered by object size (0 is the largest item, 1 is the second largest, etc.)
color_code	The vision_color_code_t for which an object will be returned

Returns: The vision_object_s_t object corresponding to the given color code and size_id, or PROS_ERR if an error occurred.

vision_get_exposure ¶

Gets the exposure parameter of the Vision Sensor.

This function uses the following values of errno when an error state is reached:

ENXIO - The given value is not within the range of V5 ports (1-21).
ENODEV - The device cannot be configured as a vision sensor (e.g. it has been reconfigured)

int32_t vision_get_exposure ( uint8_t port )

#define VISION_PORT 1

void initialize() {
  if (vision_get_exposure(VISION_PORT) < 50)
    vision_set_exposure(VISION_PORT, 50);
}

Parameters
port	The V5 port number from 1-21

Returns: the current exposure percentage parameter from [0,150], PROS_ERR if an error occurred

vision_get_object_count ¶

Returns the number of objects currently detected by the Vision Sensor.

This function uses the following values of errno when an error state is reached:

ENXIO - The given value is not within the range of V5 ports (1-21).
ENODEV - The device cannot be configured as a vision sensor (e.g. it has been reconfigured)

int32_t vision_get_object_count ( uint8_t port )

#define VISION_PORT 1

void opcontrol() {
  while (true) {
    printf("Number of Objects Detected: %d\n", vision_get_object_count(VISION_PORT));
    delay(2);
  }
}

Parameters
port	The V5 port number from 1-21

Returns: The number of objects detected on the specified vision sensor. Returns PROS_ERR if the port was invalid or an error occurred.

vision_get_signature ¶

Gets the object detection signature with the given id number.

This function uses the following values of errno when an error state is reached:

vision_signature_s_t vision_get_signature ( uint8_t port,
                                            const uint8_t signature_id )

                        #define VISION_PORT 1
#define EXAMPLE_SIG 1

                        void opcontrol() {
  vision_signature_s_t sig = vision_get_signature(VISION_PORT, EXAMPLE_SIG);
  vision_print_signature(sig);
                        }

Parameters
port	The V5 port number from 1-21
signature_id	The signature id to read

Returns: A vision_signature_s_t containing information about the signature.

vision_get_white_balance ¶

Gets the white balance parameter of the Vision Sensor.

This function uses the following values of errno when an error state is reached:

ENXIO - The given value is not within the range of V5 ports (1-21).
ENODEV - The device cannot be configured as a vision sensor (e.g. it has been reconfigured)

int32_t vision_get_white_balance ( uint8_t port )

#define VISION_PORT 1
#define VISION_WHITE 0xff

void initialize() {
  if (vision_get_white_balance(VISION_PORT) != VISION_WHITE)
    vision_set_white_balance(VISION_PORT, VISION_WHITE);
}

Parameters
port	The V5 port number from 1-21

Returns: Returns the current RGB white balance setting of the sensor

vision_print_signature ¶

Prints the contents of the signature as an initializer list to the terminal.

int32_t vision_print_signature ( const vision_signature_s_t sig )

#define VISION_PORT 1
#define EXAMPLE_SIG 1

void opcontrol() {
                                vision_signature_s_t sig = vision_get_signature(VISION_PORT, EXAMPLE_SIG);
  vision_print_signature(sig);
}

Parameters
sig	The signature for which the contents will be printed

Returns: 1 if no errors occured, PROS_ERR otherwise

vision_read_by_sig ¶

Reads up to object_count object descriptors into object_arr.

This function uses the following values of errno when an error state is reached:

ENXIO - The given value is not within the range of V5 ports (1-21).
ENODEV - The device cannot be configured as a vision sensor (e.g. it has been reconfigured)
EINVAL - sig_id is outside the range [1-7]
EDOM - size_id is greater than the number of available objects.

int32_t vision_read_by_sig ( uint8_t port,
                             const uint32_t size_id,
                             const uint32_t sig_id,
                             const uint32_t object_count,
                             vision_object_s_t *const object_arr )

#define VISION_PORT 1
#define EXAMPLE_SIG 1
#define NUM_VISION_OBJECTS 4

void opcontrol() {
  vision_object_s_t object_arr[NUM_VISION_OBJECTS];
  while (true) {
    vision_read_by_sig(VISION_PORT, 0, EXAMPLE_SIG, NUM_VISION_OBJECTS, object_arr);
    printf("sig: %d", object_arr[0].signature);
    // Prints "sig: 1"
    delay(2);
  }
}

Parameters
port	The V5 port number from 1-21
size_id	The first object to read from a list roughly ordered by object size (0 is the largest item, 1 is the second largest, etc.)
sig_id	The signature number for which objects will be returned
object_count	How many objects to read
object_arr	A pointer to copy the data into

Returns: The number of object signatures copied. This number will be less than object_count if there are fewer objects detected by the vision sensor. Returns PROS_ERR if the port was invalid, an error occurred, or fewer objects than size_id were found. All objects in object_arr that were not found are given VISION_OBJECT_ERR_SIG as their signature.

vision_read_by_size ¶

Reads up to object_count object descriptors into object_arr.

This function uses the following values of errno when an error state is reached:

ENXIO - The given value is not within the range of V5 ports (1-21).
ENODEV - The device cannot be configured as a vision sensor (e.g. it has been reconfigured)
EDOM - size_id is greater than the number of available objects.

int32_t vision_read_by_size ( uint8_t port,
                              const uint32_t size_id,
                              const uint32_t object_count,
                              vision_object_s_t *const object_arr )

#define VISION_PORT 1
#define NUM_VISION_OBJECTS 4

void opcontrol() {
  vision_object_s_t object_arr[NUM_VISION_OBJECTS];
  while (true) {
    vision_read_by_size(VISION_PORT, 0, NUM_VISION_OBJECTS, object_arr);
    printf("sig: %d", object_arr[0].signature);
    // Prints the signature of the largest object found
    delay(2);
  }
}

Parameters
port	The V5 port number from 1-21
size_id	The first object to read from a list roughly ordered by object size (0 is the largest item, 1 is the second largest, etc.)
object_count	How many objects to read
object_arr	A pointer to copy the data into

Returns: The number of object signatures copied. This number will be less than object_count if there are fewer objects detected by the vision sensor. Returns PROS_ERR if the port was invalid, an error occurred, or fewer objects than size_id were found. All objects in object_arr that were not found are given VISION_OBJECT_ERR_SIG as their signature.

vision_read_by_code ¶

Reads up to object_count object descriptors into object_arr.

This function uses the following values of errno when an error state is reached:

ENXIO - The given value is not within the range of V5 ports (1-21).
ENODEV - The device cannot be configured as a vision sensor (e.g. it has been reconfigured)

int32_t vision_read_by_code ( uint8_t port,
                              const uint32_t size_id,
                              const vision_color_code_t color_code,
                              const uint32_t object_count,
                              vision_object_s_t* const object_arr )

#define VISION_PORT 1
#define EXAMPLE_SIG 1
#define OTHER_SIG 2
#define NUM_VISION_OBJECTS 4

void opcontrol() {
  vision_object_s_t object_arr[NUM_VISION_OBJECTS];
  vision_color_code_t code1 = vision_create_color_code(VISION_PORT, EXAMPLE_SIG, OTHER_SIG, 0, 0, 0);
  while (true) {
    vision_read_by_code(VISION_PORT, 0, code1, NUM_VISION_OBJECTS, object_arr);
    printf("sig: %d", object_arr[0].signature);
    // Prints the signature of the largest object found
    delay(2);
  }
}

Parameters
port	The V5 port number from 1-21
size_id	The first object to read from a list roughly ordered by object size (0 is the largest item, 1 is the second largest, etc.)
color_code	The vision_color_code_t for which objects will be returned
object_count	How many objects to read
object_arr	A pointer to copy the data into

Returns: The number of object signatures copied. This number will be less than object_count if there are fewer objects detected by the vision sensor. Returns PROS_ERR if the port was invalid, an error occurred, or fewer objects than size_id were found. All objects in object_arr that were not found are given VISION_OBJECT_ERR_SIG as their signature.

vision_set_auto_white_balance ¶

Set the white balance parameter manually on the Vision Sensor.

This function uses the following values of errno when an error state is reached:

ENXIO - The given value is not within the range of V5 ports (1-21).
ENODEV - The device cannot be configured as a vision sensor (e.g. it has been reconfigured)
EINVAL - Enable was not 0 or 1

int32_t vision_set_auto_white_balance ( uint8_t port,
                                        const int32_t rgb )

#define VISION_PORT 1

void initialize() {
  vision_set_auto_white_balance(VISION_PORT, true);
}

Parameters
port	The V5 port number from 1-21
enabled	Pass 0 to disable, 1 to enable

Returns: Returns 0 if no errors occurred, PROS_ERR otherwise

vision_set_exposure ¶

Sets the exposure parameter of the Vision Sensor.

This function uses the following values of errno when an error state is reached:

ENXIO - The given value is not within the range of V5 ports (1-21).
ENODEV - The device cannot be configured as a vision sensor (e.g. it has been reconfigured)

int32_t vision_set_exposure ( uint8_t port,
                              const uint8_t exposure )

#define VISION_PORT 1

void initialize() {
  if (vision_get_exposure(VISION_PORT) < 50)
    vision_set_exposure(VISION_PORT, 50);
}

Parameters
port	The V5 port number from 1-21
exposure	The new exposure setting from [0,150]

Returns: 1 if no errors occurred, PROS_ERR otherwise

vision_set_led ¶

Sets the vision sensor LED color, overriding the automatic behavior.

This function uses the following values of errno when an error state is reached:

ENXIO - The given value is not within the range of V5 ports (1-21).
ENODEV - The device cannot be configured as a vision sensor (e.g. it has been reconfigured)

int32_t vision_set_led ( uint8_t port,
                         const int32_t rgb )

#define VISION_PORT 1

void initialize() {
  vision_set_led(VISION_PORT, COLOR_BLANCHED_ALMOND);
}

Parameters
port	The V5 port number from 1-21
rgb	An RGB code to set the LED to

Returns: 0 if no errors occured, PROS_ERR otherwise

vision_set_signature ¶

Stores the supplied object detection signature onto the vision sensor.

Note

This saves the signature in volatile memory, and the signature will be lost as soon as the sensor is powered down.

This function uses the following values of errno when an error state is reached:

int32_t vision_set_signature ( uint8_t port,
                                                       const uint8_t signature_id,
                                                                                                                                                 vision_signature_s_t* const signature_ptr )

#define VISION_PORT 1
                        #define EXAMPLE_SIG 1

void opcontrol() {
  vision_signature_s_t sig = vision_get_signature(VISION_PORT, EXAMPLE_SIG);
                                sig.range = 10.0;
                                vision_set_signature(VISION_PORT, EXAMPLE_SIG, &sig);
}

Parameters
port	The V5 port number from 1-21
signature_id	The signature id to store into
signature_ptr	A pointer to the signature to save

Returns: 1 if no errors, occurred, PROS_ERR otherwise

vision_set_white_balance ¶

Set the white balance parameter manually on the Vision Sensor.

This function will disable auto white-balancing.

This function uses the following values of errno when an error state is reached:

ENXIO - The given value is not within the range of V5 ports (1-21).
ENODEV - The device cannot be configured as a vision sensor (e.g. it has been reconfigured)

int32_t vision_set_white_balance ( uint8_t port,
                                   const int32_t rgb )

#define VISION_PORT 1
#define VISION_WHITE 0xff

void initialize() {
  vision_set_white_balance(VISION_PORT, VISION_WHITE);
}

Parameters
port	The V5 port number from 1-21
rgb	The white balance parameter

Returns: Returns 1 if no errors occurred, PROS_ERR otherwise

vision_set_zero_point ¶

Sets the (0,0) coordinate for the Field of View

This will affect the coordinates returned for each request for a vision_object_s_t from the sensor, so it is recommended that this function only be used to configure the sensor at the beginning of its use.

This function uses the following values of errno when an error state is reached:

ENXIO - The given value is not within the range of V5 ports (1-21).
ENODEV - The device cannot be configured as a vision sensor (e.g. it has been reconfigured)

int32_t vision_set_zero_point ( uint8_t port,
                                   vision_zero_e_t zero_point )

#define VISION_PORT 1

void initialize() {
  vision_set_zero_point(VISION_PORT, E_VISION_ZERO_CENTER);
}

Parameters
port	The V5 port number from 1-21
zero_point	One of `vision_zero_e_t` to set the (0,0) coordinate for the FOV

Returns: Returns 1 if no errors occurred, PROS_ERR otherwise

vision_set_wifi_mode ¶

Sets the Wi-Fi mode of the Vision Sensor

This function uses the following values of errno when an error state is reached:

ENXIO - The given value is not within the range of V5 ports (1-21).
EACCESS - Another resources is currently trying to access the port

int32_t vision_set_wifi_mode ( uint8_t port,
                                   const uint8_t enable )

#define VISION_PORT 1

void initialize() {
  vision_set_wifi_mode(VISION_PORT, 0);
}

Parameters
port	The V5 port number from 1-21
enable	Disable Wi-Fi on the Vision Sensor if 0, enable otherwise (e.g. 1)

Returns: Returns 1 if no errors occurred, PROS_ERR otherwise

typedef struct __attribute__((__packed__)) vision_signature {
  uint8_t id;
  uint8_t _pad[3];
  float range;
  int32_t u_min;
  int32_t u_max;
  int32_t u_mean;
  int32_t v_min;
  int32_t v_max;
  int32_t v_mean;
  uint32_t rgb;
  uint32_t type;
} vision_signature_s_t;

vision_object_s_t ¶

This structure contains a descriptor of an object detected by the Vision Sensor.

typedef struct __attribute__((__packed__)) vision_object {
        // Object signature
        uint16_t signature;
        // Object type, e.g. normal, color code, or line detection
        vision_object_type_e_t type;
        // left boundary coordinate of the object
        int16_t left_coord;
        // top boundary coordinate of the object
        int16_t top_coord;
        // width of the object
        int16_t width;
        // height of the object
        int16_t height;
        // Angle of a color code object in 0.1 degree units (e.g. 10 -> 1 degree, 155 -> 15.5 degrees)
        uint16_t angle;

        // coordinates of the middle of the object (computed from the values above)
        int16_t x_middle_coord;
        int16_t y_middle_coord;
} vision_object_s_t;

Value
signature	Object signature
type	Object type, e.g. normal, color code, or line detection
left_coord	left boundary coordinate of the object
top_coord	top boundary coordinate of the object
width	width of the object
height	height of the object
angle	angle of a color code object in 0.1 degree units (e.g. 10 -> 1 degree, 155 -> 15.5 degrees)
x_middle_coord	coordinates of the middle of the object (computed from the values above)
y_middle_coord	coordinates of the middle of the object (computed from the values above)

Enumerated Values ¶

vision_object_type_e_t ¶

This enumeration defines the different types of objects that can be detected by the Vision Sensor.

typedef enum vision_object_type {
  E_VISION_OBJECT_NORMAL = 0,
  E_VISION_OBJECT_COLOR_CODE = 1,
  E_VISION_OBJECT_LINE = 2
} vision_object_type_e_t;

vision_zero_e_t ¶

This enumeration defines different zero points for returned vision objects.

typedef enum vision_zero {
  E_VISION_ZERO_TOPLEFT = 0,
  E_VISION_ZERO_CENTER = 1
} vision_zero_e_t;

Value
E_VISION_ZERO_TOPLEFT	(0,0) coordinate is the top left of the FOV
E_VISION_ZERO_CENTER	(0,0) coordinate is the center of the FOV

Typedefs ¶

vision_color_code_t ¶

Color codes are just signatures with multiple IDs and a different type.

::: typedef uint16_t vision_color_code_t;

Vision Sensor C API¶

Functions ¶

vision_clear_led ¶

vision_signature_from_utility ¶

vision_create_color_code ¶

vision_get_by_sig ¶

vision_get_by_size ¶

vision_get_by_code ¶

vision_get_exposure ¶

vision_get_object_count ¶

vision_get_signature ¶

vision_get_white_balance ¶

vision_print_signature ¶

vision_read_by_sig ¶

vision_read_by_size ¶

vision_read_by_code ¶

vision_set_auto_white_balance ¶

vision_set_exposure ¶

vision_set_led ¶

vision_set_signature ¶

vision_set_white_balance ¶

vision_set_zero_point ¶

vision_set_wifi_mode ¶

Macros ¶

VISION_FOV_WIDTH ¶

VISION_FOV_HEIGHT ¶

Data Structures ¶

vision_signature_s_t ¶

vision_object_s_t ¶

Enumerated Values ¶

vision_object_type_e_t ¶

vision_zero_e_t ¶

Typedefs ¶

vision_color_code_t ¶