Metadata-Version: 2.4
Name: criminaldetector_ucf
Version: 0.1.6
Summary: Real-time suspicious-activity detection using a UCF-Crime Keras model with live banner overlay
License: MIT
Project-URL: Homepage, https://github.com/your-username/criminaldetector_ucf
Project-URL: Repository, https://github.com/your-username/criminaldetector_ucf
Project-URL: Issues, https://github.com/your-username/criminaldetector_ucf/issues
Keywords: anomaly detection,criminal activity,UCF-Crime,computer vision,video analysis,deep learning,keras
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tensorflow>=2.12
Requires-Dist: opencv-python>=4.7
Requires-Dist: numpy>=1.23
Requires-Dist: yt-dlp>=2023.1.1
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# criminaldetector_ucf

[![PyPI version](https://badge.fury.io/py/criminaldetector-ucf.svg)](https://pypi.org/project/criminaldetector-ucf/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Real-time **suspicious-activity detection** powered by a UCF-Crime Keras model.  
A coloured banner is drawn in the top-left corner of every frame:

| Banner | Meaning |
|--------|---------|
| 🟩 **Status: Normal** | No anomalous activity detected |
| 🟥 **Status: Suspicious** | Potential criminal activity detected |

---

## Installation

```bash
pip install criminaldetector_ucf
```

For YouTube support `yt-dlp` is included automatically.  
For GPU acceleration install the appropriate `tensorflow` variant first.

---

## Quick Start

```python
from criminaldetector_ucf import CriminalDetector

det = CriminalDetector("best_model_ucf.keras")

# ── local video file ───────────────────────────────────────────────────────
for result in det.run("clip.mp4"):
    print(f"[{result.frame_idx:05d}] {result.label}  score={result.score:.3f}")

# ── webcam (index 0) ───────────────────────────────────────────────────────
for result in det.run(0):
    if result.label == "Suspicious":
        print(f"⚠ Suspicious activity at t={result.timestamp:.1f}s")

# ── RTSP stream ────────────────────────────────────────────────────────────
for result in det.run("rtsp://192.168.1.100:554/live"):
    pass

# ── YouTube URL ────────────────────────────────────────────────────────────
for result in det.run("https://www.youtube.com/watch?v=XXXXXXXXXXX"):
    pass
```

Press **q** or **ESC** to close the preview window.

---

## API Reference

### `CriminalDetector`

```python
CriminalDetector(
    model_path: str,
    threshold:   float = 0.5,   # score ≥ threshold → Suspicious
    frame_count: int   = 16,    # temporal window size
    input_size:  tuple = (224, 224),
    stride:      int   = 8,     # run inference every N frames
    show:        bool  = True,  # open cv2 preview window
    save_path:   str | None = None,  # save annotated video here
)
```

#### `.run(source)` → generator of `FrameResult`

| Parameter | Type | Description |
|-----------|------|-------------|
| `source` | `int` | Webcam index |
| `source` | `str` | File path, RTSP URL, or YouTube URL |

#### `.predict_clip(frames)` → `FrameResult`

Run inference on a manually assembled list of frames (must equal `frame_count`).

---

### `FrameResult`

| Field | Type | Description |
|-------|------|-------------|
| `frame_idx` | `int` | 0-based frame counter |
| `timestamp` | `float` | Seconds elapsed since stream start |
| `label` | `str` | `"Normal"` or `"Suspicious"` |
| `score` | `float` | Raw model output in `[0, 1]` |
| `frame` | `np.ndarray` | BGR frame with banner drawn |

---

## Advanced Usage

### Save annotated video to disk

```python
det = CriminalDetector(
    "best_model_ucf.keras",
    show=False,
    save_path="output.mp4",
)
results = list(det.run("input.mp4"))
print(f"Processed {len(results)} frames → output.mp4")
```

### Collect all suspicious timestamps

```python
suspicious = [
    r.timestamp
    for r in det.run("clip.mp4")
    if r.label == "Suspicious"
]
print("Suspicious at:", suspicious)
```

### Tune sensitivity

```python
# More sensitive (fires earlier)
det = CriminalDetector("best_model_ucf.keras", threshold=0.35)

# Less sensitive (fewer false positives)
det = CriminalDetector("best_model_ucf.keras", threshold=0.65)
```

### Use only the overlay helper

```python
import cv2
from criminaldetector_ucf import draw_banner

frame = cv2.imread("snapshot.jpg")
annotated = draw_banner(frame, label="Suspicious", score=0.82)
cv2.imwrite("annotated.jpg", annotated)
```

---

## Model Notes

The package expects a Keras model that:

1. **Input shape** — `(batch, T, H, W, 3)` where `T` = temporal window,
   `H × W` = frame size.  Defaults are `T=16`, `H=W=224`.  
   The package auto-reads the shape from the model if available.

2. **Output** — either a sigmoid scalar `(batch, 1)` or a softmax pair
   `(batch, 2)` where index 1 is the *anomaly* class.

3. **Custom layer** — `TemporalAttention` (package `CriminalDetector`) is
   automatically registered on import so `.keras` / `.h5` files load without
   any extra steps.

---

## Requirements

| Package | Min version |
|---------|-------------|
| `tensorflow` | 2.12 |
| `opencv-python` | 4.7 |
| `numpy` | 1.23 |
| `yt-dlp` | 2023.1.1 |

Python ≥ 3.8 required.

---

## License

MIT — see [LICENSE](LICENSE).
