Skip to content

Commit 166ddd3

Browse files
esdandreuesdandreu
committed
Improved documentation
1 parent 4c40e36 commit 166ddd3

2 files changed

Lines changed: 173 additions & 36 deletions

File tree

‎README.md‎

Lines changed: 99 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,139 @@
11
# python-recorder
22

3-
Visual and Acoustic Odometry recorder using python. Devices: RealSense D435i
4-
camera, RODE VideoMicNTG and smartLav+ microphones
5-
6-
Framework
7-
8-
TODO ros
3+
Device independent framework for synchronized recording. Originally designed to
4+
record audio and video from a Realsense camera and several microphones. This
5+
framework is designed for researchers collecting multimodal datasets. It
6+
provides an easy command line application which allows to configure, test and
7+
use the available sensors in the host machine. The framework can be divided in
8+
two main features:
9+
10+
## Devices
11+
They provide a common interface to initialize, `start` and `stop` a recording,
12+
whether is a camera, a microphone or any other sensor. When the recording is
13+
stopped, device parameters (e.g., `samplerate` in microphones, `framerate` in
14+
cameras) as well as a `start_timestamp` and an `end_timestamp` are saved
15+
together with the recorded data which allows fine synchronization of data from
16+
multiple devices in post-processing.
17+
18+
Devices are configurable through a command line application, which searches for
19+
available options in the host machine. At the same time, they are saved in a
20+
[`yaml` formatted text file](./example-config.yaml). Which allows easy access
21+
to device exclusive configuration parameters.
22+
23+
Multiple devices compose a [`Recorder` object](./recorder/recorder.py), which
24+
is responsible for initializing all its devices, setup an output folder for the
25+
recordings, and start and stop the recording.
26+
27+
Adding new devices classes is simple, one just needs to extend the [`Device`
28+
class](./recorder/device/device.py) and override its abstract methods (`find`,
29+
`_start`, `_stop` and `show_results`).
930

1031
## Listeners
11-
`listen` command does not setup the recorder. The listener is responsible of
12-
setting up the recorder as it sees fit. In the case of the `localhost`
13-
listener, a `GET` request to the `/setup` endpoint is necessary before trying
14-
to start the recording via the `/start` endpoint.
32+
Researchers usually want to synchronize the recording with a specific event, a
33+
test or experiment, which can be triggered by a different machine. A `Listener`
34+
is an interface between a `Recorder` and an external event. At the moment, the
35+
only one available is a [`Localhost`
36+
listener](./recorder/listener/localhost.py). Which triggers the recording
37+
according to `GET` requests through the local network. But additional listeners
38+
can be added by extending the [`Listener`
39+
class](./recorder/listener/listener.py) and overriding its abstract methods. An
40+
example of another listener would be a `ROS` node that subscribes to a specific
41+
topic and triggers the recording according to a specific set of messages.
42+
43+
Listeners can be setup through the `listen`. This command does not initialize
44+
the devices. The listener is responsible of executing `recorder.setup()` as it
45+
sees fit. In the case of the `localhost` listener, a `GET` request to the
46+
`/setup` endpoint is necessary before trying to start the recording via the
47+
`/start` endpoint.
1548

1649
# Setup
50+
It is recommended to use a virtual environment in order to isolate the
51+
installation, as it provides a command line interface named `recorder` that can
52+
conflict with other system packages.
1753

18-
Clone this repository to your local machine. Detailed instructions about
19-
cloning repositories and installing python dependencies can be found
20-
[here](https://docs.google.com/document/d/15Mj3x9Im7Yfz3sPo5f4dUjQZgabjVtIL2RBHvM2798E/edit?usp=sharing).
21-
22-
## Install Python (3.5 - 3.9)
23-
Do not install the latest version of Python (currently 3.10) as it is not
24-
compatible with Intel RealSense SDK yet.
25-
26-
https://www.python.org/downloads/
27-
28-
## Install Intel RealSense SDK 2.0
29-
30-
https://github.com/IntelRealSense/librealsense/releases
31-
32-
## Install dependencies
33-
Open a terminal in the directory where this file is located. Then create a
34-
virtual environment:
3554
```
3655
python -m venv venv
37-
```
56+
````
3857
3958
Activate the environment on Windows:
59+
4060
```
4161
venv\Scripts\activate
4262
```
63+
4364
or on MacOS and Linux:
65+
4466
```
4567
source venv/bin/activate
4668
```
4769
48-
Finally, install dependencies with pip:
70+
Install from [Pypi](https://pypi.org/project/python-recorder/). There are
71+
optional dependencies that define which devices and listeners are available,
72+
due to the fact some of these dependencies are not available for all operative
73+
systems. Check [extras](#extras) for more information about it.
74+
```
75+
pip install python-recorder[all]
76+
```
77+
78+
or install this repository to use the latest development versions.
4979
```
50-
pip install -r requirements.txt
80+
pip install git+https://github.com/AcousticOdometry/python-recorder.git[all]
5181
```
5282
83+
## Extras
84+
Extras can be installed through [the `pip install`
85+
command](https://pip.pypa.io/en/stable/cli/pip_install/#requirement-specifiers)
86+
by specifying them at the end of the package name:
87+
88+
```
89+
pip install python-recorder[extra_one,extra_two]
90+
```
91+
92+
The available extras are defined in [`pyproject.toml`](./pyproject.toml) and
93+
are described here:
94+
95+
- `realsense`: [Intel
96+
Realsense](https://www.intel.com/content/www/us/en/architecture-and-technology/realsense-overview.html)
97+
devices depend on [pyrealsense2](https://pypi.org/project/pyrealsense2/).
98+
- `all`: All the extras defined above.
99+
53100
# Usage
54101
Check the usage with the `--help` option:
55102
```
56-
python vao-recorder.py --help
103+
recorder --help
57104
```
58105
59106
# Workflow
60107
61108
Configure the devices to be used. One can always modify the configuration
62109
manually in the generated `yaml` file.
63110
```
64-
python vao-recorder.py config
111+
recoder config
65112
```
66113
67114
Test that the chosen audio devices are working
68115
```
69-
python vao-recorder.py test microphone
116+
recorder test microphone
70117
```
71118
72119
Record an experiment with the configured devices
73120
```
74-
python vao-recorder.py record
75-
```
121+
recorder record
122+
```
123+
124+
Listen to `GET` requests through the local network
125+
```
126+
recorder listen localhost
127+
```
128+
129+
# Contributing
130+
We are open to contributions. Please, feel free to open an issue or pull
131+
request with any improvement or bug report. The framework is simple and easily
132+
extensible, it should fit easily in many projects.
133+
134+
## TODO
135+
136+
- [ ] ROS listener
137+
- [ ] Complete test suite
138+
- [ ] Camera device with `OpenCV`
139+
- [ ] Speedup the configuration file creation with compiled code?

‎example-config.yaml‎

Lines changed: 74 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,77 @@ microphone:
1010
channels: 2
1111
samplerate: 44100.0
1212
samplewidth: 2 # Sample width in bytes when stored in the `wav` file
13-
realsense: {}
13+
realsense:
14+
0:
15+
name: Intel RealSense D435I
16+
description: The camera is placed facing forwards parallel to the ground
17+
serial_number: '918512073836'
18+
streams:
19+
Accel:
20+
format: motion_xyz32f
21+
framerate: 63
22+
intrinsics:
23+
- - 1.0
24+
- 0.0
25+
- 0.0
26+
- 0.0
27+
- - 0.0
28+
- 1.0
29+
- 0.0
30+
- 0.0
31+
- - 0.0
32+
- 0.0
33+
- 1.0
34+
- 0.0
35+
type: accel
36+
Color:
37+
coeffs:
38+
- 0.0
39+
- 0.0
40+
- 0.0
41+
- 0.0
42+
- 0.0
43+
format: rgb8
44+
framerate: 30
45+
fx: 921.0354614257812
46+
fy: 921.243408203125
47+
height: 720
48+
model: inverse_brown_conrady
49+
ppx: 645.3656616210938
50+
ppy: 357.691650390625
51+
type: color
52+
width: 1280
53+
Depth:
54+
coeffs:
55+
- 0.0
56+
- 0.0
57+
- 0.0
58+
- 0.0
59+
- 0.0
60+
format: z16
61+
framerate: 30
62+
fx: 422.5686950683594
63+
fy: 422.5686950683594
64+
height: 480
65+
model: brown_conrady
66+
ppx: 427.68402099609375
67+
ppy: 239.21221923828125
68+
type: depth
69+
width: 848
70+
Gyro:
71+
format: motion_xyz32f
72+
framerate: 200
73+
intrinsics:
74+
- - 1.0
75+
- 0.0
76+
- 0.0
77+
- 0.0
78+
- - 0.0
79+
- 1.0
80+
- 0.0
81+
- 0.0
82+
- - 0.0
83+
- 0.0
84+
- 1.0
85+
- 0.0
86+
type: gyro

0 commit comments

Comments
 (0)