Installation Guide

Before You Start

Get these sorted first, otherwise step 2 will fight you.

• Python 3.10 or 3.11. Grab it from python.org. Not 3.12 — TensorFlow 2.16 doesn't support it on every platform and you'll waste an hour finding that out. During the Windows installer, tick "Add Python to PATH" or nothing on this page will work.
• About 3 GB of free disk space for the virtual environments.
• 4 GB of free RAM while training, 2 GB to run the app.
• The Agricultural Crops Image Dataset. Download it and arrange it so the 30 class folders sit directly inside a folder named Agricultural-crops-dataset — almond, banana, cardamom and so on, no extra nesting.
• A GPU is optional. Nice, not necessary.

Step 1 — Set up the training environment

Open a terminal in the project folder and create a virtual environment:

python -m venv venv
source venv/bin/activate

On Windows that activate line is venv\Scripts\activate instead. You'll know it worked when (venv) appears at the start of your prompt.

Now install the packages:

pip install --upgrade pip
pip install tensorflow==2.16.1 numpy pandas matplotlib seaborn scikit-learn pillow jupyter

On a Mac with an M1, M2 or M3 chip, swap that TensorFlow line for pip install tensorflow-macos tensorflow-metal. This install takes a few minutes. Go make chai.

Step 2 — Train the model

jupyter notebook crop_classification_training.ipynb

Your browser opens with the notebook. Find the config cell near the top and set DATA_DIR to wherever your dataset folder actually lives. Then run every cell from top to bottom, in order. Don't skip around.

When it's done, an artifacts/ folder appears containing crop_cnn_model.keras (about 29 MB), labels.json, metrics.json, an optional crop_cnn_model.tflite, and a handful of PNG training charts.

In a hurry? Set CFG["TRAIN_SCRATCH_BASELINE"] = False before running to skip the comparison model.

Step 3 — Set up the web application

The Flask app gets its own environment. Keep them separate.

cd cropvision

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Step 4 — Copy the model artifacts across

cp -r ../artifacts ./artifacts

On Windows, just drag the folder in. The app needs crop_cnn_model.keras and labels.json at minimum. The metrics.json file and the charts are optional and only affect what the model card page can display.

Step 5 — Configure your environment file

cp .env.example .env

Open .env and fill it in:

SECRET_KEY=paste_a_long_random_string_here
ARTIFACT_DIR=artifacts
MAX_UPLOAD_MB=8
ENABLE_GRADCAM=1
TOP_K=3

Generate a proper secret key rather than typing "abc123":

python -c "import secrets; print(secrets.token_hex(32))"

Step 6 — Run it

python app.py

Open http://localhost:5000 in your browser and drop a crop photo onto the upload box. The first prediction takes a few seconds because TensorFlow initialises lazily on first load. Every request after that is fast.

Checking It Actually Works

Confirm the model loaded:

curl http://localhost:5000/health

You want to see {"status": "ok", "model": "loaded", "classes": 30, "gradcam": true}. If classes says anything other than 30, your labels file is wrong.

Test the API directly:

curl -X POST http://localhost:5000/api/predict -F "image=@test_leaf.jpg"

And check the templates without TensorFlow involved at all:

pip install flask pillow numpy
python smoke_test.py

Things That Usually Go Wrong

"Model file not found" on every page

Step 4 didn't happen, or it happened into the wrong folder. Check that cropvision/artifacts/crop_cnn_model.keras exists. If you put the artifacts somewhere else on purpose, point ARTIFACT_DIR in .env at that path.

Predictions are confident but wrong on phone photos

EXIF rotation is getting stripped somewhere, so the model is looking at a sideways image. Confirm ImageOps.exif_transpose is still sitting inside _prepare() in model_service.py.

Accuracy is suspiciously close to 100%

Duplicate removal is off. Set CFG["DROP_DUPLICATES"] = True and retrain. This one matters — an inflated number is worse than a lower honest one.

Worker gets killed during startup on a VPS

TensorFlow holds 500 to 700 MB per Gunicorn worker. On a 2 GB server set workers = 1 in deploy/gunicorn_config.py, on 4 GB set 2, and use threads for concurrency instead. Leave preload_app off; forking after TensorFlow initialises is unreliable.

Unstyled 413 error when uploading

Nginx rejected the file before Flask saw it. Raise client_max_body_size in the Nginx config above whatever MAX_UPLOAD_MB is set to.

First request is really slow

That's expected, not a bug. TensorFlow initialises lazily and the warm-up pass runs on first load. Don't demo the very first request in front of your examiner. Hit the page once beforehand.