# User Manual

This section provides an exhaustive description about how to use OpenCFU. If you are using it for the first time, you should maybe have a look at the video tutorial section. Questions and feedback are more than welcome, so feel free to contact me. In this manual, I will use the example of bacterial colonies, but you can obviously use the same instructions for whatever circular objects you wish to count.

## Installation

### Windows Users

Simply run and download the setup.

### GNU/Linux Users

Linux users can compile OpenCFU for their machine. Information is available in the developers' corner.

### MacOSX

OpenCFU is not available for Mac OSX yet.

## The User Interface

The three main areas of the graphical interface.

### Panel

The top of the panel shows the result as “X/Y”, where X is the number of valid colonies and Y is the total number of objects including excluded ones. The result can be set as “NA” by clicking on the “Set as NA box”. “Show objects” and “Line width” can be modified to change how the objects are represented on the display without changing the results.

In this example 62 bacterial colonies while valid and 8 have been excluded.

The bottom part of the panel allow the user to change processing parameters.

### Image display

The processed image is annotated with yellow and blue rectangles for each valid colony or red and black rectangles for invalid colonies. Scrolling up and down with the mouse will zoom in and out. Left-clicking on an colony will select it while right-clicking will change its state (e.g. valid -> invalid).

Here, the two non-colony objects are excluded.

### Results

The results of the processing are shown below the display. They can be saved and altered (see Results).

## Processing Parameters

Each time a processing variable is modified in the panel, the program will automatically re-analyse the image accordingly.

### Input Images

OpenCFU accepts usual types of images (JPEG, TIFF, PNG, BMP...). The images can be either in colour or grey-scale. It is possible to add several files at the same time or to drag-and-drop files from a folder. After loading the first files, one can browse the list of files using the “<<”, “<”, “>” and “>>” buttons.

### Threshold

The threshold can be one of three types: “regular”, “inverted” or “bilateral” according to the relative darkness of the colonies compared to the background.

From left to right, these images should be analysed with a regular, inverted and bilateral threshold.

The value of threshold is a number defining how stringent the analysis will be. The higher the threshold the more likely colonies will be missed. Conversly, a very low threshold could result in false positives. Usual values are between 3 and 30. It is also possible to ask OpenCFU to find a value of threshold automatically (“Auto”).

### Radius

This parameter allows the user to constrain the analysis to objects of a certain size (between “Min” and “Max”). The size is in pixel. The minimal radius is an important parameter as it allows the user to exclude very small particles/noise that otherwise would be interpreted as colonies. By default, the maximal radius is automatically calculated from the image dimensions (“Auto-max”), but can be manually specified.

### ROIs and Mask

In OpenCFU, it is possible to define one or several regions of the image where the colonies lie. This is useful when the goal is to enumerate colonies in different areas. Different methods allow users to apply a mask:

- None: the default method; the entire image is used, no mask is set.
- Draw mask: A video tutorial explains how to draw masks. Briefly, a built-in tool to draw mask will pop up and allow to draw multiple circular or polygonal masks. To draw a circular mask, one simply clicks on three points of a the edge of the circle. Clicking on “+/add” whilst drawing a polygon will close the shape.
- From file: A video tutorial explains how to use an external file as a mask. Briefly, the mask file (e.g. a PNG file) should be a grey-scale image in which each level of grey represents a region.
- Auto: If the colonies are located in a circular container such as bacterial colonies in a Petri dish, the program can try to detect the container and define it as a ROI.

### Colour Filter

It is often possible to use colour information in order to improve colonies discrimination or to exclude unwanted objects. OpenCFU provides two variables to play with:

- Hue: this is an angle (between 0 and 360°) corresponding roughly to the “colour”(e.g. red, green, blue...). In OpenCFU, the user can specify a given hue ± a tolerance value (from 0 to 180°). If the distance between the hue of an object and the selected hue is higher than the tolerance, it will be excluded.
- Saturation: the saturation is an approximation of how “vibrant” a colour is. It ranges from 0 (the colour is grey) to 255 (extremely colourful). See the wiki pages for hue and saturation.

### Auto Outlier Filter

OpenCFU can also automatically find objects that are different from the average objects and exclude them. In order to do this, the software will first calculate the “average object colour” and then exclude colonies that are too different from this value. If there are too few (less than 10) clearly defined objects, the filter will not work.

## Results

### Per image

For each image, a summary result is given. It contains the following information:

- ID: a unique identifier.
- File name: the name of the input file.
- #Objects: the number of valid objects/colonies.
- #Excluded: the number of objects/colonies that have been excluded by filters (i.e. ROI, colour or auto-filter).
- Comment: An optional user-writable comment that can for instance describe the image.
- Full path: The complete path to the analysed image. This is useful when working with images with the same names in different folders.

### Per Object

In addition to the summary result, a list of objects is displayed. When clicking on a row of the list, the corresponding object will be highlighted on the display. Conversely, when left-clicking on an object in the display, the corresponding row will be selected in the list. Objects are can be sorted according to several criteria by clicking on the name of one of the features:

- ID: a unique identifier.
- Valid: whether the object has not been excluded by filters. One can click on the valid box to override the result given by OpenCFU. This is also possible by right clicking on the object in the display.
- X and Y: the X and Y coordinates of the of the center of the object (the origin being at the top-left of the image).
- ROI: the ROI in which the colony lies, or “0” if the colony does not belong to any ROI (in this case it is excluded by default). When no mask is used the ROI is 1 for all colonies (see ROI and Masks).
- Area: the area of the colony in number of pixels.
- Radius: the radius of the colony in pixels.
- R, G and B: the intensity of red, green and blue, from 0 to 255.
- Hue and Sat: the hue and saturation (see Colour Filter).
- #N in Cluster: the number of colony in the same “cluster” as the object/colony. Colonies that have been separated form each other during processing belong to the same cluster.

### Saving results

In order to save results, one simply needs to click on the “Save all” button, at the bottom of the result panel. A dialogue then will ask what kind of output is wanted. A summary output corresponds to the “Per image” result representation while a detailed output is similar to the “Per object” list (but for all images). In both cases, the result must be a saved as a CSV file.

## Getting Good Pictures

TODO

##