This repository contains the code for developing a machine learning model to estimate soil crop residue levels from images. Designed for integration into a mobile application, this model aims to provide a quick, accessible alternative to traditional residue estimation methods, like the line-transect method.

This project is containerized with Docker; to set up and run this project, it is recommended to have Docker installed on your machine. This will standardize the development environment and make the use of HPC resources easier.

Note: The commands in this guide are provided in Bash and were run from the repository directory on an Ubuntu system.

git clone https://github.com/brandonxu360/residue-estimator.git
cd residue-estimator

• Ensure you have the necessary image data stored in a local folder. By default, this is expected to be in the data/ directory at the root level of the project.
• The image data can be found at here. You may need to request access from maintainers.
• Inside the data/ folder, the structure should precisely follow that of the online data source. It is easiest to simply download the data into the /data folder. In general, you can expect:
  • data/images/label — containing the labeled images
  • data/images/original — containing the original images

Note: If your data is stored elsewhere, you will need to provide the correct location when running the container.

Our Docker images can be found on our Docker Hub Repository.

Recommended: Instead of building the Docker image from scratch, you can pull it directly from Docker Hub using the following command:

docker pull brandonxu/residue-estimator-model:version1.1

This is recommended to guarantee image consistency.

Alternatively, use the following command to build the Docker image from the Dockerfile:

docker build -t brandonxu/residue-estimator-model:version1.1 .

After pulling the Docker image, run the container with the following command, mapping your local data directory to the container:

docker run --rm -v $(pwd)/data:/app/data brandonxu/residue-estimator-model:version1.1

For interactive mode, use:

sudo docker run --rm -u $(id -u):$(id -g) -it -v "$(pwd)/data:/app/data" brandonxu/residue-estimator-model:version1.1

Note: If your data is stored in a different location, please replace $(pwd)/data with that location.

For more information about running containers, please visit the Docker docs:

• Docker Manual - Running Containers
• Docker Docs Reference - Run

For access requests or further information, please contact:

• Brandon Xu
• Amin Norouzi