boc/atm-anomaly-detection/docs/DATASET_GUIDE.md

# ATM Anomaly Detection Dataset Guide

## Overview

This guide describes how to prepare training data for the ATM anomaly detection model.

## Directory Structure

```
data/
├── raw/                    # Original images from cameras
│   ├── atm_001_20260701_120000_front.jpg
│   ├── atm_001_20260701_120005_side.jpg
│   └── ...
├── processed/              # Resized and normalized images
│   └── ...
├── annotations/            # Label files
│   ├── atm_001_20260701_120000_front.txt
│   └── ...
└── splits/                 # Train/val/test splits
    ├── train/
    │   ├── images/
    │   └── labels/
    ├── val/
    │   ├── images/
    │   └── labels/
    └── test/
        ├── images/
        └── labels/
```

## Image Naming Convention

Format: `{atm_id}_{timestamp}_{camera_angle}.jpg`

Examples:
- `atm_001_20260701120000_front.jpg`
- `atm_001_20260701120000_side.jpg`
- `atm_002_20260701123000_wide.jpg`

## Annotation Format (YOLO)

Each `.txt` file contains one line per object:

```
<class_id> <x_center> <y_center> <width> <height>
```

All values are normalized to [0, 1] relative to image dimensions.

Example:
```
0 0.45 0.52 0.12 0.08
5 0.78 0.35 0.05 0.03
```

## Class IDs

| ID | Class Name | Description |
|----|-----------|-------------|
| 0 | physical_damage | Visible damage to structure |
| 1 | vandalism | Intentional damage |
| 2 | graffiti | Unauthorized markings |
| 3 | dirt_debris | Excessive dirt or debris |
| 4 | obstruction | Objects blocking view/access |
| 5 | skimming_device | Card skimmer attached |
| 6 | suspicious_attachment | Unknown device attached |
| 7 | out_of_service | Machine not functioning |
| 8 | screen_damage | Cracked or broken screen |
| 9 | cash_jam | Cash dispenser issue |
| 10 | receipt_jam | Printer issue |
| 11 | lighting_failure | Poor or no lighting |
| 12 | camera_blind | Security camera blocked |
| 13 | network_down | Connectivity issue |

## Annotation Guidelines

### Bounding Boxes
- Tight fit around anomaly
- Include entire affected area
- Do not include unaffected surroundings

### Multiple Anomalies
- Each anomaly gets its own bounding box
- Overlapping boxes are OK
- Same-class overlaps: merge if touching

### Difficult Cases
- Partially visible anomalies: annotate visible portion
- Ambiguous cases: mark with low confidence
- False positives in training: do not annotate

## Data Collection Best Practices

### Camera Setup
- Resolution: minimum 1920x1080
- Angle: front-facing, eye-level
- Lighting: avoid extreme shadows
- Distance: capture full ATM in frame

### Coverage
- Multiple angles per ATM
- Different times of day
- Various weather conditions
- Both normal and anomalous states

### Minimum Dataset Size
- Training: 1000+ images per class
- Validation: 200+ images per class
- Test: 200+ images per class

## Augmentation Strategy

Applied during training:
- Horizontal flip (50%)
- Brightness ±20%
- Rotation ±5 degrees
- Scale 50-150%

Not applied (preserve realism):
- Vertical flip
- Extreme rotation
- Color distortion

## Quality Checks

Before training:
1. Verify all images load correctly
2. Check annotation format
3. Validate bounding boxes within image bounds
4. Ensure class distribution is reasonable
5. Remove duplicates

## Tools

- [LabelImg](https://github.com/tzutalin/labelImg) - GUI annotation tool
- [CVAT](https://cvat.org/) - Online annotation platform
- [Roboflow](https://roboflow.com/) - Dataset management