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.

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!

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 ¹⁾. 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.

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).

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

Normally, the line tracking algorithm will choose the straightest path (branch) when encountering an intersection. ²⁾ 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.

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().

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).

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.

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.

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.

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.

The number of lines in the vectors variable.

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

Inside the Vector struct:

Calling this prints the vector information to the console.

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

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

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

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

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.)

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.

The number of intersections in the intersections variable.

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:

Calling this prints the intersection information to the console.

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

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

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

This array contains the lines in the intersection.

Inside the IntersectionLine struct:

This variable contains the tracking index of the line.

This variable contains the angle in degrees of the line.

The number of barcodes in the barcodes variable.

This array contains the detected barcodes.

Inside the Barcode struct:

Calling this prints the barcode information to the console.

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

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

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.

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