Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Port Pupil Wiki #3

Merged
merged 2 commits into from Mar 16, 2017
Merged

Port Pupil Wiki #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
410ed5a
port latest updates from pupil wiki
nathakits Mar 16, 2017
fbdcdb5
fix spelling mistake
nathakits Mar 16, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 1 addition & 1 deletion community/academic-citation.md
View file
Open in desktop
Expand Up @@ -18,7 +18,7 @@ We have been asked a few times about how to cite Pupil in academic research. Ple
<div class="content-container">
<div class="header-link">
<a href="#cite-pupil">
<h3 id="cite-pupil">Papers that Cite Pupil</h3>
<h3 id="cite-pupil">Papers that cite Pupil</h3>
</a>
</div>
</div>
Expand Down
47 changes: 31 additions & 16 deletions developer-docs/dependecies/linux.md
View file
Open in desktop
Expand Up @@ -32,20 +32,33 @@ These installation instructions are tested using **Ubuntu 16.04 or higher** runn
</div>
</div>

Let's get started! Its time for `apt-get`. Just copy paste into the terminal and listen to your machine purr.
Let's get started! Its time for `apt`! Just copy paste into the terminal and listen to your machine purr.

```
sudo apt install -y pkg-config git cmake build-essential nasm wget python-setuptools libusb-1.0-0-dev python-zmq python-dev python-pip python-opengl python-opencv python-scipy libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libswscale-dev libavresample-dev ffmpeg libglew-dev libglfw3-dev libopencv-dev
sudo apt install -y pkg-config git cmake build-essential nasm wget python3-setuptools libusb-1.0-0-dev python3-dev python3-pip python3-numpy python3-scipy libglew-dev libglfw3-dev
```

> ffmpeg >= 3.2
```
sudo add-apt-repository ppa:jonathonf/ffmpeg-3
sudo apt-get update
sudo apt install libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libswscale-dev libavresample-dev ffmpeg libav-tools x264 x265
```

> OpenCV

```
# The requisites for opencv to build python3 cv2.so library are:
# (1) python3 interpreter found
# (2) libpython***.so shared lib found (make sure to install python3-dev)
# (3) numpy for python3 installed.
# If cv2.so was not build, delete the build folder, recheck the requisites and try again.

git clone https://github.com/itseez/opencv
cd opencv
mkdir build
cd build
cmake -D CMAKE_BUILD_TYPE=RELEASE ..
cmake -D CMAKE_BUILD_TYPE=RELEASE -D BUILD_TBB=ON -D WITH_TBB=ON ..
make -j2
sudo make install
sudo ldconfig
Expand All @@ -54,11 +67,12 @@ sudo ldconfig
> Turbojpeg

```
wget -O libjpeg-turbo.tar.gz http://sourceforge.net/projects/libjpeg-turbo/files/1.4.2/libjpeg-turbo-1.4.2.tar.gz/download
wget -O libjpeg-turbo.tar.gz https://sourceforge.net/projects/libjpeg-turbo/files/1.5.1/libjpeg-turbo-1.5.1.tar.gz/download
tar xvzf libjpeg-turbo.tar.gz
cd libjpeg-turbo-1.4.2
./configure --with-pic
cd libjpeg-turbo-1.5.1
./configure --with-pic --prefix=/usr/local
sudo make install
sudo ldconfig
```

> libuvc
Expand All @@ -82,16 +96,17 @@ sudo udevadm trigger
> Install packages with `pip`

```
sudo pip install numexpr
sudo pip install cython
sudo pip install psutil
sudo pip install pyzmq
sudo pip install msgpack_python
sudo pip install git+https://github.com/zeromq/pyre
sudo pip install git+https://github.com/pupil-labs/PyAV
sudo pip install git+https://github.com/pupil-labs/pyuvc
sudo pip install git+https://github.com/pupil-labs/pyndsi
sudo pip install git+https://github.com/pupil-labs/pyglui
sudo pip3 install numexpr
sudo pip3 install cython
sudo pip3 install psutil
sudo pip3 install pyzmq
sudo pip3 install msgpack_python
sudo pip3 install pyopengl
sudo pip3 install git+https://github.com/zeromq/pyre
sudo pip3 install git+https://github.com/pupil-labs/PyAV
sudo pip3 install git+https://github.com/pupil-labs/pyuvc
sudo pip3 install git+https://github.com/pupil-labs/pyndsi
sudo pip3 install git+https://github.com/pupil-labs/pyglui
```

> Finally, we install 3D eye model dependencies
Expand Down
4 changes: 2 additions & 2 deletions developer-docs/dependecies/macos.md
View file
Open in desktop
Expand Up @@ -77,7 +77,7 @@ brew install libjpeg-turbo
brew install libusb
brew tap homebrew/science
brew install ffmpeg
brew install opencv3 --with-eigen --with-qt --with-ffmpeg --with-opencl --HEAD --with-contrib --with-python3 --force
brew install opencv3 --with-ffmpeg --with-contrib --with-python3 --with-qt5
brew install glew
brew tap homebrew/versions
brew install glfw3
Expand All @@ -88,7 +88,7 @@ brew install ceres-solver
```

<aside class="notice">
Note - Pay close attention to Caveats messages generated by brew install. After installing opencv3 you may need to enable Python bindings:
Note - Pay close attention to `Caveats` messages generated by brew install. After installing `opencv3` you may need to enable Python bindings:
</aside>

```
Expand Down
18 changes: 9 additions & 9 deletions developer-docs/dependecies/windows.md
View file
Open in desktop
Expand Up @@ -66,16 +66,15 @@ To install an extension open command line with admin rights and run `python -m p
* [boost_python](http://www.lfd.uci.edu/~gohlke/pythonlibs/#boost.python): boost_python-1.59-cp35-none-win_amd64.whl

For networking install:

* `python -m pip install https://github.com/zeromq/pyre/archive/master.zip`
* `python -m pip install win_inet_pton`

There are some further python extensions that are specific to pupil:
You also need to install Python libraries that are specific to Pupil. Download the `.whl` file and install with `pip`.

* [PyAV](https://github.com/pupil-labs/PyAV)
* [pyglui](https://github.com/pupil-labs/pyglui)
* [pyndsi](https://github.com/pupil-labs/pyndsi)
* [pyuvc](https://github.com/pupil-labs/pyuvc)
* [PyAV](https://github.com/pupil-labs/PyAV/releases/latest)
* [pyglui](https://github.com/pupil-labs/pyglui/releases/latest)
* [pyndsi](https://github.com/pupil-labs/pyndsi/releases/latest)
* [pyuvc](https://github.com/pupil-labs/pyuvc/releases/latest)

##### Setup GLFW

Expand All @@ -102,6 +101,7 @@ There are some further python extensions that are specific to pupil:
* git clone --recursive https://github.com/tbennun/ceres-windows.git
* Copy the Eigen directory to ceres-windows
* Copy ceres-windows\ceres-solver\config\ceres\internal\config.h to ceres-windows\ceres-solver\include\ceres\internal\
* Open `glog\src\windows\port.cc` and comment out [L58-64](https://github.com/tbennun/glog/blob/7553b4193d856b4ba4e74cf064a5a70eb6a87cdd/src/windows/port.cc#L58-L64)
* Open the vs2012 sln file using VS2015. Agree to upgrade the compiler and libraries
* Build the static library versions of libglog and ceres-solver

Expand Down Expand Up @@ -129,7 +129,7 @@ There are some further python extensions that are specific to pupil:
</div>
</div>

In order to support isochronous USB transfer on Windows, you will need to install drivers for the cameras in your Pupil headset. Follow setup steps on [this wiki page](#win-driver-setup).
In order to support isochronous USB transfer on Windows, you will need to install drivers for the cameras in your Pupil headset. Follow setup steps on [this wiki page](https://github.com/pupil-labs/pupil/wiki/Windows-Driver-Setup).

<div class="content-container">
<div class="header-link">
Expand Down Expand Up @@ -163,12 +163,12 @@ run_player.bat path_to_recording

* Clone PyAV to your system `git clone https://github.com/pupil-labs/PyAV.git`
* Download and extract [ffmpeg-3.2-dev](http://ffmpeg.zeranoe.com/builds/win64/dev/ffmpeg-3.2-win64-dev.zip)
* Download and extract [ffmpeg-3.2-shared] (http://ffmpeg.zeranoe.com/builds/win64/shared/ffmpeg-3.2-win64-shared.zip)
* Download and extract [ffmpeg-3.2-shared](http://ffmpeg.zeranoe.com/builds/win64/shared/ffmpeg-3.2-win64-shared.zip)
* Copy the dlls from the ffmpeg-3.2-win64-shared\bin directory to the pupil\pupil_external\ directory
* Open "Developer command prompt for VS2015" and cd to PyAV directory
* Run `python setup.py clean --all build_ext --inplace --ffmpeg-dir=path\to\ffmpeg-3.2-dev -c msvc`
* `pip wheel .`
* `pip install .`


[google-group]: http://groups.google.com/group/pupil-discuss
[google-group]: http://groups.google.com/group/pupil-discuss
13 changes: 1 addition & 12 deletions developer-docs/usb-bandwidth-sync.md
View file
Open in desktop
Expand Up @@ -59,17 +59,6 @@ We have tested these and found that we can run 3 pupil camera at 720p@60fps+2x48
Note - You may have other consumers on the same USB bus already so your milage may vary depending on your machine and selected usb plug on that machine.
</aside>

<div class="content-container">
<div class="header-link">
<a href="#windows-opencv">
<h3 id="windows-opencv">Windows, OpenCV?</h3>
</a>
</div>
</div>
<div class="header-border-bottom"></div>

Since this trick requires libuvc as a custom video backend it will work on mac and linux but not work on windows until somebody implements iso-transfers for libusb on windows. If you want to use the cameras with OpenCV I would suggest using [pyuvc](https://github.com/pupil-labs/pyuvc) to get frames from the cameras.

<div class="content-container">
<div class="header-link">
<a href="#use-more-bus">
Expand All @@ -92,7 +81,7 @@ If you want to not be limited by the bandwidth of a single usb bus you can use a

Each camera we use is a free running capture device. Additionally each camera runs in a separate process. Instead of frame-locking the camera through special hardware we acquire timestamps for each frame. These timestamps are then used to correlate data from each camera in time and match frames based on closest proximity.

Data from each eye camera is sent via IPC to the world process. Since this involves three separate processes it can happen that data from one camera arrives earlier that another. However for each camera the frames will be ordered and timestamps are monotonically increasing. In the main process we match the available data timewise when we need. In Pupil Player we can do matching after the fact to work with perfectly sorted data from all three cameras. If you require the data to be matched over being recent I would recommend collecting data in the queue for a few more frames in world.py before dispatching them in the events dict. (I'll actually do some tests on this subject soon.)
Data from each eye camera is sent via IPC to the world process. Since this involves three separate processes it can happen that data from one camera arrives earlier that another. However for each camera the frames will be ordered and timestamps are monotonically increasing. In the main process we match the available data timewise when we need. In Pupil Player we can do matching after the fact to work with perfectly sorted data from all three cameras. If you require the data to be matched over being recent I would recommend collecting data in the queue for a few more frames in world.py before dispatching them in the events dict. (I ll actually do some tests on this subject soon.)

<div class="content-container">
<div class="header-link">
Expand Down
61 changes: 22 additions & 39 deletions developer-docs/win-driver-setup.md
View file
Open in desktop
Expand Up @@ -26,9 +26,8 @@ In order to support isochronous USB transfer on Windows, you will need to instal
</div>
<div class="header-border-bottom"></div>

1. Download and install [libusbk 3.0.7.0](https://sourceforge.net/projects/libusbk/files/libusbK-release/3.0.7.0/libusbK-3.0.7.0-setup.exe/download).
1. Download [Zadig](http://zadig.akeo.ie/downloads/zadig_2.2.exe).
1. Plug in your Pupil headset
1. Download and install [7zip](http://www.7-zip.org/download.html)
1. Download and extract [Pupil camera driver installer](https://drive.google.com/uc?export=download&id=0Byap58sXjMVfR0p4eW5KcXpfQjg)

<div class="content-container">
<div class="header-link">
Expand All @@ -39,42 +38,26 @@ In order to support isochronous USB transfer on Windows, you will need to instal
</div>
<div class="header-border-bottom"></div>

1. Start ZadiG.

<p align="center">
<img width="80%" src="/images/windows_driver_setup/zadig_001.jpg" title="Start ZadiG">
</p>
1. Navigate to `pupil_labs_camera_drivers_windows_x64` directory
1. Double click *`InstallDriver.exe`* - this will install drivers. Follow on screen prompts.
1. Open `Windows Device Manager` from `System > Device Manager`. Verify the drivers are correctly installed in `Windows Device Manager`. Your Pupil headset cameras should be listed under a new category titled: `libusbK Usb Devices`. Note: In some cases `Pupil Cam1` may show three of the same `ID` as the camera name. Don't worry - just make sure that the number of devices are the same as the number of cameras on your Pupil headset.
1. Download the latest release of Pupil software and launch `pupil_capture.exe` to verify all cameras are accessible.

2. In the `Options` menu **check** `List All Devices`.

<p align="center">
<img width="80%" src="/images/windows_driver_setup/zadig_002.jpg" title="Zadig options menu">
</p>

3. In the `Options` menu **uncheck** `Ignore Hubs or Composite Parents`. In the dropdown list you should now see devices with the name *Pupil Cam1* followed by an ID

<aside class="notice">
Note - The number of devices depends on your headset configuration. For example, if you have a binocular setup, you will see Pupil Cam1 ID2, Pupil Cam1 ID1, Pupil Cam1 ID0.
</aside>

<p align="center">
<img width="80%" src="/images/windows_driver_setup/zadig_003.jpg" title="Zadig pupil cam">
</p>

4. Select one of the **Pupil Cam1** devices. Select `libusbK (v3.0.7.0)` from the options list (to the right of the green arrow ➡️ ). Click `Replace Driver`.

<p align="center">
<img width="80%" src="/images/windows_driver_setup/zadig_004.jpg" title="Zadig replace driver">
</p>

5. Repeat Step 4 with the other **Pupil Cam1** devices until the `Driver` field reads `libusbK (v3.0.7.0)` for all **Pupil Cam1** devices

6. Verify the driver is correctly replaced in `Windows Device Manager`. Your Pupil headset cameras should be listed under a new category titled: `libusbK USB Devices`.
<div class="header-link">
<a href="#install-driver">
<h3 id="install-driver">Troubleshooting</h3>
</a>
</div>
</div>
<div class="header-border-bottom"></div>

<aside class="notice">
Note - Device names will all show up with the same name in Windows - don't worry - just make sure that the number of devices are the same as the number of cameras you have connected.
</aside>
If you had tried to install drivers with previous driver install instructions and failed, or are not able to access cameras in Pupil Capture. Please try the following:

<p align="center">
<img width="80%" src="/images/windows_driver_setup/device_manager_check.jpg" title="Windows device manager libusbK">
</p>
1. In `Device Manager` (`System > Device Manager`)
1. `View > Show Hidden Devices`
1. Expand `libUSBK Usb Devices`
1. For each device listed (even hidden devices) click `Uninstall` and check the box agreeing to `Delete the driver software for this device` and press `OK`
1. Repeat for each device in libUSBK Usb Devices
1. Unplug Pupil headset (if plugged in)
1. Restart your computer
1. Install drivers from step 2 in the `Install drivers for your Pupil headset` section