---
title: "Robot Settings"
description: "Robot settings in LumiScan VGR - the JSON robots section with robots, grippers, coordinate transformations, waypoints and path segments for a grip."
product: "LumiScan VGR"
component: "lumiscan-vgr"
version: "1.8.4"
display_version: "1.8.4.8"
latest_version: true
language: "en"
url: "https://docs.hdvisionsystems.com/en/lumiscan-vgr/json-settings/robots.html"
---

# Robot Settings – LumiScan VGR

The `robots` section defines the robots, grippers, coordinate transformations, and motion information required for robot interaction.

A physical robot can be represented by multiple configurations, for example when different grippers are used. Robot settings also describe the positions and motion segments required to approach and execute a grip.

## Robot Parameters

- [RobotSettings](https://docs.hdvisionsystems.com/en/lumiscan-vgr/api/settings/robot-settings.html)

### Coordinate Transformations

- [Transform](https://docs.hdvisionsystems.com/en/lumiscan-vgr/api/settings/transform.html)

### Waypoints

- [WaypointSettingsBase](https://docs.hdvisionsystems.com/en/lumiscan-vgr/api/settings/waypoint-settings-base.html)
  - [WaypointSettings](https://docs.hdvisionsystems.com/en/lumiscan-vgr/api/settings/waypoint-settings.html)
    - [Absolute Waypoint](https://docs.hdvisionsystems.com/en/lumiscan-vgr/api/settings/waypoint-settings-waypoint-type-wp-absolute.html)
    - [Relative Waypoint](https://docs.hdvisionsystems.com/en/lumiscan-vgr/api/settings/waypoint-settings-waypoint-type-wp-relative.html)
    - [Clone Waypoint](https://docs.hdvisionsystems.com/en/lumiscan-vgr/api/settings/waypoint-settings-waypoint-type-wp-clone.html)
    - [Grip Point Waypoint](https://docs.hdvisionsystems.com/en/lumiscan-vgr/api/settings/waypoint-settings-waypoint-type-wp-grip-point.html)

### Path Segments

- [PathSegmentSettings](https://docs.hdvisionsystems.com/en/lumiscan-vgr/api/settings/path-segment-settings.html)

## Hand-Eye Calibration: Station-Mounted and Robot-Mounted Cameras {#hand-eye-calibration}

*From v2.0.0.*

Each robot entry declares where its cameras sit, with `cameraMountType`:

| `cameraMountType` | Meaning |
| --- | --- |
| `STATIC` (default) | No camera of this robot is carried. `cameraToRobot` holds one hand-eye transform per camera, from the camera to the robot base frame, and `cameraToMove` is not read. This is the behaviour of every project written before eye-in-hand support, and a project that does not set `cameraMountType` keeps it. |
| `MOVING` | The robot carries the cameras listed in `cameraToMove`. This map holds one hand-eye transform per camera, from the camera to the robot’s **move frame** (the link named by `moveFrame`, normally the flange), **not** to the TCP. These cameras need the robot’s current move-frame pose for every capture. `cameraToMove` must not be empty. |

> [!IMPORTANT]
> `cameraMountType` is the gate, not the whole answer. Which cameras a `MOVING` robot actually carries is decided **per camera**, by whether the camera is listed in `cameraToMove`. A camera of the same robot that is **not** listed there is taken to be fixed in the cell: it is still resolved through `cameraToRobot` and needs no pose. One robot entry can therefore serve a wrist camera and an overhead camera at the same time, and only the wrist camera has to be given a pose.

The move frame is used rather than the TCP for two reasons: it is the frame the robot already reports (`IN_PoseMoveInRobot` on the PLC interface, and the pose that `GetBestResult` returns over OPC UA), so the two combine without any further conversion; and it does not change when the TCP is re-taught, so re-teaching a gripper does not invalidate a camera calibration.

Supply the pose with:

- **PLC (PROFINET)**: write `IN_PoseMoveInRobot`. LumiScan VGR takes a snapshot of it when it handles `IN_TriggerCameraRequest` (see [Camera Mounted on the Robot](https://docs.hdvisionsystems.com/en/lumiscan-vgr/plc-settings.html#moving-camera)).
- **OPC UA**: call `CaptureImageWithPose`, or `SetCapturePose` followed by `CaptureImage`. `SetCapturePose` may also be called **after** a capture and before `ComputeObjects`; results already computed from the previous pose are discarded, so they are recomputed with the new one. `GetCapturePose` reads back the pose currently in effect.
- **User interface**: the **Set Capture Pose…** dialog ([A15](https://docs.hdvisionsystems.com/en/lumiscan-vgr/user-interface.html)).

In each case the pose is expressed in the robot’s own pose format, the units and rotation convention configured in `poseFormat`, so it is exactly what the robot reports and what LumiScan VGR returns as a grip pose.

If a capture is attempted with a **carried** camera and no pose has been supplied, it fails with `MISSING_ROBOT_POSE` instead of falling back to a guess. A camera of the same robot that is not carried is unaffected and captures normally.

### The Recorded Capture Pose {#recorded-capture-pose}

A capture from a carried camera can only be interpreted together with the pose the robot was at, so LumiScan VGR saves that pose with the capture and reads it back when the recording is replayed.

Whenever a capture is exported (`exportPcl` or `exportCenterView`) and the active camera is one the robot carries, a file named after the capture is written next to it:

```
data/<cameraId>/2026-09-22_14-03-51_123.png
data/<cameraId>/2026-09-22_14-03-51_123.ply
data/<cameraId>/2026-09-22_14-03-51_123.pose.json
```

It holds the move-frame pose in robot base coordinates twice:

- `moveToBase`: the 4x4 transform in metres. A replay uses this one, so a recording stays readable even if the project’s `poseFormat` is changed afterwards.
- `robotFormat`: the same pose in the robot’s own format, i.e. the numbers shown on the robot pendant. It is not read back as the pose; it is compared with `moveToBase` when the file is loaded, so a changed `poseFormat` shows up as a warning instead of silently changing what every recorded number means.

Replaying the folder with `--simulate-camera` picks the pose up automatically, so an eye-in-hand recording is reproduced without entering the pose again by hand. This applies only to a simulated camera; a real camera always takes its pose from the PLC, OPC UA or the user interface as described above.

> [!NOTE]
> LumiScan VGR cannot currently ask a simulated camera which frame it has just replayed. A dataset recorded from one robot position therefore replays exactly; a dataset recorded from several positions logs a warning naming the pose it used, and only the frames taken at that pose are correct. Split such a recording into one dataset per robot position.

A pose file that is missing, unreadable or does not contain a valid rigid transform is reported and ignored, and the capture then fails with `MISSING_ROBOT_POSE`, the same refusal as if no pose had been supplied.

### What `moveFrame` Has To Name {#move-frame}

`moveFrame` is the name of a **link in the URDF file**. The choice is not cosmetic: it is the one setting that three things depend on, and nothing else in LumiScan VGR uses it (inverse kinematics, trajectory planning, collision checking, waypoints and the 3D view are all independent of it):

1. **What LumiScan VGR reports.** `OUT_PoseMoveInRobot` (PROFINET), `GripPointPose` (OPC UA) and the trajectory are the pose of this link in `baseFrame`, i.e. the pose the robot is commanded to reach. Pointing `moveFrame` at a different link shifts every commanded pose by the transform between the two links, with no error anywhere.
2. **What the robot reports.** With `cameraMountType` `MOVING`, the pose written to `IN_PoseMoveInRobot` (or passed to `SetCapturePose`) must be the pose of this same link.
3. **What the camera was calibrated against.** `cameraToMove` is measured from the camera to this same link.

`moveFrame` is optional. From v2.0.0, an absent `moveFrame` means the TCP: the end effector of the URDF (its one leaf link), which inverse kinematics places on each grip pose. Name the flange instead when the robot controller is commanded in flange coordinates (no tool configured on the controller). Before v2.0.0 an absent `moveFrame` fell back to `baseFrame`, and a separate `tcpFrame` named the TCP.

With `cameraMountType` `MOVING`, `moveFrame` must differ from `baseFrame`; the settings file is refused at load otherwise, because a camera cannot be mounted on a flange that **is** the robot base.

> [!NOTE]
> A URDF may attach the move frame through a `floating` joint, and the standard LumiScan VGR robot model does exactly that: `robot_base --(floating)-→ flansch --(fixed)-→ tcp`. Inverse kinematics then places a free-floating flange instead of modelling a real arm. This does not affect an eye-in-hand camera: the floating joint is **above** the move frame while the camera is rigidly below it, and the camera-to-base transform is computed from the supplied pose and `cameraToMove` alone, without the URDF.