Mech-Viz Interface¶

This section introduces Adapter interfaces related to Mech-Viz, as listed below.

Start Mech-Viz Project
Stop Mech-Viz Project
Pause and Continue Mech-Viz
Set Task Parameters
Read Task Parameters
Set TCP
Set Velocity
Set Point Cloud Collision Parameters
Mech-Viz Return Value

Start Mech-Viz Project ¶

A function to start Mech-Viz project has been defined in the Adapter class in the adapter.py file, and therefore you can directly call the start_viz() function. Besides, you can rewrite self.before_start_viz() and self.after_start_viz() according to actual needs of the project to define the process before and after starting the Mech-Viz project.

Function Definition

def start_viz(self, in_new_thread=True, timeout=None):
    if not self.is_viz_registered():
        logging.error("{} has not registered in {}.".format(jk.mech_viz, jk.mech_center))
        self.code_signal.emit(ERROR, VIZ_NOT_REGISTERED)
        self.viz_finished_signal.emit(True)
        self.viz_not_registerd()
        return False
    if self.is_viz_in_running():
        logging.info("{} is already running.".format(jk.mech_viz))
        self.code_signal.emit(WARNING, VIZ_IS_RUNNING)
        self.viz_finished_signal.emit(False)
        self.viz_is_running()
        return False
    self._read_viz_settings()
    if not self.viz_project_dir:
        self.msg_signal.emit(ERROR, _translate("messages", "The project of {0} is not registered. Please make sure Autoload Project is selected in {0}.").format(jk.mech_viz))
        self.viz_finished_signal.emit(True)
        return False
    msg = {"simulate": self.is_simulate, "project_dir": self.viz_project_dir}
    if self.is_keep_viz_state:
        msg["keep_exec_state"] = self.is_keep_viz_state
    if self.is_save_executor_data:
        msg["save_executor_data"] = self.is_save_executor_data
    self.before_start_viz()
    self.viz_finished_signal.emit(False)
    if in_new_thread:
        threading.Thread(target=self.wait_viz_result, args=(msg, timeout)).start()
    else:
        self.wait_viz_result(msg, timeout)
    self.after_start_viz()
    return True

By default, start_viz() will wait for Mech-Viz to finish execution in a new thread, which is to avoid affecting operations other than starting Mech-Viz project.

The example below shows how to set Step parameters dynamically by calling the self.before_start_viz() function.

def before_start_viz(self):
     self.set_move_offset(x, y, z)

Before starting Mech-Viz project, the X, Y, or Z-axis offset of a target will be configured according to the read data.

Stop Mech-Viz Project ¶

A function to stop Mech-Viz project has been defined in the Adapter class in the adapter.py file, and therefore you can directly call the stop_viz() function.

Function Definition

def stop_viz(self, timeout=None):
    if not self.is_viz_registered():
        self.code_signal.emit(WARNING, VIZ_NOT_REGISTERED)
        return False
    self.call_viz("stop", timeout=timeout)
    self.code_signal.emit(INFO, VIZ_STOP_OK)
    return True

Pause and Continue Mech-Viz ¶

A function to pause and continue Mech-Viz project has been defined in the Adapter class in the adapter.py file. The pause_viz function corresponds to the Pause/Continue button in Mech-Viz and can only be used for simulation.

Function Definition

def pause_viz(self, msg, timeout=None):
       if not self.is_viz_registered():
           self.code_signal.emit(WARNING, ADAPTER_CANCEL_PAUSE)
           return
       self.call_viz("switchPauseContinue", msg, timeout)
       self.code_signal.emit(INFO, ADAPTER_PAUSE_VIZ if msg.get(
           "to_pause") else ADAPTER_CONTINUE_VIZ)

Set Task Parameters ¶

Usually, you can directly call the set_task_property() function in the Adapter class to set Task parameters dynamically.

Function Definition

def set_task_property(self, msg, timeout=None):
    return self.call_viz("setTaskProperties", msg, timeout)

In the above function, msg determines the parameters configured in different Tasks.

move ¶

When running a Mech-Viz project, sometimes you need to fine-tune the X-axis, Y-axis, and Z-axis offset in the move Task, which can be enabled by adding the function below in the main program.

Example

def set_move_offset(self, name, x_offset, y_offset, z_offset):
    msg = {"name": name,
           "values": {"xOffset": x_offset / UNIT_PER_METER,
                      "yOffset": y_offset / UNIT_PER_METER,
                      "zOffset": z_offset / UNIT_PER_METER}}
    self.set_task_property(msg)

In the above example, name is the name of the move Task and UNIT_PER_METER is 1000. Since the unit of x_offset, y_offset, and z_offset is usually millimeter, and the data unit used in Mech-Viz is meter, you need to use UNIT_PER_METER to convert the unit.

If the following set_move_offset() function is called, the X-axis, Y-axis, and Z-axis offset in the “move_1” Task will be changed accordingly.

self.set_move_offset("move_1", 100, 200, 300)

move_list/move_grid ¶

The move_list and move_grid Tasks should be configured in Mech-Viz in advance, and then Adapter will modify the index according to the logic. The method to create and call the function is the same as those of the move and pallet interface functions.

outer_move ¶

The outer_move Task can be used when multiple targets from external services are sent to Mech-Viz for path planning. You can set JPs, TCP, and the object pose in the Task, as shown below.

Example

class CustomOuterMoveService(OuterMoveService):
    def gather_targets(self, di, jps, flange_pose):
        self.add_target(self.move_target_type, [0.189430,-0.455540,0.529460,-0.079367,0.294292,-0.952178,0.021236])

When Mech-Viz executes to the outer_move Task, the function getMoveTargets() will be called. Different outer_move Tasks can be distinguished by their service names.

def _register_service(self):
   self.outer_move_service = CustomOuterMoveService()
   self._outer_move_server, port = register_service(outer_move_service, port)

The Setting Parameters panel of the outer_move Task in Mech-Viz is shown in the figure below.

../../../../../_images/viz_interface_01.png

Attention

A Task to define picking should be put before the outer_move Task. Otherwise, an error message “- The posture of the object is invalid when the object is not held!” will pop up.

Pallet ¶

When running a Mech-Viz project, sometimes you need to configure parameters for different pallet-type Tasks. The specific Task to be configured can be found according to the name of the pallet-type Task. All parameters displayed in the Task parameters panel in Mech-Viz can be configured.

Example

For example, the parameters Current Index and File Name for the Task custom_pallet_pattern usually need to be modified, and you can add a function as shown below in the main program.

Hint

The Dir Path and File Name will be displayed only when the Dynamic Load is checked.

def set_stack_pallet(self, name, curIndex, fileName):
    msg = {
        "name": name,
        "values": {
            "curIndex": curIndex,
            "fileName": fileName,
        }
    }
    self.set_task_property(msg)

In the above example, “curIndex” corresponds to the parameter name Current Index, and “fileName” corresponds to the parameter name File Name in the Task parameters panel in Mech-Viz.

The statement as shown below is used to call the set_stack_pallet() function.

self.set_stack_pallet("common_pallet_1", 2, "re.json")

For the Task predefined_pallet_pattern, the parameter values of Current Index, Pallet Type, Carton Length, Carton Width, Carton Height, Rows/Unit, Cols/Unit, and Layer Count usually need to be modified. You can add a function as shown below in the main program.

def set_stack_pallet(self, name, curIndex, stack_type):
    pallet_info = self.box_data_info[stack_type]
    """
        pallet_info: Length(mm), Width(mm), Height(mm), pallet type, rows, columns, layers
    """
    msg = {
        "function": "setTaskProperties",
        "name": name,
        "values": {
            "curIndex": curIndex,
            "palletType": pallet_info[3],
            "cartonLength": pallet_info[0] / UNIT_PER_METER,
            "cartonWidth": pallet_info[1] / UNIT_PER_METER,
            "cartonHeight": pallet_info[2] / UNIT_PER_METER,
            "cylinderRows": pallet_info[4],
            "cylinderCols": pallet_info[5],
            "layerNum": pallet_info[6]
        }
    }
    self.set_task_property(msg)

Since there are multiple parameters need to be configured, you will usually write the parameters into an Excel file first, and then the data in the Excel file can be read by the program and recorded into the self.box_data_info, and the index of stack_type can be used to obtain certain parameter values of the Task.

When comparing the msg value in the custom_pallet_pattern and predefined_pallet_pattern class, you can find that the biggest difference is the “values”. If you need to configure the parameters of a specific Task, you can add corresponding parameter names and values in “values”. You can refer to the above examples to configure parameters of other pallet-type Tasks.

branch_by_msg ¶

When the Mech-Viz project executes to the branch_by_msg Task, it will wait for an external signal sent by Adapter to specify an exit port to take. You can use the function as shown below to control the branch_by_msg Task.

Example

def set_branch(self, name, area):
    time.sleep(1) # The delay of 1s here is to wait for the Mech-Viz executor to fully start
    try:
        info = {"out_port": area, "other_info": []}
        msg = {"name": name,
               "values": {"info": json.dumps(info)}}
        self.set_task_property(msg)
    except Exception as e:
        logging.exception(e)

In the above example, name is the name of the branch_by_msg Task, area specifies the exit port. The serial number of the exit port starts from 0, and will be added one if a port is added. If the Task is asked to take the first port on the left, then area=0. If the set_branch function is called before starting a Mech-Viz project, an “no actuator” error message will be returned.

counter ¶

When using the counter Task, you will need to set the total count and current count. The function used to configure parameters in this Task is shown below.

Example

def set_counter_property(self, name, count, curCount):
    msg = {"name": name,
           "values": {"count": count, "currentCount": curCount}}
    self.set_task_property(msg)

The statement to call the function is shown below.

self.set_counter_property("counter_1", 5, self.success_stack_num)

self.success_stack_num is the number of successfully palletized cartons. If a carton falls during palletizing, and Mech-Viz is stopped with manual intervention, the value of “currentCount” will not be stored in “counter_1” Task. After restarting Mech-Viz, the current count of the counter Task can be reset via self.success_stack_num.

Read Task Parameters ¶

If you need to read parameters of a specific Task when running the Mech-Viz project, you can add a function as shown below in the main program.

Example

def read_move_pallet(self, name):
     msg = {"name": name,
            "properties": ["xOffset","yOffset","zOffset", ]}
     return read_task_property(msg)

In the above example, “name” is used to locate the Task whose parameters need to be read. The parameters after “properties” can be modified according to actual needs. In this example, the values of parameters “xOffset”, “yOffset”, and “zOffset” need to be read. The statement to call the function is shown below.

self.read_move_pallet("move_3")

The result is shown below.

{'zOffset': -0.23, 'xOffset': -0.12, 'yOffset': -0.15}

Set TCP ¶

You only need to specify the corresponding index in Mech-Viz’s end effector list to set the TCP. The end effector list index in Mech-Viz starts from 0, and the index number is an integer. Do not use an index number out of the boundary. The function to set TCP is shown below.

Example

def set_tcp(self, index):
    msg = {"function": "setTcp", "index": index}
    self.call("executor", msg)

Set Velocity ¶

To adjust the robot velocity dynamically, you can add a function as shown below in the main program.

Example

def set_vel(self, vel_scale):
    msg = {"function": "setConfig",
           "velScale": vel_scale / 100, "accScale": vel_scale / 100}
    self.call("executor", msg)

If the velocity needs to be set as 80%, the following function can be called.

self.set_vel(80)

Attention

This function must be called after starting the Mech-Viz project, or else an error may occur. The prerequisite for this function is the same as that of set_branch(). Therefore, the set_vel() function is usually called in the set_branch() function instead of calling it in a new thread. An example is shown below.

def set_branch(self, name, area):
    time.sleep(1)
    if self.box_data_info[int(self.pallet_info)][7] <= 10:
        self.set_vel(100)
    else:
        self.set_vel(80)
    try:
        info = {"out_port": area, "other_info": []}
        msg = {"function": "setTaskProperties",
               "name": name,
               "values": {"info": json.dumps(info)}}
        self.set_task("executor", msg)
    except Exception as e:
        logging.exception(e)

Set Point Cloud Collision Parameters ¶

The setConfig() interface function corresponds to the parameters related to collision detection in Mech-Viz. The method to set cloud collision parameters interface is the same as that of setting velocity, and the main difference is the msg value. An example is shown below.

Example

msg = {}
msg["function"] = "setConfig"
msg["check_pcl_collision"] = True
msg["collided_point_thre"] = 5000
msg["collide_area_thre"] = 20
msg["pcl_resolution_mm"] = 2
self.call("executor", msg)

Mech-Viz Return Value ¶

The return values of Mech-Viz are as shown in the table below.

Return Value	Description
Finished	The execution has finished properly. Please note that when visual_move Task takes the exit port on the right (Other failures), this value will be returned as well.
Command Stop	The Stop button has been clicked on or the stop_viz() function has been called.
No targets	There were no vision points returned by Mech-Vision.
No proper vision poses	The vision point was unreachable as the robot could not move to that point or the robot would collide with others.
PlanFail	Mech-Viz failed to plan the path.
SceneCollision	A collision was detected.

According to the value returned by Mech-Viz, corresponding interface functions are provided in base class of Adapter.