wiki:v2:line_api
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
wiki:v2:line_api [2018/06/04 22:19] pixycam [Line tracking API] |
wiki:v2:line_api [2018/10/10 20:05] (current) jfrench added protocol reference link |
||
|---|---|---|---|
| Line 9: | Line 9: | ||
| </code> | </code> | ||
| - | The functions in this API will always return errors unless the [[wiki:v2:line_tracking|line_tracking]] program is being run. | + | See also the [[wiki:v2:general_api|Pixy2 General API]], [[wiki:v2:ccc_api|Color Connected Components API]], and [[wiki:v2:video_api|Video API]] for other functionality. |
| - | A good program to run to familiarize yourself the Line Tracking algorithm is the *line_hello_world* example found in the Arduino library. | + | For a byte-level reference to the protocol, check out the new [[wiki:v2:protocol_reference|Pixy2 Serial Protocol - Packet Reference]] |
| + | |||
| + | |||
| + | 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 ==== | ==== 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. | + | 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! |
| Line 43: | Line 49: | ||
| * Barcodes are reported after they meet the filtering constraint. | * 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. | * 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.}}] | ||
| | | ||
| Line 76: | Line 85: | ||
| - | Turn angles are specified in degrees, with 0 being straight ahead, left being 90 and right being -90 (for example), although any valid angle can be used. Valid angles are between -180 and 180. | + | 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.}}] | ||
| Line 87: | Line 99: | ||
| 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. | 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 can be used. Valid angles are between -180 and 180. | + | |
| + | 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) === | === int8_t setVector(uint8_t index) === | ||
| Line 94: | Line 107: | ||
| === int8_t reverseVector() === | === 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. | 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 ==== | ==== Member variables ==== | ||
| + | |||
| === uint8_t numVectors === | === uint8_t numVectors === | ||
| The number of lines in the **vectors** variable. | The number of lines in the **vectors** variable. | ||
| + | |||
| === Vector vectors[] === | === Vector vectors[] === | ||
| This array contains either all of the detected lines if getAllFeatures() is called or the Vector if getMainFeatures() is called. | This array contains either all of the detected lines if getAllFeatures() is called or the Vector if getMainFeatures() is called. | ||
| + | |||
| Inside the Vector struct: | Inside the Vector struct: | ||
| == void print() == | == void print() == | ||
| Calling this prints the vector information to the console. | Calling this prints the vector information to the console. | ||
| + | |||
| == uint8_t m_x0 == | == 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.)) | 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 == | == 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). | 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 == | == uint8_t m_x1 == | ||
| - | This variable contains the x location of the head of the Vector or line. The value ranges between 0 and _frameWidth_ (79). | + | 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 == | == uint8_t m_y1 == | ||
| - | This variable contains the y location of the head of the Vector or line. The value ranges between 0 and _frameWidth_ (52). | + | 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 == | == 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.) | 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 == | == uint8_t m_flags == | ||
| Line 130: | Line 153: | ||
| 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. | 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 === | === uint8_t numIntersections === | ||
| The number of intersections in the **intersections** variable. | The number of intersections in the **intersections** variable. | ||
| + | |||
| === Intersection intersections[] === | === 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. | 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: | Inside the intersection struct: | ||
| + | |||
| == void print() == | == void print() == | ||
| Calling this prints the intersection information to the console. | Calling this prints the intersection information to the console. | ||
| + | |||
| == uint8_t m_x == | == uint8_t m_x == | ||
| This variable contains the x location of the intersection. The value ranges between 0 and _frameWidth_ (79). | This variable contains the x location of the intersection. The value ranges between 0 and _frameWidth_ (79). | ||
| + | |||
| == uint8_t m_y == | == uint8_t m_y == | ||
| This variable contains the y location of the intersection. The value ranges between 0 and _frameHeight_ (52). | This variable contains the y location of the intersection. The value ranges between 0 and _frameHeight_ (52). | ||
| + | |||
| == uint8_t m_n == | == uint8_t m_n == | ||
| This variable contains the number of lines (branches) in the intersection and in the **m_intLines** array. | This variable contains the number of lines (branches) in the intersection and in the **m_intLines** array. | ||
| + | |||
| == IntersectionLine m_intLines[] == | == IntersectionLine m_intLines[] == | ||
| This array contains the lines in the intersection. | This array contains the lines in the intersection. | ||
| + | |||
| Inside the IntersectionLine struct: | Inside the IntersectionLine struct: | ||
| + | |||
| == uint8_t m_index == | == uint8_t m_index == | ||
| This variable contains the tracking index of the line. | This variable contains the tracking index of the line. | ||
| + | |||
| == int16_t m_angle == | == int16_t m_angle == | ||
| This variable contains the angle in degrees of the line. | This variable contains the angle in degrees of the line. | ||
| + | |||
| === uint8_t numBarcodes === | === uint8_t numBarcodes === | ||
| The number of barcodes in the **barcodes** variable. | The number of barcodes in the **barcodes** variable. | ||
| + | |||
| === Barcode barcodes[] === | === Barcode barcodes[] === | ||
| This array contains the detected barcodes. | This array contains the detected barcodes. | ||
| + | |||
| Inside the Barcode struct: | Inside the Barcode struct: | ||
| + | |||
| == void print() == | == void print() == | ||
| + | |||
| Calling this prints the barcode information to the console. | Calling this prints the barcode information to the console. | ||
| + | |||
| == uint8_t m_x == | == uint8_t m_x == | ||
| This variable contains the x location of the barcode. The value ranges between 0 and _frameWidth_ (79). | This variable contains the x location of the barcode. The value ranges between 0 and _frameWidth_ (79). | ||
| + | |||
| == uint8_t m_y == | == uint8_t m_y == | ||
| This variable contains the y location of the barcode. The value ranges between 0 and _frameHeight_ (52). | This variable contains the y location of the barcode. The value ranges between 0 and _frameHeight_ (52). | ||
| + | |||
| == uint8_t m_flags == | == uint8_t m_flags == | ||
| Line 185: | Line 227: | ||
| 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. | 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 == | == uint8_t m_code == | ||
wiki/v2/line_api.1528150752.txt.gz · Last modified: 2018/06/04 22:19 by pixycam
Page Tools
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
