Terminology

• RAW image file - A JPEG+RAW image file as directly captured by a PiCam v2, saved as a .JPEG
• RGB image - A 3D numpy.ndarray: a 2D array of "pixels" (row-major), where each "pixel" is a 1D array of [red, green, blue] channels with a value between 0 and 1. This is our default format for interacting with images. An example 4-pixel (2x2) image would have this shape:

[
 [ [r1, g1, b1], [r2, g2, b2] ],
 [ [r3, g3, b3], [r4, g4, b4] ]
]

• ROI - An RGB image that has been cropped to a specific Region of Interest (ROI).
• ROI definition - A 4-tuple in the format provided by cv2.selectROI: (start_col, start_row, cols, rows), used to define a Region of Interest (ROI).

Usage

The function process_experiment is meant to be run from a local Jupyter Notebook.

Pre-reqs

Some set up is required before you can run process_experiment locally. These directions are very minimal - check with software team if you have questions or run into problems.

awscli

Install:

1. Follow instructions here: https://docs.aws.amazon.com/cli/latest/userguide/installing.html Note: I had to use pip and not pip3 to successfully install awscli
2. Run aws --version from the command line to confirm it's installed correctly

Set up credentials:

1. Generate an AWS access key
2. Run aws configure and put in the access key ID and secret key
3. Confirm your credentials are working by running aws s3 ls - you should get a list of directories

Running

See this example jupyter notebook: "process_experiment - for Cosmobot experiments.ipynb" in the Jupyter Snippets folder: https://drive.google.com/drive/folders/1A-Rlb-VYTwQ6Tl3sm12eR-cnmCHbj6UP

Testing

Tests are run with tox. Tox will set up the full environment needed to run the tests, including installing dependencies.

Running tests

Install tox

pip install tox

Note: You may need to install tox-venv as well if you run into issues with your python virtual environment.

To run tests, cd to the base level of this directory and call

tox

Running tests in docker

Note: The current docker configuration only installs python 3.6.8. To run tests with docker, ensure you have both docker and docker-compose installed locally. Start the python container with

docker-compose up -d --no-recreate

Then get an interactive shell in the container with

docker-compose exec python bash

From there cd to /app and run tox as described above.

Diagnostics

process_experiment returns a diagnostics DataFrame as one of its outputs. It also raises warnings if any of the diagnostic values are outside of expected ranges.

The DataFrame is indexed by file path and each column is a particular diagnostic. Some diagnostics are numeric and others are booleans. Most boolean diagnostics are simply derived from the numeric diagnostics by checking whether they are in or outside of expected ranges.

Dark frame diagnostics

These diagnostics columns are prefixed with "dark_frame_" in the output DataFrame (eg. one column name will be dark_frame_min_value_before):

• min_value_before, min_value_after: minimum value of any color pixel before and after dark frame correction (in DNR, across all channels).
  • min_value_after should always be less than min_value_before. If not, min_value_increased will be True and a warning will be raised.
• mean_value_before, mean_value_after: mean pixel value before and after dark frame correction (in DNR, across all channels).
  • mean_value_after should always be less than mean_value_before. If not, mean_value_increased will be True and a warning will be raised.
• negative_pixels_pct_before, negative_pixels_pct_after: The fraction of pixels that were negative before and after dark frame correction.
  • If negative_pixels_pct_after is greater than 0.51, too_many_negative_pixels_after will be True and a warning will be raised.
• nan_values_after: number of NaN values in the image after dark frame correction.
  • This should be zero; if not, nan_values_present will be True and a warning will be raised.
• iso: ISO of the image capture.
  • If this does not match the ISO used in training (100), iso_mismatch_with_training will be True and a warning will be raised.
• exposure_time: exposure time of the image capture.
  • If this is outside of the range used to train the dark frame regression (0.000009s to 6s), exposure_out_of_training_range will be True and a warning will be raised.

Flat field diagnostics

These diagnostics columns are prefixed with "flat_field_" in the output DataFrame(eg. one column name will be flat_field_cv_before):

• cv_before, cv_after: Coefficient of variation across all color channels, before and after flat field correction.
  • This should generally decrease with flat fielding. If it increases, cv_increased will be True and a warning will be raised.
• flat_field_factor_max, flat_field_factor_min: The minimum and maximum values of the flat field, which is defined as (image after flat field correction) / (image before flat field correction).
• nan_values_after: number of NaN values in the image after flat field correction.
  • This should be zero; if not, nan_values_present will be True and a warning will be raised.

Intensity adjustment diagnostics

These diagnostics columns are prefixed with "intensity_adj_" in the output DataFrame:

No diagnostics are currently implemented for intensity adjustment.