Welcome to FoxMask’s documentation

You will find on theses pages information related to the installation and usage of FoxMask. It is intended to be read by users as well as developers.

Getting Started

Installation

We provide two methods for installing and using FoxMask:

Standalone installation on Linux

This is the recommended method for production.

This method will install FoxMask on your Linux computer. We provide an automated install script, which will take care of installing all the dependencies needed to run FoxMask as well as the software itself. It is made for Ubuntu 16.04. The file is located in install-scripts/install-ubuntu16.sh of the FoxMask repository. You can also download the file directly sh an run it. To execute the script, simply run the following command as a standard user. Note that you will need to have sudo rights.

$ sh install-ubuntu16.sh

Note

You can issue the install command from any directory, the script will download all the needed softwares in your home directory. Please do not run the script prefixed by sudo.

Once the installation if finished, you will have a foxmask directory in your home folder where you will find the software and a set of images to test the software. Congratulation, you are now ready to start using FoxMask on your Linux Box ! Consult our Usage page to get started.

This installation have been successfully tested on Ubuntu 16.04, on bare metal computers as well as on GCE (Google Cloud Engine) and VirtualBox 5.0.

Installation through a virtual machine

We do not recommend this installation for production.

We provide a complete virtual environment to run and use FoxMask. The main advantages of this installation is that you can rapidly get FoxMask running on any platform. However, there are important drawbacks to consider:

  • Poor performances compared to standalone installation
  • A bit heavy to manage (Vagrant + VirtualBox + share usb)

Despite theses drawbacks, we consider that using our FoxMask box can be very useful for first time users wanting to test the software, or for development purposes.

Note

Again, let me emphasize that this method is suitable to rapidly get FoxMask up and running on another platform than Ubuntu. However, anyone serious about implementing an automated image analysis pipeline with FoxMask should consider installing it on bare metal hardware running a Linux OS, or on a virtual infrastructure running libvirt. We provide a fully automated installation script, successfully tested on Ubuntu 16.04. Please see Standalone installation on Linux to install FoxMask on you Linux machine.

To run the FoxMask virtual machine on your Linux, Mac or Windows computer, you will need the following three open source softwares:

Follow the installation procedure for your platform. Once theses softwares are installed, you are ready to install FoxMask by issuing the following command:

git clone https://github.com/edevost/foxmask.git

This will fetch all needed components to run the virtual machine. Once the clone command is completed, you can start the virtual machine by issuing the following commands:

cd foxmask
vagrant up

This will boot the virtual machine. You can also manage you virtual machine through VirtualBox software, and start or stop your machine from there. The start process will bring you to the Ubuntu desktop. The default user and password on this virtual environment is vagrant vagrant. Once the machine is ready, you can proceed to our Usage section to launch FoxMask on the provided set of images.

Testing on your own set of images

To test FoxMask on your own set of images, you will have to make your images available to the virtual machine. To do so, we recommend saving your image set on an usb drive, and make the drive available to VirtualBox. There are many good tutorials on the web explaining the process:

Making this work will demand a bit of work and reading, but nothing out of reach of any computer users with minimal computer knowledge. The main steps to get your FoxMask virtual machine to have access to an usb drive plugged on your host computer are the following:

  • Shutdown your FoxMask virtual machine if it is running
  • Plug your usb drive on your computer (host)
  • Install Virtual Box 5.0 extension pack
  • Activate usb controller on VirtualBox
  • Add your drive

Once your drive is added, boot your FoxMask virtual machine and check if there is a link to your drive on the desktop. If everything went well, you will have direct access to your usb drive on your virtual machine ! You can then proceed to our Usage section to start using FoxMask on your set of images.

Usage

FoxMask program is shipped with a sample images directory (images/example/) where you will find 50 jpeg images of Arctic fox. We encourage you to test FoxMask on this sample of images.

To run FoxMask on the default provided set of images, you simply have to run the following command, from the foxmask directory:

python2 foxmask.py

This will launch the analysis process. You will see images being analyzed and mask created. At the end of the process, a CSV file is exported with the image names and the presence of detected objects (0 or 1). If required, masks and images with detected objects are also copied in subfolders.

Configuration

Configuration of where the images sets are as well as where to write results are all confined in the file parameters.py. In this file you will find configurable variables used when the program is executed:

imagesDir
The directory where the images to analyze are located. This directory can be anywhere (shared folder, usb drive, local disk), it just need to be accessible by your machine running FoxMask. It can consist of one single folder or a set of folders. FoxMask will iterate through the folders and analyze them all.
outputDir
The location where the results of the analysis will be written
maxgap
The maximum time gap (in seconds) between two consecutive images to build the sequence.
minsize
Minimum size of moving objects to be considered as an animal

Contribution

Contributions to the FoxMask project is highly welcome and encouraged ! You can contribute in many ways. Note that you need a GitHub account to contribute to the project.

Report issues

You can report any issues with the project in the source code repository on GitHub. These issues can be of any kind, wrong documentation, issues with installation or usage of FoxMaks. Please write as much information as possible when submitting your issue.

Contribute to the documentation

You can visit the documentation pages directly on GitHub and edit the documentation page you wish modify. You can then submit your modification.

Contribute to the code

You can easily contribute to the code by cloning the repository, checkout to a new branch, work and your branch, and push your branch to FoxMask repository. If you get a permission denied on push, please contact a FoxMask developer to grant you access. Example workflow:

git clone https://github.com/edevost/foxmask.git
git checkout -b my-new-feature
[work on your feature]
git add *your modified files*
git commit -m 'meaningfull message concerning your modification'
git push origin my-new-feature

You can then submit a pull request on GiHub. Thank you for contributing !

Code documentation

The foxmask.py module will evaluate the background based on images located, by default, in the Images directory of the FoxMask repository, and perform a foreground segmentation to identify moving objects. The main routine of the code will iterate through every folders present in the Images directory, and analyze found images. The Images directory is set by a variable define in parameters.py: imagesDir.

Example:

To run this module, simply invoke it from the command line.

$ python2 foxmask.py

The ultimate output of this module is a Results directory, under which resulting masks are copied, as well as images containing moving objects (as the result of the analysis). Tables are also written, one table for each directory analyzed. Each table contains the name of the image, the result (0 or 1) of detection and parameters used during the analysis.

Setup

The following class will do all the preliminary setup required to run the code and clean temporary files and directories. One variable residing in parameters.py can be parametrised: rmmasks, defining if resulting masks should be kept. This could be useful, for example, for visual evaluation of the analysis.

class foxmask.Setup[source]
delmaskresults(folder)[source]

Remove the MasksResults directory. The MasksResults directory is created by the cpp command (calling ForegroundSegmentation), on each run, and resides in the folder being analyzed. If the variable rmmasks (in parameters.py) is set to 1, the directory will be removed after each run. If not, masks will be kept in place.

getfolders()[source]

This function will take as input the imagesDir variable specified in parameters.py and return a list of all folders present in it. This list will then feed the software with all the folders containing images to be analyzed. Each folders are considered as a single analyzed entity.

Returns:
list. A list of all folders in imagesDir.
maketempdir(folder)[source]

Creation of a temporary directory in which all analyzed images will be written. This directory will be created in all folders being analyzed and removed after each run.

Note

For performances issue, the images analyzed are being resized, so this function exist to create a place where to store the resized images. Theses resized images, placed in a temporary folder, will be the one actually analyzed by the software.

Returns:
string. The location of the actual folder being analyzed concatenated with temp1.

Images to analyze and metadata

The following class will gather all images in the folder being analysed, and search in each image metadata for the DateTimeOriginal, which is the time the picture was taken. Based on the latter, groups of images are made.

class foxmask.Getimagesinfos[source]
getimageslist(folder)[source]

Generate a list of all images under folder, which is the actual folder being analyzed. This folder is the actual result of the iteration over the folderslist list. As written, the code will only gather .jpg images.

Note

This function should be rewritten using ignore case, and should be able to gather other images format.

Returns:
list. The list of images under the folder being analyzed.
getimagesmeta(imglist)[source]

Get metadata DateTimeOriginal from every image in imglist and store them into a list. It’s crucial to get the accurate time of creation as it is used by getimpg() to group images that were taken few seconds apart.

Format returned:

>>> datetime.datetime(2014, 8, 6, 16, 5, 55)
Returns:
list. List of datetime objects representing the exact time the image were taken.
getimpg(sortedlisttags)[source]

This will group images based on the differences in time between each shot. It is crucial that the listtags are well sorted by time.

sortimages(imglist, listtags)[source]

Sort images based on their metadata. This function can not be called before getimagesmeta.