Skip to content

README.md

Latest commit

 

History

History
190 lines (135 loc) · 7.33 KB

README.md

File metadata and controls

190 lines (135 loc) · 7.33 KB
Raw

AI-Based Rockfall Prediction and Alert System

An experimental safety dashboard for open-pit mining. The system accepts a site image and location, stores the image in Cloudinary, retrieves the latest upload from MongoDB, and combines slope, weather, and machine-learning features to estimate rockfall risk.

Status: This is a prototype for research and demonstration. It is not a certified mine-safety system and must not be used as the sole basis for operational decisions or emergency response.

What It Includes

  • React + Vite dashboard for image upload, location search, map display, and risk visualization.
  • Express API for Cloudinary uploads, MongoDB persistence, location search, and prediction orchestration.
  • Python prediction service that loads a trained scikit-learn model, estimates slope from an image when available, retrieves weather data, and returns a risk level.
  • Leaflet map integration for displaying the selected location and prediction result.

Architecture

Browser (Vite / React)
	|
	| upload, search, latest-info requests
	v
Express API (server/)
   |             |                 |
   v             v                 v
MongoDB      Cloudinary       Python process
				  |
				  v
			 model.pkl + WeatherAPI

Requirements

  • Node.js 18 or newer and npm
  • Python 3.10 or newer
  • MongoDB
  • A Cloudinary account
  • A WeatherAPI key
  • Jupyter and the packages listed in ml_training/requirements.txt for model training

The model artifact is intentionally not committed. Generate it from the training notebook or provide it locally at the path expected by the Python service.

The training notebook

The training workflow lives in ml_training/train_model.ipynb. Run it when the model needs to be rebuilt or when the training data or feature preparation changes.

The notebook follows this process:

  1. It loads yosemodiFinal_with_rockfall.csv into a pandas DataFrame and inspects the columns, categories, and missing values.
  2. It standardizes combined season labels such as Winter - Spring and Fall - Winter into the season categories used by the application.
  3. It fills missing season values, removes Day, Month, Time (PST), and Year, and keeps the rock-unit categories represented in the current training selection.
  4. It separates the target (Rockfall) from the input features. The feature set includes slope movement type, season, volume statistics, relative size, rock unit, slope angle, and trigger.
  5. It splits the records into training and test sets using a 20% test split and random_state=10.
  6. It builds a scikit-learn preprocessing and Random Forest pipeline. Categorical columns are one-hot encoded so the trained pipeline can accept the same string values used by the Python service.
  7. It evaluates the test predictions with accuracy, a classification report, and a confusion matrix.
  8. It serializes the complete pipeline to model.pkl with pickle.

To reproduce the model locally:

cd ml_training
python -m venv .venv
.\\.venv\\Scripts\\Activate.ps1
pip install -r requirements.txt
jupyter notebook train_model.ipynb

Run the notebook cells in order. The notebook saves model.pkl in the notebook's working directory. Keep that file at ml_training/model.pkl; the Python service loads it with the relative path ../ml_training/model.pkl when started from python_service. The generated model is ignored by Git because it is a build artifact rather than source data.

The notebook's reported accuracy is useful as a development signal, but it is not a safety guarantee. The dataset size, class balance, feature quality, geographic coverage, and validation strategy should be reviewed before relying on the model.

Configuration

Create these files locally. They are ignored by Git and must never be committed:

server/.env

PORT=4000
MONGODB_URI=
CLOUDINARY_CLOUD_NAME=
CLOUDINARY_API_KEY=
CLOUDINARY_API_SECRET=

python_service/.env

WEATHER_API_KEY=

The Python process receives the key from its environment. Do not put API keys in predict_rockfall.py, request payloads, frontend code, or browser-exposed VITE_* variables.

vite-project/.env

VITE_API_URL=http://localhost:4000

Only non-secret values should use the VITE_ prefix because Vite exposes them to browser code.

Installation

Install each service independently:

cd server
npm install

cd ..\vite-project
npm install

cd ..\python_service
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

On macOS or Linux, activate the environment with source .venv/bin/activate.

Running Locally

Start the API first:

cd server
npm start

In a second terminal, start the frontend:

cd vite-project
npm run dev

Open the Vite URL shown in the terminal, normally http://localhost:5173.

The API normally listens on http://localhost:4000 and exposes:

Method Route Purpose
GET / Health response
POST /api/upload-image Upload one image using multipart field image
GET /location/search-location?q=... Search locations through Nominatim
GET /location/locate?q=... Resolve a location
GET /location/get-latest-info Run prediction for the latest stored image

Prediction Inputs and Outputs

The backend sends the latest image location to Python through standard input as JSON. The predictor returns coordinates, slope angle, weather values, trigger, risk probability, risk level, and a timestamp.

Risk levels are currently mapped as follows:

Probability Level
< 0.20 MINIMAL
0.20-0.39 LOW
0.40-0.59 MEDIUM
0.60-0.79 HIGH
>= 0.80 CRITICAL

Data and Model Notes

  • Training data and the notebook are under ml_training/.
  • The runtime expects ml_training/model.pkl; this generated model is not included in the repository.
  • The live model receives fixed values for several fields, including volume, relative size, rock unit, and slope movement type. These defaults limit how much a prediction reflects the selected site.
  • DEM processing currently treats grayscale image values as elevation and uses fixed geographic bounds in the Python script. Replace these assumptions with calibrated DEM metadata before scientific or operational use.
  • If DEM or weather retrieval fails, the predictor uses fallback estimates. These fallbacks are useful for development but are not reliable measurements.

Security and Repository Hygiene

  • Keep .env files, credentials, model artifacts, virtual environments, node_modules, caches, and generated outputs out of Git.
  • Use least-privilege MongoDB and Cloudinary credentials, restrict allowed origins in production, and add authentication and rate limiting before deployment.
  • Review uploaded-file type, size, and content validation before exposing the API publicly.

Development Checks

cd vite-project
npm run lint
npm run build

cd ..\server
node --check server.js

There is currently no automated test suite. Prediction, upload, database failure, missing model, invalid image, and malformed-location cases should be covered before production use.

License

No project license has been specified yet. Add a license file before accepting external contributions or publishing the project for reuse.