Skip to content

IndyDCP3: IndyEye Python API Documentation

See also

Python IndyDCP3 client

The IndyEye class in the neuromeka package allows you to execute the recognition tasks for IndyEye from outside the IndyEye app or Conty. To create a client object, import the IndyEye class from the neuromeka package.

1
from neuromeka import IndyEye

After creating an IndyEye class object, specify the IndyEye server's IP address.

1
eye = IndyEye(eye_ip='192.168.0.100')

Usage Example: 

from neuromeka import IndyDCP3
from neuromeka import IndyEye
from neuromeka.eye import *

robot_ip = "192.168.0.10"
eye_ip = "192.168.0.100"

indy = IndyDCP3(robot_ip=robot_ip)
eye = IndyEye(eye_ip=eye_ip)

task_pos = indy.get_control_data()['p']
pose_obj = eye.detect(cls=1, task_pos=task_pos, mode=DetectKey.REF_TO_OBJECT, robot_ip=robot_ip)
print(pose_obj)  # [335.287, 53.583, 442.725, -5.815, 17.223, 86.578] # [mm, mm, mm, deg, deg, deg]

Warning

Up to version 3.2.0.6, the IndyEye client in the neuromeka package uses meters (m) as the unit for position values.
If you upgrade to version 3.2.0.7 or higher, you will need to modify your code related to position values.

# Version ~3.2.0.6
eye = IndyEye(eye_ip=eye_ip)
task_pos = indy.get_control_data()['p'] # Task position (mm)
for i in range(len(task_pos)):
    task_pos[i] = task_pos[i]/1000  # Convert mm to m
pose_obj = eye.detect(cls=1, task_pos=task_pos, mode=DetectKey.REF_TO_OBJECT, robot_ip=robot_ip)
print(pose_obj)  # [0.335, 0.0535, 0.442, -5.815, 17.223, 86.578] # [m, m, m, deg, deg, deg]

# Version 3.2.0.7 and higher
eye = IndyEye(eye_ip=eye_ip)
task_pos = indy.get_control_data()['p'] # Task position (mm)
pose_obj = eye.detect(cls=1, task_pos=task_pos, mode=DetectKey.REF_TO_OBJECT, robot_ip=robot_ip)
print(pose_obj)  # [335.287, 53.583, 442.725, -5.815, 17.223, 86.578] # [mm, mm, mm, deg, deg, deg]

class IndyEye

Creates a client object that can connect to the IndyEye server.

  • Parameters:

    • eye_ip (str): The IP address of the IndyEye server.
    • pose_unit (str, optional): The unit to use when manually entering position values. Choose between "mm" and "m". The default is "mm".

      • Added in version 3.2.0.7.

  • Returns:

    • IndyEye client instance.

Example: 

from neuromeka import IndyEye
eye = IndyEye(eye_ip="192.168.0.100")


# Version 3.2.0.7 and higher (For passing task_pos with meters as a unit)
eye = IndyEye(eye_ip="192.168.0.100", pose_unit="m")

task_pos = indy.get_control_data()['p'] # Task position (mm)
for i in range(len(task_pos)):
    task_pos[i] = task_pos[i]/1000  # Convert mm to m
pose_obj = eye.detect(cls=1, task_pos=task_pos, mode=DetectKey.REF_TO_OBJECT, robot_ip=robot_ip)
print(pose_obj)  # [335.287, 53.583, 442.725, -5.815, 17.223, 86.578] # [mm, mm, mm, deg, deg, deg]

Method List

Method Description
run_command() Execute a command
get_object_dict() Retrieve class information
detect() Execute the Detect command
detect_by_object_name() Execute the Detect command by class name
retrieve() Execute the Retrieve command
get_version() Retrieve the IndyEye version
image() Retrieve the current camera image

run_command(cmd, cls=0, pose_cmd=None, robot_ip=None)

Executes a command. Commands can be selected from EyeCommand class: EyeCommand.DETECT, EyeCommand.RETRIEVE, EyeCommand.GETLIST.

  • Parameters:

    • cmd (EyeCommand): Type of recognition command.
    • cls (int): Index of the object class to recognize. Default is 0.
      • If this value is 0, the first detected object will be returned as a result.
    • pose_cmd (float[6], optional): Current task position of the robot, in the order of [x, y, z, u, v, w]. Default is None.
      • If None, coordinates are received from the currently connected robot.
    • robot_ip (str, optional): IP address of the robot controller. Default is None.

  • Returns:

    • dict: Dictionary of recognition results.

  • Raises:

    • ValueError: If any of the x, y, z values in pose_cmd are greater than 10m.

Example: 

>>> from neuromeka.eye import *
>>> eye.run_command(cmd=EyeCommand.DETECT, cls=0, task_pos=None, robot_ip="192.168.0.10")
{'detected': True, 'passed': True, 'cls': 1,
'tar_ee_pose': [0.400, 0.0, 0.400, 180.0, 0.007, 180.0],
'tar_tool_pose': [0.383, -0.002, -0.0948, 0.575, 2.228, -18.348],
'tar_obj_pose': [0.383, -0.002, -0.0948, 0.575, 2.228, -18.348],
'tool_idx': 0, 'error_state': False, 'error_module': ''}

get_object_dict()

Returns a dictionary of object classes that can be recognized based on the currently loaded graph in IndyEye. Class indices start at 1.

  • Returns:
    • dict: {class index: "class name", ...}

Example: 

>>> eye.get_object_dict()
{1: "sheet", 2: "orange"}

Recognition Functions

detect(cls, task_pos, mode=DetectKey.REF_TO_END_TOOL, robot_ip=None)

Captures the current camera image and returns the recognition result. If the "On retrieve" value of the Select module in the graph is "On", it must be used together with the retrieve() function.

  • Parameters:

    • cls (int): Index of the object class to recognize. Default is 0.
      • If this value is 0, the first detected object will be returned as a result.
    • task_pos (float[6], optional): Current task position of the robot, in the order of [x, y, z, u, v, w]. Default is None.
      • If None, coordinates are received from the currently connected robot.
    • mode (DetectKey, optional): Key indicating what value to receive as a result. Default is DetectKey.REF_TO_END_TOOL.
    • robot_ip (str, optional): IP address of the robot controller. Default is None.

  • Returns:

    • If recognized, float[6]: Position of the recognized object in the reference coordinate system [x, y, z, u, v, w], units in mm, deg.
    • If not recognized, None.

  • Raises:

    • ValueError: If any of the x, y, z values in task_pos are greater than 10m.

Example: 

object_result = eye.detect(1, task_pos=None, robot_ip="192.168.0.50")

detect_by_object_name(target_name, task_pos, mode=DetectKey.REF_TO_END_TOOL, robot_ip=None)

Executes the detect command using the class name instead of the class index.

  • Parameters:

    • target_name (str): Name of the object class to recognize.
    • task_pos (float[6], optional): Current task position of the robot, in the order of [x, y, z, u, v, w]. Default is None.
      • If None, coordinates are received from the currently connected robot.
    • mode (DetectKey, optional): Key indicating what value to receive as a result. Default is DetectKey.REF_TO_END_TOOL.
    • robot_ip (str, optional): IP address of the robot controller. Default is None.

  • Returns:

    • If recognized, float[6]: Position of the recognized object in the reference coordinate system [x, y, z, u, v, w], units in mm, deg.
    • If not recognized, None.

  • Raises:

    • ValueError: If any of the x, y, z values in task_pos are greater than 10m.

Example: 

object_result = eye.detect_by_object_name("sheet", task_pos=None, robot_ip="192.168.0.10")

retrieve(cls, task_pos, mode=DetectKey.REF_TO_END_TOOL)

Selects and retrieves objects one by one from the list of recognition results obtained by detect(). This function can be used only when the "On retrieve" value of the Select module in the graph is "On".

  • Parameters:

    • cls (int): Index of the object class to recognize. Default is 0.
      • If this value is 0, the first detected object will be returned as a result.
    • task_pos (float[6], optional): Current task position of the robot, in the order of [x, y, z, u, v, w]. Default is None.
      • If None, coordinates are received from the currently connected robot.
    • mode (DetectKey, optional): Key indicating what value to receive as a result. Default is DetectKey.REF_TO_END_TOOL.

  • Returns:

    • If recognized, float[6]: Position of the recognized object in the reference coordinate system [x, y, z, u, v, w], units in mm, deg.
    • If there are no more objects in the list, returns None.

  • Raises:

    • ValueError: If any of the x, y, z values in task_pos are greater than 10m.

Example: 

robot_ip = "192.168.0.10"
eye.detect(1, task_pos=None, robot_ip=robot_ip)
object_results = []
while True:
    object_result = eye.retrieve(1)
    if object_result is None:
        break
    object_results.append(object_result)
print(object_results)

Utility Functions

get_version()

Returns the version of the currently connected IndyEye server.

  • Returns:
    • str: Version information.

Example: 

>>> eye.get_version()
"0.6.0"

image()

Returns the current camera image from the IndyEye server.

  • Returns:
    • PIL.Image: Current camera image.

Example: 

current_image = eye.image()
current_image.show()

class EyeCommand

Defines the types of commands used in the run_command() function.

  • DETECT = 0: Detect command.
  • RETRIEVE = 1: Command to retrieve objects one by one from pre-captured results.
    • The Select module in the graph must have the ON RETRIEVE option set to On.
  • GETLIST = 3: Command to retrieve the class list.

class DetectKey

Defines keywords used to receive specific values as results in the detect(), detect_by_object_name(), and retrieve() functions.

  • DETECTED = 'detected': Whether the object was recognized.
  • PASSED = 'passed': Whether the object passed inspection.
  • CLASS = 'cls': Index of the recognized object's class.
  • REF_TO_END_TOOL = 'tar_ee_pose': 6D task position to pick the object.
  • REF_TO_PICK_POINT = 'tar_tool_pose': 6D Tool Center Position to pick the object.
  • REF_TO_OBJECT = 'tar_obj_pose': 6D Position of the recognized object.
  • TOOL_INDEX = 'tool_idx'
  • ERROR_STATE = 'error_state': Whether an error occurred in IndyEye.
  • ERROR_MODULE = 'error_module': Name of the module where the error occurred in IndyEye.
  • CLASS_NAMES = 'class_names'