Awesome
Command-line tools bundles command-line applications to manipulate event files.
install
clone
To download Command Line Tools, run:
git clone --recursive https://github.com/neuromorphic-paris/command_line_tools.git
dependencies
Debian / Ubuntu
Open a terminal and run:
sudo apt install premake4
macOS
Open a terminal and run:
brew tap tonyseek/premake
brew install tonyseek/premake/premake4
If the command is not found, you need to install Homebrew first with the command:
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Windows
Install Chocolatey (https://chocolatey.org/) by running as administrator (Start > Windows Powershell > Right click > Run as Administator):
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
Open Powershell as administator and run:
choco install -y premake.portable
choco install -y visualstudio2019buildtools
choco install -y visualstudio2019-workload-vctools
choco install -y ffmpeg
compilation
Run the following commands from the command_line_tools directory to compile the applications:
premake4 gmake
cd build
make
cd release
Windows users must run the following commands from non-administrator Powershell instead:
premake4 vs2010
cd build
Get-ChildItem . -Filter *.vcxproj | Foreach-Object {C:\Program` Files` `(x86`)\Microsoft` Visual` Studio\2019\BuildTools\MSBuild\Current\Bin\MsBuild.exe /p:PlatformToolset=v142 /property:Configuration=Release $_}
The command-line applications are located in the release directory.
documentation
timecode
Time parameters in command-line applications (timestamps, durations, decays...) support three input formats:
- raw integers (
42
,12345
...), interpreted as microseconds - hh:mm:ss timecodes (
00:00:00
,04:20:00
,0:0:678
,00:1440:00
...) - hh:mm:ss.uuuuuu timecodes (
00:00:00.123456
,04:20:00.000000
,0:0:678.9
...), timecodes with more than 6 digits are rounded to the nearest microsecond.
crop
crop generates a new Event Stream file with only events from the given region.
./crop [options] /path/to/input.es /path/to/output.es left bottom width height
Available options:
-p
,--preserve-offset
prevents the coordinates of the cropped area from being normalized-h
,--help
shows the help message
cut
cut generates a new Event Stream file with only events from the given time range.
./cut [options] /path/to/input.es /path/to/output.es begin end
begin
and end
must be timecodes.
Available options:
-h
,--help
shows the help message
dat_to_es
dat_to_es converts a TD file (and an optional APS file) to an Event Stream file.
./dat_to_es [options] /path/to/input_td.dat /path/to/input_aps.dat /path/to/output.es
If the string none
is used for the td (respectively, aps) file, the Event Stream file is build from the aps (respectively, td) file only.
Available options:
-h
,--help
shows the help message
es_to_csv
es_to_csv converts an Event Stream file to a CSV file (compatible with Excel and Matlab):
./es_to_csv [options] /path/to/input.es /path/to/output.csv
Available options:
-h
,--help
shows the help message
es_to_frames
es_to_frames converts an Event Stream file to video frames. Frames use the P6 Netpbm format (https://en.wikipedia.org/wiki/Netpbm) if the output is a directory. Otherwise, the output consists of raw rgb24 frames.
./es_to_frames [options]
Available options:
-i file
,--input file
sets the path to the input .es file (defaults to standard input)-o directory
,--output directory
sets the path to the output directory (defaults to standard output)-b timestamp
,--begin timestamp
ignores events before this timestamp (timecode, defaults to00:00:00
),-e timestamp
,--end timestamp
ignores events after this timestamp (timecode, defaults to the end of the recording),-f frametime
,--frametime frametime
sets the time between two frames (timecode, defaults to00:00:00.020
)-s style
,--style style
selects the decay function, one ofexponential
(default),linear
,window
,cumulative
, andcumulative_shared
-t tau
,--tau tau
sets the decay function parameter (timecode, defaults to00:00:00.200
)- if
style
isexponential
, the decay is set toparameter
- if
style
islinear
, the decay is set toparameter / 2
- if
style
iswindow
, the time window is set toparameter
- if
style
iscumulative
, the time window is set toparameter
- if
style
iscumulative-shared
, the time window is set toparameter
- if
-j color
,--oncolor color
sets the color for ON events (color must be formatted as#hhhhhh
whereh
is an hexadecimal digit, defaults to#f4c20d
)-k color
,--offcolor color
sets the color for OFF events (color must be formatted as#hhhhhh
whereh
is an hexadecimal digit, defaults to#1e88e5
)-l color
,--idlecolor color
sets the background color (color must be formatted as#hhhhhh
whereh
is an hexadecimal digit, defaults to#191919
)-r ratio
,--discard-ratio ratio
sets the ratio of pixels discarded for cumulative mapping, ignored if the style is cumulative or cumulative-shared (defaults to 0.01)-a
,--add-timecode
adds a timecode overlay-d digits
,--digits digits
sets the number of digits in output filenames, ignored if the output is not a directory (defaults to6
)-r ratio
,--discard-ratio ratio
sets the ratio of pixels discarded for tone mapping, ignored if the stream type is not atis, used for black (resp. white) if--black
(resp.--white
) is not set (defaults to 0.01)-v duration
,--black duration
sets the black integration duration for tone mapping (timecode, defaults to automatic discard calculation)-w duration
,--white duration
sets the white integration duration for tone mapping (timecode, defaults to automatic discard calculation)-x color
,--atiscolor color
sets the background color for ATIS exposure measurements (color must be formatted as #hhhhhh where h is an hexadecimal digit, defaults to#000000
)-h
,--help
shows the help message
Once can use the script render.py to directly generate an MP4 video instead of frames. es_to_frames must be compiled before using render.py, and FFmpeg (https://www.ffmpeg.org) must be installed and on the system's path. Run python3 render.py --help
for details.
The commands below show how to manually pipe the generated frames into FFmpeg:
cat /path/to/input.es | ./es_to_frames | ffmpeg -f rawvideo -s 1280x720 -framerate 50 -pix_fmt rgb24 -i - -c:v libx264 -pix_fmt yuv420p /path/to/output.mp4
You may need to change the width, height and framerate of the video depending on the es_to_frames
options and the Event Stream dimensions. You can use ./size /path/to/input.es
to read the dimensions:
cat /path/to/input.es | ./es_to_frames --frametime 10000 | ffmpeg -f rawvideo -s $(./size /path/to/input.es) -framerate 100 -pix_fmt rgb24 -i - -c:v libx264 -pix_fmt yuv420p /path/to/output.mp4
You can also use a lossless encoding format:
cat /path/to/input.es | ./es_to_frames | ffmpeg -f rawvideo -s 1280x720 -framerate 50 -pix_fmt rgb24 -i - -c:v libx265 -x265-params lossless=1 -pix_fmt yuv444p /path/to/output.mp4
es_to_ply
es_to_ply converts an Event Stream file to a PLY file (Polygon File Format, compatible with Blender).
./es_to_ply [options] /path/to/input.es /path/to/output_on.ply /path/to/output_off.ply
Available options:
-t timestamp
,--timestamp timestamp
sets the initial timestamp for the point cloud (timecode, defaults to00:00:00
)-d duration
,--duration duration
sets the duration for the point cloud (timecode, defaults to00:00:01
)-h
,--help
shows the help message
event_rate
event_rate plots the number of events per second (slidding time window).
./event_rate [options] /path/to/input.es /path/to/output.svg
Available options:
-l tau
,--long tau
sets the long (foreground curve) time window (timecode, defaults to00:00:01
)-s tau
,--short tau
sets the short (background curve) time window (timecode, defaults to00:00:00.010
)-i size
,--width size
sets the output width in pixels (defaults to1280
)-e size
,--height size
sets the output height in pixels (defaults to720
)-h
,--help
shows the help message
evt2_to_es
evt2_to_es converts a raw file (EVT2) into an Event Stream file.
./evt2_to_es [options] /path/to/input.raw /path/to/output.es
Available options:
-x size
,--width size
sets the sensor width in pixels if not specified in the header (defaults to640
)-y size
,--height size
sets the sensor height in pixels if not specified in the header (defaults to480
)-n
,--normalize
offsets the timestamps so that the first one is zero-h
,--help
shows the help message
evt3_to_es
evt3_to_es converts a raw file (EVT3) into an Event Stream file.
./evt3_to_es [options] /path/to/input.raw /path/to/output.es
Available options:
-x size
,--width size
sets the sensor width in pixels if not specified in the header (defaults to1280
)-y size
,--height size
sets the sensor height in pixels if not specified in the header (defaults to720
)-n
,--normalize
offsets the timestamps so that the first one is zero-h
,--help
shows the help message
rainmaker
rainmaker generates a standalone HTML file containing a 3D representation of events from an Event Stream file.
./rainmaker [options] /path/to/input.es /path/to/output.html
Available options:
-t timestamp
,--timestamp timestamp
sets the initial timestamp for the point cloud (timecode, defaults to00:00:00
)-d duration
,--duration duration
sets the duration for the point cloud (timecode, defaults to00:00:01
)-r ratio
,--ratio ratio
sets the discard ratio for logarithmic tone mapping (default to0.05
, ignored if the file does not contain ATIS events)-f duration
,--frametime duration
sets the time between two frames (defaults toauto
),auto
calculates the time between two frames so that there is the same amount of raw data in events and frames, a duration in microseconds can be provided instead,none
disables the frames, ignored if the file contains DVS events-a
,--dark
renders in dark mode-h
,--help
shows the help message
rainbow
rainbow represents events by mapping time to colors.
./rainbow [options] /path/to/input.es /path/to/output.ppm
Available options:
-a alpha
,--alpha alpha
sets the transparency level for each event (must be in the range ]0, 1], defaults to0.1
)-l color
,--idlecolor color
sets the background color (color must be formatted as#hhhhhh
whereh
is an hexadecimal digit, defaults to#191919
)-h
,--help
shows the help message
size
size prints the spatial dimensions of the given Event Stream file.
./size /path/to/input.es
Available options:
-h
,--help
shows the help message
spectrogram
spectrogram plots a short-time Fourier transform.
./spectrogram [options] /path/to/input.es /path/to/output.png /path/to/output.json
Available options:
-b [timecode]
,--begin [timecode]
ignores events before this timestamp (timecode,defaults to 00:00:00
)-e [timecode]
,--end [timecode]
ignores events after this timestamp (timecode, defaults to the end of the recording)-l [int]
,--left [int]
input region of interest in pixels (defaults to 0)-o [int]
,--bottom [int]
input region of interest in pixels (defaults to 0)-c [int]
,--width [int]
input region of interest in pixels (defaults to input width)-d [int]
,--height [int]
input region of interest in pixels (defaults to input height)-t [timecode]
,--tau [timecode]
decay in µs (timecode, defaults to00:00:00.100000
)-m [mode]
,--mode [mode]
polarity mode, one ofon
,off
,all
,abs
(defaults toall
)on
only uses ON eventsoff
only uses OFF eventsall
multiplies the complex activity by 1 for ON events and -1 for OFF eventsabs
multiplies the complex activity by 1 for all events
-i [float]
,--minimum [float]
minimum frequency in Hertz (defaults to5e6 / (end - begin)
)-j [float]
,--maximum [float]
maximum frequency in Hertz (defaults to10000.0
)-f [int]
,--frequencies [int]
number of frequencies (defaults to100
)-s [int]
,--times [int]
number of time samples (defaults to1000
)-g [float]
,--gamma [float]
gamma ramp (power) to apply to the output image (defaults to0.5
)-h
,--help
shows the help message
spatiospectrogram
-i [path]
,--input [path]
sets the path to the input .es file (defaults to standard input)-o [path]
,--output [path]
sets the path to the output directory (defaults to standard output)-b [timecode]
,--begin [timecode]
ignores events before this timestamp (timecode, defaults to00:00:00
)-e [timecode]
,--end [timecode]
ignores events after this timestamp (timecode, defaults to the end of the recording)-f [timecode]
,--frametime [timecode]
sets the time between two frames (timecode, defaults to00:00:00.020
)-c [int]
,--scale [int]
scale up the output by the given integer factor (defaults to1
)-t [timecode]
,--tau [timecode]
decay in µs (timecode, defaults to00:00:00.100000
)-m [mode]
,--mode [mode]
polarity mode, one ofon
,off
,all
,abs
(defaults toall
)on
only uses ON eventsoff
only uses OFF eventsall
multiplies the complex activity by 1 for ON events and -1 for OFF eventsabs
multiplies the complex activity by 1 for all events
-p [float]
,--minimum [float]
minimum frequency in Hertz (defaults10.0
)-q [float]
,--maximum [float]
maximum frequency in Hertz (defaults to10000.0
)-u [int]
,--frequencies [int]
number of frequencies (defaults to100
)-g [float]
,--frequency-gamma [float]
gamma ramp (power) to apply to the output frequency (defaults to0.5
)-k [float]
,--amplitude-gamma [float]
gamma ramp (power) to apply to the output amplitude (defaults to0.5
)-r [float]
,--discard [float]
amplitude discard ratio for tone-mapping (defaults to0.001
)-a
,--add-timecode
adds a timecode overlay-d [int]
,--digits [int]
sets the number of digits in output filenames, ignored if the output is not a directory (defaults to6
)-h
,--help
shows the help message
The commands below show how to manually pipe the generated frames into FFmpeg:
cat /path/to/input.es | ./spatiospectrogram | ffmpeg -f rawvideo -s 1280x720 -framerate 50 -pix_fmt rgb24 -i - -c:v libx264 -pix_fmt yuv420p /path/to/output.mp4
You may need to change the width, height and framerate of the video depending on the spatiospectrogram
options and the Event Stream dimensions. You can use ./size /path/to/input.es
to read the dimensions:
cat /path/to/input.es | ./spatiospectrogram --frametime 10000 | ffmpeg -f rawvideo -s $(./size /path/to/input.es) -framerate 100 -pix_fmt rgb24 -i - -c:v libx264 -pix_fmt yuv420p /path/to/output.mp4
You can also use a lossless encoding format:
cat /path/to/input.es | ./spatiospectrogram | ffmpeg -f rawvideo -s 1280x720 -framerate 50 -pix_fmt rgb24 -i - -c:v libx265 -x265-params lossless=1 -pix_fmt yuv444p /path/to/output.mp4
statistics
statistics retrieves the event stream's properties and outputs them in JSON format.
./statistics [options] /path/to/input.es
Available options:
-h
,--help
shows the help message
contribute
development dependencies
Debian / Ubuntu
Open a terminal and run:
sudo apt install clang-format # formatting tool
macOS
Open a terminal and run:
brew install clang-format # formatting tool
test
To test the library, run from the command_line_tools directory:
premake4 gmake
cd build
make
cd release
Windows users must run premake4 vs2010
instead, and open the generated solution with Visual Studio.
You can then run sequentially the executables located in the release directory.
After changing the code, format the source files by running from the command_line_tools directory:
clang-format -i source/*.hpp source/*.cpp
Windows users must run Edit > Advanced > Format Document from the Visual Studio menu instead.
license
See the LICENSE file for license rights and limitations (GNU GPLv3).