PDS field test docs

.gitlab-ci.yml

@@ -16,6 +16,7 @@ image: ubuntu:22.04
 
 stages:          # List of stages for jobs, and their order of execution
   - build
+  - deploy
 
 vale-linting:
   image:
@@ -35,3 +36,36 @@ vale-linting:
     - vale --minAlertLevel error /builds/syntron/support/csr/o3r/documentation/.
 
 
+internal-pages:
+  image: python:3.8-slim
+  stage: build
+  script:
+    - pip install sphinx myst-parser
+    - mkdir site && cd site
+    - sphinx-quickstart 
+        -p PDS 
+        -a ifm-CSR 
+        -r [] 
+        -l en 
+        --extensions 'myst_parser' 
+        --sep 
+    - echo "master_doc = 'index_pds'" >> source/conf.py
+    - echo "myst_enable_extensions = ['colon_fence',]" >> source/conf.py
+    - cp -r ../PDS/* source/.
+    - sphinx-build source build
+  after_script: 
+    - pwd
+    - ls site
+    - cp -r site/build public
+  artifacts:
+    paths:
+      - public
+
+
+pages:
+  stage: deploy
+  script:
+    - ls public
+  artifacts:
+    paths:
+      - public

CalibrationRoutines/IntroToCalibrations/calibration_cheat_sheet.md

@@ -0,0 +1,51 @@
+
+# Calibration values cheat sheet
+Below are provided the rotation values for cameras mounted vertically and horizontally, to be used as reference when calibrating the camera for testing.
+
+## Camera mounted horizontally - Label on top
+```json
+{
+"rotX": 0,
+"rotY": 1.57,
+"rotZ": -1.57,
+"transX": 0,
+"transY": 0,
+"transZ": 0
+}
+```
+
+## Camera mounted horizontally - Label at the bottom
+```json
+{
+"rotX": 0,
+"rotY": 1.57,
+"rotZ": 1.57,
+"transX": 0,
+"transY": 0,
+"transZ": 0
+}
+```
+
+## Camera mounted vertically - Cables on top
+```json
+{
+"rotX": 0,
+"rotY": 1.57,
+"rotZ": 0,
+"transX": 0,
+"transY": 0,
+"transZ": 0
+}
+```
+
+## Camera mounted vertically - Cables at the bottom
+```json
+{
+"rotX": 0,
+"rotY": 1.57,
+"rotZ": -3.142,
+"transX": 0,
+"transY": 0,
+"transZ": 0
+}
+```

PDS/Calibration/pds_calibration.md

@@ -0,0 +1,110 @@
+---
+nosearch: true
+---
+
+# Camera calibration for PDS
+
+The PDS application always returns the position of an object with respect to the calibrated coordinate system. Typically, the calibrated coordinate system corresponds to the fork tines, so that the coordinate system will go up and down with the forks and the pallet position will always be provided with reference to the current position of the forks.
+
+## Concepts
+### PDS coordinate system
+PDS expects the orientation of the coordinate system to be as follows:
+- X is pointing in direction of the forks,
+- Y is pointing to the left of the forks,
+- Z is pointing up.
+
+When uncalibrated, the camera coordinate system is such that Z is pointing away from the camera, and X is pointing away from the cables. This is represented in the image below:
+
+![Uncalibrated camera coordinate system](resources/default_camera_coord_sys.png)
+
+The uncalibrated coordinate system does not correspond to what PDS expects. Consequently, if no calibration is set, PDS will raise an error.
+
+To fit the expected coordinate system of PDS, the coordinate system has to be rotated. An example of a correctly calibrated coordinate system would be as shown in the image below, where the origin of the coordinate system is placed at the center of the base of the forks:
+
+![Coordinate system calibrated to the center of the base of the forks](resources/forks_base_center_coord_sys.png)
+
+Note that the user can decide where to place the origin of the coordinate system. We show a couple of examples [below](#examples).
+
+PDS will look for a pallet within a defined volume of interest. By default, it expects the camera to be placed at approximately the same level as the bottom plane of the pallet. 
+For more details about the volume of interest for the different PDS commands, refer to their respective documentation.
+
+Note that errors in the camera calibration will lead to errors in the position of the targeted object. If CAD data is known to be precise enough, it can be used to extract calibration values for the camera. Otherwise, any of [the calibration methods](../../CalibrationRoutines/index_calibrations.md) provided by ifm can be used.
+
+### Robot Coordinate System
+PDS' coordinate system will most often be different from the Robot Coordinate System (RCS):
+- The RCS is usually in a fixed position on the robot's chassis, whereas PDS' coordinate systems moves with the forks. The transformation between the RCS and the PDS coordinate system will depend on the position of the forks and has to be implemented by the user.
+- The RCS is typically in the middle of the steering axis, whereas PDS' coordinate system is located around the forks base or tip.
+- In general, the axis of the RCS and the PDS coordinate systems will be parallel. The X axis of the RCS usually points in the direction of travel, and PDS' coordinate system X axis points in the direction of the forks, which would typically be towards the back of the vehicle. The Z axis will point upwards in both coordinate system.
+
+:::{note}
+Note that these comments represent most typical use cases, but your coordinate system might be different. The coordinate system can be adjusted to fit your specific setup.
+:::
+
+## Examples
+
+### Tip of fork coordinate system
+Let's take for example a camera mounted horizontally, looking straight ahead, directly between the two forks. 
+Let's assume the fork tines coordinate system's origin is at the tip of the right fork, like shown in the image below:
+![Coordinate system calibrated to the tip of the right fork](resources/forks_tips_coord_sys.png)
+
+Let's also assume the following measurements:
+
+![Translation values from the camera to the tip of the right fork](resources/translations_to_fork_tip.png)
+
+Then, the values for the rotation and translations are as follows, shown in the Vision Assistant calibration wizard:
+
+![Calibration values for the tip of fork example](resources/calibration_values_fork_tips.png)
+
+This is equivalent to setting the following parameters in the relevant port's JSON configuration:
+```json
+{
+    "ports":{
+        "portX":{
+            "processing":{
+                "extrinsicHeadToUser":{
+                    {
+                        "rotX": 0.00,
+                        "rotY": 1.57,
+                        "rotZ": -1.57,
+                        "transX": 1.00,
+                        "transY": 0.25,
+                        "transZ": 0.05
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+### Base of forks coordinate system
+
+Let's take another example and assume the camera is mounted horizontally pointing forward, directly between the two forks, and the origin of the coordinate system is at the base of forks, right between the two forks, as shown in the image below:
+![Coordinate system calibrated to the center of the base of the forks](resources/forks_base_center_coord_sys_with_cam.png)
+
+Let's assume that the center of the coordinate system is 5 cm below the camera, and on the same (YZ) plane:
+![Measurements between the camera and the coordinate system](resources/translation_to_forks_base_center.png) 
+
+With these measurements, we would have the following calibration values:
+![Calibration values with the coordinate system at the base of the forks](resources/calibration_values_fork_base.png)
+This is equivalent to setting the following parameters in the relevant port's JSON configuration:
+```json
+{
+    "ports":{
+        "portX":{
+            "processing":{
+                "extrinsicHeadToUser":{
+                    {
+                        "rotX": 0.00,
+                        "rotY": 1.57,
+                        "rotZ": -1.57,
+                        "transX": 0.00,
+                        "transY": 0.00,
+                        "transZ": 0.05
+                    }
+                }
+            }
+        }
+    }
+}
+```

PDS/Configuration/configuration.md

@@ -0,0 +1,49 @@
+---
+nosearch: true
+---
+
+# Configuration
+
+The PDS application is instantiated with a set of JSON parameters. 
+A minimal instantiation is as follows, where `"app0"` can be replaced by another app index if required:
+
+```json
+{
+    "applications":{
+        "instances":{
+            "app0":{
+                "class": "pds"
+            }
+        }
+    }
+}
+```
+:::{note}
+The user can refer to the [JSON schema](../../Technology/configuration.md#json-schema) after instantiating the application for more details on the available parameters.
+:::
+
+This is equivalent to creating a PDS app in the Vision Assistant:
+
+![Instantiating a PDS app in the Vision Assistant](resources/instantiate_app.png)
+
+![Instantiated app with default settings](resources/default_app.png)
+
+The app will be instantiated with all parameters set to their default values. 
+The parameters can be further configured and are described below.
+
+
+| Parameter                                      | Description                                                                                                                                                                                                              |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `name`                                         | Providing a custom name for the PDS application                                                                                                                                                                          |
+| `ports`                                        | The port that is used by the PDS application                                                                                                                                                                             |
+| `state`                                        | The current app state (default: `CONF`)                                                                                                                                                                                  |
+| `configuration/customization/command`          | The command to be executed by PDS (`getPallet`, `getRack`, `getItem`, `volCheck` or `nop`). `nop` corresponds to no operation. After a command is executed by the PDS, the command parameter is set back to `nop` value. |  |
+| `configuration/customization/getPallet`        | Configure the `getPallet` command. Refer to [the `getPallet` documentation](../GetPallet/getPallet.md) for further details on the relevant parameters.                                                                   |
+| `configuration/customization/getRack`          | Configure the `getRack` command. Refer to [the `getRack` documentation](../GetRack/getRack.md) for further details on the relevant parameters.                                                                           |
+| `configuration/customization/getItem`          | Configure the `getItem` command. Refer to [the `getItem` documentation](../GetItem/getItem.md) for further details on the relevant parameters.                                                                           |
+| `configuration/customization/volCheck`         | Configure the `volCheck` command. Refer to [the `volCheck` documentation](../VolCheck/volCheck.md) for further details on the relevant parameters.                                                                       |
+| `configuration/port/mode`                      | To designate the measurement range: 2 or 4 meters. This parameter is configurable only in `CONF` state.                                                                                                                  |
+| `configuration/port/acquisition/channelValue`  | Channel value where each channel corresponding to a different modulation frequency. This parameter is configurable only in `CONF` state.                                                                                 |
+| `configuration/port/acquisition/exposureLong`  | Parametrize the long exposure time. This parameter is configurable only in `CONF` state. The default value works for the majority of use cases and we do not recommend changing this value.                              |
+| `configuration/port/acquisition/exposureShort` | Parametrize the short exposure time. This parameter is configurable only in `CONF` state. The default value works for the majority of use cases and we do not recommend changing this value.                             |
+| `configuration/port/acquisition/offset`        | Shifts the starting point of the measured range. This parameter is configurable only in `CONF` state. The default value works for the majority of use cases and we do not recommend changing this value.                    |

PDS/Cpp/CMakeLists.txt

@@ -0,0 +1,47 @@
+cmake_minimum_required(VERSION 3.11)
+
+project(o3r_examples CXX)
+
+#Global compiler flags
+set(CMAKE_BUILD_TYPE Release) # Release or Debug
+set(CMAKE_CXX_EXTENSIONS OFF) # OFF -> -std=c++14, ON -> -std=gnu++14
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED true)
+
+#find ifm3d on the system
+find_package(ifm3d 1.5.3 CONFIG
+  REQUIRED COMPONENTS device framegrabber deserialize
+  )
+
+## Volume check example
+add_executable(vol_check vol_check.cpp)
+target_link_libraries(vol_check
+                      ifm3d::device
+                      ifm3d::framegrabber
+                      )  
+
+## Get pallet example
+add_executable(get_pallet get_pallet.cpp)
+target_link_libraries(get_pallet
+                      ifm3d::device
+                      ifm3d::framegrabber
+                      )  
+
+## Get item example
+add_executable(get_item get_item.cpp)
+target_link_libraries(get_item
+                      ifm3d::device
+                      ifm3d::framegrabber
+                      )   
+## Get rack example
+add_executable(get_rack get_rack.cpp)
+target_link_libraries(get_rack
+                      ifm3d::device
+                      ifm3d::framegrabber
+                      )                                                         
+## Get rack example
+add_executable(get_flags get_flags.cpp)
+target_link_libraries(get_flags
+                    ifm3d::device
+                    ifm3d::framegrabber
+                    )