Parallax Tsl1401-db User manual

®

Web Site: www.parallax.com

Forums: forums.parallax.com

Sales: [email protected]

Technical: [email protected]

Office: (916) 624-8333

Fax: (916) 624-8003

Sales: (888) 512-1024

Support: (888) 997-8267

Web Site: www.taosi c.com

Sales: sales@taosi c.com

Office: (972) 673-0759

Fax: (972) 943-0610

TSL1401-DB #28317): Linescan Camera Module

Product Overview

General Description

The TSL1401-DB is a daughterboard that provides a TAOS TSL1401R 128-pixel li ear array se sor a d a

le s. It is desig ed to plug i to a motherboard (e.g. MoBoStamp-pe (p/ 28300), MoBoProp (p/ 28303,

i developme t), Propeller Backpack (p/ 28327)) or the DB-Expa der (p/ 28325). This module will

allow its host system to “see” i o e dime sio . Two- dime sio al visio ca also be achieved by movi g

either the subject or the se sor i a directio perpe dicular to the se sor axis.

Features

• Provides visio i o e dime sio with 128-pixel resolutio .

• Three-li e serial i terface with a alog i te sity output for each pixel.

• I cluded 7.9mm le s provides a field of view equal to subject dista ce.

• Plug-compatible with Parallax motherboards.

• Coprocessor driver firmware for the MoBoStamp-pe available for dow load.

• Ca be i terfaced directly to a BASIC Stamp for some fu ctio s.

• O board accessory socket for strobe output or 50/60Hz fluoresce t light sy c i put.

• Ru s from 3.3V or 5V supplies. (5V is eeded for the optio al LED strobe attachme t.)

Applications

• Measure height, width, diameter, thick ess.

• Locate objects, li es, edges, gaps, holes.

• Cou t items; measure co veyor coverage.

• Determi e volume, shape, orie tatio .

• Read simple barcodes.

• Lear the pri ciples of machi e visio .

What’s Included

TSL1401-DB with le s.

What You Need to Provide

• Parallax motherboard, or DB-Expa der with BASIC Stamp a d carrier board (such as the BOE).

Introduction

What the Module Sees

The TSL1401R chip is a li ear array (li esca ) se sor. It co sists of a si gle row of 128 photodetectors.

The TSL1401-DB i cludes a le s to form images o the se sor array. What results is somewhat like

peeri g through the arrow crack of a partially ope ed door to see a thi slice of what lies behi d it. The

illustratio below helps to explai the co cept:

TOP VIEW

First Pixel

Last Pixel

The output from each observed pixel is a a alog voltage proportio al to light i te sity. The a alog

i te sity curve correspo di g to the image above would look somethi g like this:

Here, you ca see ot o ly the edges of the bagel a d the hole i the middle, but also the i te sity

variatio s caused by the seeds a d herbs o its surface.

The overall width (field of view) see by the TSL1401-DB, usi g the i cluded 7.9mm le s, is

approximately equal to the subject dista ce. So, for example, if the module is 1 meter away from the

subject, it will see a li ear slice of the subject that’s 1 meter wide a d 1/128

th

of a meter high.

Focusi g the TSL1401-DB’s le s is accomplished by screwi g it i or out. Whe screwed almost all the

way i , dista t subjects will be i focus. To focus o closer subjects, the le s eeds to be screwed out a

bit. O ce proper focus is achieved, it may be ecessary to secure the le s from vibratio by wrappi g

tape arou d the le s bezel a d le s holder barrel. If the le s is screwed i far e ough, a small O-ri g

s apped i to the crevice betwee the le s bezel a d le s holder barrel will serve the same purpose.

Note: The use of a thread locker (e.g. Loc-Tite) or a y cya oacrylic adhesive (e.g. Super Glue) is

ot

recomme ded ear le s eleme ts, as the fumes ca destroy a y optical coati gs that may be

prese t.

If you are usi g the TSL1401-DB with a Parallax MoBoStamp-pe, you ca use the PC-hosted mo itor

program, described later i this docume t, as a aid to focusi g.

Interface and Basic Operation

Refer to the schematic o the last page of this docume t for the TSL1401-DB’s pi out, a d to TAOS’s

TSL1401R-LF datasheet (available from www.taosi c.com) for the se sor chip’s particulars. For ormal

operatio (i.e. without exter al strobi g or sy ci g), there are o ly three sig als that eed to be

co sidered: SI (digital output to the se sor: begi s a sca /exposure), CLK (digital output to the se sor:

latches SI a d clocks the pixels out), a d AO (a alog pixel i put from the se sor: 0 – Vdd, or tri-stated if

beyo d pixel 128). The TSL1401 datasheet describes these sig als i detail, so that descriptio wo ’t be

repeated here, except as it relates to the BASIC Stamp.

If you are usi g the TSL1401-DB with Parallax’s DB-Expa der (p/ 28325), the pi correspo de ces are

as follows:

TSL1401R Pin DB-Expander Pin

AO A

SI B

CLK C

The TSL1401R is a

light-i tegrati g

device. It’s a bit like photographic film i that regard: the lo ger you

expose it, the brighter the resulti g image. Also, like film, it ca saturate, such that if exposed too lo g,

everythi g – eve the darkest subjects – will look completely white. The exposure time (also called

“i tegratio time”) is the time i terval betwee SI pulses. (Well, actually, the exposure does ’t

really

begi u til 18 clocks

after

SI; but it’s ofte co ve ie t to ig ore that detail if those clocks occur quickly

e ough.) Duri g each exposure, all the pixels eed to be clocked out of the device to prepare it for the

ext exposure. However, the exposure i terval for each pixel begi s a d e ds with the SI pulse, ot with

the mome t it’s clocked out, as with some other se sors. Therefore, all the pixels get exposed

simulta eously, a d the acquired image represe ts the same i terval i time for each of them.

There are two ways to acquire images with the TSL1401R: co ti uous a d o e-shot. I co ti uous

imagi g, the SI pulses occur i a steady stream, with 129 or more pixel clocks i betwee , duri g each

exposure i terval. To acquire a image, you eed to wait for the ext SI pulse time before clocki g out

the pixels that co stitute the image. These pixels will represe t the light received duri g the previous

exposure i terval. Waveforms illustrati g this method are show below:

Tri-

Stated

Tri-

Stated

Tri-

Stated

1 2 3 4 5 6 7 8 9 10 . . . 129 1 2 3 4 5 6 7 8 9 10 . . . 129

SI

CLK

AO

Clock out scan n-1

Integrate scan n

Clock out scan n

Integrate Scan n+1

I o e-shot imagi g, the TSL1401R is left idle u til it’s time to s ap a picture. The SI clocked i , a d

128 pixels are rapidly clocked out a d discarded. The you simply wait u til the desired exposure time

(si ce the SI pulse) has elapsed a d pulse SI agai . At this poi t, you ca clock out the pixels resulti g

from the timed exposure. Here is a sample waveform:

Tri-

Stated

Tri-

Stated

Tri-

Stated

1 129 1 2 3 4 5 6 7 8 9 10 . . . 129

SI

CLK

AO

Clock out garbage

Integrate scan Clock out scanIDLE IDLE

I all the discussio that follows, we will be usi g o e-shot imagi g.

Operation with the BASIC Stamp

This sectio explai s how to use the TSL1401-DB directly with a BASIC Stamp. If you have the

MoBoStamp-pe BASIC Stamp 2pe motherboard, you ca skip this sectio a d proceed to the sectio

titled “Operatio with the MoBoStamp-pe”.

Connection

The followi g illustratio shows how to co ect the TSL1401-DB to a BASIC Stamp, usi g Parallax’s

Board of Educatio a d a DB-Expa der board:

Vdd

Vin

Vss

P15

P14

P13

P12

P11

P10

P9

P8

P7

P6

P5

P4

P3

P2

P1

P0

The sig al pi outs a d port usage show above are co siste t with the examples to follow i this sectio .

You ca also use the DB-Exte sio Cable (p/ 500-28301) to separate the TSL1401-DB from the DB-

Expa der board if you eed to.

Image Acquisition

The output of the TSL1401R is a a alog sig al, but the BASIC Stamp does ot have a alog i put

capability (except via RCTIME, which is ’t fast e ough to read 128 pixels). How, the , is it possible to use

this device with a BASIC Stamp? We do it by co ecti g the AO sig al directly to o e of the Stamp’s

digital i puts. Whe do e this way, the BASIC Stamp will threshold the a alog i put. A ythi g over about

2 volts will read as a 1; a ythi g u der, as a 0. By treati g the sig al this way, it’s possible to i put a

stri g of 1s a d 0s that represe t light a d dark portio s of the “sce e” bei g recorded. A complete

sca , the , would require 128 bits of data (i.e. 16 bytes, or 8 words), which the BASIC Stamp ca

accommodate ha dily.

O ce these bits have bee read i , it’s possible to a alyze “features” of the sce e by looki g for groups

of light a d dark pixels. For example, if you wa ted to measure the width of a light object agai st a dark

backgrou d, you could read i the image, the cou t the umber of “1” bits i the data. Likewise, if you

wa ted se se the edge of a “web” (e.g. paper i a paper mill) to keep the web o track, you would look

for the first occurre ce of a light or dark pixel i each sca .

The followi g PBASIC code fragme t (take from the complete program template show later i this

sectio ) ca be used to read a si gle sca from the TSL1401-DB. It co sists of five li es of code, which

are show a d discussed i dividually:

SHIFTOUT SI, CLK, 0, [1\1]

SI a d CLK are defi ed i the larger program’s preamble as PINs a d co ect to like- amed ports o

the TSL1401-DB. This stateme t clocks out SI as a si gle bit of sy chro ous serial data, which starts a

ew exposure i terval.

PWM CLK, 128, 1

We wa t to clock through all 128 pixels as fast as possible, si ce we’re just timi g a exposure here, ot

readi g data. The PW stateme t fits the bill perfectly. The 128 i this stateme t is the duty cycle

(50%), ot the umber of pulses. The umber of pulses is give by the 1, which represe ts the le gth of

time to output the PWM sig al. For the BS2, this is omi ally 1mS. (Actually it’s more like 1.2mS a d

co sists of about 150 cycles.)

PULSOUT SI, exp >> 1 MIN 1016 - 1016

This stateme t sets the exposure time. exp ca be either a co sta t or a variable a d represe ts the

le gth of the exposure i microseco ds. The reaso for usi g PULSOUT i stead of PAUSE, say, is that

the timi g resolutio is so much fi er. A d the reaso for se di g the pulse o SI is that it’s ot used for

a ythi g else dur g this time, a d, so lo g as we do ’t clock the pulse with CLK the se sor chip is

u affected. The value subtracted from the pulse width (1016) represe ts the timi g overhead from the

PBASIC program, mi us the start-of-i tegratio delay to the 18

th

clock i the PW stateme t. This

mea s that the mi imum exposure time will be about 2.032mS.

Note: Timi gs for BASIC Stamps other tha the BS2 will vary, a d the value subtracted will eed to

be adjusted accordi gly.

SHIFTOUT SI, CLK, 0, [1\1]

This clocks out the SI pulse agai to e d the exposure a d begi actual data readout.

SHIFTIN AO, CLK, LSBP E, [pdata(0)\16, pdata(1)\16, pdata(2)\16, pdata(3)\16]

SHIFTIN A0, CLK, LSBP E, [pdata(4)\16, pdata(5)\16, pdata(6)\16, pdata(7)\16]

These two stateme ts read 128 bits of thresholded pixel data from the AO pi i to a eight-positio

word array, declared pdata word(8), least-sig fica t bits first. Doi g it “i li e” like this is faster tha

doi g it i a loop.

Here are the waveforms from the above acquisitio routi e, with the various sectio s a otated:

Tri-

Stated

Tri-

Stated

Tri-

Stated

1 129 1 2 3 4 5 6 7 8 9 10 . . . 129

SI

CLK

AO

SHIFTOUT SHIFTOUT

SHIFTI 16 x 8

PWMOUT PULSOUT

IDLE IDLE

150

2V Input Threshold

Thresholded Data

You ca use DEBUG to display the acquired pixels, as i the followi g program fragme t. (A somewhat

fa cier versio is give i the complete program later i this sectio .)

FO i = 0 TO 7

DEBUG BIN16 pdata(i) EV 16

LSB first, but DEBUG’s BIN formatter displays data SB-first. So we eed to reverse the order of the

bits to get a accurate picture of the pixel order. O e might well ask why we did ’t just read the data i

MSB first to begi with. After all, SHIFTIN, ca do that just as easily. The a swer lies i the image

a alysis routi es to follow.

Image Analysis

A alyzi g a li esca image to extract useful i formatio from it i volves two major operatio s: pixel

cou ti g, a d pixel a d edge locatio . The PBASIC subrouti es that perform these operatio s treat the

origi al array of eight words as a array of 128 bits, each bit correspo di g to a si gle pixel. Bit 0 is the

first pixel read; bit 127, the last. (This mappi g is why the pixels eeded to be read i LSB first.) Here’s

how the word a d bit arrays are declared:

pdata VA Word(8)

pixels VA pdata.BIT0

Cou ti g light or dark pixels withi a give ra ge is simple. Here’s the code that does it:

CountPix:

cnt = 0 'Initialize count.

IF (lptr <= rptr AND rptr <= 127) THEN 'Valid range?

FO i = lptr TO rptr ' Yes: Loop over desired range.

IF (pixels(i) = which) THEN cnt = cnt + 1 ' Add to count when pixel matches.

ETU N

cnt ca be declared as a byte, si ce it will ever exceed 128. lptr a d rptr are also bytes that ca ra ge

from 0 to 127, i clusive. They i dicate the ra ge over which the cou ti g occurs. which is a bit variable

that i dicates whether to cou t dark pixels (0) or light pixels (1). Cou ti g pixels is ha dy for computi g

a object’s area – either i o e sca , or cumulatively over multiple sca s for two-dime sio al objects

passi g u der the camera o a co veyor.

Locati g the first occurre ce of a dark or light pixel withi a give ra ge is ’t much harder:

FindPix:

IF (found = 1 AND lptr <= rptr AND rptr <= 127) THEN

'Still looking & within bounds?

IF (dir = FWD) THEN ' Yes: Search left-to-right?

FO lptr = lptr TO rptr ' Yes: Loop forward.

IF (pixels(lptr) = which) THEN ETU N ' eturn on match.

FO rptr = rptr TO lptr ' No: Loop backward.

IF (pixels(rptr) = which) THEN ETU N ' eturn on match.

ENDIF

found = 0 'Didn't look or nothing found.

ETU N ' eturn.

found is a bit variable that should be i itialized to 1 for the search to comme ce a d i dicates whe the

subrouti e retur s whether the desired pixel has bee fou d (0 = o; 1 = yes). lptr a d rptr have the

same mea i g as i the cou ti g routi e, except that o e or the other ca get moved to the locatio of

the fou d pixel. Combi ed with the cumulative effect that found has, this make it easier to perform a

whole stri g of searches. dir is a bit variable that i dicates which e d of the (lptr, rptr) ra ge to start

the search from. You ca predefi e the co sta ts FWD (= 0, “left_to_right”) a d BKWD (= 1, “right-to-

left”) to assig to dir to make your programs more readable. which, as with the cou ti g routi e,

i dicates what ki d of pixel to look for. You ca predefi e co sta ts for which as well (DRK = 0; BRT =

1) for readability.

Whe FindPix retur s, found will i dicate whether the desired pixel was located, a d either lptr (if dir

= FWD) or rptr (if dir = BKWD) will poi t to the fou d pixel locatio .

Sometimes, it’s ecessary to locate a edge i stead of just a pixel. A

light edge

, for example is o e that

begi s with a dark pixel, the tra sisitio s to a light o e. The FindPix routi e ca be used to fi d edges,

too, by looki g for the first pixel

opposite

of the edge you’re seeki g, the the ext pixel after that that

matches the edge value. The routi e to do it is:

FindEdge:

which = 1 - which 'Look for opposite kind of pixel first.

GOSUB FindPix

which = 1 - which 'THEN look for desired pixel.

GOSUB FindPix

ETU N

Locati g pixels a d edges is ha dy for fi di g objects i a field of view a d measuri g their “exte ts”. A

object’s

exte t

i cludes its outside bou daries a d everythi g i betwee , regardless of pixel i te sity.

For example, i the bagel illustratio , the bagel’s exte t would i clude the hole, while its

area

(obtai ed

by cou ti g bright pixels) would ot.

Here is a complete program which i corporates all the routi es described above (a d the some). It

acquires images a d locates bright objects, computi g both their exte ts a d areas. You ca also use it

as a template for your ow programs.

' =========================================================================

'

' File...... TSL1401_scan.bs2

' Purpose... Image capture and processing demo using the TSL1401-DB

' Author.... Phil Pilgrim, Bueno Systems, Inc.

' E-mail....

' Started... 11 July 2007

' Updated...

'

' {$STAMP BS2}

' {$PBASIC 2.5}

'

' =========================================================================

' -----[ Program Description ]---------------------------------------------

' This program demonstrates image capture and processing using the

' TSL1401-DB (Parallax p/n 28317). It continuously acquires and displays

' images from the TSL1401 sensor chip. It then locates both left and right

' bright edges, displaying them graphically using DEBUG. Finally it

' computes both the area and extent of the object found.

' -----[ evision History ]------------------------------------------------

' -----[ I/O Definitions ]-------------------------------------------------

ao PIN 0 'TSL1401 's analog output (threhsolded by Stamp).

si PIN 1 'TSL1401 's SI pin.

clk PIN 2 'TSL1401 's CLK pin.

' -----[ Constants ]-------------------------------------------------------

D K CON 0 'Value assignd to "which" for dark pixels.

B T CON 1 'Value assigned to "which" for bright pixels.

FWD CON 0 'Value assigned to "dir" for left-to-right search.

BKWD CON 1 'Value assigned to "dir" for right-to-left search.

' -----[ Variables ]-------------------------------------------------------

VariableName VA Byte ' What is variable for?

pdata VA Word(8) 'Pixel data, as acquired LSB first from sensor.

pixels VA pdata.BIT0 '128-bit pixel array mapped onto pdata.

exp VA Word 'Exposure (integration) time in 2uSec units.

lptr VA Byte 'Left pixel pointer for count and find operations.

rptr VA Byte ' ight pixel pointer for count and find operations.

i VA Byte 'General-purpose index.

cnt VA Byte ' esult of pixel-count routine.

which VA Bit 'Indicates seeking D K or B T pixels/edges.

dir VA Bit 'Indicates direction of search (FWD or BKWD).

found VA Bit 'Indicates pixels found (= 1), or not found (= 0).

' -----[ Program Code ]----------------------------------------------------

' NOTE: This code assumes that DEBUG will wrap after 128 characters,

' regardless of the DEBUG window width. Later versions of DEBUG

' may not do this, and you will have to add C s where needed.

exp = 8333 'Set exposure time to 8333uSec (1/120th sec).

DEBUG HOME 'Go to home position on DEBUG screen.

GOSUB DispHdr 'Display the pixel location header.

DO 'Begin the scan-and-process loop.

GOSUB GetPix 'Obtain a pixel scan.

DEBUG C S XY, 0, 2 'Move to column 0, row 2.

GOSUB DispPix 'Display the pixels here.

lptr = 0 : rptr = 127: which = B T : dir = FWD : found = 1

'Initialize parameters for find.

GOSUB FindEdge 'Find first dark-to-light edge going L-> .

dir = BKWD 'Switch directions.

GOSUB FindEdge 'Find first dark-to-light edge going L<- .

DEBUG CL EOL 'Clear the next line.

IF found THEN 'Both edges found?

DEBUG C S X, (lptr - 1), "_|" 'Yes: Display left edge.

DEBUG C S X, rptr, "|_" ' Display right edge.

GOSUB CountPix ' Compute area (light pixel count).

DEBUG C , C , "Area = ", DEC cnt,' Display area ...

" Extent = ", DEC rptr - lptr + 1, CL EOL '... and extent of object.

ELSE 'No: Display failure message.

DEBUG C , C , "No object found.", CL EOL

ENDIF

LOOP

END

' -----[ Subroutines ]-----------------------------------------------------

' -----[ GetPix ]----------------------------------------------------------

' Acquire 128 thresholded pixels from sensor chip.

' exp is the exposure time in microseconds.

GetPix:

SHIFTOUT si, clk, 0, [1\1] 'Clock out the SI pulse.

PWM clk, 128, 1 ' apidly send 150 or so CLKs.

PULSOUT si, exp >> 1 MIN 1016 – 1016 'Wait for remaining integration time.

SHIFTOUT si, clk, 0, [1\1] 'Clock out another SI pulse.

' ead 8 words (128 bits) of data.

SHIFTIN ao, clk, LSBP E, [pdata(0)\16, pdata(1)\16, pdata(2)\16, pdata(3)\16]

SHIFTIN ao, clk, LSBP E, [pdata(4)\16, pdata(5)\16, pdata(6)\16, pdata(7)\16]

ETU N

' -----[ DispHdr ]---------------------------------------------------------

' Display a header to aid in identifying pixel positions.

DispHdr:

FO i = 0 TO 12 'Display tens digits.

DEBUG DEC i DIG 0

IF i < 12 THEN DEBUG " " ELSE DEBUG C

DEBUG DEC i // 10

' -----[ DispPix ]---------------------------------------------------------

' Display 128 pixels: light pixels as "1"; dark, as "_".

DispPix:

FO i = 0 TO 127

IF pixels(i) THEN DEBUG "1" ELSE DEBUG "."

' -----[ FindEdge ]--------------------------------------------------------

' Find the first edge within the range lptr through rptr, in the direction

' given by dir and of the type indicated by which (0 = light-to-dark;

' 1 = dark-to-light).

FindEdge:

which = 1 - which 'Look for opposite kind of pixel first.

GOSUB FindPix

which = 1 - which 'Then look for desired pixel,

' by falling through to FindPix.

' -----[ FindPix ]---------------------------------------------------------

' Find the first pixel within the range lptr through rptr, in the direction

' given by dir and of the type indicated by which (0 = dark; 1 = light).

FindPix:

IF (found = 1 AND lptr <= rptr AND rptr <= 127) THEN

'Still looking & within bounds?

IF (dir = FWD) THEN ' Yes: Search left-to-right?

FO lptr = lptr TO rptr ' Yes: Loop forward.

IF (pixels(lptr) = which) THEN ETU N ' eturn on match.

FO rptr = rptr TO lptr ' No: Loop backward.

IF (pixels(rptr) = which) THEN ETU N ' eturn on match.

ENDIF

found = 0 'Didn't look or nothing found.

ETU N ' eturn.

' -----[CountPix]----------------------------------------------------------

' Count pixels within the range lptr through rptr, of the type indicated by

' which (0 = dark; 1 = light).

CountPix:

cnt = 0 'Initialize count.

IF (lptr <= rptr AND rptr <= 127) THEN 'Valid range?

FO i = lptr TO rptr ' Yes: Loop over desired range.

IF (pixels(i) = which) THEN cnt = cnt + 1 ' Add to count when pixel matches.

ETU N

Pseudo-analog Pixel Acquisition

Eve though pixels acquired by the BASIC Stamp are thresholded a d co verted to si gle bits, it’s still

possible to obtai a picture of each pixel’s a alog value – at least for static subjects that do ’t move. The

voltage output from a y give pixel i the TSL1401R ca be expressed as follows:

Output voltage = k × LightIntensity × IntegrationTime

Where k is a co sta t. At the two-volt threshold level, this ca be rewritte :

2 = k × LightIntensity × IntegrationTime

What we wa t this formula to a swer is this: For a give light i te sity to produce a output at the two-

volt threshold, how lo g does the i tegratio time have to be? Solvi g the above equatio gives us our

a swer:

IntegrationTime = 2 / (k × LightIntensity)

This mea s that if we wa t all the pixels whose light i te sity is at or above a certai level to read as

o es, all we have to do is i tegrate for a time

i versely proportio al

to that i te sity level, a d those

pixels will read as o es after thresholdi g. By iterati g over a ra ge of i te sity levels a d displayi g

each li e of pixels o e above the other, we ca obtai a a alog bar graph of i te sity levels. Here’s the

code s ippet that does it. It ca be plugged i to the mai code template show above:

inten VA cnt

DEBUG HOME 'Go to home position on DEBUG screen.

GOSUB DispHdr 'Display the pixel location header.

FO inten = 32 TO 8 'Cycle through intensities in reverse.

exp = 32000 / inten * 8 'Compute exposure time as inverse of intensity.

GOSUB GetPix 'Acquire the binary pixels.

GOSUB DispPix 'Display them.

NEXT 'Continue with next lower intensity level.

END

Here’s what the output looks like whe viewi g a bagel lighted from the fro t:

You ca see where the hole is, as well as the outside edges. However, this also illustrates a couple pitfalls

of fro t lighti g: specular reflectio (glare) from the black backgrou d surface (i.e. black ot bei g all

that black), a d rou ded-off edges. Proper lighti g tech iques e compass a e tire subject area of their

ow . The last chapter of this docume t li ks to various resources o the i ter et that cover this

importa t topic.

Operation with the MoBoStamp-pe

The TSL1401-DB is desig ed to plug i to the MoBoStamp-pe. Though it will work i either socket, it is

recomme ded that socket “B” be used i order to make socket “A” available for i terface-type

daughterboards requiri g access to Vi . I all the examples i cluded here, socket “B” is assumed (a d

sometimes required). Here’s a photo of the TSL1401-DB plugged i to the MoBoStamp-pe, socket “B”:

Loading the TSL1401R Driver Firmware

Before pluggi g i the TSL1401-DB, you will first wa t to load the firmware driver for it i to the

coprocessor associated with socket “B”. Be sure you’ve dow loaded the program “LoadAVR.exe” from the

Parallax website, as well as the hex file for the TSL1401R driver, “TSL1401DB01.hex”. Co ect your

MoBoStamp-pe to the PC’s USB port, a d the ru LoadAVR.exe. Select “TSL1401DB01.hex” as the file to

upload a d socket “B” as the desti atio . The click “Upload”. O ce the file has uploaded successfully,

you ca plug the TSL1401-DB i to its socket.

TSL1401-DB Monitor Program

There is a Wi dows PC host program that will let you see what the TSL1401-DB sees i real time. It’s

called “TSL1401_mo itor.exe”, a d it ca be dow loaded for free from the Parallax website. Just copy it

to the directory of your choice.

With the MoBoStamp-pe/TSL1401-DB (the “camera”) co ected to your PC’s USB port, start up the

mo itor program. After it makes a co ectio , it will upload its ow PBASIC code,

which replaces a y

program curre tly i memory

. The you should see somethi g like what appears o the ext page.

Starti g from the top, here are some poi ts of i terest i the display, some of which will be discussed i

more detail later:

• Scan Window: Every sca from the camera gets appe ded to this image, from right to left,

circulati g back to the left edge whe the scree is filled. By slowly rotati g the camera o the

motherboard’s short axis, you ca obtai a two-dime sio al “sce e”. The bottom pixels i this

wi dow correspo d to the leftmost pixels obtai ed i each sca .

• Trigger/Sync Control: Sca s ca be free-ru i g, triggered, or gated. Triggeri g a d gati g

are co trolled by Pi 3, which is a BS2pe port commo to both daughterboards. Whe triggeri g

is set, a high-to-low edge o Pi 3 will cause a si gle sca to be acquired. Whe gati g is set,

sca s will be obtai ed co ti uously while Pi 3 is low. Usi g the “Ext. Sy c” butto , sca s ca

also be sy chro ized to a exter al source. The sig al for this is obtai ed from the o board 6-pi

mezza i e co ector. The forthcomi g LightSYNC-DBM plugs i to this co ector a d provides a

sig al sy chro ized to the 50/60Hz variatio s i light level from fluoresce t lamps. This makes

the camera immu e to these variatio s by starti g all exposures at the same poi t o the

50/60Hz cycle. Whe sy ci g is used i co ju ctio with triggeri g or gati g, the trigger/gate

co ditio must be met first,

the

the sy c pulse must be received.

• Acquisition Control: You ca start a d stop sca i g with these co trols or obtai sca s o e

at a time.

• Exposure Controls: These set the exposure type a d time. Exposure times ca be either fixed

or automatic. Whe set to fixed, you ca set the actual time usi g the umerical co trol. Whe

set to automatic, exposure time is co sta tly adjusted to mai tai the peak pixel value betwee

certai bou ds. I this case, the umerical boxes show the actual exposure time for a y give

exposure.

• Lighting Controls: Whe used with the forthcomi g StrobeLED-DBM, which plugs i to the 6-pi

mezza i e socket, these co trols adjust the type a d timi g of the light output from the LED.

Types are “Off”, “Normal”, a d “Strobed”. Normal mode mea s that the LED is o for the

duratio of each exposure at a bright ess level that ca be set i the umerical wi dow. I

strobed mode, the bright ess level is fixed at maximum bright ess, with the duratio bei g the

adjustable factor.

• Scope Window: This wi dow shows the a alog output of each pixel i real time. The horizo tal

mage ta li es represe t high a d low thresholds for bi ary pixel acquisitio , similar to the BS2

acquisitio discussed i the previous sectio , but co trollable. I ormal comparator-style

acquisitio , the separatio betwee these li es is the comparator hysteresis. These li es ca be

moved up a d dow by positio i g the cursor betwee them a d draggi g them with the left

mouse butto held dow . The separatio (hysteresis) ca also be adjusted, by draggi g with the

right mouse butto held dow . The vertical cya -colored li es determi e the area of i terest for

image a alysis. They ca be dragged left a d right, i dividually, with the left mouse butto held

dow . The yellow li e – a d a y yellow feature, for that matter – represe ts the result of a

image a alysis measureme t.

• Image Brightness Window: The arrow wi dow below the scope wi dow is divided i to three

slices. The bottom slice shows the i sta ta eous image bright ess for each pixel as a gray level.

The ext slice up, shows which pixels register as “light” pixels after thresholdi g. The top slice is

used to show image a alysis results (i yellow) whe those results i clude locatio or cou t

i formatio .

• Binary Acquisition Controls: These adjust the threshold types a d values a d are discussed i

their ow sectio below. Suffice it to say here that cha ges to these co trols are reflected i the

mage ta li es displayed i the scope wi dow.

• Image Analysis Controls: These co trols make it easy to measure various features i a

acquired image to test what might work or ot work i your applicatio . They are discussed i

detail i their ow sectio to follow. The value i the wi dow after “equals” (i yellow) is the

umerical result to which the yellow graphics coi cide. I the example above, this is the value of

the first pixel i the regio defi ed by “betwee 1 a d 255”. The “Code” butto will be used i a

future rev of this program to write a PBASIC program for you that performs the sca acquisitio s

a d performs the image a alysis that you’ve selected.

Focus

The mo itor program e ables almost i sta t feedback for focusi g the le s. Below are two scree shots:

o e of a backlit comb that’s i focus, a d o e that’s ot. Notice the sharper edges a d more pro ou ced

detail i the i -focus image. This is what you eed to strive for. By screwi g the le s i a d out, while

watchi g the scope wi dow, you will be able to maximize the sharp ess of your image to obtai the best

– a d most repeatable – results.

Backlit Comb i Focus Backlit Comb Out of Focus

Cosine Effect

You may have oticed i the images above that the ce ter of the image is brighter tha the edges. This

is a optical property that’s prese t i early all imagi g systems. It’s k ow as the “cosi e effect”, a d it

makes images appear brighter ear their ce ters tha at the edges. This happe s because a light

emitter, such as a diffuse backlight, is brighter o -axis tha off-axis. Si ce the edges of a flat light source

are captured more off-axis tha the ce ter, they appear darker. Compou di g the effect is the fact that,

behi d the le s, light striki g the se sor at the edges comes i at a more oblique a gle tha light striki g

the ce ter. This effect becomes more pro ou ced as the imagi g le s’s focal le gth decreases (i.e.

becomes more wide-a gle).

Here’s a sca of just the backlight, without a ythi g i fro t of it. Eve though the backlight itself is very

eve ly illumi ated, it appears to have a cosi e-shaped bright ess co tour whe imaged with the camera.

Image from Backlight O ly, Showi g the Cosi e Effect

Differe t ways of deali g with this effect are discussed later i the sectio “Image A alysis a d

Measurme t”.

Note: This also illustrates the importa ce of keepi g everythi g clea . Do you see that little divot i

the trace, about two-thirds of the way across? It was caused by a ti y li t fiber cli gi g to the se sor

chip. If you see somethi g like this, u screw the le s housi g from the board, a d use dry

compressed air, or a soft cloth to remove whatever is causi g the problem.

Binary Image Acquisition

The AVR firmware that you uploaded to the MoBoStamp-pe e ables a wealth of image acquisitio

optio s, particularly i the co versio of grayscale pixel values to bi ary light/dark values suitable for

image a alysis. Bi ary pixels are acquired usi g

sub-pixel resolutio

. This e ables the acquisitio of 255

bi ary pixels from the 128 grayscale pixels output from the TSL1401R. The firmware accomplishes sub-

pixel resolutio duri g image acquisitio time by i terpolati g a virtual pixel betwee every pair of actual

pixels, as show below:

0 1

2

3

4

5

122

123

124

125

126

127

Gray-level Pixel Numbers

Binary Pixel Numbers

12345678910 11 245 246 247 248 249 250 251 252 253 254

255

All light/dark thresholdi g takes place usi g the values of the 255 real a d i terpolated pixels, yieldi g

255 bits of data, whose positio s are umbered 1 through 255. (Note: This o e-based umberi g is

differe t from that of the direct BS2 umberi g show earlier. That was zero-based to co form with

PBASIC’s zero-based subscript co ve tio s.) Bi ary pixel 0 is o -existe t i this system a d is used i

the co text of image a alysis to i dicate “feature ot fou d”.

Co versio from gray-level to bi ary pixels always uses two thresholds for each pixel. Normal, compare-

to-level thresholdi g treats the area betwee the two thresholds as a “hysteresis ba d”. I order to

tra sitio from dark to light, a pixel must attai a light level above the upper threshold. To tra sitio

from light to dark, a pixel’s level must si k below the lower threshold. Excursio s i to a d out of the

hysteresis ba d, without crossi g it completely, will ot result i a dark-to-light or light-to-dark tra sitio .

This helps to elimi ate “hair trigger” tra sitio s whe the level is ear threshold. (Of course, if this is

what you wa t, you ca always set the hysteresis value to zero.) This ki d of compariso is illustrated i

the above diagram by the color of the dots.

The firmware also supports “wi dow” compariso s, i which values i side the hysteresis ba d evaluate to

zero; those above or below, to o e. This is useful for determi i g how much a subject’s light i te sity

deviates from a acceptable ra ge of levels, for example.

Thresholds ca also be either “fixed”, as the example above illustrates, or “floati g”. A floati g threshold

follows the co tour of the pixel respo se as a ki d of movi g average whose filter co sta t is

programmable. This ca be ha dy for thresholdi g subjects whose illumi atio is u eve . It also allows

the detectio of extreme edges, while ig ori g ge tly risi g or falli g light levels. The scree shots below

illustrate this:

Here, a floati g threshold with a filter factor of 6 has bee selected. Now, see what happe s whe the

filter factor is cha ged to 2:

O ly the most extreme risi g edges are detected i this case, as i dicated by the gree area i the

arrow strip below the scope wi dow. I fact, o e of the most importa t applicatio s of floati g

thresholds is edge detectio .

A other applicatio of floati g thresholds is i “texture” detectio . Texture is a characteristic associated

with rapidly alter ati g pixel values. The seeds a d herbs o a bagel represe t texture, for example. I

fact, a possible applicatio might be i specti g bagels to see if they have e ough “stuff” spri kled o

them. I this case, we would set the floati g threshold level to zero, the filter to zero, a d the hysteresis

to a level co siste t with how much texture we wa t to call “good”. Also, we’ll use wi dow compariso ,

so that risi g a d falli g pixel values get treated equally. Here is a example, usi g a bagel with stuff o

it (top) compared to a plai bagel (bottom):

Notice how the gree “o e” pixels capture the texture of the coated bagel, a d eve the fact that the

right side of that bagel has more stuff o it tha the left side.

Image Analysis and Measurement

The mo itor program is capable of performi g feature measureme t o bi ary images. A “feature” ca

be a edge locatio , the ce troid of a object, the bright ess of the brightest pixel, etc. The feature to be

measured is selected o the measureme t co trol bar at the bottom of the scree :

Possible values for the various optio s are:

Which Type Feature Aspect Between

And Equals

First Dark Pixel Value 1 to 255 1 to 255 Result

Last Light Edge Locatio

Extreme Object Cou t

Average Area

Overall

Exte t

Not all combi atio s of these values will make se se or be realistic for the BASIC Stamp to compute. I

such cases the result will be show as “ /a”. If a measureme t

ca

be computed, though, the umerical

value will be show i the “equals” box, a d a graphical i dicator (also i yellow) will be displayed at the

appropriate place o the scope.

I a subseque t versio of the program, the Code butto will produce the PBASIC program ecessary to

acquire a image a d make the desired measureme t.

Now let’s defi e some terms:

First: Begi i g at the left-ha d side, the first feature to match the co ditio s.

Last: Begi i g at the left-ha d side, the last feature to match the co ditio s.

Extreme Dark Pixel: Least bright pixel.

Extreme Light Pixel: Brightest pixel.

Average: Mea value of the feature(s) matchi g the co ditio s.

Dark Edge: Light-to-dark tra sitio , readi g from left to right.

Light Edge: Dark-to-light tra sitio , readi g from left to right.

Object: The spa betwee a edge of the object type (dark/light) a d a edge of the opposite type.

Value: The i te sity of a pixel or collectio of pixels.

Location: The pixel i dex (1 – 255) of the selected feature, or zero if the feature was ’t fou d.

Count: The umber of features meeti g the specified co ditio s.

Area: The umber of dark or light pixels e compassed by the selected feature.

Extent: The umber of total pixels e compassed by the selected feature.

Whe experime ti g with the various measureme t optio s, it’s ofte ha dy to freeze image acquisitio

usi g the Stop or Single butto . That way, you ca adjust the measureme t parameters with a image

that’s ot itself cha gi g.

Now, let’s explore image a alysis usi g a real-life example: bottli g juice. Before the bottles are cased,

the bottler wa ts to k ow two thi gs: a) is the bottle full, a d b) is the cap o ? I this example, bottles

will be passi g betwee a backlight a d the camera. So the camera will be looki g through the bottle

towards the backlight. This is what it will see. To the right of this image is a rotated scope display,

showi g what the TSL1401-DB sees. (Lighter is to the left; darker, to the right.)

Parallax TSL1401-DB User manual

Popular Control Unit manuals by other brands