Calc Results by Python

Description

This Step runs a user-defined script through Python and outputs the calculation results to Mech-MSR.

The characteristics of this Step are as follows:

  • Support multi-threading.

  • Load Python script in real time.

  • Support various data type conversions when transferring data between C++ and Python.

  • Allow for the display of the Python’s log in the log panel of Mech-MSR.

Usage Scenario

When a custom calculation is required, this Step can be used to run the user-defined Python script and the measurement solution can be simplified.

Input and Output

  • Input: determined by the data type input in the Input Ports parameter.

  • Output: determined by the data type input in the Output Ports parameter.

You can specify the data type of the input/output ports according to the data type of the previous or subsequent Steps’ input/output ports.

Installation and Usage

Installation

Python 3.9.13 and two commonly used Python libraries, NumPy and OpenCV, are built into Mech-MSR. The “Calc Results by Python” Step will use the built-in Python environment while the Step running. If there is any missing Python library when you use this Step, you need to install the library in the Mech-MSR’s built-in Python environment. The procedures for installation are as follows:

  1. Navigate to the Python installation directory of Mech-MSR. For example, C:\App\Mech-MSR-2.0.0\python.

  2. In the current directory, hold down the Shift key, right-click, and then select the Open PowerShell window here option from the context menu.

  3. Execute the python -m pip install xxx command (xxx is the name of the Python library) in the Windows PowerShell window to download and install the corresponding Python library.

    install python library
If the installation of Python libraries fails due to network issues, refer to What to do if a Python library installation fails? for troubleshooting.

Usage Instructions

After preparing the Python script, please follow the procedure below to use the Step. For detailed description of the parameters, refer to Parameter Description.

  1. Set the data type for the input and output ports. Enter the data type for Input Ports and Output Ports according to the data type of the previous or subsequent Steps’ input/output ports.

  2. Specify the file path to the Python script. Select the file path to the script to be loaded in the Script File Path parameter.

  3. Set the name of the function to be called. Once the Script File Path has been specified, this Step will retrieve the function names in the script automatically, and you can select the name of the function to be called in the drop-down list of Func Name.

  4. Run the Step.

  • When writing the Python scripts, you can directly write the functions to process data without writing the statements in the scripts to obtain Mech-MSR data.

  • When the Python script is modified, and you want to use the new script to run this Step in real time, click Reload File in the Execution Flags parameter group.

Notes

Please pay attention to the following issues when you write the Python script and run the script in this Step.

Third-Party Library is Recommended

Because running a Python script in Mech-MSR differs from running the script in Python directly, some Python libraries could not be installed successfully or they cannot function properly after being installed, it is recommended to use third-party libraries.

Use the NumPy Library

The NumPy library is used to support some complicated formats of data. If a parameter type is ndarray, but the NumPy has not been imported, an error may occur. Therefore, you should add the import numpy statement at the beginning of the script.

Pay Attention to the Data Dimension when Writing the Script

When writing the Python script, please note the dimension of data corresponding to each port of the Step.

  • 0 dimension by default: Image, Cloud(XYZ), Cloud(XYZ-Normal), Surface, Profile

  • 1 dimension by default: NumberList, BoolList, IndexList, StringList, Shape3DList

  • 2 dimensions by default: PoseList, Pose2DList, Size3DList

Use “[]” after the data type to add a dimension.

For example, the data dimension of NumberList is 1, while the data dimension of NumberList[] is 2.

Import Predefined Modules

When the input or output port type of this Step is Surface, Profile, or Shape3DList, predefined module(s) must be imported.

When using a Python script in Mech-MSR to process data of types Surface, Profile, or Shape3DList, you should import the corresponding predefined module into the script. This allows Python to recognize and operate the data structure when running the script. If the required module is not imported, the script will fail to recognize these classes and encounter errors during execution.

You can find these predefined modules in the software installation directory (e.g., C:\Mech-MSR-2.0.0\python\Lib\py_module). These modules can be used to handle the following three types of data:

  • Surface data

    • Description: Represents the scan data of the object surface, usually including the depth map and intensity image.

    • Port type: Surface

    • Module to import into a Python script: mmind_surface

      Instructions
      from mmind_surface import *		# must be imported
      
      def test_surface(surface):
          print(surface) # is a class
          print(type(surface)) # is a class
          print(surface.depth) # is numpy.ndarray (n, m)
          print(surface.intensity) # is numpy.ndarray (n, m)
          print(surface.xResolution)
          print(surface.yResolution)
          print(surface.xOffset)
          print(surface.yOffset)
          print(surface.zOffset)
      
          return surface
      
      
      def test_surfaces(surfaces):
          print(type(surfaces)) # is list
          for surface in surfaces:
              print(type(surface)) # is class
              print(surface.depth)
              print(surface.intensity)
              print(surface.xResolution)
              print(surface.yResolution)
              print(surface.xOffset)
              print(surface.yOffset)
              print(surface.zOffset)
          return surfaces
  • Profile data

    • Description: Represents profile data. A profile is made up of points containing X and Z values, reflecting changes in height across a cross-section of an object.

    • Port type: Profile

    • Module to import into a Python script: mmind_profile

      Instructions
      from mmind_profile import *		# must be imported
      
      def test_surface(profile):
          print(profile) # is a class
          print(type(profile)) # is a class
          print(profile.points) # is numpy.ndarray (n,2)
          print(profile.yResolution)
          print(profile.xOffset)
          return profile
      
      
      def test_surfaces(profiles):
          print(type(profiles)) # is list
          for profile in profiles:
              print(type(profile)) # is a class
              print(profile.points) # is numpy.ndarray (n,2)
              print(profile.yResolution)
              print(profile.xOffset)
          return profiles
  • Geometric features

    • Description: Represents geometric features such as points, lines, planes, and circles.

    • Port type: Shape3DList

    • Modules to import into a Python script: mmind_feature and mmind_util

      Instructions
      from mmind_util import *		# must be imported
      from mmind_feature import *		# must be imported
      
      def test_shape3dList(point_list, line_list, plane_list, circle_list):
          point = point_list[0]       # class PyPoint3D
          line = line_list[0]         # class PyLine3D
          plane = plane_list[0]       # class PyPlane3D
          circle = circle_list[0]     # class PyCircle3D
      
          p_x = point.x               # number
          p_y = point.y
          p_z = point.z
      
          l_p = line.point            # class PyVector3D
          l_d = line.direction        # class PyVector3D
          print(l_d.x, l_d.y, l_d.z)
      
          p_a = plane.a               # number
          p_b = plane.b
          p_c = plane.c
          p_d = plane.d
      
          c_p = circle.point          # class PyVector3D
          c_r = circle.radius         # number
          c_n = circle.normal         # class PyVector3D
      
      
      def create_shape3dList():
          point1 = PyPoint3D(1.0, 2.0, 3.0)
          point2 = PyPoint3D()
          point2.x = 4.0              # must be a number
          point2.y = 5.0
          point2.z = 6.0
      
          line1 = PyLine3D(PyVector3D(1.0, 1.0, 1.0), PyVector3D(1.0, 1.0, 0.0))
          line2 = PyLine3D()
          line2.point = PyVector3D(1.1, 1.2, 1.3)     # can be PyVector3D or PyPoint3D
          line2.direction.x = 0.0     # must be a number
          line2.direction.y = 1.0
          line2.direction.z = 1.0
      
          plane1 = PyPlane3D(2.0, 0.0, 0.0, 10.0)
          plane2 = PyPlane3D()
          plane2.a = 0.0056           # must be a number
          plane2.b = 0.001
          plane2.c = 0.0023
          plane2.d = -3.22
      
          circle1 = PyCircle3D(point1, 10.0, PyVector3D(0.0, 0.0, 1.0))
          circle2 = PyCircle3D()
          circle2.point = point2      # can be PyVector3D or PyPoint3D
          circle2.radius = 100.0      # must be a number
          circle2.normal = PyVector3D(0.0, 1.0, 0.0)  # must be unit vector
      
          return [point1, point2], [line1, line2], [plane1, plane2], [circle1, circle2]

Parameter Description

Input Ports

This parameter is used to specify the data type(s) of the input port(s). The input data types will be passed to the called function as parameters in the corresponding order.

Default value: Null.

Output Ports

Description: This parameter is used to specify the data type(s) of the output port(s). Data returned by the function will be returned to the Step in the corresponding order and will be parsed according to the corresponding data type.

Default value: Null.

The currently supported data types are as follows:

Step port type Data type used in Python Input data example

PoseList

List

[[10, 20, 30, 0.951, 0.255, 0.168, 0.045]], [10, 20, 30, 0.951, 0.255, 0.168, 0.045]]
(In each array, the first three values are the coordinates, and the following four values are quaternions.)

Pose2DList

List

[[0, 0, 0]], [2, 0, 120]]
(In each array, the first two values are X and Y values of the coordinates respectively, and the third value is the angle.)

NumberList

List

[1.1, 2, 999.9, -22]

StringList

String

['string_1', 'string_2', 'string_3']

Image

8-bit unsigned integer/64-bit floating point number

Image data

Cloud(XYZ)

Array

Point cloud data

Cloud(XYZ-Normal)

Array

Point cloud data with normals

Cloud(XYZ-RGB)

Array

Data of textured point cloud

Size3DList

64-bit floating point number

[[2.5, 5, 0.001], [6, 5, 0.02]]

(In each array, the first two values are the width and height, and the third value is the length of each pixel.)

IndexList

Integer

[45, 10, 90]

BoolList

Boolean

[True, False, True]

Surface

Custom class

Surface data, usually including the depth map and intensity image.

Profile

Custom class

Profile data

Shape3DList

List

[PyPoint3D(), PyPoint3D(), …​]
[PyLine3D(), PyLine3D(), …​]
[PyPlane3D(), PyPlane3D(), …​]
[PyCircle3D(), PyCircle3D(), …​]
where PyPoint3D, PyLine3D, PyPlane3D, and PyCircle3D are all custom classes, representing the geometric features of point, line, plane, and circle, respectively.

Script File Path

This parameter is used to select the file path of the script to be loaded.

Func Name

This parameter is used to set the name of the function to be called.

Troubleshooting

See Error Code List for common error messages and solutions.

We Value Your Privacy

We use cookies to provide you with the best possible experience on our website. By continuing to use the site, you acknowledge that you agree to the use of cookies. If you decline, a single cookie will be used to ensure you're not tracked or remembered when you visit this website.