===== Line tracking API ===== This API can be called through the _line_ member of the [[wiki:v2:general_api|Pixy2 object]], for example:


Pixy2 pixy;

pixy.line.getMainFeatures();

Firmware versions 3.0.11 and greater will automatically switch to the [[wiki:v2:line_tracking|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 [[wiki:v2:line_quickstart|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 [[wiki:v2:line_quickstart|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 [[wiki:v2:general_api#Error codes|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 ((unless the LINE\_MODE\_MANUAL\_SELECT\_VECTOR mode bit is set through **setMode()**, in which case the Vector is set through **setVector()**)). 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. [{{wiki:v2:image_366.png?500|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 [[wiki:v2:general_api#Error codes|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. ((but this can be changed by setting the default turn angle through **setDefaultTurn()** -- normally the default turn angle is 0 (straight ahead.) )) 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. [{{wiki:v2:image_364.png?500|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) ((The raw resolution of the line tracking algorithm is 632x108. The higher horizontal resolution is important for barcode detection/decoding. The line/vector coordinates have lower resolution because they are formed on a 79x52 occupancy grid and memory constraints prevent higher resolutions.)) == 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.