Differences

This shows you the differences between two versions of the page.

--- wiki:v2:ccc_api [2018/05/22 18:01]
pixycam
+++ wiki:v2:ccc_api [2018/10/10 20:05] (current)
jfrench added protocol reference link
@@ Line 2: / Line 2: @@
 This API can be called through the _ccc_ member of the [[wiki:v2:general_api|Pixy2 object]], for example:
 <code>
@@ Line 8: / Line 9: @@
 pixy.ccc.getBlocks();
 </code>
+See also the [[wiki:v2:general_api|Pixy2 General API]], [[wiki:v2:line_api|Line tracking API]], and [[wiki:v2:video_api|Video API]] for other functionality.
+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:color_connected_components|color_connected_components]] program when making requests through the color connected components API. Older firmware versions will return errors when attempting to call these functions while the color connected components program is not running.
+A good program to run to familiarize yourself the CCC algorithm is the *ccc\_hello\_world* example found in the Arduino library.
+[{{wiki:v2:image_365.png?500|Color connected components image coordinates from Pixy2's perspective}}]
 ==== Member functions ====
@@ Line 13: / Line 28: @@
 === int8_t getBlocks(bool wait [optional], uint8_t sigmap [optional], uint8_t maxBlocks [optional]) ===
-getBlocks() gets all detected blocks in the most recent frame.  The new data is then available in the **blocks** member variable.  It returns an [[wiki:v2:general_api#Error codes|error value]] (<0) if it fails and 0 (PIXY\_RESULT\_OK) if it succeeds.
+getBlocks() gets all detected blocks in the most recent frame.  The new data is then available in the **blocks** member variable.  The returned blocks are sorted by area, with the largest blocks appearing first in the **blocks** array.  It returns an [[wiki:v2:general_api#Error codes|error value]] (<0) if it fails and the number of detected blocks (>=0) if it succeeds.
-Setting _wait_ to false causes getBlocks() to return immediately if no new data is available (polling mode).  Setting _wait_ to true (default) causes getBlocks to block (wait) until new block data is available.
+Setting _wait_ to false causes getBlocks() to return immediately if no new data is available (polling mode).  Setting _wait_ to true (default) causes getBlocks() to block (wait) until the next frame of block data is available.  Note, there may be no block data if no objects have been detected.
 _sigmap_ is a bitmap of all 7 signatures from which you wish to receive block data.  For example, if you are only interested in block data from signature 1, you would pass in a value of 1.  If you are interested in block data from both signatures 1 and 2, you would pass in a value of 3.  If you are interested in block data from signatures 1, 2, and 3, you would pass a value of 7, and so on.  The most-significant-bit (128 or 0x80) is used for color-codes. A value of 255 (default) indicates that you are interested in all block data.
@@ Line 27: / Line 42: @@
 The number of blocks contained in the **blocks** member variable.
-=== Block *blocks ===
+=== Block blocks[] ===
+This array contains all of the block data as a result of **getBlocks()**.  The blocks in this array are sorted by area, with the largest blocks appearing first in the **blocks** array.
-This contains all of the block data as a result of **getBlocks()**.  Inside the Block struct:
+Inside the Block struct:
-== void print() --
+== void print() ==
 Calling this prints the block information to the console.
@@ Line 38: / Line 56: @@
 == uint16_t m_x ==
-This variable contains the x location of the center of the block.  The value ranges between 0 and _frameWidth_ (316).
+This variable contains the x location of the center of the block.  The value ranges between 0 and _frameWidth_ (315).
 == uint16_t m_y ==
-This variable contains the y location of the center of the block.  The value ranges between 0 and _frameHeight_ (208).
+This variable contains the y location of the center of the block.  The value ranges between 0 and _frameHeight_ (207).
 == uint16_t m_width ==
@@ Line 53: / Line 71: @@
 == uint8_t m_index ==
-This variable contains the tracking index of the block.  When Pixy2 detects a new block, it will add it to a table of blocks that it is currently tracking. It will then attempt to find the block (and every block in the table) in the next frame by finding its best match. Each block index will be kept for that object until it either leaves Pixy2's field-of-view, or Pixy2 can no longer find the object in subsequent frames (because of occlusion, lack of lighting, etc.)
+This variable contains the tracking index of the block.  When Pixy2 detects a new block, it will add it to a table of blocks that it is currently tracking and assign it a tracking index. It will then attempt to find the block (and every block in the table) in the next frame by finding its best match. Each block index will be kept for that block until it either leaves Pixy2's field-of-view, or Pixy2 can no longer find the object in subsequent frames (because of occlusion, lack of lighting, etc.)
 == uint8_t m_age ==

Documentation

User Tools

Site Tools

Differences

Page Tools