mewc-predict

Introduction

This repository contains code to build a Docker container for running mewc-predict. This is a tool used to perform inferencing for classifying species from camera trap images. The classification engine used in mewc-train is EfficientNetV2. The tool relies on a trained model file that is generated by mewc-train. Additionally you will need to have pre-processed the images to classify with MegaDetector using mewc-detect. After detection snip out the detected animals using mewc-snip which will place tightly bounded animal snip images in a subdirectory called snips.

You can supply arguments via an environment file where the contents of that file are in the following format with one entry per line:

VARIABLE=VALUE

Version 2 Updates

The mewc-predict Docker image has been updated to version 2. Key updates include:

• Base Image: Uses the new mewc-flow base image featuring tensorflow/tensorflow:2.16.1-gpu, CUDA, cuDNN, and JAX.
• Easy Model Selection: Compatible with models trained using mewc-train v2.

For users who wish to continue using version 1, the older Dockerfile and requirements can still be accessed by checking out the v1.0.11 tag:

git checkout v1.0.11

Usage

After installing Docker you can run the container using a command similar to the following. The --env CUDA_VISIBLE_DEVICES=0 and --gpus all options allow you to take advantage of GPU accelerated training if your hardware supports it. Substitute "$INPUT_DIR" for your image directory that contains and create a text file "$ENV_FILE" with any config options you wish to override.

You need to supply a keras model (shown in the command below as $SAVEFILE_$MODEL_final.keras) and a corresponding class mapping file (shown as $SAVEFILE_class_map.yaml) to the Docker command. These files are generated by training a model using mewc-train.

docker pull zaandahl/mewc-predict
docker run --env CUDA_VISIBLE_DEVICES=0 --gpus all \ 
    --env-file "$ENV_FILE" \
    --interactive --tty --rm \
    --volume "$INPUT_DIR":/images \
    --volume "/path/to/$SAVEFILE_$MODEL_final.keras":/code/model.keras \
    --volume "/path/to/$SAVEFILE_class_map.yaml":/code/class_map.yaml \
    zaandahl/mewc-predict

Optional SavedModel: if you export a TensorFlow SavedModel during training, you can mount the directory to /code/model_export and set nothing else. The container will prefer loading the SavedModel when that directory is present:

--volume "/path/to/exported_model_dir":/code/model_export \

Config Options

The following environment variables are supported for configuration (and their default values are shown). Simply omit any variables you don't need to change and if you want to just use all defaults you can leave --env-file $ENV_FILE out of the command alltogether.

Variable	Default	Description
MODEL	"ENB0"	Model architecture: EN:[B0,B2,S,M,L,XL], CN:[P,N,T,S,B,L], ViT:[T,S,B,L]
INPUT_DIR	"/images/"	A mounted point containing images to process - must match the Docker command above
PRED_FILE	"mewc_out.pkl"	EfficientNetV2 output PKL file, must be located in INPUT_DIR
PRED_CSV	"mewc_out.csv"	CSV file containing EfficientNetV2 output, must be located in INPUT_DIR
RENAME_SNIPS	True	Rename snipped images to a random string of characters after processing
SNIP_DIR	"snips"	A subdirectory under INPUT_DIR to find snipped images
SNIP_CHARS	16	Number of random characters to use when renaming snipped images
BATCH_SIZE	16	Batch size for EfficientNetV2 input
TOP_CLASSES	True	Output only top classes for each image
USE_SAVEDMODEL	True	Prefer a TensorFlow SavedModel if found at MODEL_EXPORT_DIR
MODEL_EXPORT_DIR	"/code/model_export"	Where to mount an exported SavedModel directory
MODEL_PATH	"/code/model.keras"	Path to a mounted .keras file (staged to /tmp before load)
SAFE_MODE	True	Keras safe loading; keep True unless measuring load-speed tradeoffs
XLA_JIT	"auto"	XLA JIT control: "auto" (default), "on", or "off"

Notes:

• XLA can introduce a one-time compile cost (you may see a log line like "Compiled cluster using XLA!"). For small, single-pass inference jobs, set XLA_JIT=off to avoid this overhead. For larger batches or repeated runs, XLA_JIT=on may help.
• The model file is staged from /code/model.keras to /tmp/model.keras to avoid slow bind-mount I/O on Windows; this is intentional for faster startup.

GitHub Actions and DockerHub

This project uses GitHub Actions to automate the build process and push the Docker image to DockerHub. You can find the image at:

• zaandahl/mewc-predict DockerHub Repository

For users needing the older version, the v1.0.11 image is also available on DockerHub by using the appropriate tag:

docker pull zaandahl/mewc-predict:v1.0.11