Home

Awesome

banner

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

rainbow

rainbow represents events by mapping time to colors.

./rainbow [options] /path/to/input.es /path/to/output.ppm

Available options:

size

size prints the spatial dimensions of the given Event Stream file.

./size /path/to/input.es

Available options:

spectrogram

spectrogram plots a short-time Fourier transform.

./spectrogram [options] /path/to/input.es /path/to/output.png /path/to/output.json

Available options:

spatiospectrogram

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:

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).