Organize repo: add examples, model code and updated model card

.gitattributes

@@ -33,3 +33,9 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+assets/detection_example.png filter=lfs diff=lfs merge=lfs -text
+examples/inputs/house_and_plate.png filter=lfs diff=lfs merge=lfs -text
+examples/inputs/street.png filter=lfs diff=lfs merge=lfs -text
+examples/outputs/house_and_plate_anonymized.png filter=lfs diff=lfs merge=lfs -text
+examples/outputs/plate_anonymized.jpg filter=lfs diff=lfs merge=lfs -text
+examples/outputs/street_anonymized.png filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,42 +1,118 @@
+---
+library_name: pytorch
+pipeline_tag: object-detection
+tags:
+  - object-detection
+  - faster-rcnn
+  - torchvision
+  - license-plate-detection
+  - house-number-detection
+  - anonymization
+  - privacy
+  - street-view
+---
+
 <p align="center">
-  <img src="panner.png" width="1200" alt="Vision-AN18 banner" />
+  <img src="assets/banner.png" width="1200" alt="Vision-AN18 banner" />
 </p>
 
-# Vision-AN18
+# Vision-AN18 — Faster R-CNN
 
 Privacy-preserving computer vision for detecting and anonymizing sensitive visual information in street images.
 
-## Overview
+Vision-AN18 detects **license plates** and **house numbers** in street-level images (Google Street View style), then blurs the detected regions to preserve privacy while keeping the rest of the image useful.
+
+## Examples
 
-Vision-AN18 is a deep learning pipeline designed to detect license plates and house numbers in public images (STREET VIEW GOOGLE MAPS DESIGN MODEL), then blur the identified regions to preserve privacy while keeping the overall image useful.
+Original image on the left, output of the anonymization pipeline on the right (Gaussian blur applied to each detected box).
 
-The project combines:
+| Original | Anonymized |
+| :---: | :---: |
+| ![Plate original](examples/inputs/plate.jpg) | ![Plate anonymized](examples/outputs/plate_anonymized.jpg) |
+| ![House and plate original](examples/inputs/house_and_plate.png) | ![House and plate anonymized](examples/outputs/house_and_plate_anonymized.png) |
+| ![Street original](examples/inputs/street.png) | ![Street anonymized](examples/outputs/street_anonymized.png) |
 
-- a data preparation pipeline,
-- a Faster R-CNN detection model,
-- an anonymization module,
-- a FastAPI inference service,
-- a simple Gradio demo for testing.
+### Raw detection
 
-## Key Features
+<p align="center">
+  <img src="assets/detection_example.png" width="700" alt="License plate detection example" />
+</p>
 
-- License plate detection
-- House number detection
-- Gaussian blur anonymization
-- Dataset preprocessing pipeline
-- Inference and deployment support
-- GPU-ready training workflow
+> ⚠️ **Known limitations** — license plate detection is reliable. House number detection is still imperfect (scale bias inherited from the SVHN dataset used for this class), and the model can produce false positives on large flat regions such as windows or walls (see the third example).
 
 ## Model
 
-The detection model is based on Faster R-CNN with a ResNet-50 + FPN backbone.
+| | |
+| --- | --- |
+| Architecture | Faster R-CNN |
+| Backbone | ResNet-50 + FPN |
+| Framework | PyTorch / torchvision |
+| Classes | `0: background`, `1: license_plate`, `2: house_number` |
+| Input size | min 800 / max 1333 px (resized internally) |
+| Training data | OpenLPR (plates) + SVHN (house numbers) |
+| Training hardware | NVIDIA RTX 5050 |
+
+## Usage
+
+```python
+import torch
+from PIL import Image
+import torchvision.transforms.functional as TF
+from huggingface_hub import snapshot_download
+import sys
+
+repo_dir = snapshot_download("ApyHTML19/Faster-RCNN-Vision-ANN18")
+sys.path.insert(0, repo_dir)
+from models.faster_rcnn import create_model
+
+device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+model = create_model(num_classes=3, pretrained_backbone=False)
+checkpoint = torch.load(f"{repo_dir}/best_model.pth", map_location=device)
+model.load_state_dict(checkpoint.get("model_state_dict", checkpoint))
+model.to(device).eval()
+
+CLASS_NAMES = {1: "license_plate", 2: "house_number"}
+
+image = Image.open(f"{repo_dir}/examples/inputs/plate.jpg").convert("RGB")
+with torch.inference_mode():
+    output = model([TF.to_tensor(image).to(device)])[0]
+
+for box, label, score in zip(output["boxes"], output["labels"], output["scores"]):
+    if score >= 0.5:
+        print(CLASS_NAMES[int(label)], f"{score:.3f}", [round(v) for v in box.tolist()])
+```
+
+### Blurring the detections
+
+```python
+import cv2
 
-Training was performed on an NVIDIA RTX 5050, and the model is intended to be shared on Hugging Face for easier reproducibility and deployment.
+img = cv2.imread(f"{repo_dir}/examples/inputs/plate.jpg")
+for box, score in zip(output["boxes"], output["scores"]):
+    if score < 0.5:
+        continue
+    x1, y1, x2, y2 = map(int, box.tolist())
+    img[y1:y2, x1:x2] = cv2.GaussianBlur(img[y1:y2, x1:x2], (51, 51), 0)
+cv2.imwrite("anonymized.jpg", img)
+```
 
-## Repository Structure
+## Repository structure
 
-Avainble soon on github repo
+```text
+Faster-RCNN-Vision-ANN18/
+├── README.md              # this model card
+├── best_model.pth         # trained checkpoint
+├── models/                # model definition (Faster R-CNN + ResNet-50 FPN backbone)
+│   ├── __init__.py
+│   ├── backbone.py
+│   └── faster_rcnn.py
+├── examples/
+│   ├── inputs/            # original test images
+│   └── outputs/           # anonymized results
+└── assets/                # banner and illustration images
+```
 
-## License
+## Intended use
 
-This project is intended for research and privacy-oriented computer vision experiments.
+Research and privacy-oriented computer vision experiments: anonymizing license plates and house numbers in street-level imagery before storage or publication. Not intended for surveillance or for identifying individuals.

models/backbone.py

@@ -0,0 +1,35 @@
+import torch
+import torch.nn as nn
+from torchvision.models import resnet50, ResNet50_Weights
+from torchvision.models._utils import IntermediateLayerGetter
+from torchvision.ops import FeaturePyramidNetwork
+from torchvision.ops.feature_pyramid_network import LastLevelMaxPool
+class ResNet50FPNBackbone(nn.Module):
+    def __init__(self, pretrained=True, out_channels=256):
+        super().__init__()
+        weights = ResNet50_Weights.DEFAULT if pretrained else None
+        resnet = resnet50(weights=weights)
+        self.body = IntermediateLayerGetter(
+            resnet,
+            return_layers={
+                "layer1": "c2",
+                "layer2": "c3",
+                "layer3": "c4",
+                "layer4": "c5"
+            }
+        )
+        self.fpn = FeaturePyramidNetwork(
+            in_channels_list=[
+                256,
+                512,
+                1024,
+                2048
+            ],
+            out_channels=out_channels,
+            extra_blocks=LastLevelMaxPool()
+        )
+        self.out_channels = out_channels
+    def forward(self, x):
+        features = self.body(x)
+        features = self.fpn(features)
+        return features

models/faster_rcnn.py

@@ -0,0 +1,89 @@
+import torch
+from torchvision.models.detection import FasterRCNN
+from torchvision.models.detection.rpn import AnchorGenerator
+from torchvision.ops import MultiScaleRoIAlign
+from .backbone import ResNet50FPNBackbone
+class VisionAN18FasterRCNN(FasterRCNN):
+    def __init__(
+        self,
+        num_classes=3,
+        pretrained_backbone=True
+    ):
+        backbone = ResNet50FPNBackbone(
+            pretrained=pretrained_backbone,
+            out_channels=256
+        )
+        anchor_generator = AnchorGenerator(
+            sizes=(
+                (32,),
+                (64,),
+                (128,),
+                (256,),
+                (512,)
+            ),
+            aspect_ratios=(
+                (0.5, 1.0, 2.0),
+                (0.5, 1.0, 2.0),
+                (0.5, 1.0, 2.0),
+                (0.5, 1.0, 2.0),
+                (0.5, 1.0, 2.0)
+            )
+        )
+        roi_pooler = MultiScaleRoIAlign(
+            featmap_names=[
+                "c2",
+                "c3",
+                "c4",
+                "c5",
+                "pool"
+            ],
+            output_size=7,
+            sampling_ratio=2
+        )
+        super().__init__(
+            backbone=backbone,
+            num_classes=num_classes,
+            rpn_anchor_generator=anchor_generator,
+            box_roi_pool=roi_pooler,
+            min_size=800,
+            max_size=1333,
+            rpn_pre_nms_top_n_train=2000,
+            rpn_pre_nms_top_n_test=1000,
+            rpn_post_nms_top_n_train=1000,
+            rpn_post_nms_top_n_test=300,
+            rpn_nms_thresh=0.7,
+            rpn_fg_iou_thresh=0.7,
+            rpn_bg_iou_thresh=0.3,
+            box_score_thresh=0.05,
+            box_nms_thresh=0.5,
+            box_detections_per_img=100
+        )
+        self.class_names = {
+            0: "background",
+            1: "license_plate",
+            2: "house_number"
+        }
+    def print_architecture(self):
+        print("=" * 60)
+        print("VISION-AN18 FASTER R-CNN")
+        print("=" * 60)
+        print("Backbone       : ResNet50")
+        print("Backbone       : Pretrained ImageNet")
+        print("Neck           : Feature Pyramid Network")
+        print("RPN            : Region Proposal Network")
+        print("ROI Pooler     : MultiScale RoI Align")
+        print("Detection      : Fast R-CNN Head")
+        print("Classes        : 3")
+        print("  0            : background")
+        print("  1            : license_plate")
+        print("  2            : house_number")
+        print("=" * 60)
+def create_model(
+    num_classes=3,
+    pretrained_backbone=True
+):
+    model = VisionAN18FasterRCNN(
+        num_classes=num_classes,
+        pretrained_backbone=pretrained_backbone
+    )
+    return model