README.md

# Plant Identifier – Hyderabad Locator (Python)

This project lets you:
1. Upload a **plant JPG** photo.
2. Identify the plant using the **Plant.id API** (AI model).
3. Show **where the plant has been observed in Hyderabad** (using the iNaturalist public API) and plot it on an interactive map.

It ships with a **Streamlit UI** (`streamlit_app.py`) so you can run everything locally in a few minutes.

---

## Features
- 📷 Image upload (JPG/JPEG/PNG) via Streamlit
- 🤖 AI recognition via **Plant.id** (top matches with confidence, scientific name, common names, wiki details when available)
- 📍 Hyderabad occurrences via **iNaturalist** (observations plotted on a Folium map)
- 🗺️ Interactive map embedded in the app
- 🔑 `.env` support for secrets

> **Note**: You need a free or paid **Plant.id** API key. Create an account at plant.id and copy your key into `.env` as `PLANT_ID_API_KEY`.

---

## File structure

```
plant-identifier-hyd/
├─ app/
│  ├─ streamlit_app.py        # Streamlit UI
│  ├─ plant_id_client.py      # Plant.id API client
│  ├─ location.py             # Hyderabad bbox + iNaturalist search
│  ├─ utils.py                # Helpers (image, env)
│  └─ static/
│     └─ styles.css           # Optional extra styles for Streamlit
├─ data/
│  └─ sample_images/          # Put example photos here
├─ tests/
│  └─ test_smoke.py           # Minimal smoke test
├─ .env.example               # Copy to .env and fill in your API key
├─ requirements.txt
└─ README.md
```

---

## Quickstart

1) **Clone or unzip** this folder.
2) Create a virtual environment (recommended):
```bash
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
```
3) **Install dependencies**:
```bash
pip install -r requirements.txt
```
4) **Set your API key**: copy `.env.example` to `.env` and put your Plant.id key.
5) **Run the app**:
```bash
streamlit run app/streamlit_app.py
```
6) Open the printed local URL in your browser.

---

## How it works

### Plant identification
We send the uploaded image to **Plant.id** (`/v3/identification`) and request the top candidates. We show:
- scientific name
- common names
- confidence score
- a short description if available

### Hyderabad locations
We query **iNaturalist** for recent observations within a Hyderabad bounding box. We then plot markers on a **Folium** map and embed it in Streamlit.

> The map shows where people have reported observing the plant in Hyderabad. This does not guarantee the plant is wild there; it simply shows community observations.

---

## Environment variables

Create a `.env` file in the project root:

```
PLANT_ID_API_KEY=your_plant_id_api_key_here
```

---

## Notes & Limits
- API quotas apply (Plant.id & iNaturalist).
- Identification quality depends on your photo (focus, lighting, background).
- iNaturalist observations depend on community contributions—some plants may have few or no reports in the Hyderabad area.

---

## Testing

```bash
pytest -q
```

---

## License

MIT. For learning and non-commercial demo use. Check Plant.id and iNaturalist terms of service for production use.