/HUSKYLENSPython

Primary LanguagePython

HUSKYLENS Python API

Author   : Robert (robert@dfrobot.com) 
Version  : 0.1
Date     : 08/04/2020
Github   : Github

Quick Start

USB Connection (Mac/Windows/Linux -> Huskylens)

  • pip3 install pyserial pypng
  • Place the huskylib.py file within your projects folder
  • from huskylib import HuskyLensLibrary
  • hl = HuskyLensLibrary("SERIAL", "/dev/ttyUSB0")
  • print(h1.knock()

Raspberry Pi (I2C -> Huskylens)

  • Please refer to our full guide here:

Example Script

You can test out all the functions in our provided example script. Simply run exampleHL.py after changing the the connection settings in the beginning of the file. You will need a terminal / IDE to interact with the script.

Function Format Information

function_name(ARG1,ARG2,…)
Description:
Short description of functions overall inputs and its corresponding functionality
Arguments:
Arg1 : (Variable Type) Description
Arg2 : (Variable Type) Description
Returns:
Short description the return value of the function, NONE if the function does not return

General Functions

HuskyLensLibrary(“COM_PROTOCOL”, “COM_PORT”, channel, address)

Description: Instantiate the HuskyLens class and automatically connect to your HuskyLens. This return the main object that you will run all functions on.

Arguments:
"COM_PROTOCOL" : (String) Either "SERIAL" for USB connections or "I2C" for Raspberry Pi I2C.
"COM_PORT" : (String) COM Port of the HuskyLens. Not needed for "I2C" connections.
"i2c_channel" : (Integer) I2C Channel, refer to Raspberry Pi Guide. Not needed for "SERIAL".
"i2c_channel" : (Integer) I2C Channel, refer to Raspberry Pi Guide. Not needed for "SERIAL".

Returns: Returns HuskyLens object

Examples:
hl = HuskyLensLibrary("SERIAL", "/dev/ttyUSB0")
hl = HuskyLensLibrary("I2C","", address=0x32, channel=0)

knock()

Description: Send a simple knock to the HuskyLens to ensure that you are connected and can communicate.

Returns: Returns “Knock Received” on success

frameNumber( )

Description: Get the number of frame HUSKYLENS have processed.

Returns: Frame Count


count( )

Description: Get the number of learned and unlearned objects on the screen.

Returns: Number of Ojbects on the Screen


learnedObjCount( )

Description: Get the total number of learned objects for the current running algorithm, objects do not need to be present on screen.

Returns: Number of learned objects

Data Functions

Data Format

  • Data corresponds to either block information for all algorithms except Line Tracking, which instead will return arrow information. These directly reflect the blocks/arrows you see on the HusyLens UI.

       class  Block:
   	Members:
   		x => (Integer) x coordinate of the center of the square 
   		y => (Integer) y coordinate of the center of the square 
   		width  =>  (Integer) width of the square
   		height =>  (Integer) height of the square
   		ID => (Integer) Objects ID (if not learned, ID is 0)
   		learned => (Boolean) True  if the object is learned
   		type => "BLOCK"
   class  Arrow:
   	Members:
   		xTail => (Integer) x coordinate of the tail of the arrow
   		yTail => (Integer) y coordinate of the tail of the arrow
   		xHead => (Integer) x coordinate of the head of the arrow
   		yHead => (Integer) y coordinate of the head of the arrow
   		ID => (Integer) Objects ID (if not learned, ID is 0)
   		learned => (Boolean) True  if the object is learned
   		type => "ARROW"

  • Returned data will be an array of either block or arrow information.:
    ** [block1 , block2, ... blockN] or [arrow1 , arrow2, ... arrowN]


requestAll( )
Description: Request all block or arrow data from HuskyLens. This will return block/arrow data for all learned and unlearned objects that are visible on the screen.
Returns: Returns data array [block1 , block2, ... blockN] or [arrow1 , arrow2, ... arrowN]

blocks()
Description: Request all block data from HuskyLens. This will return block data for all learned and unlearned objects that are visible on the screen.
Returns: Returns data array [block1 , block2, ... blockN]

arrows()
Description: Request all arrow data from HuskyLens. This will return block data for all learned and unlearned objects that are visible on the screen.
  • Note this should be used on the Line Tracking algorithm
Returns: Returns data array [arrow1 , arrow2, ... arrowN]

learned( )
Description: Request all block or arrow data from HuskyLens . This will return block/arrow data for all learned objects that are visible on the screen, unlearned objects are ignored.
Returns: Returns data array [block1 , block2, ... blockN] or [arrow1 , arrow2, ... arrowN]

learnedBlocks( )
Description: Request all block data from HuskyLens . This will return block data for all learned objects that are visible on the screen, unlearned objects are ignored.
Returns: Returns data array [block1 , block2, ... blockN]

learnedArrows( )
Description: Request all arrow data from HuskyLens . This will return arrow data for all learned objects that are visible on the screen, unlearned objects are ignored.
  • Note this should be used on the Line Tracking algorithm
Returns: Returns data array [arrow1 , arrow2, ... arrowN]

getObjectByID( ID )
Description: Request all block or arrow data from HuskyLens that have a designated ID and are visible on screen.
Arguments:
ID : (Integer) The desired ID of the object
Returns: Returns data array [block1 , block2, ... blockN] or [arrow1 , arrow2, ... arrowN]

getBlocksByID( ID )
Description: Request all block data from HuskyLens that have a designated ID and are visible on screen.
Arguments:
ID : (Integer) The desired ID of the object
Returns: Returns data array [block1 , block2, ... blockN]

getArrowsByID( ID )
Description: Request all arrow data from HuskyLens that have a designated ID and are visible on screen.
  • Note this should be used on the Line Tracking algorithm
Arguments:
ID : (Integer) The desired ID of the object
Returns: Returns data array [arrow1 , arrow2, ... arrowN]

Algorithm Control Functions

algorthim( algorithmName)

Description: Switch the HuskyLens to a specific algorithm.

Arguments:
algorithmName : (String) The desired algorithm to switch to.

“ALGORITHM_OBJECT_TRACKING”
“ALGORITHM_FACE_RECOGNITION”
“ALGORITHM_OBJECT_RECOGNITION”
“ALGORITHM_LINE_TRACKING”
“ALGORITHM_COLOR_RECOGNITION”
“ALGORITHM_TAG_RECOGNITION”
“ALGORITHM_OBJECT_CLASSIFICATION”

Returns: Returns “Knock Received” on success.

learn( ID )

Description: Learn the current recognized object on screen with a chosen ID

Arguments:
ID : (Integer) The desired ID of the object (1-1023 range)

Returns: Returns “Knock Received” on success.

forget( )

Description: Forget learned objects for the current running algorithm.

Returns: Returns “Knock Received” on success.

UI Related Functions

setCustomName(“Name_Value”, objectID)
Description: Set a custom name for a learned object with a specified ID. For example, if you have learned your face with an ID of 1, you can use huskylens.setCustomName(“Robert”,1) to rename the learned face to “Robert”.
Arguments:
"Name_Value" : (String) value for the desired name
objectID : (Interger) value for the learned object ID you wish to change
Returns: Returns “Knock Received” on success

customText(“Text_Value”, X, Y)
Description:

  • Place a string of text (less than 20 characters) on top of the HuskyLens UI. The position of the texts (X,Y) coordinate is the top left of the text box.

  • You can have at most 10 custom texts on the UI at once, and if you continue adding texts you will replace previous texts in a circular fashion. For example, if you enter 10 texts you will fill the text buffer. If you then insert a new text object, you will overwrite the first text position (textBuffer[0]). Inserting another new text object will overwrite the second text position (textBuffer[1]).

  • Each text is uniquely identified by its (X,Y) coordinate, so you can replace the text string at a (X,Y) coordinate instead of adding a new text object. For example, if you insert “TEST_1” at (120,120) and then later submit “TEST_2” at (120,120), you will replace the string “TEST_1” with “TEST_2” and maintain an overall text count of 1.

Arguments:
"Text_Value" : (String) value for the desired text
X : (Integer) The X coordinate for the UI Object (0-320)
Y: (Integer) The Y coordinate for the UI Object (0-240)
Returns: Returns “Knock Received” on success

clearText()
Description: Clear and delete all custom UI texts from the screen.
Returns: Returns “Knock Received” on success

Utility Functions

saveModelToSDCard( fileNum )
Description: Save the current algorithms model file (its learned object data) to the SD Card. The file will be the in the format “AlgorithimName_Backup_FileNum.conf”
Arguments:
fileNum : (Integer) The specified file number to be used in the name for the file
Returns: Returns “Knock Received” on success. If there is no SD Card inserted or an SD Card Error, there will be a UI popup on the HuskyLens outlining the issue.

loadModelFromSDCard( fileNum )
Description: Load a model file from the SD Card to the current algorithm and refresh the algorithm. The loaded file will be the following format “AlgorithimName_Backup_FileNum.conf”
Arguments:
fileNum : (Integer) The specified file number to be used in the name for the file
Returns: Returns “Knock Received” on success. If there is no SD Card inserted or an SD Card Error, there will be a UI popup on the HuskyLens outlining the issue.

savePictureToSDCard( )
Description: Save a photo from the HuskyLens camera onto the SD Card.
Returns: Returns “Knock Received” on success. If there is no SD Card inserted or an SD Card Error, there will be a UI popup on the HuskyLens outlining the issue.

saveScreenshotToSDCard( )
Description: Save a screenshot of the HuskyLens UI onto the SD Card.
Returns: Returns “Knock Received” on success. If there is no SD Card inserted or an SD Card Error, there will be a UI popup on the HuskyLens outlining the issue.