Measure¶

Introduction¶

The Measure module allows measuring of depth values in a specific region of interest.

The Measure module is an on-board module of the rc_cube.

Measuring Depth¶

The Measure module provides functionality to measure depth values in the current scene in a 2D region of interest. Optionally, the region of interest can be subdivided into up to 100 cells, for which separate depth measurements are returned in addition to the overall depth measurements of the whole region.

A depth measurement consist of the average depth mean_z, the minimum depth min_z and the maximum depth max_z, each containing 3D coordinates. The coordinates of the min_z and max_z measurements correspond to the point in the cell or overall region with the minimum and maximum distance from the camera, respectively. The x and y coordinates of the mean_z measurements define a point in the center of the cell or the overall region and the z coordinate is determined by the average of all depth value measurements (distances from the camera) in this region. Additionally, a coverage value is returned for each cell and the overall region, which is a number between 0 and 1 that reflects the fraction of valid depth values inside the respective region. A coverage value of 0 means that the cell is invalid and no depth value could be computed.

When the external pose_frame is used for the depth measurements, all 3D coordinates are computed as described above, but then transformed to the external frame. That means, the depth is always measured along the line of sight of the camera, independently of the chosen pose frame.

Interaction with other modules¶

Internally, the Measure module depends on, and interacts with other on-board modules as listed below.

Note

All changes and configuration updates to these modules will affect the performance of the Measure module.

Depth Images¶

The Measure module internally makes use of the following data:

Disparity images from the Stereo matching module (rc_stereomatching), in case an rc_viscore or rc_visard camera is used
Depth images from the Blaze module (rc_blaze), in case a Basler blaze camera is used

IO and Projector Control¶

In case the rc_cube is used in conjunction with an external random dot projector and the IO and Projector Control module (rc_iocontrol), it is recommended to connect the projector to GPIO Out 1 and set the stereo-camera module’s acquisition mode to SingleFrameOut1 (see Stereo matching parameters), so that on each image acquisition trigger an image with and without projector pattern is acquired.

Alternatively, the output mode for the GPIO output in use should be set to ExposureAlternateActive (see Description of run-time parameters).

In either case, the Auto Exposure Mode exp_auto_mode should be set to AdaptiveOut1 to optimize the exposure of both images (see Stereo camera parameters).

No additional changes are required to use the Measure module in combination with a random dot projector.

Hand-eye calibration¶

In case the camera has been calibrated to a robot, the Measure module can automatically provide points in the robot coordinate frame. For the Measure node’s Services, the frame of the output points can be controlled with the pose_frame argument.

Two different pose_frame values can be chosen:

Camera frame (camera). All points provided by the module are in the camera frame, and no prior knowledge about the pose of the camera in the environment is required. It is the user’s responsibility to update the configured points if the camera frame moves (e.g. with a robot-mounted camera).
External frame (external). All points provided by the module are in the external frame, configured by the user during the hand-eye calibration process. The module relies on the on-board Hand-eye calibration module to retrieve the sensor mounting (static or robot mounted) and the hand-eye transformation. If the mounting is static, no further information is needed. If the sensor is robot-mounted, the robot_pose is required to transform poses to and from the external frame.

Note

If no hand-eye calibration is available, all pose_frame values should be set to camera.

All pose_frame values that are not camera or external are rejected.

Parameters¶

The Measure module is called rc_measure in the REST-API and is represented in the Web GUI in the desired pipeline under Modules ‣ Measure.

Parameter overview¶

This module has no run-time parameters.

Status values¶

The Measure module reports the following status values:

Table 11 The `rc_measure` module’s status values¶
Name	Description
`data_acquisition_time`	Time in seconds required to acquire depth image
`last_timestamp_processed`	The timestamp of the last processed depth image
`processing_time`	Processing time of the last measurement in seconds

Services¶

The user can explore and call the Measure module’s services, e.g. for development and testing, using the REST-API interface or the rc_cube Web GUI on the Measure page under Modules.

The Measure module offers the following services.

`measure_depth`¶

Computes the mean, minimum and maximum depth in a given region of interest, which can optionally be subdivided into cells.

Details
This service can be called as follows.
API version 2

API version 1 (deprecated)
PUT http://<host>/api/v2/pipelines/<0,1,2,3>/nodes/rc_measure/services/measure_depth
PUT http://<host>/api/v1/nodes/rc_measure/services/measure_depth
Request

Response
Required arguments:

pose_frame: see Hand-eye calibration.

Optional arguments:

region_of_interest_2d_id is the ID of the 2D region of interest (see RoiDB) that will be used for the depth measurements.

region_of_interest_2d is an alternative on-the-fly definition of the region of interest for the depth measurements. This region of interest will be ignored if a region_of_interest_2d_id is given. The region of interest is always defined on the camera image with full resolution, where offset_x and offset_y are the pixel coordinates of the upper left corner of the rectangular region of interest, and width and height are the width and height of it in pixels. Default is a region of interest covering the whole image.

cell_count is the number of cells in x and y direction into which the region of interest is divided. If not given, a cell count of 0, 0 is assumed and only the overall values will be computed. The total cell count is computed as product of the x and y values must not exceed 100.

data_acquisition_mode: if set to CAPTURE_NEW (default), a new image dataset will be used for the measurement. If set to USE_LAST, the previous dataset will be used for the measurement.

Potentially required arguments:

robot_pose: see Hand-eye calibration.

The definition for the request arguments with corresponding datatypes is:
{
  "args": {
    "cell_count": {
      "x": "uint32",
      "y": "uint32"
    },
    "data_acquisition_mode": "string",
    "pose_frame": "string",
    "region_of_interest_2d": {
      "height": "uint32",
      "offset_x": "uint32",
      "offset_y": "uint32",
      "width": "uint32"
    },
    "region_of_interest_2d_id": "string",
    "robot_pose": {
      "orientation": {
        "w": "float64",
        "x": "float64",
        "y": "float64",
        "z": "float64"
      },
      "position": {
        "x": "float64",
        "y": "float64",
        "z": "float64"
      }
    }
  }
}
cells contains the depth measurements of all requested cells. The cells are always ordered from left to right and top to bottom in image coordinates.

overall contains the depth measurements of the full region of interest.

coverage contains the valid pixel ratio as described in Measuring Depth.

mean_z, min_z and max_z contains the measurement coordinates as described in Measuring Depth.

region_of_interest_2d returns the definition of the requested region of interest for the depth measurement.

pose_frame contains the pose frame of the depth measurement coordinates.

The definition for the response with corresponding datatypes is:
{
  "name": "measure_depth",
  "response": {
    "cell_count": {
      "x": "uint32",
      "y": "uint32"
    },
    "cells": [
      {
        "coverage": "float64",
        "max_z": {
          "x": "float64",
          "y": "float64",
          "z": "float64"
        },
        "mean_z": {
          "x": "float64",
          "y": "float64",
          "z": "float64"
        },
        "min_z": {
          "x": "float64",
          "y": "float64",
          "z": "float64"
        }
      }
    ],
    "overall": {
      "coverage": "float64",
      "max_z": {
        "x": "float64",
        "y": "float64",
        "z": "float64"
      },
      "mean_z": {
        "x": "float64",
        "y": "float64",
        "z": "float64"
      },
      "min_z": {
        "x": "float64",
        "y": "float64",
        "z": "float64"
      }
    },
    "pose_frame": "string",
    "region_of_interest_2d": {
      "height": "uint32",
      "offset_x": "uint32",
      "offset_y": "uint32",
      "width": "uint32"
    },
    "return_code": {
      "message": "string",
      "value": "int16"
    },
    "timestamp": {
      "nsec": "int32",
      "sec": "int32"
    }
  }
}

`trigger_dump`¶

Triggers dumping of the measurement that corresponds to the given timestamp, or the latest measurement, if no timestamp is given. The dumps are saved to the connected USB drive.

Details
This service can be called as follows.
API version 2

API version 1 (deprecated)
PUT http://<host>/api/v2/pipelines/<0,1,2,3>/nodes/rc_measure/services/trigger_dump
PUT http://<host>/api/v1/nodes/rc_measure/services/trigger_dump
Request

Response
The definition for the request arguments with corresponding datatypes is:
{
  "args": {
    "comment": "string",
    "timestamp": {
      "nsec": "int32",
      "sec": "int32"
    }
  }
}
The definition for the response with corresponding datatypes is:
{
  "name": "trigger_dump",
  "response": {
    "return_code": {
      "message": "string",
      "value": "int16"
    }
  }
}

Return codes¶

Each service response contains a return_code, which consists of a value plus an optional message. A successful service returns with a return_code value of 0. Negative return_code values indicate that the service failed. Positive return_code values indicate that the service succeeded with additional information. The smaller value is selected in case a service has multiple return_code values, but all messages are appended in the return_code message.

The following table contains a list of common codes:

Table 12 Return codes of the Measure module’s services¶
Code	Description
0	Success
-1	An invalid argument was provided