<< return to Pixycam.com

User Tools

Site Tools


wiki:v2:line_api

Line tracking API

This API can be called through the line member of the Pixy2 object, for example:

Pixy2 pixy;

pixy.line.getMainFeatures();

See also the Pixy2 General API, Color Connected Components API, and Video API for other functionality.

For a byte-level reference to the protocol, check out the new Pixy2 Serial Protocol - Packet Reference

Firmware versions 3.0.11 and greater will automatically switch to the line_tracking program when making requests through the line tracking API.

A good program to run to familiarize yourself the Line Tracking algorithm is the line_hello_world example found in the Arduino Pixy2 library. This quickstart guide will get you off to a good start.

Whoa, this looks complicated

The line-tracking algorithm is really easy to use, especially if you stick to getMainFeatures(), which does it's best to keep your program simple, and it does a pretty good job. If you haven't stepped through this quickstart guide, do it!

The getAllFeatures() function is for more advanced programs and applications. Steer clear of it if you're just getting started!

Member functions

int8_t getMainFeatures(uint8_t features [optional], bool wait [optional])

This function gets the latest features including the Vector, any intersection that connects to the Vector, and barcodes. The results are returned in the variables vectors, intersections, and barcodes, respectively.

The optional features argument is a bitwise-ORing of LINE_VECTOR (1), LINE_INTERSECTION (2), and LINE_BARCODE (4), depending on what features you are interested in. All features, if present, are returned by default.

Setting wait to false causes getMainFeatures() to return immediately if no new data is available (polling mode). Setting wait to true (default) causes getMainFeatures() to block (wait) until the next frame of line feature data is available, unless the current frame of features hasn't been returned before, in which case, it will return immediately with the current frame's features. Note, there may be no feature data if no features have been detected.

If successful, the result is a bitwise-ORing of LINE_VECTOR (1), LINE_INTERSECTION (2), and LINE_BARCODE (4), depending on the data returned. If unsuccessful it returns an error value (<0).

getMainFeatures() tries to send only the most relevant information. Some notes:

  • The line tracking algorithm finds the best Vector candidate and begins tracking it from frame to frame 1). The Vector is often the only feature getMainFeatures() returns.
  • Intersections are reported after they meet the filtering constraint. Only intersections that connect to the Vector are reported.
  • Barcodes are reported after they meet the filtering constraint.
  • Each new barcode and intersection is reported only one time so your program doesn't need to keep track of which features it has/hasn't seen previously.
Line tracking image coordinates from Pixy2's perspective. See note (3) below about resolution.

int8_t getAllFeatures(uint8_t features [optional], bool wait [optional])

This function returns all lines, intersections and barcodes that the line tracking algorithm detects. The results are returned in the variables vectors, intersections, and barcodes, respectively.

The optional features argument is a bitwise-ORing of LINE_VECTOR (1), LINE_INTERSECTION (2), and LINE_BARCODE (4), depending on what features you are interested in. All detected features are returned by default.

Setting wait to false causes getMainFeatures() to return immediately if no new data is available (polling mode). Setting wait to true (default) causes getMainFeatures() to block (wait) until the next frame of line feature data is available. Note, there may be no feature data if no features have been detected.

If successful, the result is a bitwise-ORing of LINE_VECTOR (1), LINE_INTERSECTION (2), and LINE_BARCODE (4), depending on the data returned. If unsuccessful it returns an error value (<0).

int8_t setMode(uint8_t mode)

This function sets various modes in the line tracking algorithm. The mode argument consists of a bitwise-ORing of the following bits:

LINE_MODE_TURN_DELAYED

Normally, the line tracking algorithm will choose the straightest path (branch) when encountering an intersection. 2) Setting LINE_MODE_TURN_DELAYED will prevent the line tracking algorithm from choosing the path automatically. This is useful if your program doesn't know beforehand which path it wants to take at the next intersection.

LINE_MODE_MANUAL_SELECT_VECTOR

Normally, the line tracking algorithm will choose what it thinks is the best Vector line automatically. Setting LINE_MODE_MANUAL_SELECT_VECTOR will prevent the line tracking algorithm from choosing the Vector automatically. Instead, your program will need to set the Vector by calling setVector().

LINE_MODE_WHITE_LINE

Normally, the line tracking algorithm will try to find dark lines on a light background (black lines). Setting LINE_MODE_WHITE_LINE will instruct the line tracking algorithm to look for light lines on a dark background (white lines).

int8_t setNextTurn(int16_t angle)

This function tells the line tracking algorithm which path it should take at the next intersection.

Turn angles are specified in degrees, with 0 being straight ahead, left being 90 and right being -90 (for example), although any valid angle value can be used. Valid angles are between -180 and 180.

Angle coordinates from Pixy2's perspective.

setNextTurn() will remember the turn angle you give it, and execute it at the next intersection. The line tracking algorithm will then go back to the default turn angle for subsequent intersections.

Upon encountering an intersection, the line tracking algorithm will find the path in the intersection that matches the turn angle most closely.

int8_t setDefaultTurn(int16_t angle)

This function tells the line tracking algorithm which path to choose by default upon encountering an intersection. The line tracking algorithm will find the path in the intersection that matches the default turn angle most closely. A call to setNextTurn() will supercede the default turn angle for the next intersection.

Turn angles are specified in degrees, with 0 being straight ahead, left being 90 and right being -90 (for example), although any valid angle value can be used. Valid angles are between -180 and 180.

int8_t setVector(uint8_t index)

If the LINE_MODE_MANUAL_SELECT_VECTOR mode bit is set, the line tracking algorithm will no longer choose the Vector automatically. Instead, setVector() will set the Vector by providing the index of the line.

int8_t reverseVector()

The Vector has a direction. It normally points up, from the bottom of the camera frame to the top of the camera frame for a forward-moving robot. Calling reverseVector() will invert the vector. This will typically cause your robot to back-up and change directions.

Member variables

uint8_t numVectors

The number of lines in the vectors variable.

Vector vectors[]

This array contains either all of the detected lines if getAllFeatures() is called or the Vector if getMainFeatures() is called.

Inside the Vector struct:

void print()

Calling this prints the vector information to the console.

uint8_t m_x0

This variable contains the x location of the tail of the Vector or line. The value ranges between 0 and frameWidth (79) 3)

uint8_t m_y0

This variable contains the y location of the tail of the Vector or line. The value ranges between 0 and frameWidth (52).

uint8_t m_x1

This variable contains the x location of the head (arrow end) of the Vector or line. The value ranges between 0 and frameWidth (79).

uint8_t m_y1

This variable contains the y location of the head (arrow end) of the Vector or line. The value ranges between 0 and frameWidth (52).

uint8_t m_index

This variable contains the tracking index of the Vector or line. When Pixy2 detects a new line, it will add it to a table of lines that it is currently tracking. It will then attempt to find the line (and every line in the table) in the next frame by finding its best match. Each line index will be kept for that line until the line either leaves Pixy2's field-of-view, or Pixy2 can no longer find the line in subsequent frames (because of occlusion, lack of lighting, etc.)

uint8_t m_flags

This variable contains various flags that might be useful.

LINE_FLAG_INTERSECTION_PRESENT: This flag is only available if getMainFeatures() is called and the Vector is provided. This flag indicates that an intersection was detected but may not have met the filtering constraint.

LINE_FLAG_INVALID: This flag is only available if getAllFeatures() is called. This flag indicates that the line has been detected but has not met the filtering constraint.

uint8_t numIntersections

The number of intersections in the intersections variable.

Intersection intersections[]

This array contains either all of the detected intersections if getAllFeatures() is called or a single intersection that connects to the Vector if present and if getMainFeatures() is called.

Inside the intersection struct:

void print()

Calling this prints the intersection information to the console.

uint8_t m_x

This variable contains the x location of the intersection. The value ranges between 0 and frameWidth (79).

uint8_t m_y

This variable contains the y location of the intersection. The value ranges between 0 and frameHeight (52).

uint8_t m_n

This variable contains the number of lines (branches) in the intersection and in the m_intLines array.

IntersectionLine m_intLines[]

This array contains the lines in the intersection.

Inside the IntersectionLine struct:

uint8_t m_index

This variable contains the tracking index of the line.

int16_t m_angle

This variable contains the angle in degrees of the line.

uint8_t numBarcodes

The number of barcodes in the barcodes variable.

Barcode barcodes[]

This array contains the detected barcodes.

Inside the Barcode struct:

void print()

Calling this prints the barcode information to the console.

uint8_t m_x

This variable contains the x location of the barcode. The value ranges between 0 and frameWidth (79).

uint8_t m_y

This variable contains the y location of the barcode. The value ranges between 0 and frameHeight (52).

uint8_t m_flags

This variable contains various flags that might be useful.

LINE_FLAG_INVALID: This flag is only available if getAllFeatures() is called. This flag indicates that the barcode has been detected but has not met the filtering constraint.

uint8_t m_code

This variable contains the value of the code, which can range between 0 and 15.

1)
unless the LINE_MODE_MANUAL_SELECT_VECTOR mode bit is set through setMode(), in which case the Vector is set through setVector()
2)
but this can be changed by setting the default turn angle through setDefaultTurn() – normally the default turn angle is 0 (straight ahead.)
3)
The raw resolution of the line tracking algorithm is 632×108. The higher horizontal resolution is important for barcode detection/decoding. The line/vector coordinates have lower resolution because they are formed on a 79×52 occupancy grid and memory constraints prevent higher resolutions.
wiki/v2/line_api.txt · Last modified: 2018/10/10 20:05 by jfrench