Tutorial - CameraTrapDetectoR/DesktopApp GitHub Wiki

This tutorial goes over how to use the CameraTrapDetectoR desktop application.

If you haven't already, install the package.

We've provided five test images you can use to follow along with the demo and test out different model arguments. Download and extract the images, save them to an easily accessible directory, and proceed to launching the application.

Organize your image directory

An organized image directory is essential to making sure your CameraTrapDetectoR session runs smoothly. Place all images to be run through the model in the same directory. You may set up a recursive directory with images in different folders, but make sure to remove any images you do not wish to run through the model. CameraTrapDetectoR only searches for file types specified in the file_extensions argument; it will ignore all other file types.

The model was trained on images of size 408 x 307 pixels, and will resize your images before running them through the neural network. You may see a slight decrease in model run time if you resize your images to these dimensions before running the model.

You have the option to enter location data for your images (latitude / longitude) to help narrow down potential species. However, this option can only be set once for all images in a given model run. If you would like to use this option, all your images must originate from the same location. Alternatively, you can split your image directory by location, and run the model separately on images from each location.

Launch the app

Double click the desktop shortcut you extracted in the installation process. You should see a pop-up window with the drop-down arguments on the left, and brief explanations of each argument on the right. See the Troubleshooting section of the install page if your app screen is blank.

Set your data directory

The only argument you must specify is the location of your images. Click the data_dir button to open your file directory, then use the black arrows to the left of the folders to navigate to your image directory. Once you navigate to the folder that contains all your images, click the text on the left pane to select that folder. If you have organized your images in multiple folders, select the folder that contains all your separate image folders and set the recursive argument to TRUE so the model sees all your images. If you wish to only run images in a particular folder or sub-directory, make that selection carefully so you do not send extra images through the model.

Set other model arguments

You are technically able to run the model with all other arguments set at default values. However, we encourage you to carefully consider your research questions and thoughtfully set the remaining model arguments:

model_type

This drop-down menu allows you to select which model you would like to run. CameraTrapDetectoR currently supports four different models. The general model predicts to the level of mammal, bird, human, and vehicle. The family model recognizes 33 unique taxonomic families listed in Table 3. The species model recognizes 75 unique taxonomic species listed in Table 2. The pig_only model outputs only two labels: pig, not pig; this model was developed for applications to feral swine research.

recursive

This TRUE / FALSE drop-down menu tells the program if it should search for images within all folders inside your selected data_dir. If you have images stored in different folders you wish to send to the model, select TRUE.

redownload

This TRUE / FALSE drop-down menu tells the application whether or not to download the latest model weights stored online. It is advisable to occasionally update your model this way in order to obtain the best-performing model. You may need to be disconnected from VPN in order to download new model weights.

file_extensions

CameraTrapDetectoR currently supports the following file types: .jpg, .png, .tif, and .pdf. You can specify these file types by checking or unchecking the boxes on the Arguments menu. The model will ignore any files inside your data_dir that are not one of the accepted file types. More chosen file types does not penalize speed; if you want to guarantee all eligible images are run through the model, check all boxes.

make_plots

CameraTrapDetectoR has the ability to return copies of your images with boxes around its predictions in real time. If you would like to activate this option, select TRUE.

plot_label

If you choose make prediction plots, you also have the option to label your predictions on the image. These labels are determined by the classes of your model_type.

output_dir

This argument determines where your model output is stored. The default argument is to leave it empty, which creates a folder inside your data_dir named after model_type and date-time the model began running.

sample50

A large image data set will take a long time to run; you may want to check your model arguments on a smaller sample before committing to a full model run. In this testing process, set this argument to TRUE.

write_bbox_csv

Some users may want the placement and dimensions of predicted bounding boxes. Setting this argument to TRUE will return a .csv file in your output directory titled predicted_bboxes. This file has a separate row for each prediction with the following fields: full image path; predicted class; confidence in prediction;total predictions per image; and bounding box coordinates. Bounding box coordinates are given with (XMin, YMin) and (XMax, YMax) points corresponding to the upper left and lower right corners of the bounding box, in proportion to image size (i.e. coordinates are in the range [0, 1]).
The file will contain all model predictions, even those below the chosen score_threshold.

score_threshold

The model provides a confidence score for every prediction, indicating the model's level of confidence in that prediction. CameraTrapDetectoR only reports predictions above the set score threshold. A lower score threshold may capture more true predictions, but may also report more false predictions. A higher score threshold will reduce false predictions, but may also fail to capture some true predictions. An optimal score threshold will depend on your research questions and your images. You may want to run a small sample through the model using different score thresholds to determine what threshold is best for your data. You can either type in your selection between 0 and 0.99, or click the arrows to toggle by increments of 0.01.

overlap_correction

It is possible that predicted bounding boxes on the same image may overlap. Overlapping bounding boxes may be due to the presence of multiple individuals occupying close space. Alternatively, overlapping bounding boxes may be caused by multiple predictions of the same individual. If you wish to assess overlapping boxes and combine boxes that overlap into a single prediction, set this argument to TRUE and choose a reasonable overlap_threshold. Using this feature depends on the context of your research question and your data.

overlap_threshold

If you use an overlap correction, this argument sets the proportion of overlapping area of two boxes for them to be returned as a single detection. An optimal overlap threshold will depend on your research questions and your images. You may want to run a small sample through the model using different overlap thresholds to determine what threshold is best for your data. You can either type in your selection between 0 and 0.99, or click the arrows to toggle by increments of 0.01.

return_data_frame

This argument is not applicable to desktop app users; leave it as the default FALSE.

prediction_format

Your model output file can be delivered in two different formats: long or wide. The long format file contains one row for each predicted class per image, with five columns:

  • filename: full pathway to to image
  • prediction: predicted model class
  • confidence_in_pred: confidence score for the prediction
  • count: number of individuals detected for the predicted class in an image
  • certainty: additional confidence measure with four possible values:
    • no detection: the model did not detect any objects in the image
    • detection below score threshold: the model made a prediction, but the confidence score was below your chosen score threshold. You may want to review this image manually, or lower your score threshold if many such predictions appear in your output.
    • multiple predictions: the model made multiple predictions above your set score threshold for the object detected; the output only lists the prediction with the highest confidence score. You may want to review this image manually.
    • single prediction: this is the only prediction for the detected object above your score threshold.

The wide format file contains one row for each image. The first column contains the full pathway to the image. The subsequent columns list all possible prediction classes from your chosen model type, including an empty column for no predictions. The value in each cell contains the number of individuals predicted for that class for that image. This format does not contain additional confidence information.

latitude & longitude

You can filter predictions from the species model by location. If all your images originate from the same location, you can enter the latitude and longitude (in degrees) here to filter out species whose ranges do not include this location. If the model predicts a species non-existent at your location, CameraTrapDetectoR will review similar possible species to the prediction and make an adjusted prediction. If no similar species exist in the prediction classes, CameraTrapDetectoR will label this detection as "Animal". All images with this prediction should be manually reviewed.

h & w

If you decide to plot your bounding boxes, CameraTrapDetectoR will automatically create image copies with the same dimensions as your original image. If you want to change those dimensions, enter pixel values for height and width in these arguments. Setting image dimensions to the model defaults, $h=307$ and $w=408$, may slightly improve model run time.

lty

If you decide to plot your bounding boxes, you can adjust the line type of the bounding boxes using this argument. It accepts intergers 1-6 corresponding to the following values: 1 = solid (default); 2 = dashed, 3 = dotted, 4 = dotdash, 5 = longdash, 6 = twodash.

lwd

If you decide to plot your bounding boxes, you can adjust the line thickness of the bounding boxes using this argument. It accepts numbers greater than 0; the default is 2.

col

If you decide to plot your bounding boxes, you can adjust the line color of the bounding boxes using this argument. The drop-down argument provides various color options.

Run the model

Once you have assigned all arguments, you are ready to run the model by clicking the Run model button. Do not close the app before your model run is complete. While the model is running, you will see a pop-up window with details on accessing your output directory. Once the model is finished, this pop-up will disappear. Depending on your internet connection and how many images you run through the model, this may take a long time.