• Stars
    star
    132
  • Rank 274,205 (Top 6 %)
  • Language
    C++
  • License
    MIT License
  • Created over 5 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A library for integrating depth images into Truncated Signed Distance Fields.

Yak

GitHub Actions status GitHub issues open license - MIT support level: consortium / vendor

Yak is a library for integrating depth images into Truncated Signed Distance Fields (TSDFs). It is currently supported for Ubuntu 16.04 and Ubuntu 18.04. An example ROS node using Yak is provided in the yak_ros repository.

A ROS interface is provided at yak_ros, and a ROS2 interface is provided at yak_ros2;

Attribution

This library was originally a fork of personalrobotics/kinfu_ros, and the underlying TSDF algorithm is very similar to the implementation used there.

Technical Background

A TSDF is a probabilistic representation of a solid surface in 3D space. It is a useful tool for combining many noisy incomplete sensor readings into a single smooth and complete model.

To break down the name:

  • Distance Field: Each voxel in the volume contains a value that represents its metric distance from the closest point on the surface. Voxels very far from the surface have high-magnitude distance values, while those near the surface have values approaching zero.

  • Signed: Voxels outside the surface have positive distances, while voxels inside the surface have negative distances. This allows the representation of solid objects. The distance field represents a gradient that shifts from positive to negative as it crosses the surface.

  • Truncated: Voxels further than a specified distance from the isosurface have their values capped at +/- 1 because we are only interested in precisely representing the region of the volume close to solid objects.

The TSDF algorithm can be efficiently parallelized on a general-purpose graphics processor, which allows data from RGB-D cameras to be integrated into the volume in real time. Numerous observations of an object from different perspectives average out noise and errors due to specular highlights and interreflections, producing a smooth continuous surface. This is a key advantage over equivalent point-cloud-centric strategies, which require additional processing to distinguish between engineered features and erroneous artifacts in the scan data. The volume can be converted to a triangular mesh using the Marching Cubes algorithm for consumption by application-specific processes.

Example Output

The picture below shows a mode of an aluminum part that was reconstructed using the TSDF algorithm and meshed using the Marching Cubes algorithm.

An aluminum part reconstructed as a TSDF and meshed with the Marching Cubes algorithm.

Dependencies

CMake

Yak requires CMake 3.10.0 or newer in order to take advantage of improved support for CUDA. If you're using Ubuntu 18.04 or newer you should already have a suitable version. If you're using an older distribution (e.g. 16.04) you will need to install a compatible version of CMake yourself.

  1. Install pip (if it isn't already installed):
sudo apt install python-pip
  1. Use pip to install a newer version of CMake locally, which will not overwrite the system installation of CMake.
pip install --user cmake --upgrade
  1. (Optional, depending on the specifics of your environment) Prepend the directory where CMake was just installed to the PATH environment variable. You may also add this to .bashrc.
export PATH=:/home/YOUR_USERNAME/.local/bin:$PATH

CUDA

Yak requires an NVidia GPU and CUDA 9.0 or newer.

  1. CUDA depends on Nvidia third-party drivers and will not work with the default Nouveau drivers. Determine which version of the Nvidia driver is compatible with your computer's GPU by running ubuntu-drivers devices. Usually the driver version listed as "third-party free recommended" is suitable. You can install the recommended driver using sudo ubuntu-drivers autoinstall. Example output listed below:
== /sys/devices/pci0000:00/0000:00:02.0/0000:02:00.0 ==
modalias : pci:v000010DEd000017C8sv00001458sd000036CBbc03sc00i00
vendor   : NVIDIA Corporation
model    : GM200 [GeForce GTX 980 Ti]
driver   : nvidia-driver-418 - third-party free recommended
driver   : nvidia-driver-410 - third-party free
driver   : nvidia-driver-390 - distro non-free
driver   : xserver-xorg-video-nouveau - distro free builtin
  1. Consult the chart below (copied from here as of Februray 13 2021) to find which CUDA version is compatible with the drivers supported by your GPU. Yak is currently not compatible with CUDA <= 8.0.
CUDA Toolkit Linux x86_64 Driver Version
CUDA 11.2 >= 450.80.02
CUDA 11.1 (11.1.0) >= 450.80.02
CUDA 11.0 (11.0.3) >= 450.36.06
CUDA 10.2 (10.2.89) >= 440.33
CUDA 10.1 (10.1.105) >= 418.39
CUDA 10.0 (10.0.130) >= 410.48
CUDA 9.2 (9.2.88) >= 396.26
CUDA 9.1 (9.1.85) >= 390.46
CUDA 9.0 (9.0.76) >= 384.81
CUDA 8.0 (8.0.61 GA2) >= 375.26
CUDA 8.0 (8.0.44) >= 367.48
CUDA 7.5 (7.5.16) >= 352.31
CUDA 7.0 (7.0.28) >= 346.46
  1. Specific installation instructions vary depending on the combination of Ubuntu version, CUDA version, and Nvidia driver version. Please read the linked instructions carefully: they are very important, and CUDA may not work correctly if you skip a step!
  1. Follow the instructions in Post-installation Actions. It is not necessary to complete the steps listed under "POWER9 Setup" -- you probably do not have a POWER9-compatible system unless you work with supercomputers.

OpenMP

Yak requires OpenMP for parallelization of the marching cubes surface reconstruction process.

sudo apt install libomp-dev

OpenCV

Yak requires OpenCV 3.0 or newer. If you are using ROS then this dependency is already satisfied. Otherwise you will need to install it yourself:

sudo apt install libopencv-dev

Eigen

Yak requires Eigen 3. If you are using ROS then this dependency is already satisfied. Otherwise you will need to install it yourself:

sudo apt install libeigen3-dev

PCL

Yak requires PCL 1.8 or newer. If you are using ROS then this dependency is already satisfied. Otherwise you will need to install it yourself:

sudo apt install libpcl-dev

ros_industrial_cmake_boilerplate

Yak depends on the ros_industrial_cmake_boilerplate package to facilitate package setup and installation.

Installation

Build with ROS (recommended)

Installing ROS is beyond the scope of this readme. There are installation instructions here for ROS1 and here for ROS2.

Clone this package into the src directory of a ROS workspace. For ROS1 use catkin build to build the workspace. For ROS2 use colcon build to build the workspace.

Take a look at the yak_ros package for example implementations of ROS nodes using Yak.

Build Standalone (in development)

git clone https://github.com/ros-industrial/yak.git
cd yak
mkdir build
cd build
cmake ../yak
make
sudo make install

Examples

yak_ros and yak_ros2 provide instructions for building and running ROS demo applications.

More Repositories

1

universal_robot

ROS-Industrial Universal Robots support (https://wiki.ros.org/universal_robot)
C++
1,082
star
2

industrial_training

ROS-Industrial Training Material
C++
422
star
3

ros_qtc_plugin

ROS Qt Creator Plug-in (https://ros-qtc-plugin.readthedocs.io)
C++
397
star
4

ros_canopen

CANopen driver framework for ROS (http://wiki.ros.org/ros_canopen)
C++
339
star
5

ur_modern_driver

(deprecated) ROS 1 driver for CB1 and CB2 controllers with UR5 or UR10 robots from Universal Robots
C++
302
star
6

kuka_experimental

Experimental packages for KUKA manipulators within ROS-Industrial (http://wiki.ros.org/kuka_experimental)
C++
268
star
7

industrial_ci

Easy continuous integration repository for ROS repositories
Shell
246
star
8

robotiq

Robotiq packages (http://wiki.ros.org/robotiq)
C++
227
star
9

ros2_i_training

HTML
169
star
10

industrial_core

ROS-Industrial core communication packages (http://wiki.ros.org/industrial_core)
C++
154
star
11

fanuc

ROS-Industrial Fanuc support (http://wiki.ros.org/fanuc)
C++
153
star
12

motoman

ROS-Industrial Motoman support (http://wiki.ros.org/motoman)
C++
146
star
13

abb

ROS-Industrial ABB support (http://wiki.ros.org/abb)
C++
145
star
14

ros2_canopen

CANopen driver framework for ROS2
C++
143
star
15

abb_experimental

Experimental packages for ABB manipulators within ROS-Industrial (http://wiki.ros.org/abb_experimental)
CMake
131
star
16

noether

Tool path planning and surface segmenter
C++
121
star
17

industrial_calibration

Contains libraries/algorithms for calibrating industrial systems
C++
120
star
18

abb_robot_driver

The new ROS driver for ABB robots
C++
100
star
19

reach

A tool that allows users to visualize and quantitatively evaluate the reach capability of a robot system for a given workpiece.
C++
94
star
20

industrial_moveit

ROS-Industrial movit meta-package (http://wiki.ros.org/industrial_moveit)
C++
93
star
21

abb_libegm

A C++ library for interfacing with ABB robot controllers supporting Externally Guided Motion (689-1)
C++
93
star
22

abb_librws

A C++ library for interfacing with ABB robot controllers supporting Robot Web Services
C++
69
star
23

robodk_postprocessors

Open-source vendor-specific post-processors/code generators from RoboDK (http://robodk.com)
Python
64
star
24

easy_perception_deployment

A ROS2 package that accelerates the training and deployment of CV models for industries.
Python
54
star
25

industrial_reconstruction

Tools for surface reconstruction from 2D depth images
Python
50
star
26

easy_manipulation_deployment

A ROS2 package that allows rapid digitization of robotic work cells and ease of efficient path-planning of manipulators.
C++
49
star
27

yak_ros

Example ROS frontend node for the Yak TSDF package
C++
48
star
28

cros

A single thread pure C implementation of the ROS framework
C
47
star
29

fanuc_experimental

Experimental packages for Fanuc manipulators within ROS-Industrial (http://wiki.ros.org/fanuc_experimental)
CMake
45
star
30

stomp_ros

ROS packages for the STOMP planner (split out of industrial_moveit)
C++
37
star
31

robot_movement_interface

Drivers implementing the Robot Movement Interface, which allows access to robot specific capabilities in a standardized common format while maintaining compatibility with the ROS-Industrial Joint interface.
C++
36
star
32

human_tracker

Library for detecting and tracking humans using 3D sensing systems (stereo and kinect-like)
36
star
33

flexgui_industrial

Moved to: https://github.com/PPM-Robotics-AS/flexgui4.0
JavaScript
31
star
34

kuka

ROS-Industrial KUKA support (http://wiki.ros.org/kuka)
CMake
30
star
35

abb_driver

(old) ROS driver for ABB IRC5 / RW5 or RW6 controllers (Simple Message & RAPID)
AMPL
29
star
36

staubli_experimental

Experimental packages for Staubli manipulators within ROS-Industrial (http://wiki.ros.org/staubli_experimental)
CMake
27
star
37

staubli_val3_driver

ROS-Industrial (simple message) driver for StΓ€ubli CS8 and CS9 robot controllers (VAL 3 application)
TeX
26
star
38

docker

ROS-Industrial docker and cloud tools
Dockerfile
23
star
39

stomp

Stochastic Trajectory Optimization for Motion Planning (STOMP)
C++
22
star
40

reach_ros2

ROS2 packages for REACH
C++
17
star
41

staubli

ROS-Industrial Staubli support (http://wiki.ros.org/staubli)
C++
17
star
42

ros_industrial_cmake_boilerplate

CMake
16
star
43

packml_ros2

State machine based system programming, monitoring and control in ROS 2
C++
16
star
44

motoman_experimental

Experimental packages for Motoman manipulators within ROS-Industrial
C++
15
star
45

abb_robot_driver_interfaces

ROS message and service definitions for a ROS driver for ABB robots
CMake
13
star
46

rep

ROS-Industrial REPs
12
star
47

crcl

11
star
48

workcell_explorer

Repository for GSoC 2018 focusing on creation of a ROS package for Robotic Workcell exploration
CMake
11
star
49

ur_msgs

ROS messages and services for Universal Robots robot controllers.
CMake
11
star
50

industrial_calibration_tutorials

Tutorials for industrial calibration package.
CMake
11
star
51

keyence_experimental

C++
10
star
52

siemens_tutorials

C++
10
star
53

ros_industrial_meetings

Repository for tracking ROS-Industrial developers meeting minutes
9
star
54

packet-simplemessage

Wireshark Lua dissector for the ROS-Industrial SimpleMessage protocol
Lua
8
star
55

reach_ros

ROS1 Packages for REACH
C++
8
star
56

siemens_experimental

C++
8
star
57

intelligent_actuator

ROS package for serial communication with the Robo Cylinder
Python
8
star
58

swri-ros-pkg

Automatically exported from code.google.com/p/swri-ros-pkg
C++
7
star
59

abb_egm_rws_managers

A C++ library for encapsulating ROS agnostic components for a ROS driver for ABB robots
C++
6
star
60

ros2_quality_assurance_guidelines

A collection of documentation which contains detailed instructions and tutorials for improving ROS 2 package quality, following REP-2004 quality level and integrating CI into one's development workflow.
Python
6
star
61

industrial_pcl_experimental

ROS Industrial addons, utilities, and other libraries that extend or are useful with the Point Cloud Library (PCL)
C++
5
star
62

jenkins_config

Contains jenkins CI configuration scripts.
Python
4
star
63

socketcan_interface

DO NOT USE YET
C++
4
star
64

industrial_experimental

Contains experimental packages for industrial_core.
C++
3
star
65

yak_ros2

Example ROS 2 frontend node for the Yak TSDF package
C++
3
star
66

ros_industrial_issues

Repository for tracking common ROS-Industrial issuses.
3
star
67

tolomatic

C++
2
star
68

industrial_pcl

ROS-Industrial PCL Extension meta-package. http://wiki.ros.org/industrial_pcl
C++
2
star
69

rvip

A ROS package for easy integration of a hybrid 2D-3D robotic vision technique for industrial tasks.
1
star
70

robotiq_experimental

Experimental robotiq packages within ROS-Industrial
C++
1
star
71

siemens_drivers

Open source drivers for Siemens devices
1
star
72

fake_ar_publisher

C++
1
star
73

ros_profinet_experimental

1
star
74

acuity

Support for acuity laser products
Python
1
star
75

error_resolution_diagnoser

C++
1
star
76

fanuc_demos

Demos of ROS(-Industrial) functionality specifically for (simulated) Fanuc robots
1
star
77

industrial_calibration_ros2

ROS Utilities for Industrial Calibration
Python
1
star
78

epd_onnxruntime_vendor

CMake
1
star
79

error_classification_server

Python
1
star