Update README.md

README.md

@@ -7,4 +7,77 @@ base_model:
 - vikhyatk/moondream2
 pipeline_tag: image-text-to-text
 library_name: transformers
----
+---
+
+# Perception-moondream2
+
+**Perception-moondream2** is a specialized Vision-Language Model (VLM) fine-tuned for dense urban traffic scene understanding. Built on top of the highly efficient `moondream2` architecture, this model is designed to analyze CCTV and traffic camera feeds to generate highly detailed, comprehensive textual descriptions of traffic conditions.
+
+## Model Details
+- **Base Model:** [vikhyatk/moondream2](https://huggingface.co/vikhyatk/moondream2) (Revision: 2024-08-26)
+- **Architecture:** Vision Encoder + Phi-1.5 Text Decoder
+- **Task:** Dense Image Captioning & Visual Question Answering (VQA)
+- **Language:** English
+
+## Training Data
+The model was fine-tuned on the [Subh775/Traffic-Perception-VL](https://huggingface.co/datasets/Subh775/Traffic-Perception-VL) dataset. This dataset consists of complex, real-world urban traffic scenes (such as bustling streets in Bengaluru, India). 
+
+The training focused on teaching the model to accurately perceive and describe:
+- **Vehicle Types & Colors:** Identifying auto-rickshaws, scooters, motorcycles, and cars.
+- **Traffic Density & Flow:** Estimating congestion levels and movement.
+- **Pedestrian Activity:** Tracking people walking on sidewalks or crossing streets.
+- **Infrastructure:** Recognizing road layouts, lanes, shops, signage, and greenery.
+
+## Intended Use Cases
+- **Smart City Analytics:** Automated monitoring of CCTV feeds to detect congestion or accidents.
+- **Traffic Management:** Generating real-time text logs of intersection activity.
+- **Autonomous Driving Context:** Providing dense contextual descriptions for self-driving datasets.
+
+---
+
+## Usage and Inference
+
+Because this model relies on the custom Moondream2 architecture, you will need to use `trust_remote_code=True` when loading it via the `transformers` library.
+
+### Prerequisites
+Make sure you have the required libraries installed:
+```bash
+pip install transformers pillow einops
+```
+### Python Inference Script
+```python
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from PIL import Image
+
+# 1. Define the model ID
+model_id = "Subh775/Perception-moondream2"
+
+# 2. Load the tokenizer and model
+# Note: trust_remote_code=True is required for the moondream2 architecture
+tokenizer = AutoTokenizer.from_pretrained(model_id)
+model = AutoModelForCausalLM.from_pretrained(
+    model_id, 
+    trust_remote_code=True,
+    torch_dtype=torch.float16, # Recommended for memory efficiency
+    device_map="auto"
+)
+
+# 3. Load your traffic/CCTV image
+image_path = "path_to_your_traffic_image.jpg"
+image = Image.open(image_path).convert("RGB")
+
+# 4. Encode the image using the vision encoder
+enc_image = model.encode_image(image)
+
+# 5. Ask the model to describe the scene
+# We use the same prompt that the model was fine-tuned on
+prompt = "Describe this traffic scene in detail."
+
+answer = model.answer_question(enc_image, prompt, tokenizer)
+
+print("Traffic Scene Analysis:")
+print("-" * 50)
+print(answer)
+```
+