Mech-Viz Interface
This section introduces Adapter interfaces related to Mech-Viz, as listed below.
Start Mech-Viz Project
A function to start the 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 processing 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 TrueBy default, “start_viz()” will wait for the running of the Mech-Viz project to finish in a new thread, which avoids affecting operations other than starting the 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, and Z-axis offsets of a target will be set according to the read data.
Stop Mech-Viz Project
A function to stop the 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 TruePause and Continue Mech-Viz Project
A function to pause and continue the 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 Step Parameters
Usually, you can directly call the “set_task_property()” function in the Adapter class to set Step parameters dynamically in Mech-Viz.
Function definition
def set_task_property(self, msg, timeout=None):
return self.call_viz("setTaskProperties", msg, timeout)In the above function, “msg” determines the Step parameters to be set.
Fixed-Point Move
Sometimes you need to fine-tune the X-axis, Y-axis, and Z-axis offset in the Fixed-Point Move Step when running a Mech-Viz project, which can be achieved by adding the function below in the main program for controlling Mech-Viz project.
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 “Fixed-Point Move” Step and “UNIT_PER_METER” is 1000. Since the unit of x_offset, y_offset, and z_offset is usually millimeter, but 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 offsets in the “move_1” Step in the Mech-Viz project will be changed accordingly.
self.set_move_offset("move_1", 100, 200, 300)Move by List/Move by Grid
The “Move by List” and “Move by Grid” Steps usually should be configured in Mech-Viz in advance, and then Adapter will modify the start index according to the logic. The method to create and call the function is the same as those of the Fixed-Point Move and Palletize interface functions.
External Move
The “External Move” Step 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 “External Move” Step, 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])The CustomOuterMoveService class is developed based on the OuterMoveService class. self.move_target_type indicates the target type. Valid values: 0, 1, and 2. A value of 0 indicates the JP type, a value of 1 indicates the TCP type, and a value of 2 indicates the object pose type. Mech-Viz calls getMoveTargets() when running an External Move Step. Different External Move Steps 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)| If self.move_target_type is set to 2, you must place a Step that defines the picking before the External Move Step. Otherwise, the following error message will pop up: - The posture of the object is invalid when the object is not held!. |
Palletizing
When running a Mech-Viz project, sometimes you need to set parameters for different pallet-type Steps. The specific Step to be configured can be found according to the name of the palletizing-type Step. All parameters displayed in the Step Parameters panel in Mech-Viz by selecting the Step in the graphical programming workspace can be modified.
Example
For example, the parameters “Starting Index” and “Pattern File Path” (Pattern File Path is available only when Dynamic Load is selected) for the “Custom Pallet Pattern” Step usually needs to be modified, and you can add a function as shown below in the main program.
def set_stack_pallet(self, name, startIndex, fileName):
msg = {
"name": name,
"values": {
"startIndex": startIndex,
"fileName": fileName,
}
}
self.set_task_property(msg)In the above example, “startIndex” corresponds to the “Starting Index” parameter, and “fileName” corresponds to the “Pattern File Path” parameter in the Step 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 Step “Predefined Pallet Pattern”, the parameter values of Starting Index, Pallet Type, Carton Length, * Carton Width*, Carton Height, Rows, Columns and Layer Count usually need to be modified. You can add a function as shown below to the main program.
def set_stack_pallet(self, name, startIndex, 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": {
"startIndex": startIndex,
"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 multiple parameters need to be set, in most cases, you can write the parameter settings into an Excel file first. Then, the file data can be read by the program and recorded in “self.box_data_info”. The value of “stack_type” can be used to obtain certain parameter values of the Step. Names such as “startIndex”, “PalletType”, and “cartonLength” are fixed names in Mech-Viz.
By comparing the “msg” values in the Custom Pallet Pattern and Predefined Pallet Pattern class, you can find that the largest difference is the “values”. If you need to set the parameters of a specific Step, you can add corresponding parameter names and values in “values”. You can refer to the above examples to set parameters of other palletizing-type Steps.
Branch by Msg
When the Mech-Viz project executes to the “Branch by Msg” Step, 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” Step.
Example
def set_branch(self, name, area):
time.sleep(1) # The delay of 1s here is to wait for the {product-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” Step, “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 Step 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 by Mech-Viz.
Counter
When using the “Counter” Step, you will need to set the parameters “Count” and “Current Count”. The function used to set parameters in this Step 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)In this example, “self.success_stack_num” is the number of successfully palletized cartons. If the box is dropped in the palletizing, and Mech-Viz is stopped under human intervention, the value of “currentCount” will not be stored in the “Counter_1” Step. After restarting the Mech-Viz project, the current count of the “Counter” Step can be set using “self.success_stack_num”.
Read Step Parameters
If you need to read parameters of a specific Step when the Mech-Viz project is running, you can add a function as shown below to 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 Step 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 calling result is shown below.
{'zOffset': -0.23, 'xOffset': -0.12, 'yOffset': -0.15}In addition, please note that the parameter values obtained from a Mech-Viz Step may be the planned values, but not the values of real execution. The planned progress usually is ahead of the real execution process (Mech-Viz will plan out the future motion as early as possible). The following will use “curIndex” (current index) of the palletizing-type Steps as an example. You can add the function as shown below to the main program.
def read_pallet_current_index(self, name):
msg = {"name": name,
"properties": ["curIndex"]}
return read_task_property(msg)The statement to call the function to obtain the “curIndex” value is shown below.
self.read_pallet_current_index("common_pallet_1")The calling result is shown below.
{'curIndex': 5}In the above example, “5” indicates that five rounds of planning have finished. For example, for a carton palletizing project, “5” indicates that five cartons have been palletized in the planning progress. However, the number of cartons that have been palletized by the robot may be less than 5. Therefore, values of parameters such as “curIndex” indicate the planned values, but not the values in real execution.
Set TCP
You only need to specify the corresponding index of the end tool in the tool list of Mech-Viz to set the TCP. The indexes of tools in the end tool list of Mech-Viz is an integer that starts from 0. 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 Globally When Project Is Running
To adjust the robot velocity dynamically when the Mech-Viz project is running, you can add a function as shown below to 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 function can be called as shown below.
self.set_vel(80)| This function must be called after the Mech-Viz project is started, 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 following table describes the return values of Mech-Viz.
| Return value | Description |
|---|---|
Finished |
The execution has finished properly. Please note that when the “Vision Move” Step takes the exit port on the right (Other failures) in the Mech-Viz project, Mech-Viz will return this value 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 the base class of Adapter.