//=============================================================================
// Copyright © 2017 FLIR Integrated Imaging Solutions, Inc. All Rights Reserved.
//
// This software is the confidential and proprietary information of FLIR
// Integrated Imaging Solutions, Inc. ("Confidential Information"). You
// shall not disclose such Confidential Information and shall use it only in
// accordance with the terms of the license agreement you entered into
// with FLIR Integrated Imaging Solutions, Inc. (FLIR).
//
// FLIR MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
// SOFTWARE, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
// PURPOSE, OR NON-INFRINGEMENT. FLIR SHALL NOT BE LIABLE FOR ANY DAMAGES
// SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
// THIS SOFTWARE OR ITS DERIVATIVES.
//=============================================================================

===============================================================================
==
== README
==
===============================================================================

===============================================================================
TABLE OF CONTENTS
===============================================================================
1. DEPENDENCIES
1.1. DEPENDENCY INSTALLATION
2. USB RELATED NOTES
3. SPINNAKER INSTALLATION
3.1 GIGE CAMERA SETUP
4. SPINNAKER REMOVAL
5. RUNNING PREBUILT UTILITIES
5.1. SPINVIEW_QT
5.2. SPINUPDATECONSOLE


===============================================================================
1. DEPENDENCIES
===============================================================================

To install Spinnaker on linux you will need to have a few prerequisite
libraries installed.  Below is a list of libs that Spinnaker and other
components depend on.

1) Core Image Acquisition Library
The core library includes Spinnaker and Spinnaker-C

- libusb-1.0-0 (version 1.0.17 or greater recommended)

Strongly recommended:
Ubuntu 18.04 LTS:   Linux kernel version 4.15.0-20 or later.

2) Graphical User Interface Factory Library
GTKmm is an optional supported GUI toolkit. 

- libgtkmm-2.4-dev

3) Video Recording Library
Recording functions are required for SpinVideo. Examples like SpinView_QT and
SaveToAvi depened on SpinVideo.

- libavcodec57
- libavformat57
- libswscale4
- libswresample2
- libavutil55

-------------------------------------------------------------------------------
1.1. DEPENDENCY INSTALLATION
-------------------------------------------------------------------------------

To install these dependencies, the most straightforward approach is to use your
system's built-in package management utility. In the case of Ubuntu, the utility
is named "apt". Below is a set of one-line commands that can be used to install
all the required dependencies for various releases of Ubuntu Long Term Support
(LTS).

Ubuntu 18.04:
user$:  sudo apt-get install libavcodec57 libavformat57 \
        libswscale4 libswresample2 libavutil55 libusb-1.0-0 libgtkmm-2.4-dev


===============================================================================
2. USB RELATED NOTES
===============================================================================

On Linux systems, image size is restricted to 2MiB or less by default. To
increase this limit so that you can make use of your imaging hardware's full
capabilities, you will need to make a minor change to your system.
More information on these changes can be found at:
<https://www.ptgrey.com/tan/10685#ConfiguringUSBFS>

1. Open the /etc/default/grub file in any text editor. Find and replace:

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash"

with this:

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash usbcore.usbfs_memory_mb=1000"

2. Update grub with these settings:
$ sudo update-grub

3. Reboot and test a USB 3.1 camera.
If this method fails to set the memory limit, run the following command:
$ sudo sh -c 'echo 1000 > /sys/module/usbcore/parameters/usbfs_memory_mb'

To confirm that you have successfully updated the memory limit, run the following command:
$ cat /sys/module/usbcore/parameters/usbfs_memory_mb


===============================================================================
3. SPINNAKER INSTALLATION
===============================================================================

Once all the Dependencies are installed, just install the Spinnaker deb files.
There are eleven different packages that need to be installed.

The Spinnaker packages are:
- libspinnaker-<version>_<platform>.deb
- libspinnaker-<version>_<platform>-dev.deb
- libspinnaker-c-<version>_<platform>.deb
- libspinnaker-c-<version>_<platform>-dev.deb
- libspinVideo-<version>_<platform>.deb
- libspinVideo-<version>_<platform>-dev.deb
- libspinVideo-c-<version>_<platform>.deb
- libspinVideo-c-<version>_<platform>-dev.deb
- spinview-qt-<version>_<platform>.deb
- spinview-qt-<version>_<platform>-dev.deb
- spinupdate-<version>_<platform>.deb
- spinupdate-<version>_<platform>-dev.deb
- spinnaker-<version>_<platform>.deb
- spinnaker-doc-<version>_<platform>.deb

The packages with a preceding 'lib' are all the shared objects and their
respective dev packages.  The spinnaker package installs the capture application
which can be launched by typing 'spinview' in a terminal or through the
Applications menu.  The spinnaker-doc package contains our documentation in
pdf format (located in /usr/share/doc/spinnaker-doc).

To install these packages, we provide an easy to use install script.  You can
run the script in the same directory that you have unpacked the software into.
The install script is called 'install_spinnaker.sh'

code eg:
user$ sudo sh install_spinnaker.sh

This script will install all the Spinnaker libraries, example code, example
apps and documentation.  The Spinnaker install script will also ask you to
configure udev so that a user will be able to use the usb devices.  If
you choose to configure the usb devices this script will change
permissions on the nodes to give this particular user full read and write
access to the device nodes.  It will overwrite the default Ubuntu permissions.
After running this script everything should be installed and set up for use.

Unfortunately restarting udev doesn't seem to set the permissions on the device
nodes immediately.  You may need to restart the machine before the user can
access the device nodes.


-------------------------------------------------------------------------------
3.1 GIGE CAMERA SETUP
-------------------------------------------------------------------------------

To setup your network interface to use GigE cameras, run ifconfig and find the
network adapter that you intend to use the cameras on (eg. enp15s0):

user$ ifconfig


Then, open up /etc/network/interfaces in a text editor (as sudo):

user$ sudo gedit /etc/network/interfaces

and add the following lines (change enp15s0 to match the one shown in ifconfig):

    iface enp15s0 inet static 
    address 169.254.0.64 
    netmask 255.255.0.0 
    mtu 9000 

    auto enp15s0

If using multiple interfaces, ensure that the addresses used are on different subnets
(eg. 169.254.0.64 and 169.253.0.64).
After closing the editor, it is recommended to reboot the computer before using
any GigE cameras.


===============================================================================
4. SPINNAKER REMOVAL
===============================================================================

To remove Spinnaker just run the uninstall script that we provide.  The
removal script will also remove the udev rules therefore restoring the original
ubuntu permissions on the device nodes.

code eg:
user$: sudo sh remove_spinnaker.sh


===============================================================================
5. RUNNING PREBUILT UTILITIES
===============================================================================
In addition to prebuilt examples (eg: Acquisition, ChunkData, etc),
along with the source code for these examples, Spinnaker SDK ships with a
a number of prebuilt tools for evaluating cameras (ie: SpinView), upgrading
firmware (ie: SpinUpdateConsole), and so on. 

To make using these tools more convenient, Spinnaker SDK ships with a few 
command-line scripts used to automatically set the appropriate environment 
variables so these tools can be run from any PWD via the command-line, or when 
launching the tools via a custom icon/shortcut. To run the following tools, 
simply invoke their "launcher" command via the command line, and you will not 
have to change the PWD to "/usr/bin" or modify environment variables in order 
to launch them.

-------------------------------------------------------------------------------
5.1. SpinView_QT
-------------------------------------------------------------------------------
SpinView_QT: A graphical application for testing cameras and viewing live streaming
         of image data from all supported FLIR cameras.
Location:   /usr/bin/SpinView_QT
Short Name: SpinView
Launcher:   spinview

-------------------------------------------------------------------------------
5.2. SpinUpdateConsole
-------------------------------------------------------------------------------
SpinUpdateConsole: A console application for updating the firmware on FLIR cameras.
Location:   /usr/bin/SpinUpdateConsole
Short Name: SpinUpdateConsole
Launcher:   SpinUpdateConsole
