# README #

EyeRISConvert - Tools for extracting particle rois and stats from Raytrix camera images

### Overview ###

Forked from SPConvert

* EyeRISConvert is a collection of python scripts to process raytrix particle images into rois and particle stats
* Version: 0.2
* Authors: 
    * Paul L. D. Roberts, Eric Orenstein
    * additional object features: Filip Mróz


### Quickstart ###

The fastest way to get your system setup is to install Anaconda and then add the opencv and pystache python modules through conda:

1. Install Anaconda for python 3.6 or 3.7 from https://anaconda.org/
2. Open a terminal and install the required python modules:
    * `$ pip install opencv-python`
    * `$ pip install opencv-contrib-python`
    * `$ pip install pystache`
    * `$ pip install pandas`
    * `$ pip install pyntcloud`
3. Change to the EyRISConvert directory and process a set of Raytrix data
    * `$ python RaytrixParticleProc.py [settings_file] [input dir] [pattern] [output_dir]`
4. Once that has finished, build the static web app
    * `$ python BuildWebApp.py [settings_path] [data_path]`

### Requirements ###
* python 3.6 or 3.7, numpy, scipy, skimage, opencv3, pystache, pandas, pyntcloud, imageio
* Tested on mac, and windows

The requirements are also listed in requirements.txt file.

### Settings ###

Some of the processing steps can be controlled via a settings file. These are typically placed in config/

### Additional Data files ###

To collate image data with other sensors, the script BuildWebApp.py can load a MiniROV log file from data/

Support for other sensors can be added relatively easily

### Detailed Description ###

EyeRISConvert takes as input a directory or directory of directories of images and builds image mosaics and stats from these images.
It is designed to take as input images from real-time ROI detection systems such as the Scripps Plankton Camera (http://spc.ucsd.edu)
and build a web app that is similar to the image browsers from spc.ucsd.edu

The code collects all of the images in the directory, loads them into RAM and then splits the work of processing them over multiple
processes up to NCPU-1. The processing consists of:

1. color conversion
2. edge-detection and segmentation
3. morphological feature extraction
4. foreground masking
5. inverse filtering of masked foreground

The results are then saved into a new directory structure and a web app is build from the data using pystache (mustache) templates
and some javascript and html files stored in the app directory.

### Data Output ###

#### RaytrixParticleProc ####

##### rois/ #####

The roi subdir contains a list of directories each containing a few thousand rois. Each roi is saved with a
file name of te format:

`frame_prefix-[ROI number]-[left]-[top]-[right]-[bottom]-[depth]`

`[ROI number]` is the number of that roi out of the total from that frame
`[left]`, `[top]`, `[right]`, `[bottom]` are the coordinates of the bounding box rectangle
`[depth]` is the estimated depth of the roi in the scene in mm away from the focal plane towards the camera.

##### images/ #####

The images subdir holds a converted and bounding box labeled image for each processed frame. This
shows where the ROIs were taken from in the image

##### stats/ #####

The stats subdir holds any recorded stats for the particle processing or roi generation, typically in csv
format

##### clouds/ #####

The clouds subdir holds one .ply format point cloud for each image. The units in the cloud are millimeters
and the z coordinate is the distance away frm the focal plane towards the camera.

#### BuildWebApp ####

The output from this script is a standalone web app than can be opened to view the rois in a mosaic with
a searchable database organized by the available sensor data and object size.

### Configuring for a Specific Camera ###

There are a few settings that need to be adjusted to use with a different camera. The primary ones are:

1. BayerPattern: This needs to match your camera, for example BG is used for the SPC, SPCP cameras and RG is used for the SPC-BIG, UW, USC cameras
2. PixelSize: This is pixel size of pixels in object space in um/pixel of the given camera/lens combination, it is converted to mm/pixel in the code
    * SPC: 7.38 um/pixel (Sony ICX814, 3.69 um pixels with 0.5x objective)
    * SPCP: 0.62 um/pixel (Sony ICX834, 3.1 um pixels with 5x objective)
    * SPC2: 7.38 um/pixel (Sony ICX814, 3.69 um pixels with 0.5x objective)
    * SPCP2: 0.738 um/pixel (Sony ICX814, 3.69 um pixels with 5x objective)
    * SPC-PWSSC, NOAA: 22.6 um/pixel (Sony ICX834, 3.1 um pixels with 0.137x objective)
    * SPC-BIG, UW, USC: 25.18 um/pixel (Sony IMX253, 3.45 um pixels with 0.137x objective)
    * Raytrix Cameras: this should be the calibrated pixel size at the focal plane

### Contribution guidelines ###

* Help is needed to improve this code. Specific areas are:

0. Error handling for missing settings, there is slim to none currently
1. Improved control of processing and app building parameters via settings.xml
2. Management of cases with more images then can fit in RAM
3. Handling bad images, images that are too large or small
4. Better integration of RaytrixParticleProc with BuildWebApp to remove redundancy

* Contact Paul Roberts (proberts@mbari.org) for information about contributing code, bugs, etc.