id-card-detector: Faster R-CNN Region Extraction for National ID Cards

The sub-problem split that defines this project

The README frames the task as three sub-problems: identify the regions of interest that hold the required information, crop those regions, and run OCR over the crop. The project itself covers the first two and hands the third to EasyOCR when the --ocr flag is present. The stated use case is extracting fields such as name, surname, and date of birth from a national identity card, and the repository ships three sample card images (an old card, a new card, and a licence) under static/. That decomposition is the honest part of the design: detection and reading are separate failure domains, and a mislocalized box ruins the OCR regardless of how good the OCR engine is. The README also claims the project can do object detection, object classification, and multiple object detection at the same time, which follows from using a two-stage detector rather than a classifier. Who this is for: engineers building a document intake pipeline who want a working reference for the detection stage and are willing to treat the model as a component they own. It is not a product, and the README does not present it as one.

How the TF2 SavedModel path actually runs

The modern path loads a TensorFlow 2 SavedModel from model/saved_model/ and, per the modernization notes, automatically resolves and calls the serving_default signature. The output keys are assumed to be detection_boxes, detection_scores and detection_classes, and the README warns plainly that SavedModel output keys can vary between models and that these defaults may need adjusting. Class names come from a lightweight parser that reads an ID-to-name mapping out of data/labelmap.pbtxt, which replaces the TF1 label map machinery. Visualization is OpenCV: the top-scoring box is drawn green, the others red, and the best region of interest is written to output_cropped.png at the project root. The camera script adds a different data flow. It draws boxes over the live feed and maintains a right-hand panel of up to nine cropped detections sorted by score; pressing a number key from 1 to 9 runs OCR on that snapshot and shows the result under an OCR Result label. That panel is the most interesting piece of interface design in the repository, because it turns a streaming detector into something a human can correct frame by frame. It is also the part with the least documentation: the README describes the keys but not how snapshots are retained or aged out.

Install commands, flags, and the two backends

Installation is split by platform. The one-shot path uses a platform requirements file: requirements-macos-apple.txt for Apple Silicon, requirements-cpu.txt for Intel macOS, Linux, and Windows CPU. The split path installs TensorFlow first, then requirements-modern.txt. The pinned versions in the README are tensorflow-macos==2.16.1 with tensorflow-metal==1.2.0 on Apple Silicon, tensorflow==2.20.0 on Intel macOS and Linux CPU, and tensorflow==2.17.1 on Windows CPU. On Python 3.12 the README advises upgrading pip first. The image script is invoked as python3 id_card_detection_image.py --image /path/to/img.jpg --ocr --min_score 0.6. The flags are --image (defaults to test_images/image1.png), --min_score (default 0.60, range 0 to 1), --ocr, and --yolo_model. Passing --yolo_model switches the detector backend to YOLO, accepting either a local .pt path or a name such as yolov8n.pt, after pip3 install ultralytics. The camera script takes --camera (device index, default 0), --min_score (default 0.50), --yolo_model, and --ocr, with hotkeys q, p, s, b, and 1 through 9. Note the threshold asymmetry: 0.60 for stills, 0.50 for the camera. The README does not explain why.

The legacy TF1 flow is still in the repository

requirements.txt and the original entry point are kept for the TensorFlow 1.15 flow, which requires Python 3.7. The README calls it hard to set up on modern systems and warns that TF1 dependencies, especially on macOS and ARM, are incompatible with modern Python, suggesting Docker or a dedicated Python 3.7 environment. This is a maintenance liability rather than a feature. The modernization notes say TensorFlow 1 graph code and the TF Object Detection API dependency were removed, with no more object_detection.* imports, yet the legacy requirements file remains. Anyone who clones the repository and runs the obvious pip3 install -r requirements.txt will land in the unsupported path. The README does not mark requirements.txt as deprecated at the top of the file, only in the section that describes it. A reader who skims the setup section can miss this.

Where the detector breaks down

The first limitation is the model artifact. The README documents how to load model/saved_model/ but never states where those weights come from, what they were trained on, or how to reproduce them. There is no training script described, no dataset description, and no evaluation numbers. If the SavedModel directory is absent from a fresh clone, the default TF2 path cannot run at all, and the README offers no fallback beyond switching to YOLO with a generic yolov8n.pt, which is a general object detector and was not trained on ID cards. The second limitation is the output-key assumption. The README says SavedModel output keys can vary and that defaults expect detection_boxes, detection_scores and detection_classes, so a model exported with different signature names fails at inference rather than at load time, which is a harder error to diagnose. The third is the single-crop output: the image script saves only the best ROI as output_cropped.png, so a card photographed at an angle, or a frame containing two cards, loses the other regions. The camera script partly addresses this with its nine-slot panel, but the image path does not. Fourth, the README's own note that lowering --min_score to 0.3 or 0.5 shows more candidates is an admission that the default threshold trades recall for a clean picture, not a tuned operating point. Finally, no OCR accuracy is reported anywhere, and EasyOCR on a cropped card region is subject to the usual problems with glare, rotation, and non-Latin scripts, none of which the README discusses.

YOLO as the alternative backend, and what changes

The repository's own alternative is the YOLO backend, which is a genuinely different approach rather than a drop-in swap. Faster R-CNN is two-stage: a region proposal network generates candidate boxes and a second head classifies and refines them. YOLO is single-stage: it predicts boxes and classes in one pass over a grid. The practical consequences for this project are visible in the flags. The README's YOLO examples use --min_score 0.4 rather than the TF2 default of 0.6, which suggests the score distributions are not comparable between backends and that you cannot carry a threshold across. The YOLO path also accepts a model name like yolov8n.pt, which means the default is a generic COCO-trained checkpoint, not a card-specific one, so out of the box it will not know what an ID card field is. The advantage is portability: ultralytics installs without the TensorFlow version pinning that dominates the setup section, and the same .pt file runs on CPU or GPU without the tensorflow-macos and tensorflow-metal split. If you already have a YOLO training pipeline and card annotations, that path is the shorter one. If you have a TF2 SavedModel already, the TF2 path avoids a second dependency tree.

Licence, upgrade cost, and what the refresh did not fix

The repository is MIT licensed, which permits commercial use and modification provided the copyright notice and permission notice are retained. That is the least restrictive common option, but it covers the code only. The README does not state the provenance or licence of the SavedModel weights in model/saved_model/, and a model trained on identity documents may carry obligations that the MIT licence on the Python files does not address. Treat the weights as a separate question and resolve it before shipping anything. On upgrade cost: the project was refreshed after more than seven years and the modernization notes list what changed, but the version pins are already uneven (TensorFlow 2.16.1 on Apple Silicon, 2.17.1 on Windows, 2.20.0 on Linux), which means three dependency matrices to track. There are no releases retrieved for this repository, so there is no tag to pin against and no changelog beyond the README section. The last push was 2026-05-16, so the project is active, but activity is not the same as a support commitment. The README's own closing note, that output keys can vary and should be adjusted easily if different, is the kind of instruction that reads as reassurance and functions as a warning. Budget for reading the SavedModel signature yourself with the TensorFlow saved_model CLI before you trust the defaults.

Editorial conclusion

Adopt it if you need a small, MIT-licensed reference implementation that shows the full pipeline from detection to cropped ROI to OCR text, and you are prepared to supply or retrain the SavedModel yourself. Do not adopt it if you need a maintained, versioned model artifact, GPU training code, or a supported Windows TF1 path. Before you commit, verify that model/saved_model/ exists in your checkout, that its serving_default signature exposes detection_boxes, detection_scores and detection_classes as the README expects, and that data/labelmap.pbtxt maps the class indices your model actually emits.

Official sources

1. Issues
2. License: MIT
3. mesutpiskin/id-card-detector on GitHub
4. README