Musnad_Final_Collection

Musnad_Final_Collection — Musnad Script Character Detector (Multi-Head CNN, TensorFlow + Flask)

Overview

This project builds an object-detection style model to detect and classify Musnad script characters in an image.

The system includes:

• A TensorFlow/Keras multi-head CNN that predicts per-grid-cell:
  • Objectness (is there a character?)
  • Bounding box (x, y, w, h)
  • Class (which Musnad character)
• A Flask web app (app.py) that lets you upload an image and returns an annotated result.
• Scripts to train, verify data, and run inference.

A pre-trained model is included:

• musnad_detector_multi_head.keras (~76MB)

Folder contents (main files)

• app.py
  • Flask UI for uploading an image and showing detection results.
• train.py
  • Training entry point (multi-output losses + callbacks) and saves to musnad_detector_multi_head.keras.
• detect.py
  • Simple local inference script that runs detection on an image and saves detection_result.jpg.
• model.py
  • build_musnad_detector() model architecture (CNN backbone + 3 detection heads).
• dataset.py
  • Dataset pipeline (loads prepared dataset splits from dataset/).
• loss.py
  • Loss functions for each head: objectness / box / class.
• generate_data.py, verify_data.py
  • Helpers for creating/verifying the dataset.
• classes.txt
  • List of Musnad character classes (one character per line).
• Reports/docs:
  • walkthrough.md
  • academic_technical_report.md
  • complete_project_report.md
  • final_academic_report.md

Model (high level)

Grid-based detector

• Input size: 224x224
• Grid size: S = 7 (7x7 cells)
• Outputs (per cell):
  • obj_output: shape (7, 7, 1) with sigmoid
  • box_output: shape (7, 7, 4) with sigmoid (relative offsets/sizes)
  • cls_output: shape (7, 7, num_classes) with softmax

Architecture

Defined in model.py:

• CNN backbone: stacked Conv2D + BatchNorm + LeakyReLU + MaxPool blocks
• Final feature layer: Conv2D(1024)
• Heads: 1x1 conv layers for each output head

Training

File: train.py

• Batch size: 32
• Epochs: 20
• Optimizer: Adam(lr=1e-4)
• Uses separate losses + loss weights:
  • obj_output: 1.0
  • box_output: 5.0 (emphasize box quality)
  • cls_output: 1.0
• Callbacks:
  • ModelCheckpoint (best on val_loss)
  • ReduceLROnPlateau
  • EarlyStopping

Expected dataset folder (relative to project root):

• dataset/ with splits like train and val (see dataset.py).

Inference

1) Flask web app

File: app.py

• Loads musnad_detector_multi_head.keras.
• Uploads are stored under: static/uploads/.
• Draws red bounding boxes and labels on the original image.

Run:

python app.py

Then open:

• http://127.0.0.1:5000

2) Script-based inference

File: detect.py

• Loads model and runs prediction.
• Saves output image as: detection_result.jpg.

Note: detect.py loads CLASSES_FILE dynamically from the local project path (classes.txt).

Notes / caveats

• The project includes multiple report markdown files; walkthrough.md is a good quick overview.
• The Keras model file is already included, so you can run inference without training.

Suggested clearer folder names

• musnad-character-detector-tf-flask
• musnad-script-object-detection
• musnad-multihead-detector-keras