Skip to content
Permalink
Browse files

(Tracked On: DSO-6823)

Updated main readme and contributing and corrected license file.
Updated record-playback readme (added screenshots as welll).
CR changes added.
Renamed rs-headless to rs-save-to-disk
  • Loading branch information...
Shahaf, Ziv
Shahaf, Ziv committed Aug 23, 2017
1 parent b9a529b commit b491fba563bd822cd1d3a5f25a99570447e12d3a
@@ -593,7 +593,7 @@ option(ENFORCE_METADATA "Require WinSDK with Metadata support during compilation
option(BUILD_PYTHON_BINDINGS "Build Python bindings" OFF)

# This parameter is meant for disabling graphical examples when building for
# headless targets.
# save-to-disk targets.
option(BUILD_GRAPHICAL_EXAMPLES "Build graphical examples and tools." ON)

if((BUILD_EXAMPLES AND BUILD_GRAPHICAL_EXAMPLES) AND WIN32)
@@ -1,3 +1,10 @@
# How to Contribute

This project welcomes third-party code via GitHub pull requests. Please review the CLA agreement located in the root of the repository. For each pull request submitted, please state your legal name and the text, "I agree to the terms of the Intel® RealSense™ Cross Platform API CLA."
This project welcomes third-party code via GitHub pull requests.

Please review the [Individual Contributor License Agreement (CLA)](CLA.md).

Please use the following template when submitting a new pull request:

> \<legal name here\>,
> I agree to the terms of the Intel® RealSense™ Cross Platform API CLA.
@@ -187,10 +187,10 @@
same "printed page" as the copyright notice for easier
identification within third-party archives.

Copyright [yyyy] [name of copyright owner]
Copyright 2017 Intel Corporation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
you may not use this project except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0
@@ -74,8 +74,8 @@ Calling __*rs2_get_frame_metadata*__ without testing for attribute support may r


## Employing metadata attributes in demos
The samples that demonstrate querying and retrieval of metadata are `rs-headless` and `rs-config-ui`.
- `rs-headless` saves the metadata attributes available for each stream into a comma-separated text file. For instance, for the Depth stream the possible [output ](./metadata/cpp-headless-output-DEPTH-metadata.csv) is:
The samples that demonstrate querying and retrieval of metadata are `rs-save-to-disk` and `rs-config-ui`.
- `rs-save-to-disk` saves the metadata attributes available for each stream into a comma-separated text file. For instance, for the Depth stream the possible [output ](metadata/rs-save-to-disk-output-DEPTH-metadata.csv) is:

Stream |Depth
:-----:|------:|
Binary file not shown.
Binary file not shown.
@@ -59,6 +59,6 @@ endif()


add_subdirectory(capture)
add_subdirectory(headless)
add_subdirectory(save-to-disk)
add_subdirectory(multicam)
add_subdirectory(pointcloud)
@@ -9,7 +9,7 @@ For a detailed explanations and API documentation see our [Documentation](../doc
## List of Samples:

1. [Capture](./capture) - Shows how to syncronize and render multiple streams.
2. [Headless](./headless) - Demonstrates how to render and save video streams on headless systems without graphical interface.
2. [Save To Disk](./save-to-disk) - Demonstrates how to render and save video streams on headless systems without graphical interface.
3. [Multicam](./multicam) - Demonstrates how to work with more then one RealSense device simulteniously.
4. [Pointcloud](./pointcloud) - Showcases Projection API while generating and rendering 3D pointcloud.
5. Background Segmentation - Shows a simple method for dynamic background removal from video.
@@ -1,7 +1,7 @@
# ubuntu 16.04 LTS cmake version 3.5.1
cmake_minimum_required(VERSION 2.8.3)

project(RealsenseExamplesHeadless)
project(RealsenseExamplesSaveToDisk)

# Save the command line compile commands in the build output
set(CMAKE_EXPORT_COMPILE_COMMANDS 1)
@@ -16,18 +16,18 @@ elseif(COMPILER_SUPPORTS_CXX0X)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++0x")
endif()

# headless
add_executable(rs-headless rs-headless.cpp)
target_link_libraries(rs-headless ${DEPENDENCIES})
include_directories(rs-headless ../../common ../../third-party ../../third-party/tclap/include)
set_target_properties (rs-headless PROPERTIES
# save-to-disk
add_executable(rs-save-to-disk rs-save-to-disk.cpp)
target_link_libraries(rs-save-to-disk ${DEPENDENCIES})
include_directories(rs-save-to-disk ../../common ../../third-party ../../third-party/tclap/include)
set_target_properties (rs-save-to-disk PROPERTIES
FOLDER "Examples"
)

install(
TARGETS

rs-headless
rs-save-to-disk

RUNTIME DESTINATION
${CMAKE_INSTALL_PREFIX}/bin
File renamed without changes.
@@ -1,4 +1,4 @@
# rs-headless Sample
# rs-save-to-disk Sample

## Overview

@@ -44,14 +44,14 @@ pipe.start();

// Write images to disk
std::stringstream png_file;
png_file << "rs-headless-output-" << vf.get_profile().stream_name() << ".png";
png_file << "rs-save-to-disk-output-" << vf.get_profile().stream_name() << ".png";
stbi_write_png(png_file.str().c_str(), vf.get_width(), vf.get_height(),
vf.get_bytes_per_pixel(), vf.get_data(), vf.get_stride_in_bytes());
std::cout << "Saved " << png_file.str() << std::endl;

// Record per-frame metadata for UVC streams
std::stringstream csv_file;
csv_file << "rs-headless-output-" << vf.get_profile().stream_name()
csv_file << "rs-save-to-disk-output-" << vf.get_profile().stream_name()
<< "-metadata.csv";
metadata_to_csv(vf, csv_file.str());
}
@@ -7,13 +7,16 @@ Linux | Windows |
[![Build Status](https://travis-ci.org/IntelRealSense/librealsense.svg?branch=development)](https://travis-ci.org/IntelRealSense/librealsense) | [![Build status](https://ci.appveyor.com/api/projects/status/6u04bgmpwfejpgo8?svg=true)](https://ci.appveyor.com/project/dorodnic/librealsense-s4xnv) |

## Overview
**Intel® RealSense™ SDK 2.0** is a cross-platform library (Linux, Windows, Mac) for working with Intel® RealSense™ depth cameras (SR300 and the D400 series).
It allows streaming of depth, color and fisheye video, and provides intrinsic and extrinsic calibration information. The library also offers synthetic streams (pointcloud, depth aligned to color and vise-versa) and support for motion tracking. In addition, the SDK has a built-in support for [record and playback](./src/media/readme.md).
**Intel® RealSense™ SDK 2.0** is a cross-platform library (Linux, Windows, Mac) for working with Intel® RealSense™ depth cameras (SR300 and the RS400 series).

The library aims to provide an easy to use API and tools for computer vision professionals, game developers and other Intel RealSense technology enthusiasts.
> For Intel® RealSense™ legacy cameras, please refer to the [latest legacy release](https://github.com/IntelRealSense/librealsense/tree/v1.12.1).
The SDK allows depth, color and fisheye streaming, and provides intrinsic and extrinsic calibration information.
The library also offers synthetic streams (pointcloud, depth aligned to color and vise-versa), motion tracking, and a built-in support for [record and playback](./src/media/readme.md) of streaming sessions.

The library aims to provide an easy to use API and tools for computer vision professionals, robotics programmers, game developers, and other Intel RealSense technology enthusiasts.

We provide a C, C++, and [Python](./wrappers/python) API.
Developer kits containing the necessary hardware to use this library are available for purchase at [click.intel.com](http://click.intel.com/realsense.html).

## Quick Start

@@ -59,7 +62,8 @@ while (true)
```
For more information on the library, please follow our [examples](./examples), and read the [documentation](./doc) to learn more.

## Contributing
In order to contribute to Intel RealSense SDK, please follow our [contribution guidelines](CONTRIBUTING.md).

## License

This project is licensed under the Apache License, Version 2.0 - see the [LICENSE](LICENSE) file for details
This project is licensed under the [Apache License, Version 2.0](LICENSE).
@@ -8,13 +8,14 @@ In addition to streaming video and other data from devices and sensors, the real
The SDK is recording a single device to a single [rosbag file](http://wiki.ros.org/rosbag), using mostly standard ROS messages. This allows files recorded by the SDK to be replayed using any ROS tools \ application.


----------
Quick Start
-------------

#### Code Example: `rs2::recorder`
#### `rs2::recorder`

> :exclamation: If you are not familiar with the basic streaming examples, please follow them before moving on
> :exclamation: If you are not familiar with the basic streaming [examples](../../examples), please follow them before moving on
To enable recording on any device, simply create a **rs2::recorder** from it and provide a path to the desired output file:
To enable recording of any device, simply create a **rs2::recorder** from it and provide a path to the desired output file:
```cpp
//Create a context and get the first device
rs2::context ctx;
@@ -27,12 +28,12 @@ if (devices.size() > 0)
//recorder "is a" device, so just use it like any other device now
}
```
A **recorder** has the same functionality as a "real" device, with additional control for recording, such as pausing and resuming record.
A `recorder` has the same functionality as a "real" device, with additional control for recording, such as pausing and resuming record.

----------
#### Example: `rs2::playback`

> :exclamation: If you are not familiar with the basic streaming examples, please follow them before moving on
#### `rs2::playback`

> :exclamation: If you are not familiar with the basic streaming [examples](../../examples), please follow them before moving on
Recorded files can be loaded and used to create a playback device by simply loading a file to the context:
```cpp
@@ -42,14 +43,37 @@ rs2::context ctx;
rs2::playback device = ctx.load_device("my_file_name.bag");
//playback "is a" device, so just use it like any other device now
```
The above code creates a playback device, which can be used is any device, but has the obvious limitation of only playing the recorded streams. Playback devices can be used to query information on the device and it sensors, and can be extended to which ever extension the "real" device could.
A **playback** provides additional functionalities such as Seek, Pause, Resume and RealTime playing.
The above code creates a playback device, which can be used as any device, but has the obvious limitation of only playing the recorded streams.
Playback devices can be used to query information on the device and it sensors, and can be extended to which ever extension the "real" device could.
A `playback` provides additional functionalities such as seek, pause, resume and playback speed.


------

Playback and Record in RealSense Viewer
-------------

Among its many features, the [RealSense Viewer](../../tools/realsense-viewer) allows recording a device, and loading a file to playback.

To record a streaming session, simply click the "bars" icon next to the device name, choose "Record to File...", and select the destination for the file.

![Recording a device](../../doc/img/record_screenshot.png)

### Basics Terminology
After choosing a file destination, a red dot will appear next to the device's name, indicating that it is recording.
Starting a stream will save its frames to the file, and once all streams are stopped, recording will complete automatically.

To replay a file, click "Add Source", choose "Load Recorded Sequence" and select the file you want to play.
Once you select the file, the Viewer will automatically add it the the list of source, and a popup should appear stating that the file was loaded:

![Loading Recorded Sequence](../../doc/img/playback_screenshot.png)
>Notice that devices that were loaded from file have a "movie" icon next to their name.
After loading the file, you can start streaming its streams, view its controls (with the values at time of record), pause the playback, choose speed, and use the seek bar to navigate trough frames.


Under the Hood
------

#### Basics Terminology

A **Device** is a container of Sensors with some correlation between them (e.g - all sensors are on a single board, sensors are mounted on a robot and share calibration information, etc.). A **Sensor** is a data streaming object, that provides one or more Streams.
**Stream** is a sequence of data items of a single data type, which are ordered according to their time of creation or arrival. The Sensor provides the Streams frames to the user.
@@ -60,9 +84,9 @@ Devices and Sensors can have **Extensions** that provide additional functionalit

Finally, we will refer to a an actual implementation of devices and sensors as "live" or "real" devices and sensors.

### Rosbag
#### Rosbag

#### Overview on ROSBAG file structure
##### Overview on ROSBAG file structure

The Rosbag file consists of data records, each data that is written to the file is represented by a topic that represents the data content, message that is the data definition, and capture time.
Any topic can be coupled with any message, in our file each topic will be represented by a single message. However, we will have different topics with the same message such as property.
@@ -82,7 +106,7 @@ The flow to find a message on topic “A”:
- Access the chunk with the wanted connection, chunk info contains an offset to the paired chunk.
- Access the message from the relevant index data.

#### Dependencies
##### Dependencies
The SDK depends on ROS packages that are used for recording and playing the bag file.
The dependencies are:
- rosbag_storage
@@ -94,7 +118,7 @@ The dependencies are:

> **Note:** The above dependencies are embedded into the source files, there is no need for additional installations.
#### Topics
##### Topics

The rosbag file requires messages to be associates with Topics
> Topics are [named](http://wiki.ros.org/Names) buses over which [nodes](http://wiki.ros.org/Nodes) exchange [messages](http://wiki.ros.org/Messages). [[ROS Wiki\Topics]](http://wiki.ros.org/Topics)
@@ -177,7 +201,7 @@ The following table depicts the Topics that are supported by RealSense file form
<tr>
<td>6DOF Data</td>
<td>/device_&lt;device_id&gt;/sensor_&lt;sensor_id&gt;/&lt;stream_type&gt;_&lt;stream_id&gt;/6dof/data</td>
<td>realsense_msgs::6DoF</td>
<td>realsense_msgs::6DoF (TBD)</td>
<td>Six DOF data</td>
</tr>
<tr>
@@ -212,9 +236,9 @@ The following table depicts the Topics that are supported by RealSense file form
</tr>
<tr>
<td>Stream Exntrinsics</td>
<td>/device_&lt;device_id&gt;/sensor_&lt;sensor_id&gt;/&lt;stream_type&gt;_&lt;stream_id&gt;/tf</td>
<td>/device_&lt;device_id&gt;/sensor_&lt;sensor_id&gt;/&lt;stream_type&gt;_&lt;stream_id&gt;/tf/&lt;group_index&gt;</td>
<td><a href="http://docs.ros.org/jade/api/geometry_msgs/html/msg/Transform.html">geometry_msgs/Transform Message</a></td>
<td>Extrinsic transformation between a specific stream to another</td>
<td>Extrinsic transformation between some point of reference (indexed by group_index) to the stream in the topic</td>
</tr>
<tr>
<td>Additional Info</td>
@@ -224,22 +248,23 @@ The following table depicts the Topics that are supported by RealSense file form
</tr>
</table>
#### Messages
##### Messages
ROS uses a simplified messages description language for describing the data values (aka messages) that ROS nodes publish. This description makes it easy for ROS tools to automatically generate source code for the message type in several target languages. Message descriptions are stored in .msg files.
There are two parts to a .msg file: fields and constants. Fields are the data that is sent inside of the message. Constants define useful values that can be used to interpret those fields (e.g. enum-like constants for an integer value).
--------------
### RealSense Proprietary Messages
#### RealSense Proprietary Messages
In addition to the standard ROS messsages, the SDK writes additional proprietary messages (available in the 3rd party folder) for new data types that are recorded.
In addition to the standard ROS messsages, the SDK writes additional proprietary messages (available in the [3rd party folder](../../third-party/realsense-file/rosbag/msgs/realsense_msgs)) for new data types that are recorded.
The following are the new messages created by the SDK:
- [realsense_msgs::StreamInfo](#stream-info)
- [realsense_msgs::ImuIntrinsic](#motion-intrinsic)
--------------
#### **Stream Info**
##### **Stream Info**
<table>
<tr>
@@ -265,13 +290,13 @@ The following are the new messages created by the SDK:
</tr>
</table>
##### Supported Encoding
###### Supported Encoding
For video streams, the supported encoding types can be found at <a href="http://docs.ros.org/jade/api/sensor_msgs/html/namespacesensor__msgs_1_1image__encodings.html">ros documentation</a><br>
--------------
#### Motion Intrinsic
##### Motion Intrinsic
<table>
<tbody>
@@ -11,7 +11,7 @@ set(CMAKE_EXPORT_COMPILE_COMMANDS 1)
#set(CMAKE_VERBOSE_MAKEFILE on)

# This parameter is meant for disabling graphical examples when building for
# headless targets.
# save-to-disk targets.
option(BUILD_GRAPHICAL_EXAMPLES "Build graphical examples." ON)

include(CheckCXXCompilerFlag)

0 comments on commit b491fba

Please sign in to comment.
You can’t perform that action at this time.