Teach Pixy an object

Version 13 (Rich LeGrand, 02/25/2014 11:19 am)

1 5 Rich LeGrand
h1. Teach Pixy an Object
2 1 Rich LeGrand
3 10 Rich LeGrand
Teaching Pixy an object is super easy, but first let's talk about which objects will work well with Pixy.  Pixy uses a hue-based color filtering algorithm to detect objects.  Since Pixy uses hue (color), the object needs to have a distinct hue.  Here are some objects that are good because they have good, distinct hues.
4 1 Rich LeGrand
5 10 Rich LeGrand
!{width: 10%}http://i74.photobucket.com/albums/i241/cmucam/tennisball_zps93bb0163.jpg!
6 10 Rich LeGrand
!{width: 10%}http://i74.photobucket.com/albums/i241/cmucam/pinkpenguin_zps99f4cb1e.jpg!
7 1 Rich LeGrand
8 1 Rich LeGrand
Here are some bad objects because either there is no hue (black, white or gray) or the hue is not distinct.  
9 2 Rich LeGrand
10 10 Rich LeGrand
!{width: 10%}http://i74.photobucket.com/albums/i241/cmucam/Black_Stapler_zpsc3024407.jpg!
11 10 Rich LeGrand
!{width: 10%}http://i74.photobucket.com/albums/i241/cmucam/stone_zpsd3435436.png!
12 4 Rich LeGrand
13 10 Rich LeGrand
Keeping these guidelines in mind, choose an object to teach Pixy.  (Apply power to Pixy via battery or USB cable if you haven't already.  When you power up Pixy, it will go through a series of LED flashes.  Wait for the led to turn off before teaching Pixy.)  Hold down the button on top of Pixy.  After about 1 second, the LED will turn on, first white, then red, then other colors, but when it turns red, release the button.  
14 4 Rich LeGrand
15 10 Rich LeGrand
When you release the button, Pixy will enter what's called "light pipe" mode, where the LED color is the color of the center pixels of Pixy's image frame.  
16 4 Rich LeGrand
17 10 Rich LeGrand
[todo: insert quick video]
18 1 Rich LeGrand
19 11 Rich LeGrand
Use the LED color as feedback to determine if your object is in the center of Pixy's image frame.  When you are satisfied that the LED color matches your object color press and release the button, like you'd click your mouse.  If Pixy determines that the hue of your object is "good enough" (has enough color saturation), the LED will flash and you're done.  Pixy has now "learned" your object and will start tracking objects of the same color.  If the hue is not good enough, the LED will simply turn off (no flashing) and Pixy will not have learned your object. If the LED doesn't flash, you might choose another object that has a better color saturation, or consult the Pixy troubleshooting section **.
20 1 Rich LeGrand
21 10 Rich LeGrand
h3. Multiple Signatures
22 5 Rich LeGrand
23 10 Rich LeGrand
Pixy can learn up to seven color signatures. In the previous section, we taught Pixy the 1st color signature by releasing the button when the LED turned red. If we had continued to hold down the button, the led would have turned, orange, yellow, etc., indicating the remaining color signatures. Here are the signatures in order:
24 6 Rich LeGrand
25 5 Rich LeGrand
# Red
26 5 Rich LeGrand
# Orange
27 5 Rich LeGrand
# Yellow
28 5 Rich LeGrand
# Green
29 1 Rich LeGrand
# Cyan (light blue)
30 5 Rich LeGrand
# Blue
31 1 Rich LeGrand
# Violet
32 5 Rich LeGrand
33 10 Rich LeGrand
The color signature number is determined by _when_ you release the button.  Release the button when the LED is yellow and you're teaching signature 3.  Release the button when the LED is blue and you're teaching signature 6.  These colors _are not at all related to the hue of the object_.  The colors are used only to indicate the signature number. So, for example, signature 1 can be a yellow object, even though signature 1 is indicated by a red LED, and signature 2 could be a pink object even though signature 2 is 
34 5 Rich LeGrand
indicated by an orange LED.  
35 1 Rich LeGrand
  
36 1 Rich LeGrand
h3. Other Notes on Teaching
37 1 Rich LeGrand
38 10 Rich LeGrand
When you press and release the button to indicate that you're satisfied that the LED color matches your object color, Pixy will flash the LED, and the brightness of the flashing indicates the "goodness" of the hue of the object (how saturated).  So bright flashing is good! Try teaching Pixy a fluorescent colored object -- Pixy will indicate his (her?) happiness by flashing the LED brightly.  
39 9 Rich LeGrand
40 10 Rich LeGrand
If you accidentally find yourself teaching signature 2 when you meant to teach signature 3, for example, just hold down the button until the LED turns off.  This is how you tell Pixy to cancel teach mode.  You can then start over by holding the button down again. 
41 1 Rich LeGrand
42 5 Rich LeGrand
h3. White Balance
43 5 Rich LeGrand
44 1 Rich LeGrand
Some types of lighting (such as incandescent) have a reddish hue and others (such as fluorescent) have a bluish hue.  The lighting can affect your color signatures.  For example, if you teach an object under incandescent lighting and move into a room with fluorescent lighting, the color signatures will likely no longer work as well.  You can either re-teach all signatures or you can adjust the white balance.
45 6 Rich LeGrand
46 1 Rich LeGrand
When you first apply power to Pixy, it will spend the first 5 or so seconds determining the correct white balance to use.  It will then disable automatic white balance.  If you wish to readjust the white balance, hold down the button until the LED turns white and release.  It happens quickly, so be prepared!  Pixy is now in automatic white balance mode.  You can hold a white sheet of paper in front of Pixy so Pixy can adjust the white balance.  It only takes 2 or 3 seconds to adjust the white balance, after which you can press and release the button (like a mouse click). The LED will flash, indicating success, and you're done.   
47 6 Rich LeGrand
48 6 Rich LeGrand
h3. Teach Through PixyMon
49 9 Rich LeGrand
50 10 Rich LeGrand
You can also teach Pixy object through PixyMon.  This may be useful if the object you want to teach is small or if you want more control over which pixels are used for teaching. Begin by plugging in the USB cable between Pixy and your computer and running PixyMon.  When PixyMon comes up click on the raw icon.
51 6 Rich LeGrand
52 10 Rich LeGrand
!http://i74.photobucket.com/albums/i241/cmucam/Image139_zps92ba2ff1.jpg!
53 6 Rich LeGrand
54 12 Rich LeGrand
Now hold the object you want to teach in front of Pixy and select *Action➜Set signature 1* from the pulldown menu.
55 6 Rich LeGrand
56 10 Rich LeGrand
!{width: 50%}http://i74.photobucket.com/albums/i241/cmucam/Image127_zps75a6cdef.jpg!
57 6 Rich LeGrand
58 6 Rich LeGrand
Now select you region you want Pixy to use to learn the object.  
59 6 Rich LeGrand
60 10 Rich LeGrand
!{width: 50%}http://i74.photobucket.com/albums/i241/cmucam/Image128_zpsff146617.jpg!
61 6 Rich LeGrand
62 10 Rich LeGrand
If successful, you should see "Success!" message in the command window, followed by a response number between 0 and 100, which is the "goodness" number.  Hues with higher saturation will have higher goodness numbers. 
63 10 Rich LeGrand
64 13 Rich LeGrand
That's it! You can verify how well your color signature is working by clicking on the chef icon or selecting *Action➜Cooked Video*.  Cooked video will show which pixels match color signatures and how they form detected objects:
65 13 Rich LeGrand
66 13 Rich LeGrand
!http://i74.photobucket.com/albums/i241/cmucam/Image131_zpsf63a2ef0.jpg!
67 13 Rich LeGrand
68 13 Rich LeGrand
h3. Where to go from here
69 13 Rich LeGrand
70 13 Rich LeGrand
You can teach Pixy other objects in this way, up to seven total color signatures are possible.  Note that Pixy always saves color signatures in flash, so they will be available the next time you apply power to Pixy. 
71 13 Rich LeGrand
72 13 Rich LeGrand
You might be interested in [[Hooking up Pixy to a Microcontroller like an Arduino|hooking Pixy up to a microcontroller]].  
73 10 Rich LeGrand
 
74 6 Rich LeGrand
75 6 Rich LeGrand
76 5 Rich LeGrand
77 5 Rich LeGrand
78 5 Rich LeGrand
79 5 Rich LeGrand